Design Spec Draft

Guided Questions

Start with these if no brief is provided:

1. "What feature are we speccing? Describe it in a sentence."
2. "What platform(s): web, mobile, or both?"
3. "Do you have a Figma file or brief I should reference?"
4. "Any Storybook components you know will be used?"
5. "What are the main user actions in this flow?"

What a Complete Spec Covers

Every spec needs these sections. Flag missing ones rather than skipping them.

1. Components Used

List every Storybook component involved. Match names exactly to Storybook.

• If a pattern doesn't exist in Storybook: call it out explicitly as "new pattern"
• Note key props and variants being used (not just the component name)

2. Behavior

For each screen or section:

• What the user sees by default
• What happens when they interact (table: user action → system response)
• State transitions

3. States (Never Skip These)

Every interactive element needs all relevant states:

• Default, hover, focus, active, disabled, loading, error, empty
• Include what triggers each state
• Note if Storybook handles a state automatically or if the designer needs to spec it

4. Error States

Write every error message out in full. "Show error" is not a spec. Good error messages:

• Say what went wrong
• Tell the user how to fix it
• Don't blame the user

5. Empty States

Document every zero-data situation:

• First use (no data has ever been added)
• Search/filter that returns no results
• Content that has been deleted Use the EmptyState component from Storybook. Always include a next action.

6. Microcopy

Write all visible text:

• Headings, labels, placeholders, helper text, CTAs
• Success messages, confirmation dialogs
• No [copy TBD]. If you don't know the copy, flag it as a decision needed.

7. Responsive Behavior

For each breakpoint that applies:

• What changes at mobile vs. tablet vs. desktop
• What stays the same

8. Accessibility

• Focus order (describe the tab sequence)
• Any non-standard keyboard interactions
• ARIA notes not handled by existing components
• Color contrast flags if using custom colors

9. Out of Scope

Explicitly list what v1 does NOT include. This prevents scope creep.

10. Open Questions

List any unresolved items with an owner and due date.

Rules for Spec Language

• Use exact Storybook component names: DataTable, not "table" or "grid"
• Reference Storybook story paths: "FormField > With Error"
• Write error messages in quotes as they'll actually appear to users
• Use second person present tense: "When the user clicks X, Y happens"
• Reference Figma frames with links when they exist
• Call out when something is a new pattern (not in Storybook) so engineering knows

New Patterns Handling

When the spec requires a pattern that doesn't exist in Storybook:

1. Call it out explicitly in the "Components Used" section: "New pattern: [name] — does not exist in Storybook. See design notes."
2. Spec it as thoroughly as you would an existing component (states, accessibility, etc.)
3. Flag it for design system contribution review
4. Note the approximate impact (used in 1 place vs. will appear across 8 surfaces)

Quality Check Before Saving

• Every component is named exactly as it appears in Storybook
• All interactive states are documented (default through error)
• Every error message is written out in full — no "show error"
• Every empty state has a message AND a next action
• All microcopy is written out — no [TBD] placeholders
• Responsive behavior documented for each relevant breakpoint
• Accessibility section is present and specific
• Out of scope section is explicit
• New patterns are called out and flagged for design system review

Example Component Reference Block

## 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.