# Design System — `{{PROJECT_NAME}}`

> Single source of truth for visual tokens, component patterns, and UI conventions. Agents writing UI code (frontend skills, ui-phase, frontend-design, clone-website) MUST read this before producing components or styles. UI-SPEC.md files for individual phases cite this as their root reference.

**Last updated:** {{INIT_DATE}}
**Source of truth:** this file + the canonical token files it points to

---

## Tokens

Document the canonical token names — never restate hex / rem values inline in code. Components should reference tokens.

### Color

| Token | Purpose | Source file |
|---|---|---|
| `--ds-bg` | Page background | (e.g. `app/globals.css`) |
| `--ds-bg-raised` | Card / surface background | |
| `--ds-border` | Default border | |
| `--ds-text` | Body text | |
| `--ds-text-muted` | Secondary text | |
| `--ds-accent` | Primary accent / CTA | |
| `--ds-hover` | Hover background | |

### Typography

| Token | Purpose |
|---|---|
| `--ds-font-display` | Headings |
| `--ds-font-body` | Body text |
| `--ds-font-mono` | Code / inline mono |

### Spacing scale

Document the discrete spacing values used (e.g. `4 / 8 / 12 / 16 / 24 / 32` rem-relative) and what each maps to in Tailwind / CSS variables.

### Radius scale

| Token | Tailwind | Use for |
|---|---|---|
| `--ds-radius-sm` | `rounded` | Inputs, small chips |
| `--ds-radius-md` | `rounded-xl` | Form inputs, secondary cards |
| `--ds-radius-lg` | `rounded-2xl` | Primary surfaces, modals |
| `--ds-radius-full` | `rounded-full` | Avatars, pills |

---

## Canonical component patterns

The exact class lists / token compositions that define the project's visual identity. New components MUST match these patterns.

### Card / surface shell

```html
<div class="bg-ds-raised rounded-2xl border border-ds-border/70 p-6">
  ...
</div>
```

### Form input

```html
<input class="rounded-xl bg-ds-hover px-3 py-2 focus:ring-1 focus:ring-ds-accent/20" />
```

### Primary button

```html
<button class="rounded-xl bg-ds-accent text-white px-4 py-2 hover:opacity-90">
  ...
</button>
```

(Add: secondary button, link, badge, modal, dropdown, table row, etc. — whatever the project actually uses.)

---

## Conventions

Hard rules. Violating these = anti-pattern, must be flagged in code review.

- **Reach for `bg-ds-raised` not `bg-white`** — direct color literals lose dark-mode and theming
- **Never use `style={{}}`** — Tailwind classes or design tokens only
- **Never use `React.FC` / `React.FunctionComponent`** — function declarations only
- **Borders use `/70` or `/60` opacity** — solid `border-ds-border` is reserved for emphasis
- **Spacing increments only** — no `px-[7]` or arbitrary values; if a value isn't on the scale, the scale needs to expand or the component is wrong
- **Radius hierarchy**: outer card 2xl → inner element xl → micro element `rounded`. Never invert.

---

## RTL / multilingual

(Skip if not applicable.)

- Direction-aware spacing: use `ms-` / `me-` (Tailwind logical) not `ml-` / `mr-`
- Mirror icons that have directional intent (chevrons, arrows) for RTL
- Typography: separate Arabic + Latin font stacks via `--ds-font-display-ar` / `--ds-font-display-lat`

---

## Inspiration / source-of-language

Where did this visual language come from? Link the originating commits, PRs, or external references so future agents understand the lineage.

- **Recent canonical commits**: (e.g. `08e2e03d`, `bcc86535` — "Attio-standard redesigns of calling tabs")
- **External references**: (e.g. linear.app, attio.com, your own brand guidelines)

When extending the system, mirror the lineage rather than inventing.

---

## How agents use this file

1. **Frontend / UI skills** read this first before producing any component code
2. **`/rcode-ui-phase`** cites this file in the produced UI-SPEC.md as `read_first`
3. **`rcode-frontend-design`** ports design directions FROM this — never independently
4. **Code review skills** flag any new code that introduces hex values, raw colors, or pattern violations
5. **`/rcode-clone-website`** uses this to translate cloned styles into project-native tokens — never preserves source-site classes verbatim

---

## Maintenance

- Update when a new canonical pattern lands (e.g. a redesign sprint that shifts radius scale)
- Reference the commit that established each pattern in the "Inspiration" section
- Distillate version is regenerated by `/rcode-memory-distill`
- Audit via `/rcode-memory-audit` at every milestone close
