| 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 for its structure.
Pick the branch:
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.
