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.