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 for its structure.

Pick the branch:

• Starting a project, or no DESIGN.md exists: initialize the system.
• Writing or editing UI code: build against DESIGN.md tokens and the design principles.
• Changing an existing design: edit DESIGN.md per the guide and design principles, then propagate the change through the code via tokens.
• Reviewing a frontend: review the code against DESIGN.md and the design 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.