# 6 · Memory: DESIGN.md

You don't remember the last session. The next agent, or you tomorrow, will
start from zero and make slightly different choices. Over ten sessions,
"slightly different" becomes a product that looks like ten people built it.

A designer carries the system in their head. You carry it in a file.

---

## Rules

1. **At the start:** look for `DESIGN.md` at the project root. If it exists,
   read it before anything else and follow it.
2. **At the end:** create it if it doesn't exist; update it if you made a
   decision that changes the system.
3. **Keep it short:** under about 150 lines. It's a map of the system, not a
   copy of it. Point to the token file; don't duplicate every value.
4. **Write the why:** a decision without a reason gets undone by the next
   agent that disagrees with it.

**Agent trap:** writing `DESIGN.md` once and never updating it. A stale
memory is worse than none, because it is trusted.

---

## Template

Copy this into `DESIGN.md` and fill it in.

```markdown
# DESIGN.md

> Read this before changing any UI. Update it when you change the system.
> Last updated: <date> by <agent/human>

## Product
- What it is: <one sentence>
- Who uses it: <people + situation>
- Feel: <taste words> → <concrete decisions>

## Where the system lives
- Tokens: <path/to/tokens.css>
- Components: <path/to/components/>
- Icons: <library or folder>

## Tokens (summary)
- Colour: one accent (<name>), neutrals <ramp>, states: danger / success / warning
- Space scale: 4 8 12 16 24 32 48 64
- Type: <family>; sizes 12 14 16 20 24 32 48; weights 400 600
- Radius: <value>. Shadows: <levels>. Motion: <durations, easing>

## Components
| Component | Variants | Notes |
|-----------|----------|-------|
| Button | primary, secondary, ghost, danger | One primary per view |

## Voice
- <e.g. Plain, warm, brief. Buttons are verbs. No exclamation marks.>

## Decisions
| Date | Decision | Why |
|------|----------|-----|
| <date> | <e.g. No shadows; borders only> | <e.g. Calm feel; works in dark mode> |

## Don't
- <things that were tried and rejected, so no one tries them again>
```