/figma-variable-audit

name: figma-variable-audit
description: "Audit Figma variable collections against token architecture best practices. Trigger when someone says: audit my Figma variables, check my Figma tokens, are my variables structured correctly, Figma variable health, review my variable collections, variable naming check, or anything about auditing the quality or structure of Figma variables."
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.

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

Before producing output, check for a `.ds-ops-config.yml` file in the project root. If present, load:

• `severity.*` — overrides for finding severity ratings
• `integrations.figma` — Figma file key, default branch for mode selection
• `integrations.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 comparison

If no config file exists, proceed with defaults and manual input as before.

---

Step 0: Check Figma availability

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:**

• Explain that this skill needs a live connection to Figma to read variable collections
• Offer two alternatives:

1. The user can provide an exported variables JSON file (exported from Figma's local variables panel or via the Variables REST API) — 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 Figma 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:** 1. Use `figma_get_variables` with `resolveAliases: true` to extract all variable collections, modes, names, and resolved values 2. Use `figma_get_styles` to extract all color, text, effect, and grid styles for cross-reference (styles are sometimes used instead of or alongside variables) 3. Use `figma_get_component` for component metadata to identify component-tier variables

Request confirmation before reading. Once confirmed, connect and pull the data.

---

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 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:

• Note its name and the tier it belongs to
• Flag collections that don't map cleanly to any tier (e.g. `Misc`, `Exports`, `Legacy`)
• Flag collections that mix tiers (primitives and semantics in the same collection)
• Count variables per collection per tier

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.

---

Step 3: Audit naming conventions

For each variable name in each collection, check:

**Hierarchical naming** — do names follow a path-like convention (category.role.variant.state)?

• PASS example: `color.action.primary`, `spacing.component.gap.sm`
• FAIL example: `colorPrimary`, `primary_color`, `button_bg_default`

**Intent-based naming at semantic tier** — do semantic names describe purpose, not appearance?

• FAIL example: `color.semantic.blue` (describes colour, not intent)
• PASS example: `color.action.primary` (describes role)

**Reserved term avoidance** — flag colour names in semantic tiers (blue, red, green) and size terms (small, medium, large)

• These belong only in the primitive tier
• Flag each occurrence with suggested rename

**Naming consistency** — are casing, separators, and phrase ordering consistent across collections?

• Check for: camelCase vs snake_case, dot notation vs hyphen, variable order (role.variant.state vs variant.role.state)
• If inconsistency exists, identify the dominant pattern and flag deviations

**Ambiguity checks** — flag names that could mean multiple things:

• Examples: `default`, `base`, `normal`, `alt`, `variant`, `mi