Skip to content
UX Atlas
Design systemCraft conventionAdvanced

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 page
  1. Definition
  2. Reducing drift in order of leverage
  3. Which differences to accept
  4. Continue from here

Reducing drift in order of leverage

  1. 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. 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. 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. 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. 5

    A scheduled reconciliation

    A recurring pass comparing the two libraries, with findings logged like any other defect.

Which differences to accept

DifferenceVerdictWhy
Token valuesNever acceptableEverything downstream inherits the error.
Component namesNever acceptableBreaks communication and any mapping between the two.
States shownDesign may show fewerA design library need not render every loading permutation.
Layout behaviourCode is the truthReal reflow, overflow and text scaling only exist in the implementation.
MotionCode is the truthTiming and easing cannot be judged accurately in a static tool.

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.