Design system notes

One source, always

Every color, font, radius, and shadow lives in DESIGN.md at the root. The same tokens are mirrored in app/styles/app.css under @theme { }. Components reference tokens through CSS variables (var(--color-foreground), var(--font-display)), never hex codes inline.

Why this matters

When everything points at one source, redesigns become small. Want a different brand color? Change one value in DESIGN.md, sync app.css, hot reload. Every component picks it up. No find-and-replace across 40 files.

Two-canvas rhythm

The visual language uses two main surfaces:

• A clean white content canvas for body text and dense reading
• A deep brand canvas for hero, footer, and CTA bands

Cream shows up sparingly, as an editorial third tier between the two.

Type pairing

Headings sit in a serif (Playfair Display by default). Body and UI sit in a clean sans (PT Sans). Mixing them is load-bearing. Keep that split, change the actual fonts if you need to.

When to deviate

Do not. The point of a system is consistency. If you find yourself reaching for a value that is not in the system, the answer is almost always either "use the closest token" or "add the new token to DESIGN.md and app.css once, then use it".