/figma-variable-audit

name: figma-variable-audit
description: "Audit Figma variable collections: tier mapping, naming, alias chains, modes, orphans; can fix in place with Figma Console MCP. Triggers: audit my Figma variables, review variable collections, Figma variable health. For token files in code use token-audit."
allowed-tools: Read, Write, Grep, Glob, Bash(cat:*), Bash(find:*), Bash(head:*), Bash(ls:*)
references:
  - ../../knowledge-notes/token-architecture.md
  - ../../knowledge-notes/output-discipline.md

Figma variable audit

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.

Before you begin: verify references

Confirm that every path in this skill's frontmatter `references:` exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example `npx skills install`) dropped the repo-root `knowledge-notes/` directory. Tell the user to reinstall by a method in `1-INSTALL.md` and run `verify-install.sh` from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

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.

---

Configuration

If `.ds-ops-config.yml` exists, follow the configuration-and-recurring knowledge note (`../../knowledge-notes/configuration-and-recurring.md`) for loading, integration fallbacks and recurring runs. This skill reads:

• `severity.*` — finding severity overrides
• `integrations.figma` — Figma file key, default branch for mode selection
• `integrations.code_tokens` — code token source for the Step 6 cross-reference
• `recurring.*` — the previous variable audit, for trend comparison

---

Step 0: Check Figma availability

This skill needs to read whole variable collections. Before proceeding, check which Figma access is available by attempting a lightweight call (such as `figma_get_status` or listing available Figma tools). Two limits decide what's possible:

• **The official Figma MCP can't list collections.** Its read tools are selection-scoped — `get_variable_defs` returns only the variables a selected node uses. It can show a sample, not run a collection-wide audit. If it's the only Figma connection, say the audit would be partial and offer the alternatives below.
• **The Figma REST Variables API is Enterprise-only.** Don't suggest it to teams on other plans.

A full audit needs the Figma Console MCP (Desktop Bridge plugin), which reads every collection through the Plugin API.

**If the Console MCP is not available:**

• Explain that this skill needs collection-wide read access to Figma variables
• Offer two alternatives:

1. The user can provide an exported variables JSON file (from a variables-export plugin, or the Variables REST API on an Enterprise plan) — the audit can run against that 2. The user can run the code-based `token-audit` skill instead, which audits token files in the codebase without needing Figma

• Do not fail silently. Do not retry the connection in a loop.

**If the Console MCP is available, proceed to Step 1.**

---

Step 1: Connect to Figma and gather variables

Ask the user for a Figma file URL, file key, or node ID. Acceptable inputs:

• A complete Figma design file URL (e.g. `https://figma.com/design/abc123/Design%20System`)
• A file key alone (e.g. `abc123`)
• A node ID if auditing a specific component set (e.g. `123:456`)

If `.ds-ops-config.yml` specifies `integrations.figma.file_key`, use it automatically without asking.

**Pull Figma data.** `figma_get_variables` returns a ~2K-token summary by default and auto-summarises any full response over about 25K tokens, so a one-call read of a real library audits a truncated view. Read it in pieces: 1. `figma_get_variables` with `format: "summary"` to get the collections, their modes and variable counts. This is the audit's inventory. 2. For each collection, `figma_get_variables` with `format: "filtered"`, `collection: "<name>"`, `resolveAliases: true`, `verbosity: "standard"`, `pageSize: 100`, and `page` from 1 upwards until a page comes back with fewer than 100 variables. Keep the variable ids: findings and Step 10 fixes need them. If a response says it was summarised, halve `pageSize` and re-read that page. 3. For Step 7 (orphans), re-read each collection with `enrich: true`, `include_usage: true` and `include_dependencies: true`; without those flags the data has no consumer information and orphan claims are guesses. 4. `figma_get_styles` for colour, text, effect and grid styles, which are sometimes used instead of or alongside variables.

Component-tier collections are identified by name and alias direction in Step 2, not by reading components. Request confirmation before reading. Once confirmed, connect and pull the data, and record under Scope how many pages each collection took and whether any response was summarised.

---

Step 2: Map collections to token tiers

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