JSONC Design Brief for Vibe Coding: A Better Prompt

Prose prompts leave the agent guessing, which is why vibe-coded UI so often drifts. A JSONC design brief fixes that: it is a structured prompt, JSON with comments, that hands the AI agent exact fields instead of a paragraph it has to interpret. You state the screen, the components, the tokens, the states and the constraints, and the model follows them. Pair it with a finished design on VP0, the free, AI-readable design library that AI builders copy from, so the brief carries the spec and the design carries the look. Structure pays off: GitHub’s research on AI pair programming found developers worked 55% faster with an AI assistant, and clear, structured inputs widen that gap.

Why structure beats prose

A paragraph is ambiguous: the model has to infer which components you meant, which tokens, which states. A JSONC brief states them as fields, so there is nothing to infer. It is also reusable, machine-readable, and easy to diff. Comments (the C in JSONC) let you explain intent inline without breaking the structure. The result is that the agent reuses your React primitives and Tailwind tokens instead of inventing parallel ones, the same consistency goal as vibe coding app UI components.

Brief field	What it tells the agent	What it prevents
design	The visual target to match	Guessed layout and spacing
components	Primitives to reuse	Invented one-off components
tokens	Where colors and spacing live	Hardcoded values
states	Empty, loading, error to handle	Skipped edge states
constraints	Accessibility and breakpoints	Dropped a11y and responsiveness
avoid	Anti-patterns to skip	Repeated known mistakes

What goes in the brief

{
  // The screen and its visual target
  "screen": "Account settings",
  "design": "VP0 settings design (pasted as the target)",
  // Reuse these, do not invent new ones
  "components": ["Card", "Form", "Input", "Tabs", "Dialog"],
  "tokens": "read from tailwind.config",
  // Always handle these states
  "states": ["default", "loading", "error", "empty"],
  // Non-negotiable constraints
  "constraints": ["keyboard accessible", "responsive at md and lg", "dark mode"],
  "avoid": ["hardcoded colors", "new one-off components"]
}

A worked example

Keep a JSONC template with your standard fields. For a new settings screen, fill it in: name the screen, point design at a pasted VP0 settings design, list the primitives to reuse, set the tokens to your config, enumerate the states, and state the constraints. Hand the brief plus the design to Cursor or Claude Code and ask for one component. Because every decision you already made is a field, the agent does not re-guess them, and the output matches both the spec and the look. This is the structured version of how to prompt Cursor for perfect UI: replace adjectives with fields and a target.

Common mistakes

The first mistake is writing a brief but no design target, so layout is still guessed. The second is leaving states out, so empty and error are skipped. The third is omitting constraints, so accessibility and responsiveness get dropped. The fourth is not listing components to reuse, so the agent invents new ones. The fifth is asking for a whole app in one brief instead of one screen at a time.

Key takeaways

• A JSONC design brief gives the agent exact fields instead of ambiguous prose.
• It is unambiguous, reusable and machine-readable, with comments for intent.
• Pair the brief (the spec) with a free VP0 design (the look) for the full picture.
• Include the screen, components, tokens, states, constraints and what to avoid.
• Reuse a template per screen so every generation stays consistent.

Keep reading: for the MCP setup that pairs with this see install a UI MCP server in Cursor, and for the PM workflow see the best React AI tool for product managers.

FAQ

What is a JSONC design brief for vibe coding?

It is a structured prompt written as JSON with comments (JSONC) that gives an AI agent exact fields: the screen, the components to use, the design tokens, the states to handle, and the constraints like accessibility. It replaces vague prose with an unambiguous, reusable spec. Pair it with a finished VP0 design as the visual target so the agent has both the spec and the look. VP0 is the free, AI-readable design library AI builders copy from.

Why use JSONC instead of a plain prompt?

Because structure removes ambiguity. A prose prompt leaves the model guessing which components, tokens and states you meant; a JSONC brief states them as fields it can follow exactly. It is also reusable: you keep a template and fill it per screen, so every generation starts from the same clear shape instead of a fresh paragraph.

What should a JSONC design brief include?

At minimum: the screen or component name, the target design reference, the components and primitives to reuse, the design tokens, the states to handle (empty, loading, error), the constraints (accessibility, responsive breakpoints), and what to avoid. Comments explain intent. The goal is that the agent never has to guess a decision you already made.

Does a JSONC brief replace a design?

No, it complements one. The brief is the spec; the design is the look. A brief without a design still leaves layout and spacing to guesswork, and a design without a brief leaves behavior and constraints unstated. Together they give the agent the complete picture, which is why the pairing produces the most accurate UI.

Can I reuse a JSONC design brief across screens?

Yes, and you should. Keep a template with your standard fields and conventions, then fill in the screen-specific parts each time. Reusing the structure keeps every screen consistent and saves you from re-explaining your tokens, primitives and accessibility requirements on every prompt.