Design System Naming Conventions for Components

A component name is a search term, an API decision, and a promise about scope. When designers say “primary tile” while developers import “FeaturePanel,” every handoff includes translation work. A naming convention should reduce that work without forcing design tools and programming languages to use identical syntax.

Start with a shared naming model

List the concepts consumers already search for: button, dialog, pagination, navigation, and notification. Prefer established interface vocabulary over internal project nicknames. Record the concept, its public name in code, its design-library label, and a one-sentence definition. Agreement on meaning matters more than capitalization.

Use the JSON to TypeScript tool to turn a draft naming registry into an initial interface. Paste a small JSON record, generate the shape, then review optional fields and constrained values manually. Generated interfaces describe examples; they do not automatically capture your naming policy or all valid cases.

Separate concept identity from display syntax. A design asset called “Navigation / Breadcrumb” can correspond to a code export named Breadcrumb without introducing two different concepts. The mapping should be documented and searchable in both directions.

Name by purpose rather than appearance

“BlueBox” becomes misleading when a theme changes. “CustomerSummary” describes a domain composition but may be too specific for a foundational library. Ask what the component guarantees and which consumers should use it before choosing the noun. Name generic primitives generically and keep business workflows in product-owned packages.

Avoid positional names such as LeftPanel when the same component may move in a responsive layout or a right-to-left interface. “FilterPanel” describes a purpose that survives that change. Likewise, “LargeThing” is not a useful substitute for deciding whether size is a variant or a genuinely separate component.

Use a registry entry that makes relationships visible:

type ComponentName = {
id: string;
codeExport: string;
designLabel: string;
aliases: string[];
};

const breadcrumb: ComponentName = {
id: "navigation.breadcrumb",
codeExport: "Breadcrumb",
designLabel: "Navigation / Breadcrumb",
aliases: ["crumb-trail"]
};

The stable identifier supports cross-references even if the human-facing label changes. The TypeScript handbook explains the typing mechanics; the naming decisions remain a team responsibility.

Separate components, variants, and states

A variant is an intentional supported choice, such as emphasis or size. A state describes a condition, such as loading or invalid. A compound component exposes related parts with a coordinated contract. Mixing these categories produces names like “SmallDangerLoadingButton,” which are difficult to search and harder to maintain.

Choose a few variant axes that consumers can predict. For example, use size values consistently within a component family and document exceptions. Do not promise that “small” has the same pixel height across every platform; promise the actual meaning your library can support, such as a compact presentation within a given component.

Keep boolean names readable at call sites. A property like disabled follows native HTML expectations; a vague property like alternate does not explain what changes. Consult the React documentation on props for component API context, while preserving framework-neutral terminology in the design library.

Document invalid combinations rather than letting names suggest unlimited freedom. If a destructive action cannot use a quiet emphasis in your product context, explain that constraint and enforce it where practical. Naming is useful only when the allowed combinations have a coherent meaning.

Make discovery work in both tools

Create a small glossary with canonical names and common aliases. Search should lead “popup” to the appropriate dialog or popover documentation instead of simply reporting no results. Explain differences between neighboring concepts with concrete examples; avoid treating industry terminology as universally consistent.

In design tools, use grouping to support browsing without creating deeply nested paths that obscure the component name. In code, organize public exports around supported entry points rather than exposing private folder structure. The two systems can share a vocabulary without mirroring every folder.

A public naming policy should cover capitalization, singular versus plural nouns, abbreviations, and reserved suffixes. Keep it short enough to apply during review. Use abbreviations only when the audience reliably knows them, and provide expanded search aliases when needed.

When documenting implementation details, link to the MDN custom properties reference for CSS naming syntax. Do not use an implementation convention, such as a CSS prefix, as the sole organizing principle for all design assets. Related development resources can support platform-specific naming guidance without changing the shared glossary.

Rename without breaking recognition

Renaming an exported component can break imports, documentation links, saved searches, and conversations. Treat it as a migration rather than a cosmetic cleanup. Record the old name, new name, reason, supported transition period, and whether behavior changes at the same time.

Use compatibility aliases where your packaging and maintenance policy allow them. Mark the old name deprecated, update first-party examples immediately, and give consumers an exact replacement. Avoid leaving both names equally prominent forever, which turns a temporary bridge into a permanent ambiguity.

Test a proposed rename with people who did not invent it. Ask them to find the component using realistic tasks, not a list of approved names. If the convention requires repeated explanation, simplify the vocabulary or improve aliases before adding more rules.

Review naming drift during library releases. New terms should extend the glossary intentionally, not appear because the author preferred a different synonym. Keep further governance guidance under Design Systems, and assign one maintainer to resolve terminology conflicts when discussion stalls.

Resolve a naming collision with a task test

Imagine two teams requesting the name Select. One component opens a fixed list of choices; the other accepts text input and filters remote results. Sharing a label would hide meaningful differences in keyboard behavior, loading, and empty results. Start by describing the user task and supported interaction for each, then compare those descriptions with the existing glossary.

Run a discovery check with three realistic prompts: choose a country from a fixed list, find a customer by typing, and choose several labels. Ask contributors which documented component they would open first and why. This is a small usability exercise, not a statistical study; its value is exposing ambiguous terminology before a public API spreads.

Keep the final canonical names, rejected alternatives, and common search aliases together. If the names still require a long explanation, improve the boundary descriptions or reconsider the component split. Avoid solving the collision with arbitrary numeric suffixes or team prefixes, which preserve organizational history without helping consumers choose the correct interaction.

Key takeaways

• Name components for stable purpose, not color or screen position.
• Map design labels and code exports through a shared concept registry.
• Keep variants, states, and component parts distinct.
• Support search aliases without multiplying canonical names.
• Treat public renames as migrations with clear ownership and deadlines.