---
artifact-status: draft   # draft | approved — approval state of this generated file (gate reads this)
---
# Design Specification: {Product / Surface}

> **Last Updated:** [Date]  ·  **Author:** [PE name]  ·  **Source:** `docs/design-uiux.md` + Generated Screens `docs/ui/*.html`
> **Extracted, not invented:** token / component / breakpoint values are extracted from the Generated Screens (the Design System Seed only set the initial direction). Internal artifact — not sent to the customer. Generated/updated by `/tas-design-spec`.

> **Token-ref convention (binding):** every value is referenced as `{group.token}` — e.g. `{colors.primary}`, `{rounded.pill}`, `{typography.body}`. **Never inline a raw hex / px / font value inside Components or in code.** `/tas-dev` implements each token once as a CSS variable / theme constant and references it everywhere; `/tas-review` flags any literal that bypasses a token. If a needed token is missing, add it here first — do not improvise.

---

## Overview
{Describe the design language in prose — the chosen style direction, what the product should feel like, and how surfaces relate. Avoid vague defaults like "clean minimal".}

**Key Characteristics:**
- {3–8 bullets that define the visual signature — the rules a stranger could use to recognize this product}

## Colors
> Define the full palette as tokens. Group by role. Every color used anywhere must exist here.

### Brand & Accent
- **{Name}** (`{colors.primary}` — #{hex}): {usage — interactive elements, links, focus}
- **{Name}** (`{colors.primary-hover}` — #{hex}): {hover / active}

### Surface
- **{Name}** (`{colors.canvas}` — #{hex}): {page background}
- **{Name}** (`{colors.surface}` — #{hex}): {cards, panels}

### Text
- **{Name}** (`{colors.ink}` — #{hex}): {headlines / body}
- **{Name}** (`{colors.body-muted}` — #{hex}): {secondary text}

### Hairlines & Borders
- **{Name}** (`{colors.border}` — #{hex}): {borders, dividers}

### Brand Gradient
{Gradient tokens, or state explicitly "None" if the system uses no decorative gradients.}

## Typography

### Font Family
- **Display**: `{typography.font-display}` — {family stack + when used}
- **Body / UI**: `{typography.font-body}` — {family stack}
- **OpenType features**: {features, or "none"}

### Hierarchy
| Token | Size | Weight | Line Height | Letter Spacing | Use |
|-------|------|--------|-------------|----------------|-----|
| `{typography.h1}` | {px} | {wt} | {lh} | {tracking} | {use} |
| `{typography.h2}` | {px} | {wt} | {lh} | {tracking} | {use} |
| `{typography.body}` | {px} | {wt} | {lh} | {tracking} | Default paragraph |
| `{typography.caption}` | {px} | {wt} | {lh} | {tracking} | Captions, button text |

### Principles
- {Weight ladder, tracking rules, body size convention — the unbreakable typographic rules}

### Font Substitutes
- {Open-source fallback if the chosen face is proprietary, with tuning notes}

## Layout

### Spacing System
- **Base unit:** {e.g. 8px}.
- **Tokens:** `{spacing.xs}` {px} · `{spacing.sm}` {px} · `{spacing.md}` {px} · `{spacing.lg}` {px} · `{spacing.xl}` {px} · `{spacing.section}` {px}
- **Section / card / button padding:** {values in tokens}

### Grid & Container
- **Max content width:** {px}
- **Column patterns:** {grid columns per surface}
- **Gutters:** {px}

### Whitespace Philosophy
{How air is used — the spacing intent, not just numbers.}

## Elevation & Depth
| Level | Treatment | Use |
|-------|-----------|-----|
| Flat | No shadow/border | {where} |
| `{shadow.sm}` | {value} | {where} |
| `{shadow.lg}` | {value} | {where} |

**Shadow philosophy.** {When elevation is allowed and what it signals.}

## Shapes

### Border Radius Scale
| Token | Value | Use |
|-------|-------|-----|
| `{rounded.none}` | 0 | {where} |
| `{rounded.sm}` | {px} | {where} |
| `{rounded.md}` | {px} | {where} |
| `{rounded.lg}` | {px} | {where} |
| `{rounded.pill}` | 9999px | {where} |

### Imagery Geometry
{Aspect ratios, crops, radius on imagery, loading strategy.}

## Components
> Document every reusable component as a token composition + interaction states. Reference tokens only (`{colors.*}`, `{rounded.*}`, `{typography.*}`, `{spacing.*}`). Convention: document **default + active/pressed** states (hover optional). Variants of a component (`-active`, `-focus`, `-secondary`) are separate entries.

### Navigation
**`{component.global-nav}`** — {bg=`{colors.*}`, height, text token, link spacing, responsive collapse}

### Buttons
**`{component.button-primary}`** — bg=`{colors.primary}`, text=`{colors.on-primary}`, radius=`{rounded.pill}`, padding={tokens}, font=`{typography.body}`.
- Active: `{component.button-primary-active}` — {e.g. transform: scale(0.95)}
- Focus: `{component.button-primary-focus}` — {outline token}

**`{component.button-secondary}`** — {token composition}

### Cards & Containers
**`{component.card}`** — bg=`{colors.surface}`, radius=`{rounded.lg}`, shadow=`{shadow.sm}`, padding=`{spacing.lg}`. {content stack}

### Inputs & Forms
**`{component.input}`** — border=`{colors.border}`, radius=`{rounded.md}`, height, padding={tokens}. Focus=`{colors.primary}`; error=`{colors.error}`. {validation/error states}

### Footer
**`{component.footer}`** — {bg, text tokens, link typography, padding}

## Do's and Don'ts

### Do
- Use `{colors.primary}` for every interactive signal; reference tokens, never literals.
- {product-specific affirmative rules}

### Don't
- Don't introduce colors / sizes / fonts outside the token set.
- {product-specific prohibitions}

## Responsive Behavior

### Breakpoints
| Name | Width | Key Changes |
|------|-------|-------------|
| Phone | ≤ {px} | {layout changes} |
| Tablet | {range} | {layout changes} |
| Desktop | ≥ {px} | {layout changes} |

### Touch Targets
- Minimum {e.g. 44×44px}. {per-component notes}

### Collapsing Strategy
- {how nav / grids / typography collapse across breakpoints}

### Image Behavior
- {srcset / art-direction / aspect-ratio rules}

## Iteration Guide
1. Focus on ONE component at a time; reference its key directly (`{component.*}`).
2. Variants (`-active`, `-focus`, `-secondary`) live as separate `Components` entries.
3. Use `{token.refs}` everywhere — never inline hex/px.
4. {other product-specific iteration rules}

## Known Gaps
- {States / surfaces not yet specified — so `/tas-dev` knows to flag rather than invent}

---

## Changelog
| Date | Changes | Author |
|------|---------|--------|