# Design

> Build UI that matches a brand, reads well on a phone, and works in both light and dark — using tokens, a real type hierarchy, and layout that never scrolls sideways.

Source: https://gaitro.com/skills/design

Good product UI is consistent and legible before it's clever. Work from tokens and a few rules and most of it falls out.

## Define colours as tokens, in both themes

Put every colour on `:root` as a named token (`--bg`, `--ink`, `--accent`, …). Redefine the tokens for dark mode under both a `prefers-color-scheme: dark` block and an explicit `[data-theme="dark"]` block, so the OS setting and a manual toggle both work. Give `body` an explicit background token — never leave it transparent. A colour defined only inside a dark block is the classic unreadable bug.

## Set a type hierarchy and keep to it

Pick a display face and a body face, a small scale (say 5 sizes), and stick to them. Headings get `text-wrap: balance`; body text gets comfortable line length (~65 characters) and spacing; uppercase labels get a little letter-spacing. Use `font-variant-numeric: tabular-nums` wherever digits line up in columns.

## Make it work at phone width

- No horizontal page scroll, ever. One side gutter of at least 16px, set once.
- Grids and flex rows wrap or stack to a single column when narrow. Give any child holding text, code, or a table `min-width: 0` so it shrinks instead of pushing the page wider.
- Only tables, code blocks, and diagrams may scroll — each inside its own `overflow-x: auto` box.
- Test at ~390px, not just on a wide screen.

## Keep repeated things consistent

Cards in a row share edges, padding, and radius. Use border/fill/shadow by role — to set off the one element that needs it — not on every block, or the hierarchy flattens.

## Respect the basics

Visible keyboard focus, `prefers-reduced-motion`, and real content (never lorem ipsum) while you design. Check the result in both themes before you call it done.