Draft a UX spec with flows, states, edge cases, and component references. Grounded in your Storybook library, design principles, and UX brief.
/design-spec-draft - UX Spec DraftingTurn a brief, PRD, or feature description into a handoff-ready UX spec.
/design-spec-draft → Guided questions to draft from scratch
/design-spec-draft [feature description] → Skip questions you've already answered
/design-spec-draft [paste brief] → I'll draft from the brief
Output: Spec saved to outputs/design-specs/[feature-name]-spec.md
Template: Based on templates/design-spec-template.md
Time: 20–40 minutes for first draft
Before drafting, check:
| Source | Files/Folders | What to extract |
|---|
| Brief | outputs/briefs/ or described in chat | Problem, scope, success criteria, constraints |
| Storybook | context-library/design-system/storybook.md | Which components exist and which to use |
| Component UX | context-library/design-system/component-ux/ | Per-component rules, states, anti-patterns |
| Principles | context-library/design-system/principles.md | Accessibility standards, anti-patterns |
| Research | context-library/research/ | User expectations, known edge cases from sessions |
| Example specs | context-library/example-specs/ | Format and detail level your team uses |
| Past specs | context-library/design-specs/ | Prior decisions on adjacent patterns |
| Figma MCP (if connected) | Design file | Current visual state of work |
Start with these if no brief is provided:
Every spec needs these sections. Flag missing ones rather than skipping them.
List every Storybook component involved. Match names exactly to Storybook.
For each screen or section:
Every interactive element needs all relevant states:
Write every error message out in full. "Show error" is not a spec. Good error messages:
Document every zero-data situation:
EmptyState component from Storybook. Always include a next action.Write all visible text:
[copy TBD]. If you don't know the copy, flag it as a decision needed.For each breakpoint that applies:
Explicitly list what v1 does NOT include. This prevents scope creep.
List any unresolved items with an owner and due date.
DataTable, not "table" or "grid"FormField > With Error"When the spec requires a pattern that doesn't exist in Storybook:
[TBD] placeholders## Components Used
| Component | Storybook Path | Props Used | Notes |
|-----------|---------------|------------|-------|
| `FormField` | Forms > FormField | `label`, `helperText`, `errorMessage`, `isInvalid`, `isRequired` | Wraps all inputs |
| `TextInput` | Forms > TextInput | `placeholder`, `value`, `onChange` | Email field |
| `Button` | Actions > Button | `primary`, `isLoading`, `isDisabled` | Submit CTA |
| `Alert` | Feedback > Alert | `error` | Server error feedback |
**New patterns (not in Storybook):**
- `FilterDrawer` — multi-select filter panel. New pattern needed. Design system contribution required before launch.