Design and Code Parity
Two libraries claiming to be the same system will diverge. Decide where truth lives, and make the other side derive from it.
Definition
Parity is the degree to which the design library and the implemented components describe the same thing. Perfect parity is not achievable in two separate tools, so the useful question is which differences are acceptable and how drift is detected.
Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.
On this plate
Reach for this when
- Design and implementation disagree in review regularly.
- Setting up or auditing a component library.
- Adopting a token pipeline.
Common mistakes
- Token values copied by hand into code.
- Different names on each side.
- Guidance duplicated in two places and updated in one.
Reducing drift in order of leverage
- 1
One source for tokens
Colours, spacing, type and radii defined once and generated into both platforms. This removes the largest and most visible category of drift.
- 2
Names that match
If the design library calls it 'Menu' and the code calls it 'Dropdown', every conversation costs a translation and the mapping eventually breaks.
- 3
One documentation surface
Usage guidance written once and shown alongside both the design component and the coded one. Two sets of guidance become two systems.
- 4
Automated visual comparison
Snapshot tests on the coded components catch unintended change. They do not catch intended change that was never reflected in design, which is why the review step still matters.
- 5
A scheduled reconciliation
A recurring pass comparing the two libraries, with findings logged like any other defect.
Which differences to accept
| Difference | Verdict | Why |
|---|---|---|
| Token values | Never acceptable | Everything downstream inherits the error. |
| Component names | Never acceptable | Breaks communication and any mapping between the two. |
| States shown | Design may show fewer | A design library need not render every loading permutation. |
| Layout behaviour | Code is the truth | Real reflow, overflow and text scaling only exist in the implementation. |
| Motion | Code is the truth | Timing and easing cannot be judged accurately in a static tool. |
Signs the two have already diverged
Drift is never announced. This is what it looks like from inside the team.
- Detached instances in design files, which are forks with no changelog.
- Engineers checking the implementation rather than the design file, because they learned the file is stale.
- Props in code with no equivalent anywhere in the design library.
- The same usage guidance written in two places and updated in one.
- Review comments redlining values that should have come from a token.
- A colour shipping in production that exists in neither library.
Holding the line
Do
- Name one owner for reconciliation. Shared ownership of parity means the pass never runs.
- Generate the design tool's variables from the same token source as the code.
- Log drift as defects in the normal tracker, so it competes for time honestly.
- Delete the design library component when its coded replacement lands, rather than keeping both alive.
Do not
- Do not redline pixel values in review when the disagreement is really about a token.
- Do not treat the design file as the specification for behaviour. Reflow, overflow and motion exist only in code.
- Do not ship a component on one side without its counterpart on the other.
- Do not chase perfect parity. Decide which differences are acceptable, then audit the rest.
Commonly confused with
Close neighbours that get substituted for each other. The difference is stated first, then the condition that picks one over the other.
Design System Audits
Design systemAn inventory of the interface as built: every style, value and near-duplicate.
Key difference
An audit is a one-off count of what is actually in production. Parity is the standing relationship between the design library and the code. The audit tells you how far apart they have drifted; parity is how you stop drifting again.
Use Design and Code Parity when
- Both libraries exist and each claims to be the source of truth.
- The question is which differences are acceptable.
- You need drift detected continuously, not counted once.
Use Design System Audits when
- You are starting or repairing a system and need facts, not opinion.
- The argument about drift needs a list to settle it.
- The output is a count that justifies what the system should contain.
Local chart
SYS·010 · Region VI · Grid C4
This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.
Continue from here
Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.
Related concept
Connected closely enough to change how you apply this.
- Specification to Working CodeAI·010 · AI workflow
- Component Anatomy, States and VariantsSYS·009 · Design system
- Design System DocumentationSYS·003 · Design system
- Design TokensSYS·001 · Design system
- Design HandoffFLOW·002 · Workflow
- Design QAFLOW·003 · Workflow