In a design system for a real-estate listings site, the design library publishes a new listing card weeks before the code ships; how do you coordinate the two releases?

## Why the two releases drift apart A **design system** has two faces: a **design library** that product designers pull components from in their design editor, and **code packages** that engineers install on each platform. They are usually produced by different people with different tools and review steps. Design work often finishes first, and publishing a design library update is quick, so it is tempting to publish as soon as design review passes. On a real-estate listings site, that is how a redesigned **listing card**, with a larger photo, a price badge and a save-to-favourites control, ends up in the design library weeks before any coded version exists. ## What goes wrong when they are out of step | Situation | What designers do | What engineers do | Result | |---|---|---|---| | Design ahead of code | Use the new card in mocks and handoffs | Find no component; wait or build a local copy | Local copies that drift and must be replaced later | | Code ahead of design | Keep using the old card in mocks | Ship the new card; mocks no longer match the screen | Confusing reviews and mismatched handoffs | | Different notes for each | Read only the design library's message | Read only the package's notes | Neither group sees the whole change | The common cost is that each group works from a different picture of what the system currently offers. ## One change, two artifacts The most reliable fix is to stop treating the design asset and the code as two releases: 1. **One change record.** The new listing card is tracked as a single change, with its design and code work linked. 2. **Same train.** Both artifacts move through the same release schedule, so the design library update is published on the day the code is. 3. **One set of notes.** The release notes describe the change once, covering what designers and engineers each need to know. 4. **A clear meaning of released.** A component counts as released when every artifact the system promises is available, or the notes say exactly which ones are. ## When design must go first Sometimes designers need an upcoming component early, for instance to design a new search results page that ships at the same time as the card. That is legitimate, as long as it is visible: - **Mark it** in the design library as not yet available in code, with the release it is expected in. - **Keep it apart** from the default set designers insert from, for example in a preview area, so it is not picked up by accident. - **Check at handoff**: design reviews confirm every component in a handoff exists in code on the target platform, or has an agreed date. - **Close the gap**: when the code ships, remove the marking in the same release. ## Availability per platform A system that serves the web and native mobile rarely ships every platform on the same day. The native packages may follow the web package by a release or two. Communication should say so explicitly: - The release notes list which artifacts carry the change: design library, web package, each native package. - The component's documentation page shows the same availability, so a designer working on the mobile app can see that the new card is web-only for now. - Native teams get a planned date, not silence, so they can schedule their own adoption. ## Making it routine Coordination fails when it depends on individuals remembering to talk. Make it part of the release process instead: the release checklist includes publishing the design library, the notes template has sections for design and code, and the release is not announced until both are out or the gaps are stated. Checking afterwards whether the two sides still match is a separate audit activity; the release process's job is to stop them diverging at the moment of release. The principle is simple: a design system makes one promise to two audiences, and the release is the moment that promise is kept or broken for both at once.