The design system that stays in sync: living components, tokens, and docs
Every design system is born in sync and drifts apart over time, because components, tokens, and documentation evolve at different speeds. An agent with access to Figma, the repository, and the docs audits that drift continuously, before it becomes a visual bug in production.
Every company that grows creates, at some point, a manual: the brand's official color, the font, the spacing between elements. On the day that manual is born, everything matches, the document, the product, the printed material, all with the same blue, the same font. Except time passes, someone changes the blue in the product to a darker shade without telling anyone, the manual keeps the old blue, and six months later nobody knows what the brand's real blue is anymore. Each piece became its own source of truth, and they disagree with each other without anyone having decided that on purpose.
The finance team sets the quarter's gross margin target in a model spreadsheet, 42%. The BI dashboard leadership checks every day was configured with that target two quarters ago, and nobody updated the parameter. The slide that goes to the board, in turn, was copied from an earlier version of the presentation and still shows 38%. Three places, three numbers for the same target, and the board meeting only discovers the divergence when someone asks, live, which number is correct.
The firm updates the standard price-adjustment clause in the service agreement after losing a dispute over the correction index. The master template in the document management system was fixed. Except the precedent saved in the internal research base still cites the old clause as a reference, and a contract signed two months ago, generated from a local copy of the template, also got left behind. The divergence only shows up when a client complains about a clause the firm already thought was outdated.
The brand guide defines the official blue in hexadecimal, and the team updates that value after a visual repositioning. The site's CSS receives the update the following week. Except the printed material the distributor uses, a catalog still in stock, was printed with the old blue, and the institutional slide sales uses in meetings also wasn't updated. The brand speaking three different languages at once, without anyone having decided that.
The job and salary matrix defines the range for the mid-level engineering position. The offer letter template recruiting uses was updated with the new range. Except the careers page on the site still shows the old range, published a year ago, and a manager who just joined, unaware of the update, offers the candidate the value they remember from an old conversation. Three different ranges for the same role, circulating at the same time within the company itself.
The PRD for a new feature defines the acceptance criteria precisely. The feature goes to production, but with a last-minute adjustment nobody documented back into the PRD. The changelog support uses to answer customers still describes the original behavior, what existed before the adjustment. The customer discovers the divergence first, in a support ticket, not the internal team.
The official price table in the CRM has the updated value after the annual adjustment. The PDF price spreadsheet an older salesperson keeps on their computer still has last year's value, and they don't even know a new version exists. They close a deal at that old price, in good faith. The discrepancy only shows up when finance reconciles the signed contract against the current table.
The level-2 support SOP (standard operating procedure) is updated after a process review. The new training material enters next month's track, but the team already working the operation keeps following the old habit, because nobody told them the procedure changed. Three versions of the right way to do it coexisting in the same operation, and the SLA breaks silently.
The data retention policy is updated to match a new LGPD requirement. The system that actually applies that retention, deleting data after a deadline, keeps running with the old deadline, because the policy change never became an IT ticket. The auditor checks the system, finds the old deadline, and the control that looked ready on paper fails in practice.
The API documentation describes a field as optional after a decision to simplify the contract. The production endpoint, due to a deploy oversight, still requires that field as mandatory. The SDK clients use to integrate was generated from the new documentation, so it doesn't even send the field, and the call breaks in production for the client who followed the documentation to the letter.
Tuesday morning, you open Figma to design a new screen and use the Primary Button component from the library. It has the new blue the team approved last week. Except when the developer implements the screen, the production component still uses the old token, because nobody updated the value in the code after the change in Figma. And the design system's documentation, the guide any new team member consults, still shows a screenshot from three months ago, with an even older blue. Three places, three versions of the same truth. Nobody cheated, nobody was careless on purpose: each place simply evolved at its own speed, and the drift only shows up when someone notices the button is one color in one place and a different color in another.
The annual strategic plan sets the target of expanding into three new markets by year end. The OKR system where the team tracks progress week by week was configured with that target at the start of the year. Except the quarterly report that goes to the board was updated once, when the target dropped to two markets, and the OKR never received that correction. The review meeting turns into a discussion about which document is correct, instead of a discussion about the strategy itself.
Whoa, let me tell you about the most tedious, and most common, scene on any team working with a design system. You fix the button's blue in Figma on a Tuesday morning, feel that relief of having solved it, and three months later discover the product in production is on a different blue, and the documentation on a third one still. Nobody lied. Nobody was careless on purpose. Each place simply followed its own rhythm, with nobody on duty keeping the three of them in sync. This lesson is about that drift that's born on its own, and about how to put an agent on watch for it before it becomes a bug your customer sees before you do.
The core idea of this lesson. Every design system is born in sync: the Figma component, the design token, and the written documentation agree with each other on the day you create the system. The problem is the three evolve at different speeds, and nobody has time to keep all three updated at once. That's design system entropy: over time, each piece drifts from the other, silently, until a visual bug in production exposes the divergence to your customer. The fix isn't relying on someone's memory to keep everything matching. It's having a single source of truth for the token, name, value, and usage, and an agent with access to the code repository, the design file, and the documentation, continuously auditing whether the three still agree. You don't avoid the drift, it's inevitable. You start detecting it before the customer detects it for you.
01Design system entropy: sync once, drift forever
Think of a freshly poured foundation, leveled with millimeter precision the day it's cast. Nobody expects it to stay perfectly level forever without maintenance, the ground settles, the structure shifts, and that's why periodic building inspections exist. A design system works the same way. On the day you create the component, the token, and the documentation, all three are born matching. But each one lives in a different place, with a different owner and a different update rhythm: the designer touches Figma when redesigning a screen, the developer touches the code when shipping a sprint, and the poor documentation only gets remembered when someone needs to check it and can't find what they need.
Nobody decides to drift apart. It's the natural result of three clocks running at different speeds. And the worst part is the drift doesn't announce itself: it stays invisible until the day someone notices a button in one place isn't the same button as in another, and by then it's usually too late, because the customer who noticed first was the one using the product, not the one maintaining the system.
02The token as the single source of truth
Here's the piece that solves the problem at the root, instead of patching the symptom. A design token is the name given to a visual value, "primary-color," "default-spacing," "card-border-radius," together with the exact value it carries and where it should be used. The core idea is simple to state and hard to maintain without help: the token lives in a single place, and Figma, code, and documentation pull from that place instead of each one keeping its own separate number.
Think of it this way: just as a business needs a structured record the machine can read without inventing, your design system needs a structured contract, name, value, usage, that any tool can consult without guessing. As long as the token remains that single source, changing the blue becomes a single event, in one place, that propagates. The day each piece goes back to keeping its own number, you reopen the door to the entropy from the previous section.
For the board. A token isn't "the pretty color you picked." It's the contract: a stable name ("primary-color"), an exact value (the hex code, the pixel, the scale), and a usage rule (where it should appear). If Figma, code, and documentation agree to read that contract from the same place, they have no way to disagree with each other. If each one keeps its own copy of the value, disagreement is just a matter of time.
03The agent audits continuously, you don't need to wait for the bug to show up
With the contract defined, what's missing is the part nobody has time to do manually every month: checking whether the three ends, Figma, code repository, and documentation, still agree with the token. That's exactly where an agent with access to all three sources becomes genuinely useful. It reads the token's value in the design file, reads the equivalent value used in the component's production code, reads what the documentation states, and compares the three. When it finds a divergence, it points to exactly where: "Figma says one thing, the code says another, the docs have been out of date for X time."
Notice the shift this represents. Before, you discovered the drift in the most expensive way possible: a customer noticing a button looks different, or a visual bug reported in production. Now, the audit happens before that, routinely, on a cycle you define, weekly, every deploy, whatever makes sense for your team. The agent doesn't decide on its own which value is correct, it doesn't know whether the new blue in Figma is intentional or a mistake by whoever touched it. It just shows you the divergence so you can decide: update the code to the new value, or revert Figma to the old value. The decision remains yours. The work of watching the three clocks, that's what it takes off your shoulders.
04The map: keeping in sync is a routine, not a one-time event
Close this lesson's reasoning with an idea worth more than any specific tool: keeping a design system in sync isn't a project that ends, it's a routine that continues. You don't "solve" entropy once and for all, you install a cheap way to detect it early, always. The structured token is the piece that gives the agent something objective to compare, without it it would be guessing just like an AI reading a site with no schema. And continuous auditing is what trades "discovering it via the customer" for "discovering it before the customer."
This also ties back to what you saw in previous lessons in this track: live research feeds decisions with a real corpus, the prototype tested with a synthetic user reduces risk before the real human, and now the maintained design system guarantees that the good decision you made keeps holding six months from now, instead of becoming a forgotten exception in a corner of the product.
Now build
Choose three central components in your real task, the ones that appear on almost every screen: for example, primary button, input field, and card. For each one, check whether the token's name and value match in all three places:
- In Figma: open the component in the library and see the name and value of the color token (or spacing, or border radius) it uses.
- In the code: ask an AI with access to the repository to locate the equivalent component and show which token (or raw value, if it uses no token at all) it references.
- In the documentation: check whether the design system guide, if it exists, describes the same name and the same value you saw in the previous two places.
Note, for each of the three components: did it match in all three places, or did you find a divergence? If you found one, that's your first maintenance backlog, and it's exactly the kind of check an agent can run routinely, instead of you repeating this manual exercise every month.
Practice
1. Why does a design system drift apart over time even when nobody was careless on purpose?
2. What makes a design token work as a single source of truth, instead of just another loose copy of the same value?
3. What's the right role of an agent with access to Figma, the code repository, and the documentation, in maintaining a design system?
4. What's the real cost of discovering a design system's drift only when it becomes a visual bug in production, instead of detecting it through continuous auditing?
Fair? Let's close the message of this lesson together. Every design system is born in sync and drifts apart over time, because Figma, code, and documentation evolve at different speeds, and nobody has time to keep all three in sync manually. The fix isn't one person's heroic vigilance, it's a token that works as a single source of truth, name, value, usage, and an agent with access to all three ends continuously auditing whether they still agree. You trade "discovering the bug via the customer" for "discovering it in the routine audit, before it gets there." Maintaining a design system isn't a project that ends, it's a habit you install once and repeat always. Next.
Thanks for the feedback. It helps sharpen the next lesson.