Vibe Coding UI Specification for AI Coding Agents | HorizonX

Resources 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 specification Review the contract

Markdown file with a YAML contract. Works with Cursor, Claude Code, Codex, Lovable, v0, Bolt and other coding agents.

ui-spec.yaml v1.0 · Excerpt
spec:name: REQUIREDversion: 1.0.0tokens:color:accent: "#REQUIRED"focus: "#REQUIRED"components:button:states: [default, hover, focus-visible, active, disabled, loading]accessibility:target: WCAG-2.2-AAcontrast:normal_text: 4.5quality_gates:viewports: [360x800, 768x1024, 1280x800, 1440x900]

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.

What the agent hears

“Make it premium.”

Contrast, target sizes and component states are left to guesswork.

What the spec says

contrast.normal_text
4.5
minimum_touch_target_px
44
button.states
default, hover, focus-visible, active, disabled, loading

The contract

Six layers that make a UI direction testable.

  1. Tokens

    tokens

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

  2. Components

    components

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

  3. Responsive rules

    responsive_rules

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

  4. Accessibility

    accessibility

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

  5. Motion

    motion

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

  6. Quality gates

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

Recommended instruction

One paragraph your agent reads first.

AGENTS.md or CLAUDE.md 
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.

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.

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