In a design system for an insurance claims portal, how do you make a new status-tag variant land in the design library and the coded library together?

## The problem: two libraries, two timelines A **design system** with a design-file library and a coded library can let a change land on one side long before the other. In an **insurance claims portal**, suppose adjusters need a new status for claims waiting on the claimant: 'information needed'. The status tag, the small label shown on every claim, needs a new variant. If design adds it to the library on Monday and code ships it a month later: - Designers use it in new screens immediately. - Product engineers receive designs they cannot build, and improvise with a local tag or the nearest existing variant. - The improvised versions ship, and the real variant, when it arrives, has to replace them. The reverse happens too: engineers add a variant for an urgent fix, designers never learn of it, and new designs keep the old workaround. **Library parity** requires that one change lands on both sides together. ## Make it one change 1. **One work item, one owner.** The variant is a single piece of work that covers the design library, each coded platform and the documentation, not a design ticket and a separate code ticket. 2. **Spec first.** Designer and engineer agree the **name** and **value** ('tone: info-needed'), the **tokens** it uses, the **content rules** (short label text) and the **accessibility requirements**, such as contrast against the tag background and not relying on colour alone to convey the status. 3. **Build in parallel.** A designer and an engineer work at the same time, ideally pairing, so questions are answered in hours rather than across a handoff. 4. **Review against each other.** The design variant and the coded variant are compared side by side before either is published, checking name, values, tokens and states. 5. **Publish together.** The design library update and the code release go out in the same window, with one entry in the change notes covering both. 6. **Update the documentation** page in the same change, including the mapping of claim states to tones. ## A definition of done that enforces it | Item | Done when | |---|---| | **Spec** | Name, values, tokens and accessibility rules agreed and recorded | | **Design library** | Variant added and library update published | | **Code** | Variant implemented on every supported platform and released | | **Documentation** | Guidance, examples and the design-to-code mapping updated | | **Parity review** | Design and code variants compared side by side and signed off | If the definition of done says 'design published' and 'code released' as separate tickets, the two will drift in time. Putting both in one checklist makes a half-finished change visibly unfinished. ## When one side has to lag Sometimes a platform cannot ship in the same window, for example the native mobile release train leaves later. Then: - Mark the variant clearly as **not yet available** on the lagging platform, in the design library and in the documentation. - Keep the change open until the last platform ships. - Do not announce the variant as available until it is, or designers will use it in designs no one can build. ## Why the spec comes first Most parity failures are **naming** failures decided in isolation: design calls the new value 'pending', code calls it 'awaiting-input', and both ship. Agreeing the name before either side builds costs minutes; renaming afterwards means a change to both libraries and every product that already used either name. Choosing a purpose-based name, what the status means rather than what colour it is, also keeps it valid when the palette changes. ## What this looks like in practice For the claims portal, the work item 'Status tag: add info-needed tone' holds the spec, links to the design library change and the code change, and closes only when both are published and the documentation lists 'information needed' under the new tone. The adjuster dashboard team and the claimant app team read one announcement and can use the variant in design and code on the same day. ## Common failure modes - **Design-first publishing**, where the library leads code by weeks and invites improvised builds. - **Silent code additions**, where an engineer adds a variant that never reaches the design library. - **Separate definitions of done**, which let each side close its ticket while the pair is incomplete. - **Late naming**, where each side picks a name and the reconciliation becomes a rename.