# Terminology: Agreeing on the Words That Name Design System Parts

> Learn the core words of design systems, how they connect, and how to pick names that keep designers and developers on the same page.

**In short:** Design system terminology is the set of shared words that name its parts, so designers and developers mean the same thing when they say a word like button or card.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/terminology

## What you will learn

A design system is a shared set of parts, rules and guidance that helps a team build products in a consistent way. Every part in that system needs a name, and the names only help if everyone uses them the same way. This lesson is about that shared vocabulary. You will learn the core words, how they connect, and how to choose names that stay clear as the system grows. You will not learn how to build the parts themselves. Other lessons cover that.

- **Terminology:** The agreed words a team uses for things, plus the one meaning each word has.
- **Design system:** A shared set of parts, rules and guidance that helps a team build products consistently.
- **Term:** One word or short phrase that has one agreed meaning.
- **Naming convention:** A pattern for building names, so that similar things get similar names.
- **Glossary:** A list of terms with plain definitions, kept where everyone can read it and update it.
- **Single source of truth:** One agreed place to check the right answer, so people do not rely on memory or guesses.

## Why do shared words matter?

Words drift apart quickly. A developer may call a part a box while a designer calls the same part a card. Each person thinks the other means something different. The result is slow meetings, repeated work, and screens that look a little different from one another.

Guides written by design system teams make the same point. A shared name helps designers, developers and product owners talk about the same element. A shared vocabulary also reduces miscommunication, because a developer can build a part more accurately when the name tells them what it is.

- **Designers:** A designer who asks for a new card may mean a new layout, a new color, or an entirely new part. Without a shared word, the request is unclear, and the reply may be a guess.
- **Developers:** A developer who hears make the button bigger may change every button in the product, when only one size option was meant. The wrong change then spreads.
- **Product managers:** A product manager who hears the pattern is broken may not know which part failed. The fix takes longer, and the wrong team may start working on it.

A glossary solves much of this. It works like a single source of truth. When two people disagree about a word, they check the glossary instead of arguing from memory. A team that writes its names down early avoids a lot of later confusion.

> **Tip:** Write the first glossary before you design the first part. Renaming parts after many screens already use them is slow and easy to get wrong.

## The core vocabulary

The words below appear in almost every design system. Read them as a set. Each word has its own job, and the jobs fit together like pieces of one puzzle.

- **Token:** A token is one design decision, such as a color or a spacing amount, stored with a name and a value. The name is what people read, and the value is the actual setting. Tokens are described as the smallest pieces of a design system, and every other part can build on them.
- **Component:** A component is a reusable, single element with one clear purpose, such as a button, a text box or a checkbox. Designers make it once and reuse it on many screens. The Pay now button in the worked example below is one component.
- **Variant:** A variant is another version of the same component. The job stays the same, but a setting changes, such as size, color or shape. A small button and a large button are two variants of one button component. Sources differ a little here. Some say a variant keeps the same purpose, while others say it can serve a different purpose, such as a primary or a destructive button. Your team should pick one meaning and write it down.
- **State:** A state is the condition a component is in at a given moment. Common states include default, hover, pressed, focused and disabled. A state tells the person using the screen what is happening with that part.

- **Pattern:** A pattern is a reusable, best-practice answer to a common user problem. It is built from several components working together, such as a login form that combines text boxes, a button and a message. A pattern is not the same thing as a single component.
- **Style:** A style is a saved set of visual choices, such as a text look or a shadow, that can be applied again by name. Some tools store a token as a variable and others store it as a style, so the two words can look alike in practice. Ask your team which one it uses, and record the answer in the glossary.
- **Guideline:** A guideline is advice about how to use the system well. It answers questions such as when to use a button, when not to use it, and what to do when a state is unclear. Parts show what something is. Guidelines explain when and how to use it.

### How do the terms connect?

The words are not separate boxes on a shelf. They form a chain. Start at the bottom with tokens and move up to patterns.

1. **Tokens hold the basic decisions:** Tokens store choices such as one blue for main actions. When a token changes, every component that uses it changes too.
2. **Components use tokens:** Each component points to the tokens it needs. A button takes its fill color from a token instead of having a fixed color typed into it.
3. **Variants and states multiply components:** One button can have several variants and several states. Each combination needs its own defined look, so the team does not have to guess each time.
4. **Components combine into patterns:** A pattern uses several components together to solve one common problem.
5. **Guidelines explain the use:** Guidelines tell people how to use tokens, components and patterns well, so the whole system is easier to follow.

## How do you choose good names?

A good name tells a reader what a thing is for. A poor name describes only how it looks. Compare dark-blue with color-text-primary. The first name tells you a color, but not where the color belongs. If the brand later changes its blue, dark-blue becomes misleading. The name color-text-primary still describes the job of the text, so it keeps working after the color changes.

### Three rules for names

- **Clear:** Use plain, complete words. Avoid short forms that only one person understands. A good name should make sense to a designer, and also to a developer who has never opened the design file.
- **Consistent:** Use the same pattern everywhere. If one component uses small, medium and large for its sizes, every component should use the same three words. Pick one order for parts of a name, such as category, then role, then modifier.
- **Purpose-based:** Name a thing by its job, not by its value. A name such as color-feedback-error tells you when to use the color. A name such as red-600 tells you only the color.

Many teams also agree on letter case and separators.

> **Tip:** Test the names. Show the list to one designer and one developer. If either of them has to ask what a name means, rename it.

### Keep one term per concept

If two words point to one thing, people will believe there are two things. Choose one word and use it everywhere. Avoid vague or generic words such as thing or box when a precise word exists. Vague names are a common pitfall, and they cause confusion for everyone who reads them later.

### Why record terms in a glossary?

Write each term in one place. For each one, record the term, a plain definition, a short example and where it is used. A glossary only helps if the team can update it, so treat it as a living document. Start with the core words in this lesson, then add new terms as the system grows. Other lessons explain who approves changes and how full documentation is written.

> **Tip:** Keep the glossary close to the design files. If people have to search far for it, they will guess instead of checking.

## Worked example: the Pay now button

Imagine a checkout screen in an online shop. At the bottom sits a blue Pay now button. The terms below let the team talk about each part of it precisely.

1. **Name the component:** The button is a component. It is one reusable element with one clear purpose, which is to start payment. Any screen in the shop can reuse it.
2. **Name the states:** When the cursor rests on the button, it shows the hover state, which signals that the button can be clicked. When payment is not yet possible, the button shows the disabled state. It looks inactive and does nothing when clicked.
3. **Name the variants:** The team also makes a small version and a large version. Both do the same job, so they are two variants of one button component.
4. **Name the token:** The blue fill comes from a token named color-action-primary. The name describes the job, which is the main action. It does not say blue. If the brand changes its blue, the name still holds, and every component that uses the token updates with it.
5. **Say exactly what to change:** Now the team can speak precisely. A designer can write: change the disabled state of the Pay now button and leave the token alone. A developer then knows which single part to touch.

> **Tip:** A request that names the part, the state and the token keeps the change small. Compare make the button darker with change the hover state of the primary button.

## Check your understanding

Try these two short scenarios. Each one needs the ideas in this lesson to answer.

**Quick check:** A designer asks a developer to update the card style. The developer changes the whole Card component, but the designer only meant the background color. Which terminology idea would have prevented this?

A. Use a pattern name, because a card style spans several components
B. Name the single design decision exactly, such as the token color-surface-card, for the background color
C. Ask for a new variant of the Card component so the old one stays untouched
D. Put the request in the guideline so the developer reads it later

**Answer:** B. A token holds one design decision. Naming the exact token, such as color-surface-card, tells the developer to change only the background. A pattern or guideline name is too broad, and a new variant would add a part instead of fixing the name.

**Quick check:** On a shop site, one designer calls a grey, unavailable button inactive. Another designer calls it disabled. A developer builds a third version and names it off. What is the best fix?

A. Let each person use the word that feels clearest at the time
B. Pick one term for the state, define it, and record it in the shared glossary
C. Build a separate component for each word so that each name has its own part
D. Hide the grey button inside a pattern so that nobody needs to name it

**Answer:** B. One concept should have one term. Choosing one word, defining it and recording it in the glossary stops three words from splitting the team. Separate components would multiply parts, and hiding the button in a pattern does not solve the naming problem.

## Key takeaways

Shared words keep designers and developers aligned. Learn the core terms, which are token, component, variant, state, pattern, style and guideline. Connect them in a chain, from tokens up to patterns. Choose names by purpose, keep one term for each concept, and record every term in a glossary that the team can update.

## Sources

- [Forge Design System, Vocabulary (Jack Henry)](https://jackhenry.design/v2/foundations/content/terminology-and-vocabulary/)
- [Accor Design System, Defining things](https://design.accor.com/latest/terminology/conventions/defining-things-A5JChnvD)
- [Design Systems Glossary (designsystems.one)](https://www.designsystems.one/glossary)
- [Prototypr, Understanding the parts of a Design System](https://blog.prototypr.io/understanding-the-parts-of-a-design-system-tokens-assets-components-and-patterns-80b22c67a0a8?gi=f306753d1f8a)
- [Material Design 3, Design tokens](https://m3.material.io/foundations/design-tokens)
- [Magic Patterns, What Is a Design System?](https://www.magicpatterns.com/blog/what-is-a-design-system)
- [UX Components, Glossary](https://www.ux-components.com/glossary)
- [Wikipedia, Design system](https://en.wikipedia.org/wiki/Design_system)
- [Medium, Streamlining Your Design System: A Guide to Tokens and Naming Conventions](https://medium.com/@wicar/streamlining-your-design-system-a-guide-to-tokens-and-naming-conventions-3e4553aa8821)
- [Backlight, Naming conventions for design systems](https://backlight.dev/blog/naming-conventions-for-design-systems)
- [Aufait UX, Naming Design Tokens](https://www.aufaitux.com/blog/naming-design-tokens/)
- [Figma, Design systems 102: How to build your design system](https://www.figma.com/blog/design-systems-102-how-to-build-your-design-system/)
- [Design Systems Collective, Naming component properties](https://www.designsystemscollective.com/naming-component-properties-a-systematic-approach-for-variant-configuration-2f1a38f1fd83)
- [Kevin Bizien, Naming design system components (summary of Kat Allen)](https://kevinbizien.com/en/sharing/naming-design-system-components)
- [Sealab, Design System Best Practices from 10+ Real Builds](https://sealab.design/blog/design-system-best-practices/)
- [Claritee, Design System Naming Conventions: Establishing Clarity](https://claritee.io/blog/design-system-naming-conventions-establishing-clarity/)
- [Design Systems Collective, Design token naming that scales](https://www.designsystemscollective.com/design-token-naming-that-scales-how-to-prevent-token-chaos-b92ff4cd55fd?gi=0f5279a056e3)
- [UX Dictionary, Crafting a Comprehensive State System for Design System Components](https://uxdictionary.io/article/crafting-a-comprehensive-state-system-for-design-system-components)
- [UX Design (Medium), An interaction state of mind](https://uxdesign.cc/an-interaction-state-of-mind-705572b3ad51?gi=15dc55117611)
- [NN/g, Button States: Communicate Interaction](https://www.nngroup.com/articles/button-states-communicate-interaction/)
- [Figma, Understanding Button States in UI Design](https://www.figma.com/resource-library/button-states/)
