Design Vocabulary
A reverse dictionary for design and UI work. The goal is to go from a fuzzy description of a concept to the precise, agreed-upon word — and to know the difference between words that look interchangeable but aren't.
These are the terms from index.how/to/articulate: "the words designers use
when they know what they're looking at."
Source of truth
The authoritative list of terms and definitions is bundled next to this file:
Always pull the exact definition from there — it is the canonical content.
terms-index.md (also next to this file) is a flat list of every term name
grouped by category, for fast scanning when you don't yet know which word you're
looking for. If the index and vocabulary.md ever disagree, vocabulary.md
wins.
How to use it
Reverse lookup (the main job — "what's the word for…?")
- Read the user's loose description of the concept.
- Scan
terms-index.mdto find candidate terms, narrowing by category (the description usually points at one: spacing between letters → Typography, empty area on a page → Layout, a label attached to an element → Components). - Open
vocabulary.mdand read the matching definition(s). - Answer with: the term, its definition, and — critically — any contrasting term the definition names, so the user learns the boundary, not just the word.
Forward lookup ("what does X mean / am I using it right?")
Find the term in vocabulary.md, give the definition, and surface the nearest
confusable term so the user can confirm they mean the right one.
Disambiguation ("is this a badge or a tag?")
Pull both definitions and state the distinguishing rule plainly. Many
definitions in vocabulary.md are written specifically to draw these lines —
quote that line.
Encouraging precise usage
When reviewing copy, specs, PR descriptions, or commit messages, swap vague phrasing for the exact term where one exists ("the spacing between the letters" → "tracking"; "make the empty space bigger" → "more negative space"). Don't force jargon where plain language is clearer — precision is the goal, not density.
Near-synonyms worth disambiguating
These pairs are the ones people reach for the wrong half of. When a request touches one of them, name the distinction proactively:
- Kerning vs Tracking — kerning is between two specific characters; tracking is uniform across a run of text.
- Badge vs Tag — a badge is attached and informational; a tag is standalone, selectable, or removable.
- Tooltip vs Popover — a tooltip can't hold interactive content; a popover can.
- Opacity vs Visibility — opacity zero still occupies space and receives pointer events; visibility hidden keeps the space but removes interaction.
- Ease-in vs Ease-out — ease-out for things entering the screen; ease-in for things leaving.
- Modal vs Sheet vs Drawer — overlay that interrupts vs panel sliding from a side edge vs panel pulling up from the bottom.
- Voice vs Tone — voice is the constant personality; tone shifts with the moment.
- Chroma vs Saturation — chroma is the OKLCH, perceptually-accurate equivalent of saturation.
- WCAG vs APCA — WCAG is the established contrast standard; APCA is the newer model that accounts for font size and weight.
- Variables vs Tokens — variables are named values; tokens are design decisions both design tools and code can reference.
Categories at a glance
Use these to jump straight to the right slice of terms-index.md:
Examples
Reverse lookup
User: "What do you call the little gap between two specific letters that you nudge by hand?"
Read Typography in vocabulary.md. Answer:
That's kerning — the space between two specific characters, adjusted manually. Don't confuse it with tracking, which is letter-spacing applied uniformly across a whole word or block.
Disambiguation
User: "Should this little 'New' label be a badge or a tag?"
If it's attached to another element and just informational, it's a badge. But the moment it carries a word like "New" or a status, it starts behaving like a tag — standalone, and sometimes selectable or removable — and needs that treatment instead. The two aren't the same thing.
Precise usage in review
Spec says: "add some space so the lines aren't too cramped."
The term is leading — the vertical space between lines. Worth naming it explicitly so it's not confused with tracking (horizontal letter-spacing) or gap (space between flex/grid children).
Guidelines
- Quote definitions from
vocabulary.mdrather than paraphrasing — the wording is deliberate. - Always surface the contrasting term when one exists. The value of this vocabulary is in the boundaries between words, not the words alone.
- Match the user's locale and spelling in
vocabulary.md(it uses British spellings like "centre"). - Don't invent terms. If no listed term fits, say so and describe the concept plainly rather than coining jargon.
