From design-system-ops
Audits Figma variable collections against three-tier token architecture best practices, checking naming conventions, tier separation, alias chains, mode coverage, orphans, and DTCG readiness. For Figma-native design systems.
npx claudepluginhub murphytrueman/design-system-opsThis skill uses the workspace's default tool permissions.
A skill for auditing Figma variable collections against three-tier token architecture principles. Produces a structured report with severity-rated findings and a prioritised remediation list. For teams whose source of truth lives in Figma variables rather than code.
Audits design system token definitions for naming violations, missing semantic tiers, and structural debt in tiered architectures. Generates severity-rated findings and prioritized remediations.
Orchestrates phased Figma design system builds from codebases: extracts tokens/components, creates variables/modes/theming, sets up foundations and structure.
Audits design token usage in code and design files for consistency, coverage, gaps, and hard-coded values. Generates reports with prioritized recommendations.
Share bugs, ideas, or general feedback.
A skill for auditing Figma variable collections against three-tier token architecture principles. Produces a structured report with severity-rated findings and a prioritised remediation list. For teams whose source of truth lives in Figma variables rather than code.
This skill applies the three-tier token architecture model to Figma variables: primitives encode raw values, semantic variables encode intent, and component-tier variables map intent to specific UI contexts. Figma-native teams treat variables as their token source of truth — this audit reads Figma directly and validates the same structural dimensions as the code-based token-audit: naming conventions, tier separation, alias chains, mode coverage, orphaned variables, and DTCG readiness.
The audit is not about enforcing a particular naming convention. It's about identifying where the variable structure is working against the teams using it.
Before producing output, check for a .ds-ops-config.yml file in the project root. If present, load:
severity.* — overrides for finding severity ratingsintegrations.figma — Figma file key, default branch for mode selectionintegrations.code_tokens — path to code token source (if cross-referencing is desired)recurring.* — if this is a recurring run, load the previous report for trend comparisonIf no config file exists, proceed with defaults and manual input as before.
This skill requires a Figma MCP connection. Before proceeding, verify that Figma tools are available by attempting a lightweight call (such as figma_get_status or listing available Figma tools).
If Figma is not available:
token-audit skill instead, which audits token files in the codebase without needing FigmaIf Figma is available, proceed to Step 1.
Ask the user for a Figma file URL, file key, or node ID. Acceptable inputs:
https://figma.com/design/abc123/Design%20System)abc123)123:456)If .ds-ops-config.yml specifies integrations.figma.file_key, use it automatically without asking.
Pull Figma data:
figma_get_variables with resolveAliases: true to extract all variable collections, modes, names, and resolved valuesfigma_get_styles to extract all color, text, effect, and grid styles for cross-reference (styles are sometimes used instead of or alongside variables)figma_get_component for component metadata to identify component-tier variablesRequest confirmation before reading. Once confirmed, connect and pull the data.
Identify which variable collections map to which tiers:
Primitive tier — raw values, no semantic meaning. Examples: Primitives, Colors, Spacing, Font Sizes, Raw Colors
Semantic tier — intent-driven references to primitives. Examples: Semantic Colors, Theme, Component Tokens, Intent Colors
Component tier — scoped to a specific component context. Examples: Button, Card, Form Input, Navigation
For each collection:
Misc, Exports, Legacy)Produce a brief tier map:
Collection → Tier:
- Primitives (142 variables) → Primitive
- Semantic (67 variables) → Semantic
- Button (18 variables) → Component
- Card (12 variables) → Component
Mixed: System (54 variables) → contains both primitives and semantic
Unmapped: Legacy (8 variables) → no clear tier
If any collection is unmapped or mixed, flag this as a finding.
For each variable name in each collection, check:
Hierarchical naming — do names follow a path-like convention (category.role.variant.state)?
color.action.primary, spacing.component.gap.smcolorPrimary, primary_color, button_bg_defaultIntent-based naming at semantic tier — do semantic names describe purpose, not appearance?
color.semantic.blue (describes colour, not intent)color.action.primary (describes role)Reserved term avoidance — flag colour names in semantic tiers (blue, red, green) and size terms (small, medium, large)
Naming consistency — are casing, separators, and phrase ordering consistent across collections?
Ambiguity checks — flag names that could mean multiple things:
default, base, normal, alt, variant, misc, otherTrace the reference structure of every variable:
Correct chain direction — do component variables reference semantic variables (not primitives directly)?
button.bg.default: {Primitives.blue.500}button.bg.default: {Semantic.color.action.primary}Semantic references — do semantic variables reference primitives?
Semantic.color.primary: {Semantic.color.other}Semantic.color.primary: {Primitives.blue.500}Upward references — are there any primitives or semantics referencing component-tier variables?
Chain length — flag chains deeper than 3 hops (component → semantic → primitive is 2 hops; 3+ indicates unnecessary abstraction layers)
Broken chains — are there any aliases pointing to non-existent variables?
Produce a chain summary for at least one complete chain per tier:
Chain example: button.background.default
button.background.default → Semantic.color.action.primary (1 hop)
→ Primitives.blue.500 (2 hops)
→ #0066CC (resolved value)
Status: PASS (correct direction, 2 hops)
For each collection, list all modes and check coverage:
Mode definition — are modes named after semantic contexts (light/dark, brand variants) or implementation details?
Desktop, Mobile, iOS (platform-specific, not theme-specific)Light, Dark, High Contrast (semantic context)Mode completeness — does every variable have a value in every mode?
Mode consistency — are all variables updated together when a mode changes, or are some stale?
Produce a mode coverage matrix:
Variables per mode:
Light Dark High Contrast
Primitive 142 142 142 (complete)
Semantic 67 65 67 (1 missing in Dark: color.feedback.pending)
Button 18 18 18 (complete)
If .ds-ops-config.yml specifies integrations.code_tokens, pull the code token source and compare:
Name alignment — do Figma variable names match code token names?
color.action.primary vs Code $color-action-primaryValue alignment — do resolved Figma values match code token values?
color.action.primary: #0066CC vs Code #0064CCCoverage gaps — variables existing in Figma but not in code (and vice versa)
If no code tokens are found, document that and skip this step. Note in the output: "Code token cross-reference skipped — no code token source configured."
Orphaned variables — variables with no consumers
Duplicate values — multiple variables resolving to the same value
Primitives.blue.500: #0066CC and Primitives.navy.base: #0066CCStyle overlap — variables that duplicate style definitions
If the team is considering or has declared DTCG migration, run these checks:
Type declarations — DTCG 2025.10 requires $type annotations. Figma variables do not natively support this, so check:
$type? (e.g. color.* → color, spacing.* → dimension)Composite types — Figma doesn't have native composite types (typography, shadow, border). Check:
Mode compatibility — DTCG resolver files require mode consistency. Check:
Migration effort estimate:
Structure the report as follows:
Summary
One paragraph. What is the overall state of the Figma variable architecture? What is the most urgent problem? (One sentence for critical findings.)
Tier structure
Findings
List each finding with:
Example:
FVA-02 | High | Naming | Primitive tier contains semantic-like names.
Evidence: Primitives.color.action.primary, Primitives.color.feedback.success
Remediation: Move intent-based colours to Semantic tier. Rename primitives: color.blue.500, color.green.600
Remediation priority
Group findings into three tiers:
Mode coverage analysis (if modes exist)
Show coverage matrix and gaps.
DTCG readiness (if applicable)
Structural changes needed for clean DTCG export. Effort estimate and recommended migration sequence.
For files with fewer than 50 variables:
If the Figma Console MCP from Southleft is connected (check for figma_rename_variable, figma_update_variable, and figma_add_mode tool availability), offer to fix findings directly in Figma after presenting the audit report. This turns the audit from a report into a remediation session.
What can be fixed in place:
figma_rename_variable to rename variables that violate conventions. Rename preserves all values, modes, and alias references.figma_add_mode to add modes that should exist but don't (e.g. a collection has Light but not Dark).figma_create_variable to create semantic-tier variables that the audit identified as gaps.figma_update_variable to correct values in specific modes.What should NOT be fixed automatically:
Workflow:
When the standard Figma MCP is connected (read-only): The audit runs normally but cannot apply fixes. Present findings and note that the user will need to make changes in Figma manually. If the user asks "can you fix these?", explain that the standard Figma MCP is read-only and recommend the Figma Console MCP from Southleft for direct remediation.
End the report with:
A note on context: This audit compares Figma variables against structural best practices — it does not see why variables were structured the way they are. Some findings may flag deliberate choices. If any finding describes an intentional decision, let me know — I'll calibrate future audits to your team's conventions. The goal is to surface problems, not to second-guess decisions you've already made.