# DESIGN.md — [PROJECT NAME]

> Agent-readable visual source of truth. Replace every [bracketed item] before use.

## 1. Product and user
- Product: [one sentence]
- Primary user: [specific person]
- Main action: [the one action the interface should emphasise]
- Desired feeling: [three words, for example: calm, capable, precise]

## 2. Design direction
- Visual direction: [editorial / technical / warm SaaS / other]
- Reference principles: [what to borrow, not copy]
- Avoid: generic gradients, arbitrary colours, mixed corner radii, equal visual weight

## 3. Colour roles
| Token | Value | Use |
|---|---:|---|
| --color-base | [#HEX] | 60%: page backgrounds |
| --color-structure | [#HEX] | 30%: text and dark sections |
| --color-accent | [#HEX] | 10%: primary actions only |
| --color-muted | [#HEX] | Secondary text |
| --color-panel | [#HEX] | Cards and raised surfaces |

Rules:
- Never invent an unlisted colour.
- Use the accent only for actions, links and active states.
- Keep normal text contrast at 4.5:1 or higher.

## 4. Typography
- Display font: [FONT, weights]
- Body font: [FONT, weights]
- Mono font: [FONT]
- H1: [size / line-height / weight]
- H2: [size / line-height / weight]
- Body: [size / line-height / weight]
- Label: [size / tracking / case]

## 5. Layout and spacing
- Container: [max width]
- Spacing unit: [4px or 8px]
- Section spacing: [desktop / mobile]
- Hero structure: [split / editorial rail / other]
- Breakpoints: [values]
- Do not centre every section by default.

## 6. Components
### Buttons
- Primary: [background, text, radius, padding, hover, focus]
- Secondary: [border, text, hover, focus]

### Cards
- Surface: [token]
- Border: [value]
- Radius: [value]
- Shadow: [one approved shadow or none]

### Forms
- Label, input, focus, error and disabled states: [rules]

## 7. Motion
- Timing: [fast / standard / slow]
- Easing: [approved easing]
- Use motion for: hierarchy and feedback
- Never animate: large blocks without purpose
- Respect prefers-reduced-motion.

## 8. Accessibility
- Keyboard focus must always be visible.
- Interactive targets must be at least 44 × 44px on touch screens.
- Do not communicate state through colour alone.
- Test body text, CTA labels and form states for WCAG AA contrast.

## 9. Do / do not
Do:
- Reuse these tokens and component rules.
- Preserve clear hierarchy and asymmetric balance.
- Check the mobile layout at 375px.

Do not:
- Add colours, fonts, gradients or shadows not defined here.
- Create three identical cards simply to fill space.
- replace real copy with lorem ipsum.
- Change product logic while refining the visual layer.

## Agent execution rule
Before generating or editing any interface, read this DESIGN.md. Reuse its tokens and components. If a visual decision is not defined, ask before inventing one. After every UI change, audit the result against this file.

---
Starter template from Pixel Perfect: https://pixel-perfect-system.netlify.app/design-md-generator.html