Design System Handoffs That Survive the Agency Leaving

Most design systems built by an outside team look healthy on the day of handover. The Figma library is tidy, the component docs site loads, and the final demo goes well. Six months later the client team is copying hex values out of old screens, a second button component has appeared in the codebase, and nobody is sure whether the spacing scale is still the one in the docs.

That decay is rarely about skill. It happens because the system was never really handed over. The files moved, but the decisions, the pipeline and the habits stayed with the people who left. This article covers what a real handover looks like: what the client should own, how to structure tokens and components so a smaller in-house team can extend them, which documentation earns its keep, and a two-week transition plan you can copy.

1. What “owned by the client” actually means

Ownership is a list of things, not a feeling. Before any handover meeting, check that the client controls each of these, under their own accounts:

• Source design files. The Figma (or Penpot, or Sketch) team and the published libraries sit in the client’s organization, with at least two client-side admins. A library published from an agency workspace stops updating the moment that workspace seat is cancelled.
• The token source of truth. One repository or folder holds the design tokens as data (usually JSON), and everything else is generated from it. If tokens only exist as Figma variables, the code side will drift.
• The token pipeline. The build step that turns token JSON into CSS variables, a Tailwind theme, iOS and Android values, or whatever the platforms need. It should run in the client’s CI, not on a contractor’s laptop.
• The component repository. The coded components, their tests and their release process, in the client’s Git organization, with their own package registry access.
• The documentation site. Hosted on the client’s domain and deploy account, built from the same repo as the components so it can’t fall behind silently.

If any one of these lives somewhere the client can’t reach, they don’t fully own the system yet. They own a copy of it.

2. Structure tokens so someone else can extend them

The most common token mistake is a flat list of values named after where they were first used: header-blue, card-shadow-2, promo-red. It works for the original team because they remember the context. A new team can’t tell which tokens are safe to reuse.

A three-tier structure solves most of this:

1. Primitive tokens hold raw values with neutral names: the full colour ramp, the spacing scale, font sizes, radii. Nobody uses these directly in components.
2. Semantic tokens describe intent: color.text.default, color.surface.raised, color.border.danger. They point at primitives. This is the layer that changes when you add dark mode or rebrand.
3. Component tokens (optional, used sparingly) cover the few places where a component needs its own knob, such as button.primary.background. They point at semantic tokens.

Here is a trimmed example in the W3C Design Tokens format, which tools like Style Dictionary and Tokens Studio can read:

{
  "color": {
    "blue": {
      "500": { "$type": "color", "$value": "#2563eb" },
      "600": { "$type": "color", "$value": "#1d4ed8" }
    },
    "neutral": {
      "0":   { "$type": "color", "$value": "#ffffff" },
      "900": { "$type": "color", "$value": "#111827" }
    },
    "text": {
      "default": { "$type": "color", "$value": "{color.neutral.900}" },
      "inverse": { "$type": "color", "$value": "{color.neutral.0}" }
    },
    "action": {
      "primary":       { "$type": "color", "$value": "{color.blue.500}" },
      "primary-hover": { "$type": "color", "$value": "{color.blue.600}" }
    }
  },
  "space": {
    "1": { "$type": "dimension", "$value": "4px" },
    "2": { "$type": "dimension", "$value": "8px" },
    "4": { "$type": "dimension", "$value": "16px" }
  },
  "button": {
    "primary": {
      "background": { "$type": "color", "$value": "{color.action.primary}" },
      "text":       { "$type": "color", "$value": "{color.text.inverse}" },
      "padding-x":  { "$type": "dimension", "$value": "{space.4}" }
    }
  }
}

A few rules make this structure survive a change of team:

• Components may only reference semantic or component tokens. Add a lint rule or a simple CI check that fails when a primitive like color.blue.500 shows up in component code.
• Use the same names in design and code. If the Figma variable is text/default, the CSS variable should be –color-text-default. A designer and a developer should be able to talk about the same token without a lookup table.
• Write a one-line description on every semantic token. “Body text on default and raised surfaces” tells the next person more than the name ever will.
• Deprecate, don’t delete. Mark retired tokens with a $deprecated note and the replacement, then remove them in a planned major release.

For components, the same thinking applies. Keep the public API small and boring: a Button with variant, size and disabled is easier to own than one with fourteen props added for edge cases. Every component should have stories or examples for each state, and visual regression tests if the team can afford them. When the in-house team later needs something unusual, a small API makes it obvious whether to extend the component or build a new one.

3. Handover documentation that people actually read

Agencies often hand over a large docs site and assume the job is done. In practice the client team reads three kinds of documentation, and the rest goes stale.

Principles. One short page, five to seven statements, that explain the trade-offs the system makes. “Density over whitespace in data views” or “one primary action per screen” settles arguments that would otherwise reach the design lead every week.

Usage rules per component. For each component: when to use it, when not to, and the closest alternative. A table of do and don’t examples beats paragraphs. The “when not to use” line is the one that prevents duplicate components.

The contribution process. This is the page most handovers forget, and it matters most once the agency is gone. It should answer:

• How does someone propose a new component or token?
• Who reviews design changes, and who reviews code changes?
• How are versions numbered, and what counts as a breaking change?
• Where are decisions recorded? (A simple decisions/ folder of dated markdown files is enough.)

That decision log deserves special attention. During the build, the agency made dozens of calls: why the grid has 12 columns, why there’s no tertiary button, why the danger colour failed contrast and was darkened. If those reasons leave with the agency, the next team will either reverse good decisions or freeze in place because they’re afraid to touch anything. Ask the outgoing team to write down the ten decisions they would be most annoyed to see undone.

4. A two-week transition plan

Two weeks is enough for a mid-sized system if both sides commit people to it. The goal is that by the end, the client team has made real changes while the agency watches, not the other way round.

Week 1: transfer and shadow

• Day 1: move or confirm ownership of design files, repos, CI, package registry and docs hosting. Rotate any shared credentials.
• Day 2: walk through the token pipeline end to end. A client developer changes one semantic token and ships it to a test app.
• Day 3: walk through the component repo, tests and release process. A client developer publishes a patch release.
• Day 4: design walkthrough. A client designer updates a component in the library and publishes it.
• Day 5: the agency writes or updates the decision log and the contribution guide, then the client team reviews them and asks questions.

Week 2: reverse shadow

• Days 6 to 8: the client team builds one small new component (a badge or a tag is a good size) using the contribution process, with the agency only reviewing.
• Day 9: the client team handles one breaking change, such as renaming a token with a deprecation path.
• Day 10: final review. Anything the client team couldn’t do alone goes on a short list with an owner and a date.

The handover checklist

Use this as the sign-off list. If an item isn’t ticked, the handover isn’t finished.

Access and ownership

• • ☐ Design files and libraries live in the client’s organization, with two or more client admins
  • ☐ Component and token repos are in the client’s Git organization
  • ☐ CI pipelines, package registry and docs hosting run on client accounts
  • ☐ All agency personal access removed or downgraded to read-only after the transition

Tokens

• • • ☐ One token source of truth, stored as data
    • ☐ Primitive, semantic and component tiers clearly separated
    • ☐ Every semantic token has a description
    • ☐ Token names match between design tool and code
    • ☐ CI check blocks primitives from being used in components

Components

• • • • ☐ Every component has examples for each state
      • ☐ Tests run in CI and pass on the client’s pipeline
      • ☐ The client team has published at least one release on their own

Documentation

• • • • • ☐ Principles page written and agreed
        • ☐ Usage rules, including “when not to use”, for each component
        • ☐ Contribution process and versioning policy documented
        • ☐ Decision log with the most important past decisions

People

• • • • • • ☐ A named owner for the system on the client side
          • ☐ A named reviewer for design and one for code
          • ☐ A date set for the first review without the agency

The real test

A design system has survived the handover when the client team changes it confidently and the change doesn’t break anything. That only happens if ownership, structure and decisions all moved together. The files are the easy part. Plan for the rest from the first week of the project, not the last.

About the author

Umair Abbas is the founder of CodeFlamme, a software development agency based in Lahore, Pakistan. He writes about design systems, software development workflows, project handoffs, and long-term product ownership.