Prompt Interface
Documentation strategies that help AI choose and use the design system correctly.
Key takeaways
- Design-system docs should act as a prompt interface: structured, searchable, bounded, and example-heavy so the correct UI path is the easiest one.
- A compact context packet (surface type, user intent, allowed components, token boundaries, density, forbidden patterns, verification command) beats a long pile of links.
- A component selection rubric makes choices mechanical, so agents stop picking components by similar name.
- Strong prompts name the user, the existing components, the density target, and the screenshot widths; weak prompts just say "make it look better."
- Keep stable system context in AGENTS.md, CLAUDE.md, or DESIGN.md, and have agents report components, tokens, variants, assumptions, and verification in a fixed output shape.
Agents generate code from the context they can see. Design-system docs must therefore become a prompt interface: structured, searchable, bounded, and example-heavy.
The goal is not to write clever prompts. The goal is to make the correct UI path the easiest path for the agent to follow.
What Prompt-Friendly Docs Include
| Section | Purpose |
|---|---|
| Component purpose | When to choose it. |
| Allowed variants | What choices are legal. |
| Composition rules | How it combines with other components. |
| State examples | Loading, empty, disabled, selected, error. |
| Accessibility notes | Labels, roles, keyboard, focus. |
| Anti-patterns | What the agent should not generate. |
Prompt Context Packet
For meaningful UI work, give the agent a compact packet instead of a long pile of links.
| Field | Include |
|---|---|
| Surface type | Tool, dashboard, docs page, marketing page, game, editor, form, or modal. |
| User intent | The task the user is trying to complete, not only the component to render. |
| Allowed components | Approved primitives and composites for this task. |
| Token boundaries | Color, spacing, radius, typography, motion, and elevation rules. |
| Density target | Compact, standard, editorial, immersive, or touch-first. |
| Forbidden patterns | Known failure modes such as card nesting, fake gradients, or invented variants. |
| Verification command | The exact command or browser check that must pass. |
Task: build the account billing settings screen.
Surface type: operational SaaS settings, not marketing.
Allowed components: PageHeader, DataTable, Tabs, Button, Badge, FormField, Dialog.
Token rules: use semantic tokens only; do not hard-code raw colors or spacing.
Density: compact but readable; optimize for repeated scanning.
Forbidden: no hero section, no decorative cards, no nested cards, no invented Button variants.
Verification: run typecheck and capture desktop/mobile screenshots.Component Selection Rubric
Agents often pick a component based on a similar name. A prompt interface should make selection mechanical.
| Question | Decision rule |
|---|---|
| Is the element an action? | Use Button; use Link for navigation. |
| Is the user choosing from a small finite set? | Use radio group or segmented control. |
| Is the user toggling a binary setting? | Use switch or checkbox based on persistence and context. |
| Is the user scanning many rows? | Use table or list, not repeated decorative cards. |
| Is the content an object summary? | Use a card only if it is a repeated item or a genuinely framed object. |
Recommended Format
## Button
Use for explicit user actions. Do not use for navigation when a link is enough.
Allowed variants: primary, secondary, danger, ghost.
Allowed sizes: sm, md, lg.
Icon-only buttons require aria-label.
Bad: using primary for every action in a dense toolbar.
Good: one primary action per task surface.Weak vs Strong Prompts
Weak:
Make this dashboard look better and more modern.Strong:
Revise the dashboard for a finance operations user who scans exceptions all day.
Use the existing DataTable, Toolbar, Tabs, Badge, and Button components.
Keep density high, make risk states visually distinct, and avoid marketing-style hero layout.
After editing, run typecheck and capture 1440px and 390px screenshots to check text fit.Prompt Rules for Teams
- Keep stable system context in files such as
AGENTS.md,CLAUDE.md, orDESIGN.md. - Put task-specific intent in the user prompt.
- Mention only the relevant component docs when the task is narrow.
- Include "do not invent tokens/components" in persistent instructions.
- Ask the agent to run the design-system verification command after edits.
Figma and Tool Context
Figma MCP and similar tools can expose frames, variables, components, and screenshots. They work best when the design system has consistent names and maps Figma concepts to code concepts.
Use tool context for current source-of-truth data: frame structure, variables, component names, and screenshots. Keep durable product rules in repository files so the agent does not depend on a live tool connection for every change.
| Tool context | Repository context |
|---|---|
| Current Figma frame hierarchy | Stable component API |
| Variables and styles in the file | Token naming and semantic meaning |
| Screenshot of target layout | Product density and visual philosophy |
| Component instances in the design | Composition and accessibility rules |
Prompt Output Template
Ask agents to report decisions in a predictable shape.
Implementation summary:
- Components used:
- Tokens used:
- Variants used:
- Assumptions:
- Missing design-system coverage:
- Verification run:Output Contract
AI-generated UI should include:
- the component choices it made;
- any token or variant it could not find;
- screenshots or visual verification when the task changes UI;
- test or lint results;
- a short list of design-system assumptions.