Naming conventions for your design system
Learn

Naming conventions for your design system

Author Avatar
Written by
Aug 21, 2026

Bad naming compounds. A component called Btn in code, "Button (Primary)" in Figma, and "Buttons" on the docs page is three different names for the same thing. Each is fine in isolation. Together they make the system feel like three separate things held together by goodwill.

Good naming is one of the foundations of a usable design system. The names you choose show up in design files, in code, in documentation, in conversations. When the names match across all of those, the system works. Inconsistent naming taxes every interaction: each time someone moves between design and code, they pay the cost of translating between names. The tax compounds across the lifetime of the system.

This article covers what's worth naming consistently, the principles that hold across naming decisions, the specific conventions for components, states, files, and pages, and how to keep naming under control as the system scales and contributors multiply.

The surface area of naming

Before getting into specific conventions, it helps to see how much surface area naming covers in a design system.

A component has a name. So do its variants (primary, secondary, ghost), its states (hover, focused, disabled), its props (leadingIcon, onClick), and its slots (header, body, footer). Beyond components, every design token has a name. Every page in your documentation has a name. Every Figma library, every layer in a Figma file, every code package, every release version. The names you choose for any of those can pull the system together or pull it apart.

The principle that holds across all of them: pick a convention and stick with it. The single most damaging thing you can do to a design system's naming is to be inconsistent. Consistent-but-imperfect naming is worth more than perfect-but-inconsistent naming, because consistency is what lets readers build a mental model and reuse it.

Name by role, not description

The single most important principle in design system naming is to name things for their role, not their appearance.

A color isn't "blue" or "dark navy." It's color-action-primary or color-surface-default. A spacing token isn't "16px." It's space-component-padding or space-layout-section. The name describes what the value is for, not what it looks like.

This matters for two reasons. The first is rebranding. If your primary color changes from blue to pink, a token called color-primary-blue becomes a lie the moment the rebrand ships. A token called color-action-primary survives the rebrand without a rename. The second is composability. Semantic names let designers and developers reach for the right token without having to remember its underlying value. "I need an action color" is faster than "I need #3B82F6, unless we've updated it."

Description-based names are sometimes useful as a base layer (a primitive token called blue-500 that other tokens reference) but they shouldn't be what components and pages depend on. The companion design tokens guide covers semantic vs primitive token naming in depth.

The same principle applies to components. A component called BlueButton encodes an attribute that might change. A component called PrimaryButton describes the role and survives a redesign.

Component naming

Component names should be canonical. One name per component, used the same way in design, code, and documentation.

A few specific decisions to make.

Casing is the first. Pick one convention and use it consistently. PascalCase is the convention for component names in most JavaScript frameworks, so code-facing identifiers usually use it: PrimaryButton, SearchInput. Token names typically use kebab-case (color-action-primary) because CSS custom properties and many token formats expect it. The mistake to avoid is using one convention in code and a different one in Figma. Once they diverge, you have two names for the same thing.

Pluralization defaults to singular. Use Button, not Buttons. The exception is for grouped patterns where multiplicity is part of the meaning: Tabs, Breadcrumbs. A useful test: if "I want to use this in isolation" makes sense, the name should be singular.

Prefixing helps when you have name collisions, multiple systems, or sub-systems. A team running a design system inside a larger company might prefix all components (DsButton, DsInput). A team supporting multiple brands might prefix by brand. Don't add prefixes preemptively. Add them when you actually need to disambiguate.

Some components have multiple common names. A chip is a tag is a pill. Pick one as the canonical name and document the others as aliases on the component page. Anyone searching for any of the names should land on the same page.

The aim is for someone moving between design, code, and docs to never have to translate. The same name carries them through.

State naming

Component states are one of the highest-friction naming areas because there's no single industry convention and the names you choose end up in documentation, code, and design variants.

A baseline set of names that covers most components:

  • Default (or enabled): the resting state. Interactive but not active.
  • Hover: the pointer is over the component but hasn't pressed it.
  • Focused: the component has keyboard or screen reader focus.
  • Pressed (or active): the component is being clicked or tapped.
  • Disabled: the component is non-interactive.
  • Selected: the user has chosen this component as part of a set of options.
  • Error: the component is signaling a validation or system failure.

Other states show up depending on the component. Loading, dragged, validated, read-only, visited. Document the states your system actually uses and skip the ones it doesn't. A component without a hover state shouldn't have a "hover" variant in its documentation.

Be specific where it matters. Selected means the user has chosen this component as part of an option set. Active means the component is currently doing something. Documenting which name carries which meaning saves arguments later.

Naming in design files

The names inside your Figma files matter as much as the names on the components themselves.

Layer naming is the most-skipped piece. A frame called "Frame 23" inside a button component is invisible to most workflows until someone needs to inspect it, generate code from it, or migrate the library. Then it becomes friction for everyone touching it. The minimum bar: every named layer should describe what it is, not where it sits. "Icon" beats "Layer 4." "Container" beats "Frame 12."

Component names in Figma should match the component names in your design system. If your code says PrimaryButton, your Figma component should be named PrimaryButton. Variants surface as Figma variants where the property names and values match the documentation.

File names follow a similar logic. A file should make its contents obvious from the file list. Useful conventions include a short project identifier, a content descriptor, and a version or status indicator. auth-onboarding-v2 carries more meaning than Untitled (4). If your team works across multiple products or brands, the file name should signal which one a file belongs to.

The plugin Rename It (available for Figma, Sketch, and Adobe XD) is worth installing if you're trying to clean up layer naming in an existing file.

Page and section naming in documentation

The names of pages and sections in your documentation site are part of the system's naming surface, and they're often the part that drifts furthest from the underlying components.

Page names should match the canonical name of the thing the page documents. A page documenting the button component should be called "Button," not "Buttons" or "Action Button" or "CTA." Once a page name diverges from the component name, readers searching for the component miss the page, and the page accumulates redirects, aliases, and confusion.

Section names should describe what's in the section in language that holds up across the docs. "Foundations," "Components," "Patterns," "Content," "Getting Started." Clever names ("The Atoms," "Our Recipe Book") look fun on the homepage but make it harder for new users to figure out where to find what.

URL slugs deserve more thought than most teams give them. If your component is "Button," the URL slug is /components/button, not /components/buttons-overview or /component/btn. URL slugs end up in shared links, bookmarks, and external references. They cost more to change than any other part of the documentation.

Versioning in names

Versioning shows up in naming whenever a component or pattern goes through a substantial change.

The first decision is whether to version in the name at all. The simplest approach is to keep the name stable and version the underlying implementation. Button always refers to the current version, with deprecated versions retired through proper deprecation rather than renamed. This works when changes are evolutionary.

The harder case is when a component changes substantially enough that the old and new versions need to coexist. A button with a new API that's incompatible with the old one, or a navigation pattern that's structurally different from its predecessor. In that case, the new version takes a suffix (ButtonV2) for the duration of the migration window. The old version stays available with a "deprecated" status and a link to the new one. Once teams have migrated, the old version is retired and the new one drops the suffix.

The mistake to avoid is calling the new version ButtonNew or ButtonImproved. These names age badly and become meaningless once the migration is done.

Documentation should reflect the canonical name plus a clear deprecation status. A page called "Button (Deprecated)" with a link to "Button V2" tells the reader exactly what's happening. "Old Button" as a page name leaves the reader guessing.

Naming at scale: cross-team consistency and governance

Naming gets harder the more people contribute. A two-designer team can name things consistently by talking to each other. A fifteen-team organization can't.

A canonical naming reference helps. Publish a single page in your documentation that lists every naming convention the system uses: casing, prefixes, state names, the rules for tokens, the rules for patterns. New contributors read it once. Reviewers reference it during contribution review.

Naming review at contribution time matters more than naming review after. New components or tokens get a naming review as part of the contribution process, before they ship. Once a name is in code, it's expensive to change. Naming review is the cheapest place to catch a bad name.

When multiple teams use the same word for different things, the design system has to pick one. "Card" might mean a payment card, a UI card component, or a content card. The system picks one canonical meaning and documents the alternatives explicitly. Otherwise every internal discussion has a translation step.

Deprecation needs discipline. When a name changes, the old name doesn't just disappear. It becomes an alias for the new one until enough usage has migrated, then a deprecated reference, then it goes. Skipping any of those steps creates broken links and lost knowledge.

And someone has to own naming decisions. Naming-by-committee produces compromise names that no one likes and that nobody can remember the reasoning for. A small team (often one or two people) makes the call. Disagreements escalate to a documented principle ("name by role, not description") rather than to a vote.

The throughline is that naming at scale isn't about getting every name right on the first try. It's about having a way to fix bad names without breaking the system.

How to audit naming in an existing system

If you've inherited a system with inconsistent naming, the work isn't to rename everything at once. It's to make a plan that reduces the inconsistency over time.

Start with an inventory. List every component name, every token name, every documentation page name, every Figma library name. Most systems have between 80 and 300 entries to audit. A spreadsheet works fine.

Look for three kinds of inconsistency. The same thing called different names in different places ("Button" in code, "CTA Button" in Figma, "Primary Action" in docs). Different things called the same name ("Card" used for both a payment card and a UI container). Names that don't follow the principle the rest of the system uses (a description-based name in a system of role-based names).

Prioritize the highest-leverage fixes first. A component used everywhere has more weight than one used twice. Names that show up in external interfaces (URLs, public APIs, shared design files) cost more to change later than names that only live in internal code, so fixing those earlier saves more pain.

Migrate without breaking things. Introduce the new name first, alias the old name to it, give teams a deprecation window, then retire the old name. Don't skip the alias step. The temptation to "just rename it" produces broken links and angry developers in equal measure.

Where to go next

Naming is one of the foundations of usable documentation. A few articles in this guide go further on naming-adjacent areas.

Article 04 (The key sections of a design system) covers where naming fits into the broader structure of your documentation. Useful if you're still deciding what to name in the first place.

Article 13 (Keeping your design system documentation up to date) covers maintenance workflows, including how to handle name changes without leaving stale pages behind.

If you're working in Figma, the design tokens guide covers the specifics of layer and variable naming in design files.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post