| name | declarative-design |
| description | Use when the user wants to bring UI designs into a project for a PRD requirement. Identifies the screens/states a requirement needs, helps the user generate them via Stitch or Claude Design (or import existing exports), and places HTML + screenshot pairs under docs/designs/<FR-N>-<slug>.{html,png} so implementation can reference them. Triggers on "import these designs", "add screens for FR-001", "set up the designs for this requirement", "vibe design this screen", "/designs FR-N". |
Declarative Design
Bring UI designs into a project tied to a PRD requirement. Implements Phase 4 of the AI Development Framework V2.
Core principle
Designs are inputs to implementation, not after-the-fact polish. Each design MUST be traceable to a requirement (FR-N), machine-readable (HTML, not just a screenshot), and stored where the agent can find it (docs/designs/<FR-N>-<slug>.html). Pixel-pushing is replaced by vibe design: describe the intent, iterate on output.
When to use
- Requirement exists, no designs yet → start at Phase 1 to identify needed screens, then generate via Stitch/Claude Design.
- User already has HTML/screenshot exports → start at Phase 3 to place them.
- Designs exist but are unlinked / poorly named → start at Phase 3 with the existing files as input.
Skip for: backend-only requirements, CLI tools, internal services with no UI.
The 3 phases
Each phase has an INPUT, an OUTPUT, and a HUMAN GATE before advancing.
Phase 2 is the only phase that does not produce a file inside the repo — its output is the user going off to Stitch / Claude Design and returning with exports. The skill's job there is to give the user a useful design prompt and wait.
Operating protocol
- Identify the requirement ID. If not given, ASK. Use the same FR-N format as
generate-dev-plan and ai-driven-prd.
- Read the matching prompt file in
prompts/. Treat the prompt body as a system instruction — follow its rules literally.
- Stop at every phase boundary. Show artifact, ask: approved / refine / restart phase.
- Phase 2 fork: at the start of Phase 2, ask the user "Do you already have HTML exports for these screens?" If yes, skip to Phase 3 with those files as input. If no, produce the vibe-design prompt from templates/vibe-prompt.md.tmpl.
- Phase 3 final gate: score against references/checklist.md. All 6 items MUST pass.
Hard rules (non-negotiable)
- Naming convention:
docs/designs/<FR-N>-<slug>.{html,png} — no exceptions. The <slug> is a kebab-case short name (login, password-reset, cart-empty-state). Both HTML and PNG share the slug.
- Pair invariant: every HTML MUST have a matching PNG screenshot. The PNG is for humans skimming
docs/designs/; the HTML is for the agent.
- One screen state per file. If a requirement has 3 states (empty / loading / error), produce 3 file pairs, not 1 with all states stacked.
- Trace to AC. Each design's filename or sidecar note maps to the ACs it visualizes. If a design doesn't visualize any AC, ask the user why it's needed.
- No raw Figma exports. Figma → static image is fine for screenshots only; the HTML must come from a tool that produces clean, semantic HTML (Stitch, Claude Design, hand-written). Pixel-perfect Figma HTML exports are unreadable and useless to the agent.
- Don't hide constraints in screenshots. If a behavior matters (e.g. "submit button disabled until terms accepted"), it MUST live in the PRD's AC, not only in the design. Designs visualize; ACs specify.
- Ambiguity → ASK. Never invent a screen the requirement doesn't call for.
What NOT to do
See references/anti-patterns.md. Top three to watch:
- Bundling unrelated requirements. One file pair per
<FR-N>-<slug>[-<state>]. No auth-screens.html covering FR-001 + FR-002 + FR-003.
- Inventing states. Phase 1's screen list is the contract. Don't add a "loading" or "error" design unless the requirement calls for one.
- Stale designs. When the PRD changes meaningfully, rename affected designs to
<FR-N>-<slug>.STALE.html and rerun Phase 2 — never silently use outdated designs.
References
