The API of
the system.
Names are the public surface of every design system. Get them right once and a decade of consumers reference the same tokens without ambiguity. Get them wrong and every rebrand is a six-month grep-and-replace.
01 — Why naming
A name is a contract.
Every name in a design system — token, component, prop, CSS class — is a promise to the consumers who use it. Rename it and every consumer breaks. Get the name wrong and you live with the lie until a major version lets you fix it.
Two rules cover most of the territory: name by purpose, not appearance; and pick a grammar and stick with it. The rest is consistency — same shape, same case, same ordering, everywhere in the system.
02 — Token grammar
Four parts. One direction.
Token names read left-to-right from general to specific: category, property, variant, optional state. Same grammar across color, space, type, motion. Once the team internalizes the shape, every new token reads itself.
Token grammar
01
Category
colorWhat kind of token — color, space, type, radius, shadow, motion.
02
Property
backgroundWhat it does — background, foreground, border, ring.
03
Variant
brandWhich semantic role — brand, neutral, success, destructive.
04
Scale / state
hoverOptional · the step or interactive state — 500, hover, disabled.
03 — Component rules
Four rules that prevent the rename.
Components live longer than the people who name them. These four rules — noun not adjective, generic before specific, pascal case, slot matches part — cover the vast majority of the naming mistakes that haunt mature systems.
01
Noun, not adjective
Good
Card · Modal · ButtonBad
Awesome · Big · PrettyComponents describe what they are, not how they look. Visual variation belongs in props, not in the name.
02
Generic before specific
Good
Button · IconButton · LinkButtonBad
Btn · CTAButtonV2 · PrimaryActionButtonThe generic component anchors the family. Specific variants extend it via composition or props, not via renaming.
03
Pascal case for components
Good
DataTable · NavBar · ToastProviderBad
data-table · navBar · toast_providerPascal case distinguishes components from HTML elements in JSX. Consistency across the file tree means every import line reads the same.
04
Match the slot to the part
Good
Card.Header · Card.Body · Card.FooterBad
CardTitle · CardBodyText · CardFooterAreaCompound components mirror the visual structure. Dot notation reads as containment; suffix soup doesn't.
04 — CSS patterns
Four families. Pick one. Stop debating.
BEM, utility-first, CSS Modules, CSS-in-JS. Each has a real case for and against. Pick the one that fits how your team writes code today — and never mix two in the same codebase. Consistency beats sophistication.
01
BEM
block__element--modifier
.card__header--featuredPros
Explicit · grep-friendly · works without tooling
Cons
Verbose · class names get long fast
02
Utility-first
single-purpose class per property
flex items-center gap-2 px-4 py-2Pros
No naming overhead · co-located styles · purges unused CSS
Cons
HTML reads denser · requires Tailwind or similar
03
CSS Modules
locally scoped class names
styles.cardHeader · styles.featuredPros
Scoped by default · plain CSS in files · no collisions
Cons
One file per component · class composition is manual
04
CSS-in-JS
styled components in TS
const Card = styled.div`...`Pros
Props drive styles · co-located · typesafe
Cons
Runtime cost · bundle size · solved problems re-solved
05 — Anti-patterns
Four naming mistakes that age badly.
From real design-system audits. Each one feels harmless when shipping a single component — and becomes the reason every consumer has to be updated when the system tries to scale.
Names by appearance
Avoid
--blue-600 · --large-paddingPrefer
--brand · --space-6Once the brand is red and the padding shrinks, the names lie. Semantic names survive value changes; appearance names don't survive month two.
Versioned in the name
Avoid
ButtonV2 · CardNew · ModalRedesignPrefer
Button · Card · Modal (with deprecation warnings)Versions migrate from name suffix to git history. A component called ButtonV2 implies ButtonV3 is coming — and once V3 ships, nothing is named consistently anywhere.
Abbreviation soup
Avoid
btn · img · txt · cntPrefer
Button · Image · Text · ContainerSaving four characters costs the next developer a grep. Modern editors autocomplete; the full word is free at type-time and worth its weight at read-time.
Component named after a feature
Avoid
CheckoutFlowStep2CardPrefer
Card (used inside CheckoutFlow)Components named for one use case can't be reused. The component is what it is; the page composes it. Coupling the name to the call-site is the start of a hundred near-duplicates.
Name by purpose, never by appearance.
One grammar across every token category. No exceptions.
Spell things out. Editor autocomplete is free.
Continue
Naming locks the API. The maturity model maps the journey.
Where is your system today? Where could it be? The maturity model maps the five stages every design system passes through — and the concrete moves to climb to the next one.