Vibe Coding UI Specification for AI Coding Agents — HorizonX

Open specification · v1.0

Vibe Coding UI Specification

A vendor-neutral contract for turning visual direction into constraints that AI coding agents can implement and reviewers can verify.

Download the Markdown specification Review the contract →

Designed for workflows using Cursor, Claude Code, Codex, Lovable, v0, Bolt and other coding agents.

The problem

Adjectives are not implementation constraints.

Requests such as “make it premium” leave tokens, states, responsive behavior and accessibility for the agent to guess. The result may look persuasive in one screenshot while drifting across the product. This specification makes the missing decisions explicit before implementation begins.

The contract

Six layers that make a UI direction testable.

01

Tokens

Define color, typography, spacing, radius, shadow and layout values before components introduce one-off decisions.

02

Components

List variants, sizes and every user-visible state instead of describing only the ideal screenshot.

03

Responsive rules

Specify navigation, grids, overflow, content stress and touch behavior at measurable viewports.

04

Accessibility

Require semantic HTML, keyboard completion, visible focus, programmatic errors and WCAG 2.2 AA contrast.

05

Motion

Use named durations and easing, safe properties and reduced-motion behavior that preserves essential feedback.

06

Quality gates

Name the browsers, viewports, states and repeatable checks that must pass before completion.

Quick start

Put the specification in the agent's context.

  1. 01 Download the Markdown specification and copy the YAML contract into ui-spec.yaml.
  2. 02 Replace every value marked REQUIRED with a real product decision.
  3. 03 Link the file from AGENTS.md, CLAUDE.md or your tool's instruction file.
  4. 04 Ask the agent to implement one component or page at a time.
  5. 05 Run the acceptance checklist before merging.

Recommended instruction

Read ui-spec.yaml before changing interface code. Treat its tokens,
component states, responsive rules, accessibility requirements and
acceptance criteria as implementation constraints. If a request conflicts
with the specification, identify the conflict before writing code.

Verify the result

Specification first. Evidence before launch.

Once the interface is built, score it against the companion 15-point production-readiness checklist.

Open the readiness checklist

Questions

What teams ask before adopting the spec.

What is a vibe coding UI specification?

An explicit contract for tokens, component states, responsive behavior, accessibility, motion and verification that an AI coding agent can follow.

Which AI coding tools can use it?

It is vendor-neutral. Reference it from the instruction file used by Cursor, Claude Code, Codex, Lovable, v0, Bolt or a similar agent.

Is it free?

Yes. It is free to copy and adapt, and is maintained by HorizonX as an open resource for the interface-building community.

🍪 Usamos cookies.