skip to content

In a design system, why should the design-file component library use the same component names, variants and properties as the coded library?

level: juniorimportance: should knowfreq 38%

answer

  1. one vocabulary, two media
  2. handoff without translation
  3. a design choice maps to a prop
  4. search once, find both
  5. mismatched names hide mismatched behaviour

basics

~20 s

Matching names, variants and properties give designers and engineers one vocabulary: a design choice maps directly to a code option, handoff needs no translation, documentation describes both at once, and a mismatch becomes visible instead of hiding.

solid answer

~40 s

The design-file library and the coded library describe the same components in two media. If the designer's 'Status pill, variant: warning' is the engineer's 'Tag, tone: caution', every handoff needs a translation step, and translation is where mistakes happen. With **parity**, the component in the design file has the same **name**, the same **variants** with the same values, and the same **properties** as the coded one, so reading a design tells the engineer exactly what to write. It also lets documentation describe one component once, lets search in either library find the counterpart, and makes gaps obvious: a variant that exists in design but not in code is visible the moment someone looks for it. Parity is about the shared public vocabulary; internals on each side can differ.

go deeper

for a junior

Recall that the design-file and coded libraries should share component names, variants and properties, so a design choice maps directly to code.

for a middle

Explain what breaks when vocabularies differ, and where parity deliberately stops: code-only properties, design-only properties and runtime states.

for a senior

Show how you would reconcile two libraries that already disagree, prioritising high-use components and choosing purpose-based names over appearance-based ones.

for a principal

Weigh how strict parity should be against the cost of keeping two libraries aligned, and who decides a shared name when design and engineering disagree.

## Two libraries, one system A mature **design system** usually ships two libraries of the same components: - A **design-file library** in a design editor, which designers place into screens as linked instances. - A **coded library**, one per platform or one shared package, which engineers use to build the product on the web and on native mobile. **Library parity** means those two libraries mirror each other: the same component **names**, the same **variants** and the same **properties** with the same allowed values. It does not mean identical internals; it means the public vocabulary a designer and an engineer use is the same. ## What goes wrong without parity Consider an insurance claims portal where claimants track claims and adjusters review them. The status of each claim appears as a small coloured label. | Side | Name | Variant property | Values | |---|---|---|---| | Design file | Status pill | Variant | Default, Warning, Error, Success | | Code | Tag | tone | neutral, caution, critical, positive | Nothing here is wrong on its own, yet every handoff now needs a translation: - A designer asks for a 'Status pill, Warning'; the engineer must know that means 'Tag, caution'. - The claim state 'information needed' is designed with a new orange variant that has no code equivalent, and nobody notices until the build looks different. - Search in the documentation for 'Status pill' finds nothing in the code reference. - New team members learn two vocabularies, and conversations between design and engineering drift into ambiguity. Each mismatch is small; together they turn every screen into a small interpretation exercise and let design and code drift apart without anyone deciding they should. ## What parity gives you 1. **Lossless handoff.** A design shows the component, variant and property values; the engineer writes the same names. No redlines are needed to explain which component is meant. 2. **One documentation page.** The component's guidance, variants and examples apply to both media, with platform-specific notes where needed. 3. **Visible gaps.** When a designer needs a variant that does not exist, the absence is obvious on both sides, which starts a conversation instead of a silent one-off. 4. **Faster onboarding.** One vocabulary to learn, whatever your role. 5. **Tooling that connects the two.** Matching names make it far easier to link design components to code and to compare the two libraries automatically. ## Where parity stops Parity covers the **public vocabulary**, not everything: - **Code-only properties**, such as event handlers or test identifiers, have no meaning in a design file. - **Design-only properties**, such as a toggle to show placeholder content, have no meaning in code. - **Runtime states**, such as hover or focus, are often variants in the design file so they can be shown, but are behaviour in code. These differences are acceptable as long as they are deliberate and documented; what parity forbids is the same concept carrying two names. ## Choosing the shared name When the two sides disagree, pick the name that describes **purpose rather than appearance**, because appearance changes with themes and brands while purpose does not. 'Tone: critical' survives a palette change; 'Variant: red' does not. Settle names in the component's spec before either side builds, and treat a rename as a change to both libraries at once. For the claims portal, the team agrees on 'Status tag' with a 'tone' property of neutral, info, caution, critical and positive, and maps each claim state to a tone in the guidance. The adjuster dashboard and the claimant app now use the same component name in design reviews, tickets and code.

  • Should parity extend to naming each layer inside the design-file component?
    Not necessarily. Parity matters for the public surface: the component name, its variants and its properties, because those are what designers choose and engineers implement. Internal layers are implementation detail on the design side, just as internal elements are in code. Naming layers clearly helps maintenance, but forcing them to match code structure adds cost without improving handoff.
  • The design and code libraries already disagree on names across fifty components. Where do you start?
    Start with the most used components and the names that cause real confusion in handoff, not an alphabetical sweep. Agree each shared name in the spec, choosing purpose over appearance, then change both libraries together and note the rename for consumers. Renaming everything at once maximises disruption for little extra benefit.

saying these in an interview costs you the question

  • Designers and engineers can use different names as long as someone keeps a mapping.
  • Parity means the design component's layers must match the code's internal structure.
  • Naming variants after their colour is fine, since colour is what designers see.
  • Code-only properties such as event handlers should appear in the design file too.