Audit Your Libraries for Drift and Off-Token Debt

Workflow area: Design Systems · Tier: Core · Hands-on time: ~35 minutes

Drift is compound interest working against you. Every off-token color is a value the next theme change misses; every detached instance is a component update that will silently not arrive; every near-duplicate is a decision future designers must re-make. None of it is visible in any single file — drift is a population-level problem, which is why manual audits die of tedium halfway through. AI changes the economics of the sweep: the Figma agent and analytics can enumerate the population, and a model can cluster the findings into patterns. What they cannot do is decide which debt is worth paying down first — that is a judgment about roadmap, risk and effort, and it is the audit's actual product. And with your system now feeding AI generation (pb-26, pb-38), drift compounds twice: machines trained on a leaky system generate leaks at machine speed.

When to use — and when not to

• Use it on a quarterly cadencedrift accumulates continuously; a standing audit keeps the debt curve flat instead of discovering it at rebrand time.
• Use it before a token or theme migrationevery off-token value is a spot the migration will miss; the sweep is the migration's risk register.
• Use it before restructuring your system as AI contextpb-38's generation rules are only as good as the library they describe; audit first, restructure second.
• Skip the full sweep during active consolidationif last quarter's plan is still being executed, re-auditing measures churn, not progress; finish, then re-baseline.
• Skip auditing files that are officially deadarchive them instead; a sweep of abandoned explorations produces findings nobody will ever fix.

The recipe

1. 1.

   Define the scope and pull the instrumentation. Choose the library plus the three to five highest-traffic product files — auditing everything first time out produces a report too big to act on. Pull Figma library analytics for the baseline numbers: component insert and detach counts, and which teams use what. Detach counts are your first drift map — a component with a high detach rate is either broken or missing a variant people need.

2. 2.

   Sweep for off-token values. Run the Figma agent (or an audit plugin) over the scoped files with instructions per category: "Find every fill, stroke and text style not bound to a library token or style — list file, layer name, raw value, and frequency." Do the same for spacing and corner radii against your scale. Export the raw findings.

3. 3.

   Cluster the raw findings into patterns with a model. Paste the export into Claude:

   Copy

   These are raw drift findings from our design-file audit: off-token
   values with file, layer, value, and count. Token scale attached.
   
   1. Cluster them: which off-token values are NEAR-TOKENS (within
      rounding of a real token — likely sloppiness) vs. NEW VALUES
      (used repeatedly — likely an unmet need) vs. ONE-OFFS?
   2. For repeated new values, infer what need the token scale isn't
      meeting (e.g. #6B6F76 used 41 times ≈ a missing mid-gray text
      token).
   3. Rank clusters by blast radius: count × how central the files are.
   Output a table. Do not merge distinct values, and keep every count.
   

   This reframing is the audit's pivot: near-tokens are hygiene fixes, but repeated new values are the system telling you what it is missing. Drift is feedback, not just crime.

4. 4.

   Hunt the near-duplicates and detachment hotspots. Screenshot suspect component sets side by side and ask the model: "These five card-like components come from our files — describe the actual differences in structure, props and use. Which are genuine variants and which are re-inventions?" Cross-reference with the analytics: a component that was re-invented three times and detaches constantly is one component with a design problem, not four findings.

5. 5.

   Write the consolidation plan — prioritized, evidenced, sized. The deliverable is a plan someone can execute:

   Copy

   #  FINDING                        EVIDENCE            IMPACT  EFFORT  ACTION
   1  #6B6F76 used 41x in 3 files    [links to 5 cases]  High    Low     Add text-secondary
                                                                         token; migrate
   2  Card re-invented 4x            [component links]   High    High    Consolidate to 1 +
                                                                         2 variants; deprecate
   3  Button detach rate 22%         analytics + cases   High    Med     Add icon-trailing
                                                                         variant (top detach
                                                                         reason)
   4  Radius 6px in old files        [links]             Low     Low     Batch-fix via agent
   

   Every row links to live examples — evidence is what survives the prioritization meeting. Sequence quick wins first; momentum funds the big consolidations.

Make it yours

• Agent-assisted remediation for the mechanical rows: near-token fixes and radius normalization are exactly what generative plugins from pb-10 are for — audit finds, the plugin fixes, you review the diff.
• Trendline over snapshots: keep each quarter's headline numbers (off-token count, detach rate, duplicate families) in one sheet — a system's health is the slope, not the level, and the slope is what convinces leadership to fund stewardship.
• Pipe findings into generation rules: every consolidated decision ("one Card, two variants, never detached") goes verbatim into pb-38's generation-rules file, so AI output stops reproducing the drift you just cleaned.

Quality check

• Every finding has a link to a live instancea count without cases cannot be verified, sized, or believed.
• Near-tokens and new-values stayed separatebulk-fixing a repeated new value as sloppiness deletes the unmet need it was documenting.
• Detach reasons were investigated, not just countedthe top three detach causes name the variants your library owes people.
• The plan is sequenced by impact and effortan unranked findings dump is an audit that ends as a Slack message instead of a roadmap item.
• Deprecations have a destinationevery component marked for removal names its replacement and a migration note; deletion without a path just mints fresh drift.