Design guide
The rules this site actually follows. Every value matches a token in assets/style.css, and the examples below are built from those exact tokens.
Principles
Cards where you choose, rules where you read
Areas where you pick something (categories, deep dives) are cards, so they look pressable. Areas you read straight through (the term entries) use no cards at all — just hairlines and space. Put all 211 terms in boxes and the reading rhythm breaks on every one.
Lines, not surfaces
Structure comes from 1px rules, not from stacked shadows. Shadow is reserved for things that genuinely float — modals, dropdowns, toasts.
Hierarchy through size contrast
Make the important thing clearly large and the rest decidedly small. Set everything at similar sizes and there is no way to tell what to read first.
Spend colour sparingly
Paper, ink, and one accent. The rest — warning, error, success — appear only when the content actually carries that meaning. Never as decoration.
Nothing outside the scale
Eight type sizes, eight spacing steps, five radii. If 13px seems necessary, choose between 12px and 13.5px.
Type scale
Eight steps. No sizes outside this scale.
Line height
| Token | Value | Used for |
|---|---|---|
--lh-tight | 1.25 | Headings |
--lh-snug | 1.5 | Short sentences · labels |
--lh-body | 1.8 | Body text |
--lh-loose | 1.9 | Lead paragraphs |
Spacing
Built on 8pt. The 4 step is for fine adjustments.
--sp-14px
--sp-28px
--sp-312px
--sp-416px
--sp-524px
--sp-632px
--sp-748px
--sp-864px
Colour
Switch the theme and these swatches change with it — try the control at the top.
Paper
--bgPage background
--bg-elevCards · raised surfaces
--bg-sunkenRecessed surfaces, like a demo stage
--borderDefault hairline
--border-strongInputs · emphasised borders
Ink
--textHeadings · emphasised body
--text-subBody text
--text-dimSupporting · captions (holds 4.5:1)
Accent
--accentPrimary buttons · active state
--accent-textLinks · accent text
--accent-softSoft highlight background
Meaning
--successSuccess · request blocks
--warnCaution · easy-to-get-wrong notes
--dangerErrors · irreversible actions
Corner radius
--r-sm3pxBadges · chips · small labels
--radius-sm4pxButtons · inputs
--r-md6pxCards · boxes
--r-lg10pxLarge cards · bottom sheets
--r-full999pxFully round things
Components
The parts this site is built from. All of them use only the tokens above.
Buttons
One primary button per screen. Destructive actions are red.
Badge · Chip · Tag
A badge only displays, a chip can be pressed, a tag marks a category.
Six states
Define all six every time you build a component.
Messages
Never colour alone — always an icon and words as well.
Inputs
When in doubt
Card, or just a rule between?
Choosing → card (the category list, the deep-dive list). Reading → hairline (term entries). Showing a screen → box (demos — the border itself says "the example starts here").
When is a shadow allowed?
Only on things that genuinely float — modals, dropdowns, toasts, popovers. Never on cards or sections; use a hairline there.
How many buttons?
One filled button (primary) per screen. Everything else is outlined (secondary) or text only (ghost). Destructive actions are red.
When is a badge right?
When it only displays a count or a state. The moment it can be pressed it is a chip, not a badge.
How round should corners be?
Smaller things, less round — badges 3px, buttons 4px, cards 6px, large cards 10px. A box inside a box gets one step smaller on the inside.
What about icons?
No emoji. They render differently per device and OS and fight the brand. Use the line set in data/icons.js, and if something is missing, draw it to the same spec (24×24 grid, 1.75 stroke, currentColor). Real images or illustrations are produced separately.
How far do states go?
Default · hover · focus · pressed · selected · disabled. Never remove the focus ring (use :focus-visible so it shows for keyboard only).
Breakpoints
| Range | Width | Rule |
|---|---|---|
| Mobile | up to 767px | One column · condensed header menu · 15px side margins |
| Tablet | 768 – 1023px | Two columns |
| Desktop | 1024px and up | Two to three columns · body caps at 940px |
Accessibility baseline
- Body contrast at least 4.5:1, large text at least 3:1 (WCAG AA)
- Never carry meaning by colour alone — pair it with an icon or words
- Keep the focus ring; Tab order matches visual order
- Touch targets at least 44×44px
- Modals close on Esc and keep focus trapped inside