Design Spec Template

Copy into docs/specs/design-FEATURE.md.

---

---
id: design-your-feature
title: "Design Spec: Feature Name"
description: "UX/UI specification for Feature Name"

status: draft
owner: "@design-handle"
linked_prd: "specs/your-feature-name"
figma: "https://figma.com/file/..."
created: YYYY-MM-DD
updated: YYYY-MM-DD
---

# Design Spec: Feature Name

<div style={{display:'flex',gap:'0.5rem',marginBottom:'1.5rem'}}>
  <span className="badge badge--draft">Draft</span>
  <span className="badge badge--secondary">Owner: @handle</span>
</div>

## Overview

Brief description of the UX scope for this feature.

**Figma:** [Link to designs](https://figma.com/file/...)  
**PRD:** [Feature Name](../specs/your-feature-name)

---

## User flows

```mermaid
flowchart TD
    A[Entry point] --> B{Decision}
    B -->|Path 1| C[Screen A]
    B -->|Path 2| D[Screen B]
    C --> E[Success state]
    D --> E
```

## Screen inventory

| Screen | Description | Figma frame |
|---|---|---|
| Screen A | What user sees | [Link] |
| Screen B | What user sees | [Link] |

## Interaction notes

### Component: [Name]
- Behaviour on hover
- Behaviour on focus
- Behaviour on error
- Loading state

### Edge cases

| State | Handling |
|---|---|
| Empty state | Show illustration + CTA |
| Error state | Inline error message |
| Loading | Skeleton / spinner |

## Accessibility

- [ ] All interactive elements reachable by keyboard
- [ ] Focus order is logical
- [ ] Colour contrast ≥ 4.5:1 for body text
- [ ] ARIA labels on icon-only buttons
- [ ] Screen reader tested

## Copy

| Element | Copy |
|---|---|
| CTA | "Button text" |
| Empty state heading | "Heading text" |
| Error message | "Error text" |

## Open questions

- [ ] **@pm** — Confirm exact copy for the confirmation dialog?
- [ ] **@eng** — Can we animate the transition? What's the performance budget?

---

*Last updated by @handle on YYYY-MM-DD*