Token Sync Across Tools

Position this module against the audits in Module 4. Audits told you where the codebase had drifted from the system; this module is about a different drift — the same token existing in Figma, on a canvas, and in code, with three slightly different values and nobody sure which one is current. Every team that has run a design system for more than a year recognises the problem, because every tool wants to be the home of the tokens and none of them stays in sync on its own.

Set expectations about what gets solved. The mechanical re-entry — copying a hex value from a Figma variable panel into a CSS file, or redrawing a swatch board after a palette change — is exactly the kind of work agents do well, and the module shows it working with traced runs from this school's own repository. What does not get solved is the decision about which copy wins when they disagree. That stays human, and the module spends a full slide on why silent overwrites are the failure mode to design against.

If participants are arriving without Figma or a connected canvas in their stack, reassure them early: the pattern is source of truth, agent-run sync, and a divergence gate. The specific targets are interchangeable, and the exercise at the end works for any combination of tools.

Walk the list slowly, because the slide is really an inventory exercise in disguise — the module's closing exercise asks participants to do exactly this for their own system. The first three locations are the ones everyone names: the design tool's variables and styles, some kind of canvas or spec surface, and the code targets. The fourth and fifth are the ones that cause the embarrassing incidents: the styleguide site that still shows last year's blue, the pitch deck template with a hex value someone eyedropped in 2024.

Make the mechanism of drift concrete. Nobody decides to let copies diverge. A colour gets tweaked in code during a contrast fix and nobody updates Figma. A designer adjusts a Figma variable for a campaign and assumes engineering will notice. A canvas board is redrawn from memory. Each individual change is small and reasonable; the sum is three sources that all claim authority and a team that resolves the difference by asking whoever has been there longest.

The agent-relevant point: every one of these copies is also something an agent might read. If an agent pulls token values from a stale canvas or an old doc, the drift propagates into new work. Sync is not just hygiene for humans — it protects the quality of everything the agents build on top of the system.

The table is a decision aid, not a verdict. Code-first means the repository's token files are where changes happen, and everything else is generated; it inherits git's review, history, and CI for free, which is why this school's own system and most of the worked examples in this course take that route. Design-tool-first keeps the decisions where many design teams already make them — Figma variables and published libraries — and as of June 2026 the Figma MCP server reads variables well, while writing to the canvas is newer, beta-flagged in places, and gated by authentication and plan level. Canvas-first treats a file-backed canvas like Pencil's .pen files or an OpenPencil project as the source; it is the most agent-native option but the youngest ecosystem.

The row that matters most is changes arrive as. A source of truth is only as good as its review path. Git gives you diffs, approvals, and a history that answers who changed this and why. Figma gives you library versioning, which is real but coarser. A canvas gives you whatever its file format supports — diffable if it is text-backed, opaque if it is not.

Whatever participants choose, the non-negotiable is singularity. Two sources of truth is the same as none: every disagreement becomes an archaeology project. The rest of the module assumes one source has been picked and everything else is a mirror.

Map this onto the loop from the fundamentals course so it feels familiar rather than new: read and diff are the plan phase, propose is the plan presented for review, apply is generation, and the verification re-read plus the log are the critique evidence. The reason to insist on this shape rather than a fire-and-forget script is that token sync touches surfaces owned by different people — a designer's Figma library, an engineer's theme file — and unreviewed writes into someone else's surface is how trust in the whole system gets burned.

The diff per target detail matters. The Figma mirror might be missing two new tokens, the canvas might be one rename behind, and the docs might be perfectly current. A single global is everything in sync answer hides that texture and forces all-or-nothing updates. Per-target diffs let you approve the cheap updates immediately and hold the contentious one.

Also stress the diff in token terms point. The agent should report primary-600 changed from #2f4ec4 to #2454d8 in the source; Figma still has the old value — names and values, the same vocabulary the team uses. Screenshot comparison has its place in visual QA, but for tokens the comparison should happen at the level the decision is made.

Walk the diagram left to right. The source card is human territory: the token files in the repository, semantic names, changed only through a reviewed pull request, every change versioned and logged. The agent sync run in the middle is the previous slide drawn as a box: read, diff per target, propose, apply under review. The three mirrors on the right are the usual suspects — Figma variables written over MCP or through a local plugin, a connected canvas whose token boards are rebuilt by script rather than redrawn, and the built code outputs like the Tailwind theme and the token documentation, which CI checks against the source.

Point at the direction of the arrows, because the direction is the policy. Values flow outwards from the source. The only things that flow back are reports: a drift check on each edge that notices when a mirror was edited directly, and the divergence gate at the bottom where a human decides whether that edit becomes a pull request into the source or gets reverted in the mirror.

The gate is the part teams skip and regret. Without it, the sync script either clobbers a designer's deliberate change — and the designer learns to distrust the sync — or it quietly tolerates the difference, and you are back to three sources of truth. Either failure kills the system socially before it fails technically.

Keep the table at the level of what it means for sync rather than a tool tour. Figma's remote MCP server reads well: get_variable_defs returns the variables and styles used in a selection, and search_design_system can find tokens across libraries. Writing is the newer half — the write-to-canvas tools can create and edit variables and styles, but they sit behind OAuth, plan level, and, in larger organisations, admin allowlists. The field note this module draws on hit exactly that wall: the standalone remote client was rejected at OAuth registration with an HTTP 403 before it could even list tools, while the same server worked fine through an already-authenticated agent. Plan for the authentication boundary to be the weakest link.

Paper runs a local MCP server from its desktop app, which makes reads and writes straightforward when the app is open — get_computed_styles and get_jsx for reading, write_html and update_styles for writing — with the practical caveat that long agent sessions can drop the connection. Pencil and OpenPencil are file-backed: the design file lives in or alongside the repo, so the agent can treat it like any other text artifact and rebuild token boards by script.

The last row is easy to overlook. Code targets that are generated from the source — the Tailwind theme, the docs page — should say so in a header comment, so nobody hand-edits a file the next sync run will regenerate.

The commands are deliberately unremarkable: one line to register the Figma remote server, one for Paper's local server, and a pair of npm scripts for the file-backed OpenPencil target. The capability that matters is in the first bullet — multiple MCP servers active in the same agent session. That is what allows a single run to read variable definitions from Figma and write matching boards to a canvas, or read the repo's token files and push values out to both tools, without a human ferrying values between windows.

The npm-script wrapper is a habit worth defending. A sync that only exists as a prompt someone types from memory is not a pipeline; wrapping the build, the push, and a status command in scripts makes the run repeatable, lets CI or a schedule trigger it, and gives you a dated record — this school's repo writes a sync status file precisely so the next run starts from evidence about what worked and what was blocked, instead of from memory.

Date-stamp the claims when you teach this live: endpoints, plugin names, and auth flows in this table have all changed within the last year, and the slide says as of June 2026 for that reason. The structure — register the servers, scope the permissions, script the run — outlives any individual command.

This is the cultural core of the module. A designer who adjusts a Figma variable directly is usually not being careless — they hit a contrast problem during a review, or a campaign needed a tone shift, and the canvas was the surface in front of them. If the next sync run wipes that change without a word, the lesson they learn is that the sync is dangerous, and they will quietly stop using the shared variables at all. The drift is annoying; the silent overwrite is corrosive.

So the rule is mechanical: before writing, the run compares each mirror to the source and to the last synced state it recorded. Anything that changed in the mirror since the last run is presented as a report — here is the token, here is the source value, here is the value someone set directly, here is when. The human decision has exactly two outcomes: the edit was right, so it becomes a pull request into the source and flows back out to every mirror on the next run; or the edit should not stand, so it is reverted in the mirror, ideally with a note to whoever made it explaining where the change should have gone.

Keeping the last-synced state is what makes this tractable — without it you can see that two values differ but not which side moved. A small JSON snapshot per target, written at the end of each successful run, is enough. The change log records the decision either way, which keeps the history honest and stops the same argument re-running every quarter.

Versioning sounds like ceremony until the first time two surfaces disagree and nobody can say which one is current. The minimum viable paper trail is small: token changes arrive as pull requests, so there is a diff and an approval; a change log gets a dated entry saying what changed and why; and the token set carries a version marker — a number, a date, or simply the commit hash — that mirrors and audit reports can reference. With that in place, a stale mirror is a fact you can establish in seconds rather than a debate.

The sync run itself contributes to the trail. Each run should record which source version it pushed, which targets it touched, and what it skipped or could not reach — the blocked Figma write in this module's worked example is recorded exactly that way, as a dated status entry rather than a vague memory that the push did not work. That record is also what makes the divergence check from the previous slide possible.

Distinguish value changes from breaking changes. Adjusting the value behind an existing semantic name is cheap and flows through sync automatically. Renaming or removing a token breaks every consumer that references it — in code, on the canvas, and in any agent instruction that mentions the old name — so those changes get called out in the log with a migration note, and they are a good candidate for the agent-assisted migration workflow rather than a quiet find-and-replace.

This run is documented in two of the school's field notes — the OpenPencil sync experiment and the Figma MCP push — and the numbers and failure are from those notes, not a hypothetical. The source is code-first: the semantic colour lives in globals.css, and the change was an ordinary pull request. Everything after that point is generation. The repository's sync loop watches DESIGN.md, the app and component folders, and the token files; on change it rebuilds a machine-readable design-system inventory and regenerates the OpenPencil canvas from it — the foundations board with the colour tokens, and full-length snapshots of the affected pages. Nobody redrew anything.

The Figma leg is the honest part. The same inventory feeds a Figma-shaped payload — frames, token hierarchy, component variants, sliced page snapshots. The elegant path, pushing it through the remote Figma MCP server with a standalone client, was rejected at the authentication boundary: HTTP 403 during OAuth client registration, connection closed before tools were even listed. The status file records that as blocked, with the date. The fallback that shipped is a local Figma development plugin that reads the generated payload and writes the frames directly inside the file — boring, reliable, and entirely offline from the remote endpoint.

Two lessons to draw out. First, sync is mostly a payload problem: once the inventory existed as JSON, retargeting from OpenPencil to Figma was a renderer change, not a rethink. Second, the failure was valuable because it was recorded — the next attempt starts from evidence, not memory. That is the difference between a sync pipeline and a demo.

The authentication boundary deserves the most airtime because it is the one teams cannot prompt their way around. Remote design-tool MCP servers sit behind OAuth flows, seat types, plan levels, and — in larger organisations — admin allowlists for third-party clients. The worked example's 403 is typical, not exceptional. The mitigation is architectural: keep a local write path that does not depend on the remote endpoint at all — a development plugin, a file import, a CLI against a file-backed canvas — and treat the remote path as an optimisation you adopt when it works.

The fidelity gaps are smaller but real: bridges between tools translate imperfectly, so SVG fills can arrive as rasterised images, spacer elements get ignored, and very large or deeply nested files can error outright. Scope sync to the token and component boards rather than trying to mirror an entire design file, and the problem mostly disappears. Connection drops in long-running sessions are an annoyance with a known fix — restart the session — and not worth engineering around.

The last two are organisational. A second source of truth re-emerges whenever one group's mirror is easier to edit than the source is; the fix is usually to make the source's change path lighter, not to police the mirror harder. And sync theatre — runs that always report green because nothing checks for drift and nobody reads the status file — is the same disease as gate theatre in the previous module. A sync you do not verify is a rumour.

Keep the exercise deliberately manual. The temptation is to point an agent at the problem immediately, but the map of where tokens live is mostly organisational knowledge — which team edits the Figma library, whether the marketing templates are anyone's job, whether the canvas is even current — and that knowledge is faster to write down than to rediscover by tooling. The agent earns its keep on the next step, the recurring sync, not on the first inventory.

The three-token spot check is the part that converts this from a tidy diagram into a finding. Checking one colour, one spacing value, and one type size across every location takes a few minutes and almost always surfaces at least one disagreement — and a concrete disagreement, with file paths and screenshots, is far more persuasive inside a team than a general argument that drift probably exists.

The nomination question is the one to push on if you run this live. The justification sentence should be about where decisions and review actually happen — not about which tool people like. A team whose engineers never open Figma and whose designers never open the repo has a genuinely hard call to make here, and surfacing that tension now is cheaper than discovering it after the sync is built. The retire column matters too: every copy you can delete is a copy you never have to sync.

Recap by connecting the slides into one sentence: choose where token decisions happen, make every other copy a generated mirror, run the sync as a reviewable agent run with a drift check on every edge, and route disagreements to a human decision that gets logged. The worked example showed all of it, including the blocked Figma write — keep pointing at that, because the willingness to record a failure honestly is a better predictor of a sync pipeline surviving than any individual tool choice.

Bridge to Module 6 by zooming out. This module built one recurring run; the audits in Module 4 built another; the documentation generation mentioned throughout is a third. The final module assembles them into a standing maintenance loop — scheduled runs, proposed fixes arriving as reviewable changes, a small human rotation that approves rather than produces — and is honest about what still needs people: deprecations, taste shifts, and the breaking changes this module flagged in the change-log slide.

If participants did the mapping exercise, ask them to keep the page. Module 6's exercise — drafting the maintenance loop on one page — uses that map as its starting input, the same way Module 4's audit findings feed the fix queue.