design-system-audit

Measures existing code and Figma design systems to size a token retrofit.

77|11|Updated Jun 2, 2026
One-click install
npx skills add https://github.com/jrpease/throughline --skill design-system-audit-jrpease
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: design-system-audit
Source: https://github.com/jrpease/throughline/tree/main/skills/design-system-audit
Command: npx skills add https://github.com/jrpease/throughline --skill design-system-audit-jrpease

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Retrofitting a mature design system onto tokens is risky without knowing its true size: how many hard-coded colors live in the codebase, how many Figma variables and bindings exist, and how much is already semantic. This Skill measures both sides before anything is built or changed, so the retrofit effort is right-sized and nothing is blindly renamed or destroyed. ## Core Features & Use Cases - Code surface measurement: Runs a configurable grep scaffold that counts SCSS color variables, Tailwind color classes, JS color usages, raw hex/rgba literals, and SVG fills, with tunable patterns per repo. - Verified Figma inventory: Independently reads variables, consuming bindings, text styles, effect styles, and modes, re-reading suspicious empty results instead of guessing. - Semantic percentage scoring: Computes a 0-100 percentSemantic score that decides whether the retrofit is a rename-in-place cleanup or a rewrite, and records documentation debt for planning. - Use Case: A team with a five-year-old codebase and a drifted Figma file runs the audit, learns they are ~90% semantic with 1,200 bindings, and confidently plans a rename-and-cleanup retrofit instead of a rebuild. ## Quick Start Audit my existing design system by measuring the color usage in my repo and inventorying the variables, styles, and bindings in my connected Figma file.

Frequently Asked Questions about design-system-audit

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit an existing design system before migrating to tokens?

Run this audit skill to measure both sides of the system: it greps the codebase for color usage across SCSS, Tailwind, JS, hex literals, and SVG fills, then inventories Figma variables, bindings, and styles. The result is a manifest with counts and a percentSemantic score that sizes the migration.

What does the percentSemantic score mean in a design system audit?

percentSemantic is an integer from 0 to 100 estimating how much of the system is named by role (like text/default) versus raw values (like grey-900 or hex). A high score near 90 means the retrofit is mostly renames and cleanup; a low score indicates closer to a rewrite.

Does the design system audit work without Figma connected?

The code-surface measurement works on any repo regardless of Figma connection. The Figma inventory step requires figma.connected set to true; if it is not connected, the skill offers to run figma-environment-setup first.

Can the color grep patterns be customized for my repo conventions?

Yes. The shipped patterns are defaults, and you can supply a --config JSON file mapping each category to custom file and pattern regexes tuned to your repo's actual prefixes and accessors. The audit reports which categories used defaults versus tuned patterns.

Will the audit modify or rename anything in my design system?

No. This is strictly a measurement skill that never builds, renames, or deletes anything. All changes belong to downstream skills like token-builder and the retrofit phases.