Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 36 ยท Projects and Practice

Project: Design System Audit

Audit a Figma file for detached instances, hard-coded colors and inconsistent spacing, then fix it with variables, components and a clear action plan.

Every real design file drifts. Colors get eyedropped instead of using variables, instances get detached "just this once", and five slightly different grays appear. An audit finds that drift, measures it, and turns it into a short list of fixes. This is the capstone project: you will audit a messy Figma file (your own, or a team file you are allowed to inspect) and clean it up.

Figma cannot run on this site, so you work in Figma yourself. The code blocks are labelled JavaScript stand-ins: an audit script that runs on a small mock "file" so you see how an automated check thinks. In a real file you would use the plugin API or the REST API to collect the same data.

What to look for

Problem Why it hurts How to find it
Hard-coded colors Dark mode and rebrands break Select all, look at the Selection colors section in the right panel: unbound colors show hex values, bound ones show variable names
Detached instances No updates, no analytics Layers with a frame icon where a component was expected; the library analytics page; plugins
Near-duplicate values Visual noise (gray #64748B vs #667085) Count distinct values
Off-grid spacing Misaligned layouts Compare padding and gaps to the scale
Unnamed layers Hard handoff Names like Frame 842
Missing states Gaps in development Review each component's variants
Low contrast Accessibility failures Contrast checker plugin or calculation

Step 1: take inventory

Before fixing anything, collect numbers. Use the Selection colors panel on each page, a plugin that lists local styles and unused components, and the library's analytics. Record counts in a simple table: total frames, instances, detached frames, distinct colors, distinct font sizes.

Step 2: audit colors and tokens

The stand-in below takes a list of fill colors found on a page, groups near-duplicates and reports which should be merged into a token. Colors that are close to each other (by Euclidean distance in RGB) are probably meant to be the same.

JS Stand-in: find near-duplicate colors

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Decide a canonical value for each cluster, create or reuse a semantic variable, then bind. In Figma, select layers and use Selection colors to replace a hex with a variable in one step for every layer that shares it.

Step 3: audit spacing

Spacing that is not on a scale shows up as odd numbers (13, 17, 22). Check padding and gaps against your 4 px scale.

JS Stand-in: off-scale spacing report

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Fix by binding auto layout padding and gap to space/* variables. Where a value is a deliberate exception, leave it and add a note.

Step 4: audit components

Walk the Components page and test each main component against a checklist: all states exist, auto layout is used, variables everywhere, layer names are consistent, a description exists, an accessible focus state is present. Then check usage: which components are never used (candidates for removal) and which patterns are repeated as detached frames (candidates to become a new component).

JS Stand-in: detached frame and usage summary

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 5: score the audit

A single score helps teams track progress. Pick weights that reflect your priorities, and recompute after each cleanup session.

JS Stand-in: weighted audit score

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 6: fix in priority order

  1. Quick wins: bind colors with Selection colors; name key frames; delete unused layers and empty pages.
  2. Structure: turn repeated detached frames into components; add variants instead of copies; add properties.
  3. Systems: introduce variables and modes, a semantic layer and a spacing scale.
  4. Governance: publish, version and document; assign an owner and a request process.
  5. Prevent drift: schedule a short audit every quarter, and add a "before you detach" note to your guidelines.

Do not try to fix everything in one go. Merge in small steps and publish a changelog, because large swaps can break overrides.

Deliverables

  • A one-page audit report: the metrics table, top five problems, a screenshot of the worst offender (from your own file), and the plan.
  • A cleaned file with a changelog page.
  • A checklist the team can reuse.

Stretch goals

  • Write a real plugin (see Exporting Assets and Plugins) that lists unbound fills in the selection.
  • Use the REST API to pull a file and compute the score automatically.
  • Track the score over time in a spreadsheet.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where in Figma can you see which fills are hard-coded versus variable-bound?

    Selection colors lists each color in the selection and shows variable names where bound.
  2. 2. Two grays differ by a tiny RGB distance. What is the best action?

    Near-duplicates are usually mistakes and should become one token.
  3. 3. Many frames named 'Button copy' suggest...

    Copies of components that were detached are a common drift sign.
  4. 4. What is the best way to fix a large file?

    Incremental cleanup is safer and keeps teams informed.

Summary

  • Audit for hard-coded colors, near-duplicates, off-scale spacing, detached instances, unnamed layers, missing states and low contrast.
  • Measure first, then score, then fix in priority order.
  • Use variables, components and variants to remove drift; publish with a changelog.
  • Schedule regular audits so the system stays healthy.

Next: Back to the Figma tutorial