01 · Foundation
Why Vocabulary Wins
Most of the cost in a client project is not code — it is the round trip between “make the box pop” and the thing you actually build. The fix is not more mockups. It is a shared set of nouns: card, variant, ghost button, chip, drawer, skeleton, token. Once both sides use them, feedback stops being taste and starts being an instruction.
The good news is that the argument is over. Every major UI kit — shadcn/ui, Radix, Material, Chakra, Ant Design, Bootstrap — converged on roughly the same forty components with roughly the same names. Learn that list and you can talk to a designer, a developer and a client in one language.
The kits, and what they call things
shadcn/ui + Radix
The current default in React. Components are copied into your repo, so the names in the docs are the names in your codebase: Button, Card, Dialog, Sheet, Popover, Command.
Material (MUI)
Google’s system. Its dialect leaks everywhere: FAB, snackbar, chip, app bar, elevation. If a client says “snackbar”, they have used a Material app.
Bootstrap
Twenty years of muscle memory. Modal, jumbotron, navbar, badge, pill, offcanvas, accordion — most non-designers learned the words here.
Chakra · Ant · Mantine
Same components, small dialect shifts: Ant says Drawer and Steps, Chakra says Stack and Skeleton, Mantine says Paper for what others call Surface.
Headless kits
Radix, Headless UI, Ark and React Aria ship behaviour and accessibility with no styling. They are where the anatomy names (trigger, content, item, indicator) come from.
Figma & friends
Designers say component, variant, instance, auto-layout and token — which map almost one to one onto the code. Use their words back at them.
the five altitudes of interface language — say which one you are talking about
Say which altitude you mean
Half of all misunderstandings are altitude errors. “The cards are too heavy” might mean the shadow token, the padding, the card component, or the whole grid pattern. Naming the layer — token, element, component, pattern, page — turns a vague reaction into a one-line ticket.
The rule for this whole page
Describe any piece of interface with three words: component · variant · state. “The destructive button in its loading state” needs no screenshot. “That red thing when it’s doing the spinny bit” needs a call.01 · Foundation
Anatomy, Variant, State
Every component in every kit is described the same way. Learn this frame once and you can spec a component you have never seen before.
Component
Which thing: Card, Dialog, Combobox
Variant
Which flavour: primary, ghost, destructive
Size
sm · md · lg · icon
State
hover, focus, active, disabled, loading
Slots
header, media, content, footer
Anatomy: the named parts
Anatomy is the list of parts a component is assembled from, and headless kits publish it for every one of them. A dropdown is a trigger, content, items, separators and an indicator. A field is a label, control, helper text and error message. Point at a part by name and the change is unambiguous.
State is where projects go wrong
A mockup usually shows one state out of six. Everything else — the hover, the keyboard focus ring, the pressed look, the disabled version, the spinner while it saves — gets invented later, under time pressure, by whoever is holding the ticket.
the six states to sign off on — hover and focus are different, and phones have no hover
Two states people forget, every time
Focus-visible — the ring keyboard users navigate by. Removing it is an accessibility failure, not a style choice. Disabled — always say why nearby; a dead button with no explanation reads as a bug.Tokens: the nouns underneath
/* Tokens are the shared nouns underneath every component.
Name them by ROLE, never by appearance. */
--color-primary: #00f0ff; /* not --color-cyan */
--color-destructive: #ff7a3d; /* not --color-red */
--color-muted-foreground: #93a7c0;
--radius-sm: 4px; --radius-md: 8px; --radius-lg: 14px;
--space-1: 4px; --space-2: 8px; --space-4: 16px; --space-6: 24px;
--shadow-sm / --shadow-md / --shadow-lg /* elevation */
/* Why role names win: "make the brand color warmer" touches one
token. "--color-cyan: orange" is how design systems die. */
Client-facing payoff
When a client says “everything feels a bit sharp and cold,” the honest answer is: that is two tokens — --radius and --color-primary. Ten minutes, one commit, every screen. That sentence is worth more than any mood board.02 · Actions
Badges, Pills & Chips
These three get used interchangeably and mean different things. The difference is not the shape — it is who put it there and whether it can be clicked.
live demo — badges, pills, chips, counters
Badge — read-only status, attached to something
LiveDraftFailedBetav2.4.0Pill = badge with a round end
Chip / tag — a value the user put there and can remove
ReactDesign systemsRemote
Filter chip — a chip that is also a control
Counter badge — a number bolted to another element
🔔12also: notification badge, count badge, unread indicator
Badge
The system put it there. Read-only. Status, version, category, count. Attached to something else, never standing alone.
Pill
A shape, not a job. Fully rounded ends. A pill badge, a pill button and a pill chip are all legitimate — say which.
Chip / tag
The user put it there, or can act on it. Removable filters, recipients, selected skills. If it has an ×, it is a chip.
The one-question test
Can the user remove or toggle it? Chip. Is it just reporting a fact? Badge. Is the question about the corner radius? Pill. Is it a number stuck to an icon? Counter badge.Colour is not a label
A green badge means nothing to a colour-blind user or a screenshot in greyscale. Always ship the word — Live, Failed, Draft — with the colour, never instead of it.03 · Containers
Cards & Surfaces
A card is a bordered container holding exactly one thing: one product, one report, one person. That constraint is the whole design. The moment a card holds two unrelated things, it stops being a card and becomes a panel with a border.
live demo — click a part name to light it up
16:9 media slot
Quarterly report
Updated 2 hours ago · 14 pages
Revenue up 12% quarter over quarter, driven by renewals in the enterprise tier.
Same six slots in shadcn/ui, MUI, Chakra, Ant and Bootstrap. Learn them once and your feedback lands in every codebase.
Card, panel, tile, surface — the family
Card
One entity, repeated in a grid or list. Usually clickable as a whole.
Panel
A region of a page — a settings block, a sidebar section. Not repeated, not clickable.
Tile
A small, mostly-square card in a dense grid: a stat, a shortcut, an app icon.
Surface / Paper
The generic raised background everything else sits on. MUI and Mantine use this name directly.
Stat card / KPI
A number, a label, and usually a trend. The building block of every dashboard.
List item / row
A card that gave up its border to fit in a dense list. Same slots, horizontal.
// A card is a composition, not a single tag. Every kit
// splits it into the same named slots.
<Card>
<CardHeader>
<CardTitle>Quarterly report</CardTitle>
<CardDescription>Updated 2 hours ago</CardDescription>
</CardHeader>
<CardContent>
<Chart data={revenue} />
</CardContent>
<CardFooter>
<Button variant="ghost">Dismiss</Button>
<Button>Open report</Button>
</CardFooter>
</Card>
// Naming the slots is what makes feedback cheap:
// "move the CTA from CardFooter into CardHeader" is a
// five-minute change. "make the card better" is a meeting.
The card trap
Cards look tidy in a mockup with three of them and fall apart with sixty. Before signing off, agree what happens when the title runs to three lines, when the image is missing, and when the description is empty. Those three answers are the difference between a demo and a product.One link per card
If the whole card is clickable, the buttons inside it are a trap for keyboard and screen-reader users. Either the card is a link and the footer is decoration, or the card is inert and the buttons do the work. Pick one.03 · Containers
Heroes & Sections
The hero is the first full-width block of a page — the one that has to answer “what is this and why should I care?” before anyone scrolls. Bootstrap called it a jumbotron; marketers call it the banner or the fold. Same six parts either way.
live demo — the six parts of a hero, in order
① eyebrow / kicker
② The headline makes one promise
③ The subhead earns the click by answering “so what?” in one sentence — plain language, no adjectives you cannot measure.
⑥ social proof — “trusted by 2,400 teams” · logo row · rating
⑦ (not shown) the hero media: screenshot, illustration or video, either beside the copy (split hero) or behind it (full-bleed hero).
The five hero layouts you will be asked for
Split hero
Copy on one side, product shot on the other. The safe default — it stacks cleanly on mobile.
Centered hero
Copy centered, media below. Best when the promise is one sentence and the CTA is obvious.
Full-bleed
Image or video behind the text, edge to edge. Needs a scrim or the copy becomes unreadable.
Product / app hero
A screenshot in a browser frame or device mockup. Sells software better than any illustration.
Hero slider
A carousel in the hero slot. Clients love it; measurement rarely does — slides two and three are seldom seen.
Announcement bar
The thin strip above the nav. Not part of the hero, though it is always discussed in the same breath.
The rest of the page has names too
Below the hero, marketing pages are made of a small, repeating set of sections: feature grid, logo cloud (social proof), testimonial, pricing table, FAQ accordion, and the closing CTA band. Naming them turns “can we add a bit about the customers?” into “add a testimonial section above the pricing table.”
About “above the fold”
There is no single fold — it moves with every screen size. What survives from the idea is real, though: the headline and primary CTA should be visible without scrolling on a laptop and a phone. Say that instead, and it becomes testable.04 · Inputs
Form Controls
A form is not a pile of boxes — it is a set of fields, and a field is five parts: label, control, placeholder, helper text and error message. Most form complaints are actually about the parts nobody drew.
live demo — a field is five parts, not one box
Enter a valid email — this is the error / validation message
switch / toggle — takes effect immediately, no Save button
segmented control — 2–4 exclusive options
label · control · placeholder · helper text · error message. Placeholder is never the label — it disappears the moment someone types.
Choosing the control
wrong tool
Switch behind a Save button
Dropdown for two options
Select with 400 countries
Free-text date field
Placeholder used as the label
right tool
Checkbox — switches apply instantly
Radio group or segmented control
Combobox — type to filter
Date picker with a typed fallback
Visible label above the control
The full inventory
Input · Textarea
One line versus many. Types matter: email, tel and number change the phone keyboard.
Select · Combobox
Pick one from a list; the combobox filters as you type. Multi-select returns chips.
Checkbox · Radio
Many independent answers versus exactly one from a set.
Switch · Slider
Instant on/off, and a value dragged along a track.
Date · Time picker
Calendar popover for one date; two for a range. Always allow typing.
File upload · Dropzone
Button plus drag target, with per-file progress and a remove action.
Validation, said precisely
“It should show an error” hides three decisions: when (on submit, on blur, as they type), where (under the field, in a summary at the top, or both) and what the message says. Answer all three in the brief and forms stop being a source of rework.04 · Inputs
Sliders vs Carousels
“Slider” is the single most expensive ambiguous word in client work. To a developer it is a range input. To a marketer it is a rotating set of banners. They share no code, no anatomy and no purpose.
live demo — the two things people mean by “slider”
1 · Slider (range input) — pick a value
$0$250$500
max price: $120
parts: track · filled track · thumb (handle) · ticks · value readout. Two thumbs makes it a range slider; discrete stops make it a stepped slider.
2 · Carousel — page through content
also called a slideshow, gallery or (in marketing) a hero slider. Its parts are slides · track · dots (pagination) · prev/next arrows.
slider (range input)
Picks a value — price, volume, zoom
Parts: track, thumb, ticks, readout
Always show the current value as text
Needs keyboard arrows to be usable
carousel (slideshow)
Pages through content — banners, photos
Parts: slides, track, dots, arrows
Never auto-rotate without a pause control
Slide 1 gets the attention; plan for that
Ask one question
“Is the user choosing a number, or looking through pictures?” Numbers → slider. Pictures → carousel. It takes four seconds and saves a sprint.Before you build the carousel
Auto-rotating carousels test badly almost everywhere: people rarely reach slide two, and moving content is hostile to anyone reading slowly. If the client wants one anyway, that is their call — build it with visible dots, arrows, pause on hover, and put the most important message on slide one.05 · Overlays
Modals, Drawers & Popovers
Overlays are ranked by how rude they are. Every step up the ladder takes more attention from the user, so the only honest reason to climb it is that the previous step genuinely cannot carry the content.
Tooltip
A label. No controls, ever.
Popover
Small content, anchored
Menu
A list of actions
Drawer
A task, from an edge
Modal
Blocks everything
live demo — four overlays, four different levels of interruption
tooltip — a label, never a place to put buttons
interruption ladder: tooltip → popover → dropdown menu → drawer → modal. Every step up costs the user more attention, so step up only when you must.
Same anatomy, different names
Every overlay is a trigger, a content panel, usually a backdrop (also called the scrim), and a close affordance. Only the entrance and the level of blocking change.
// Modal / dialog: trigger, backdrop (overlay), content, close.
<Dialog>
<DialogTrigger asChild>
<Button variant="destructive">Delete project</Button>
</DialogTrigger>
<DialogContent> {/* the panel itself */}
<DialogHeader>
<DialogTitle>Delete this project?</DialogTitle>
<DialogDescription>
This removes 14 files. It cannot be undone.
</DialogDescription>
</DialogHeader>
<DialogFooter>
<DialogClose asChild><Button variant="ghost">Cancel</Button></DialogClose>
<Button variant="destructive">Delete</Button>
</DialogFooter>
</DialogContent>
</Dialog>
// Same anatomy, different names per kit:
// shadcn/Radix Dialog · Sheet · Popover
// MUI Dialog · Drawer · Popover
// Bootstrap Modal · Offcanvas· Popover
Tooltip
Hover or focus, text only. Never the sole home for information — phones have no hover.
Popover
Click to open, anchored to the trigger, can hold inputs and buttons.
Command palette
The ⌘K overlay: search everything, run anything. shadcn calls it Command; power users expect it now.
Modal debt
Modals cannot be linked to, cannot be printed, break the back button on mobile, and stack badly. Before adding one, ask whether the content can live on the page or on a route of its own. A confirmation before deleting things is a good modal; a five-step form is not.05 · Overlays
Feedback & Status
Feedback components answer three questions: is something happening, did it work, and what should I do now. Clients rarely ask for them by name, which is exactly why they should be in the brief.
live demo — telling the user what just happened
determinate progress bar — 45%. If you cannot measure it, use an indeterminate spinner instead
⚠
Alert / banner — stays on the page, tied to a region. A toast floats over the page and leaves on its own. Use a banner for conditions, a toast for events.
Choosing the messenger
Toast / snackbar
An event just happened. Floats, auto-dismisses, often carries an Undo. Never put critical information here alone.
Alert / banner
A condition is true. Stays in the page until it is no longer true — expired card, degraded service.
Skeleton
Content is coming and we know its shape. Reserves the space, so nothing jumps when data lands.
Spinner
Something is happening and we cannot say how long. Fine for a button, weak for a whole page.
Progress bar
We know the percentage. Uploads, imports, multi-step jobs. Also called a meter.
Empty state
No data yet. Explain why and offer the action that fixes it — this is the first screen every new user sees.
The four screens of every feature
Empty, loading, error, and full. A brief that only describes the full state has left three quarters of the work undefined. Ask for all four by name and estimates stop being fiction.07 · Shared Language
Layout & Spacing Words
Most feedback in a review is really about layout, expressed as feeling: cramped, busy, empty, heavy. Each of those maps onto a specific, adjustable thing.
Container
The max-width wrapper that centers content. “Use the full width” means widen or remove it.
Grid & columns
How many things sit side by side, and how that number changes on smaller screens.
Gutter / gap
Space between items. Padding is space inside one; margin is space around it.
Spacing scale
The fixed set of allowed gaps (4, 8, 12, 16, 24, 32…). “A bit more room” means one step up the scale.
Radius & elevation
Roundness and shadow depth. “Softer” is radius; “floatier” is elevation.
Breakpoint
The width where the layout changes. “It breaks on my iPad” is a breakpoint conversation.
Words worth agreeing on before the first review
feeling
It feels cramped
It feels empty
It looks heavy
It doesn’t line up
Too much scrolling
adjustment
Increase padding + gap one step
Narrow the container, or add a section
Reduce elevation, borders, and font weight
Fix alignment to the grid columns
Denser rows, or paginate the list
Say it in tokens
“Bump the card padding from space-4 to space-6 and drop the shadow to elevation-1” is a fifteen-second change anyone on the team can make. The same request as a feeling is a two-day exploration.07 · Shared Language
Client Translator
None of this means correcting anybody. It means hearing the plain-English version, repeating it back in kit vocabulary, and confirming — once — that you both mean the same thing.
Components
what they say
That popup box
The slider at the top
The little coloured tag
A box with a picture and a button
The thing that slides in from the side
The bit that pops up when you hover
The dropdown
what you write
Modal dialog (or popover, if anchored)
Hero carousel
Status badge
Card with media, title and footer CTA
Drawer / sheet
Tooltip (label only) or hovercard
Select, combobox, or dropdown menu
Behaviour
what they say
Grey it out
Show a spinny thing
Make it pop
It should say something when it saves
Make it responsive
There’s nothing there at first
what you write
Disabled state + reason text
Loading state: skeleton or spinner
Promote to primary variant
Success toast with Undo
Define behaviour at each breakpoint
Empty state with a primary action
Turn the conversation into a brief
The pay-off is that a spec written in this vocabulary is short enough that nobody skips reading it, and precise enough that nobody has to guess.
# Component request — the shape that never needs a follow-up
Component: Card (product tile)
Variants: default | featured | sold-out
Sizes: sm (sidebar) | md (grid)
States: default, hover, focus-visible, loading (skeleton), empty
Slots: media (16:9), title, description (2 lines max), price badge,
footer with primary + ghost button
Content: title truncates at 2 lines; description hidden below 400px
Behaviour: whole card is the link; footer buttons stop propagation
A11y: one link per card, alt text required on media
# Fifteen lines. No meeting.
The three-word habit
Repeat every request back as component · variant · state. “So: the pricing card, featured variant, and we need its empty state for when a plan sells out.” If that sentence is wrong, you find out in the meeting instead of in the demo.07 · Shared Language
The Glossary
Every term on this page in one searchable list, each with the names other kits use for it. Search by what the client said — popup, rounded, banner, greyed out — and it will find the word your team uses.
live — type what the client said, get the word the team uses
56 of 56 terms
Accordionaka disclosure, expander, collapsible
A stack of headers that expand in place to reveal their content.
Affordanceaka signifier
The visual hint that something can be used — the shadow that says a button is pressable.
Alertaka banner, inline message, callout
A message pinned inside the page, tied to a region. It stays until the condition clears.
Avataraka profile picture, user chip
A small round or square image standing in for a person or team; a stack of them is an avatar group.
Backdropaka scrim, overlay, dimmer
The dark translucent layer behind a modal that mutes the page underneath.
Badgeaka tag, label, status pill
A small read-only marker attached to something else — status, version, category.
Breadcrumbsaka trail
A path showing where the current page sits in the hierarchy. Not browser history.
Buttonaka CTA, action
Performs an action. If it navigates somewhere, it is a link — style it however you like, but the code should say link.
Button groupaka segmented control, toggle group
Two to four related buttons joined into one control; usually exactly one is selected.
Cardaka tile, panel, surface
A bordered container holding one thing — one product, one report, one person.
Carouselaka slider, slideshow, gallery
Content paged sideways through one viewport. In marketing briefs this is what “slider” usually means.
Checkboxaka tick box
Independent yes/no answers — any number may be checked.
Chipaka tag, token, pill
A compact value the user added, chose, or can remove — filters, recipients, skills.
Comboboxaka autocomplete, typeahead, searchable select
A text field that filters a list as you type. A plain select does not filter.
Command paletteaka command menu, spotlight, ⌘K
A search-anything overlay that runs commands and jumps to pages.
Containeraka wrapper, shell
The element that caps content width and centers it. “Make it wider” usually means change the container.
CTAaka call to action
The one action a screen is asking for. One primary CTA per view.
Dialogaka modal, popup
A window over the page that takes focus. Modal ones block everything behind them.
Draweraka sheet, off-canvas, side panel
A panel that slides in from an edge and holds a task — filters, details, settings.
Dropdown menuaka menu, context menu, kebab menu
A list of actions anchored to a trigger. Actions, not form values — that is a select.
Elevationaka depth, shadow level, z-level
How far a surface floats above the page, expressed as a shadow step.
Empty stateaka zero state, blank slate
What a list shows before it has data — an explanation plus the action that fills it.
Eyebrowaka kicker, overline, pretitle
The small line of text above a headline that gives it context.
Fieldaka form control, form group
Label + control + helper text + error message, treated as one unit.
FABaka floating action button
A round button floating over the content for the one dominant action on a screen.
Footeraka site footer, card footer
The bottom band of a page or component. Card footers hold actions; page footers hold links and legal text.
Ghost buttonaka text button, tertiary
A button with no fill or border until you hover it. The quietest real button.
Gutteraka gap, spacing
The space between columns or grid items.
Heroaka above the fold, banner, jumbotron
The first full-width block of a page: eyebrow, headline, subhead, CTA, media, proof.
Icon buttonaka square button, action icon
A button whose entire label is an icon. It still needs an accessible name.
Inputaka text field, text box
A single-line text control. Multi-line is a textarea.
Layout shiftaka jank, CLS
Content jumping as the page loads. Reserving space with skeletons prevents it.
Modalaka dialog, lightbox, popup
A dialog that blocks the page until it is answered or dismissed.
Navbaraka top bar, app bar, header
The persistent bar across the top holding brand, nav and account.
Paginationaka pager, page numbers
Numbered pages through a long list; the alternative to infinite scroll.
Pillaka rounded badge, capsule
Any small element with fully rounded ends. Pill describes the shape, not the job.
Placeholderaka ghost text, hint text
Sample text inside an empty input. Never use it as the label — it vanishes on typing.
Popoveraka flyout, hovercard
A small panel anchored to a trigger that can hold real content and controls.
Primary / secondaryaka variant, emphasis, hierarchy
How loud an action is. Primary is the recommended one; there should be only one visible at a time.
Progress baraka meter, loading bar
Shows how much of a known task is done. Unknown duration means a spinner instead.
Radio groupaka option buttons
Exactly one choice from a visible set. More than about five options wants a select.
Radiusaka corner radius, rounding
How rounded corners are. “Softer” almost always means raise the radius token.
Selectaka dropdown, picker
Choose one value from a list. Not a menu — menus run actions.
Skeletonaka shimmer, placeholder loader
Grey blocks in the shape of the content, shown while it loads.
Slideraka range input, range control
Drag a handle along a track to pick a number. Two handles makes it a range slider.
Snackbaraka toast
Material Design’s name for a toast — a short message that appears and leaves on its own.
Spinneraka loader, throbber, activity indicator
Indeterminate loading. Use when you cannot say how long it will take.
Stepperaka wizard, progress steps
A multi-step flow with a visible map of where you are. (Also: a +/− number input.)
Switchaka toggle
On/off that applies immediately. If it needs a Save button, use a checkbox.
Tabsaka tab bar, segmented pages
Peer sections where exactly one panel is visible at a time.
Toastaka snackbar, notification
A brief message floating over the page after an event, then it disappears.
Tokenaka design token, variable
A named design value — colour, spacing, radius. Change the token, change every component.
Tooltipaka hint, title text
A label on hover or focus. No buttons, no links, never the only place information lives.
Truncationaka ellipsis, line clamp
Cutting text off with “…” at one or more lines so cards stay the same height.
Variantaka style, kind, appearance
A named version of one component — primary, outline, destructive. Ask for a variant by name.
Whitespaceaka negative space, breathing room
Deliberate empty space. “Too cramped” means increase the spacing scale, not shrink the text.
07 · Shared Language
Spec Checklist
Run this before any component is estimated or built. Each unticked line is a decision somebody will otherwise make silently, at the worst possible moment.
component brief — 0/12 answered
Name the component with the kit’s word (Card, Dialog, Combobox) — not “that box”
List the variants by name: primary / secondary / destructive / outline / ghost
List the sizes and where each is used
Cover all six states: default, hover, focus-visible, active, disabled, loading
Define the empty state and the error state — every list and every form has both
Name the slots you are filling (header, media, content, footer)
Say what happens to long content: truncate, wrap, or clamp at N lines
Say what happens on a narrow screen — which parts drop, stack, or collapse
Point at spacing, radius and colour as tokens, not one-off pixel values
Give every icon-only control an accessible name
Confirm one primary action per screen — demote the rest to secondary or ghost
Agree on the interruption level: inline, tooltip, popover, drawer, or modal
If you only take three things
Name the component, name the variant, and demand all six states. Those three habits remove most of the rework in front-end projects — and they cost nothing but the vocabulary on this page.