# Design System

Create a small system of reusable decisions before producing many screens. Tokens and components should express the behavior required by [PROJECT NAME], including all states—not merely make screens look consistent.

[Kit README](README.md) · [Project Overview](Project%20Overview.md) · [PRD](Full%20PRD%20Template.md) · [Master Build Prompt](Master%20Build%20Prompt.md) · [Completion Checklist](Project%20Completion%20Checklist.md)

## Foundations

| Token Group | Required Decisions | Example Format |
| --- | --- | --- |
| Color | canvas, surfaces, text, border, action, success, warning, danger, focus | **--color-text-primary: [VALUE]** |
| Type | display, heading, body, label, code/data; size, weight, line height | **--type-body-md: [VALUE]** |
| Space | 4 or 8-based scale with semantic aliases | **--space-component-gap: [VALUE]** |
| Shape | control, card, dialog, and pill radii | **--radius-control: [VALUE]** |
| Elevation | overlays only where hierarchy requires it | **--shadow-overlay: [VALUE]** |
| Motion | duration and easing for feedback, entrance, and exit | **--motion-feedback: [VALUE]** |
| Layout | content widths, gutters, breakpoints, density | **--layout-content-max: [VALUE]** |

Every color pair needs contrast verification in its real text size and state. Focus indicators must remain visible against adjacent colors. Define light/dark themes only when both can be tested fully.

## Component Inventory

### 1. Responsive header and navigation Pattern

- Purpose: support the user when they need to understand the offer within ten seconds.
- Variants: [SIZE, EMPHASIS, OR ROLE]
- States: default, hover where relevant, focus, active, disabled with reason, loading, empty, success, warning, error.
- Accessibility: [SEMANTICS, NAME, DESCRIPTION, KEYBOARD/TOUCH BEHAVIOR]
- Content limits: [MIN/MAX LENGTH OR ITEM COUNT]

### 2. Purpose-built page templates Pattern

- Purpose: support the user when they need to reach any primary page in two navigation actions.
- Variants: [SIZE, EMPHASIS, OR ROLE]
- States: default, hover where relevant, focus, active, disabled with reason, loading, empty, success, warning, error.
- Accessibility: [SEMANTICS, NAME, DESCRIPTION, KEYBOARD/TOUCH BEHAVIOR]
- Content limits: [MIN/MAX LENGTH OR ITEM COUNT]

### 3. Contact form with validation and spam controls Pattern

- Purpose: support the user when they need to submit a contact request with clear confirmation.
- Variants: [SIZE, EMPHASIS, OR ROLE]
- States: default, hover where relevant, focus, active, disabled with reason, loading, empty, success, warning, error.
- Accessibility: [SEMANTICS, NAME, DESCRIPTION, KEYBOARD/TOUCH BEHAVIOR]
- Content limits: [MIN/MAX LENGTH OR ITEM COUNT]

### 4. SEO metadata and structured content Pattern

- Purpose: support the user when they need to understand the offer within ten seconds.
- Variants: [SIZE, EMPHASIS, OR ROLE]
- States: default, hover where relevant, focus, active, disabled with reason, loading, empty, success, warning, error.
- Accessibility: [SEMANTICS, NAME, DESCRIPTION, KEYBOARD/TOUCH BEHAVIOR]
- Content limits: [MIN/MAX LENGTH OR ITEM COUNT]

### 5. Analytics with consent-aware events Pattern

- Purpose: support the user when they need to reach any primary page in two navigation actions.
- Variants: [SIZE, EMPHASIS, OR ROLE]
- States: default, hover where relevant, focus, active, disabled with reason, loading, empty, success, warning, error.
- Accessibility: [SEMANTICS, NAME, DESCRIPTION, KEYBOARD/TOUCH BEHAVIOR]
- Content limits: [MIN/MAX LENGTH OR ITEM COUNT]

### 6. Accessible keyboard and screen-reader behavior Pattern

- Purpose: support the user when they need to submit a contact request with clear confirmation.
- Variants: [SIZE, EMPHASIS, OR ROLE]
- States: default, hover where relevant, focus, active, disabled with reason, loading, empty, success, warning, error.
- Accessibility: [SEMANTICS, NAME, DESCRIPTION, KEYBOARD/TOUCH BEHAVIOR]
- Content limits: [MIN/MAX LENGTH OR ITEM COUNT]


## Standard Component Contract

~~~text
Name: [COMPONENT]
Job: [USER NEED]
Inputs/props: [NAME, TYPE, DEFAULT, REQUIRED]
Events: [EVENT + PAYLOAD]
States: [ALL USER-VISIBLE STATES]
Responsive rule: [RULE]
Keyboard/touch: [RULE]
Content guidance: [GOOD/BAD EXAMPLE]
Test IDs: [ONLY IF NEEDED]
~~~

## Governance

1. Reuse a component when purpose and behavior match, not only appearance.
2. Add a variant when three real uses share the same contract.
3. Add a new component when a new user behavior cannot be represented safely.
4. Document breaking changes and migrate consumers together.
5. Review accessibility and visual regressions before release.

## Completion Criteria

- [ ] Tokens cover all current screens without unexplained one-off values.
- [ ] Every interactive component documents behavior and states.
- [ ] Error, empty, loading, disabled, selected, and focus states are designed.
- [ ] Design names match code and content terminology.
- [ ] The system supports content-first layouts, a clear visual hierarchy, predictable navigation, readable line lengths, and mobile breakpoints tested at 320 px and above.
- [ ] A small reference page demonstrates components with realistic sample content.