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).