Design System

---
name: design-system
description: Anchor every frontend visual decision to DESIGN.md and fundamental design principles. Use when starting a UI project, writing or editing UI code, changing an existing design, or reviewing a frontend for design adherence.
argument-hint: How should I apply/create the design system?
license: MIT
---

# Design system

Every visual decision anchors to `DESIGN.md` at the project root — the single source of truth, so each value in the code traces back to a token. See [the guide](DESIGN_GUIDE.md) for its structure.

Pick the branch:
- **Starting a project, or no `DESIGN.md` exists**: [initialize the system](INIT.md).
- **Writing or editing UI code**: build against `DESIGN.md` tokens and the [design principles](#principles).
- **Changing an existing design**: edit `DESIGN.md` per [the guide](DESIGN_GUIDE.md) and [design principles](#principles), then propagate the change through the code via tokens.
- **Reviewing a frontend**: [review the code](REVIEW.md) against `DESIGN.md` and the [design principles](#principles).

## Principles

### Color

Specifications are given in light mode — invert for dark.

Reason in a tonal palette where 0 is pure black and 1000 is pure white. Prefer a perceptually uniform colorspace like OKLCH.

**Dark mode.** Design it alongside light mode. Space darker neutrals 2–3x farther apart, dim text by 100–200, brighten borders by ~100, and cut non-neutral saturation by ~100 (colors read more saturated in dark).

**Neutrals** — 65–90% of a page:
- Surfaces: 3–5 shades (background, surface, overlay) separated by 10–20; reserve pure white for text/search fields. Ghost buttons use the background shade, rising in shade with importance.
- Borders: soft contrast against background (~150).
- Text: subtext ~600, body 780–850, headings 850–900.
- Drop shadows: subtle (100–200), high blur, light mode only.

**Theming** — per neutral in OKLCH, drop lightness 0.03, raise chroma 0.02, then set hue to the theme.

**Brand** — one color as a tonal palette of 5–11 shades (50–950): main at 500/600, accent buttons 100 above main, link text 100 below.

**Semantics** — fix lightness and chroma in OKLCH, vary hue: info (gray), success (green–teal), warning (yellow–orange), error (red).

### Typography

| Font families | Combinations |
|---|---|
| 1 | Sans-serif |
| 2 | Two sans-serifs; display heading + sans-serif body; sans-serif + serif |

Add a monospace family for machine values or code — default JetBrains Mono.

Size the scale by multiplying the smallest font by `sqrt(golden ratio)` recursively. Line height: body 150%, headers 110–130%. Build hierarchy from 4–7 weight+size+color combos.

Use icons where they carry established, cross-software meaning.

### Animation and components

Give every interaction (hover, click) and event (popover appear/dismiss) a reaction. Reach for sleek micro-animations:
- Slide-in transform on a button's text/icon on hover or click
- Confetti on success (sparingly)
- Semantic toast notifications
- Tooltips on textless buttons
- Empty and loading states

## Enforcement

Centralize control through inheritance, global styles, and token variables, so one edit propagates everywhere. In Tailwind, override `@theme` and use `@layer`.

Verify `DESIGN.md` formatting via `npx @google/design.md lint DESIGN.md`.