Cavekit Design System

# Design System: DESIGN.md for AI Agents

## Core Principle: DESIGN.md Describes WHAT It Looks Like, Not HOW to Build It

DESIGN.md is the visual equivalent of kits. It defines the project's visual language — colors, typography, spacing, components, responsive behavior — in a format AI agents can read and apply consistently. It is a **parallel constraint layer** that all Hunt phases consult.

| Document | Defines | Audience |
|----------|---------|----------|
| CLAUDE.md | How to build the project | Coding agents |
| Kits | What must be true (behavior) | All agents |
| **DESIGN.md** | **What it looks like (visual)** | **UI-building agents** |
| Plans | How to build it (tasks) | Builder agents |

### Why a Dedicated Design System Document?

Without DESIGN.md, visual decisions scatter across kits, plans, and code:
- Colors get hardcoded differently per component
- Typography choices vary between agents and sessions
- Spacing becomes inconsistent across the UI
- New components reinvent patterns that already exist

DESIGN.md centralizes these decisions. Every agent reads it before writing UI code.

---

## The 9-Section Stitch Format

DESIGN.md follows the [Google Stitch format](https://stitch.withgoogle.com/docs/design-md/overview/) — 9 sections that together define a complete visual language. Every DESIGN.md must contain all 9 sections.

### Section 1: Visual Theme & Atmosphere

The design philosophy, mood, and overall aesthetic. Use evocative, specific language — not generic terms like "clean and modern."

```markdown
## 1. Visual Theme & Atmosphere

This is a warm editorial experience built on natural materials. Think: a well-curated
bookshop with soft overhead lighting and carefully chosen display shelves. The density
is low — generous whitespace signals confidence and clarity. Every element earns its
place; nothing decorative exists without functional purpose.

**Key attributes:** Warm, unhurried, editorial, confident
**Density:** Low — generous whitespace, single-column focus
**Personality:** Thoughtful librarian, not flashy storefront
```

**What good looks like:** A new designer reading this section could sketch a rough layout without seeing any other section.

**Anti-pattern:** "Clean, modern, and professional" — this describes nothing specific.

### Section 2: Color Palette & Roles

Every color needs three things: a semantic name, a hex value, and a functional role.

```markdown
## 2. Color Palette & Roles

### Primary
| Name | Hex | Role |
|------|-----|------|
| Terracotta Brand | #c96442 | Primary CTA, active states, brand anchors |
| Terracotta Hover | #b85838 | Hover/pressed state for primary actions |

### Neutral
| Name | Hex | Role |
|------|-----|------|
| Near Black | #141413 | Primary text, headings |
| Olive Gray | #5e5d59 | Secondary text, captions |
| Parchment | #f5f4ed | Page background, default canvas |
| Ivory White | #ffffff | Card surfaces, overlays |

### Semantic
| Name | Hex | Role |
|------|-----|------|
| Success Green | #2d7d46 | Confirmation, success states |
| Warning Amber | #c27217 | Warnings, attention needed |
| Error Red | #c24132 | Errors, destructive actions |
| Info Blue | #3b6fb5 | Informational states, links |

### Dark Mode (if applicable)
| Light Name | Dark Equivalent | Hex |
|------------|----------------|-----|
| Parchment | Deep Charcoal | #1a1a1a |
| Near Black | Off White | #e8e8e8 |
```

**Rules:**
- Every hex value must be verified against the actual design or live site
- Every color must have a clear functional role — no orphan colors
- Name colors semantically (by role)