# Figma And Tooling Workflow > Use when structuring current Figma files, variables, modes, auto-layout, component properties, Dev Mode, branches, or library publishing. Use design-tokens-and-naming for the platform-neutral token contract and design-handoff-and-dev-spec for delivery evidence. - Skill: `peterbamuhigire/figma-and-tooling-workflow` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add peterbamuhigire/figma-and-tooling-workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/figma-and-tooling-workflow/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/peterbamuhigire/figma-and-tooling-workflow --- # Figma And Tooling Workflow Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com. ## Use When - Standing up a new design-system or product Figma file and you need a deliberate file/page/section structure instead of one sprawling canvas of loose frames. - Implementing the token tiers **in Figma** — turning the primitive → semantic → component tokens from `design-tokens-and-naming` into Figma **variables**, with **modes** carrying light/dark, brand/tenant, and density variation, plus breakpoint number modes. - Building components properly: **component properties** (boolean / text / instance-swap / variant) and a **variant** matrix, on **auto-layout**, so one component serves every state and size. - Deciding **styles vs variables** for colour, type, effects, and grids (the in-tool seam that decides what can be themed and what can't). - Preparing **Dev Mode** handoff — annotations, the inspect panel, variable/token names surfaced to engineering, statuses (Ready for Dev), and links into code. - Setting team conventions: **branching** for safe edits, **library publishing** discipline, and a layer/page/component **naming** scheme that survives more than one designer. ## Do Not Use When - You are deciding the *token tiers, names, OKLCH values, or export topology* themselves — that is `design-tokens-and-naming`. This skill is how those tokens are *expressed and operated in Figma* (as variables/modes); it does not invent the token model. - You are writing the *measured redline / acceptance-criteria handoff sheet* for a screen — that is `design-handoff-and-dev-spec`. This skill sets Figma up *so* Dev Mode handoff is clean; it does not replace the written spec. - You are designing a component's *variant/state/API model* as a system contract — that is `component-library-architecture`. This skill builds that model *in Figma* (properties + variants + auto-layout) but defers the architecture decisions to it. - You are choosing palette, type, layout, or motion (groups 01–04, 08) — Figma is where resolved decisions are assembled, not where they are made. - The tool in question is Sketch, Adobe XD, Axure, InVision, or paper prototyping. This skill is current Figma only; the older-tool workflows are out of scope and are not reproduced here. ## Required Inputs | Input | Source | Required? | Evidence | |---|---|---|---| | Token tiers, modes, and naming contract | `design-tokens-and-naming` | yes | Approved token source and aliases | | Component scope and state model | `component-library-architecture` | yes | Component inventory and matrices | | Team roles and release process | Design-system owners | yes | Editors, reviewers, publishers, and branch policy | - The resolved token model from `design-tokens-and-naming`: the three tiers and the semantic role map, the theme axes (which of light/dark, brand/tenant, density must coexist), and the breakpoint set. Figma variables *carry* these; they don't replace the decision. - The component scope and each component's variant/state model from `component-library-architecture`. - A namespace/prefix for the system (e.g. `mdk` for Maduuka) used consistently in variable collections, styles, components, and pages. - Who consumes the library (which teams subscribe) and the WCAG 2.2 AA floor the themed pairs must hold (`doctrine/references/wcag-2.2-criteria.md`). ## Workflow 1. **Fix the file and page architecture before drawing anything.** Decide the *file split* first: typically a **Foundations/Tokens** library file, a **Components** library file, and per-product **Product** files that consume both as published libraries — so themes and components publish once and fan out, rather than being copied. Inside each file, use **pages** as top-level sections (e.g. `Cover`, `🧱 Foundations`, `🧩 Components`, `📐 Patterns`, `🚧 WIP`, `🗄 Archive`) and **sections** (the frame-grouping primitive) to chunk a page. One canvas of loose frames is the structural cause of un-findable, un-maintainable design. See `references/figma-conventions.md` §File & page structure. 2. **Build the token tiers as variable collections, with modes as the theming seam.** In current Figma, **variables** (not styles) are where tokens live and where theming happens: - Create **collections** mapped to the token tiers — a `Primitives` collection (raw ramps, the space/size scale, radii) and a `Semantic` collection (role aliases that *reference* primitives). Component-tier values usually live on the component as bound properties or a small per-component collection. This mirrors the primitive → semantic → component tiers exactly. - Put theme variation on **modes** of the *semantic* collection: a `Theme` axis with `Light` / `Dark` (and `Brand A` / `Brand B`, or `Tenant-X`, as separate modes or a second collection). Each mode re-points the *same* semantic variable at a different primitive — the components never change, only the alias targets. This is the in-tool form of "semantic tokens are the theming seam, never the primitives." - Use **number variables in modes for breakpoints/density**: a `Breakpoint` axis (`Compact` / `Regular` / `Expanded`) driving spacing, container width, and type-step numbers, so one frame adapts by mode-switch instead of three hand-built copies. - **Alias, don't duplicate:** semantic variables point at primitives; never paste a raw hex into a semantic variable. A semantic variable holding a literal is the Figma form of a component reaching past the semantic layer. See `references/figma-conventions.md` §Variables & modes. 3. **Decide styles vs variables deliberately — they are not interchangeable.** Use **variables** for anything that must theme or switch by mode: all colour fills/strokes, spacing, radius, and single-axis values. Use **styles** where Figma still needs a *bundled, multi-property* object: **text styles** (font, size, line-height, spacing, weight as one applied unit — back the size by a variable where possible), **effect styles** (shadows/blur, themed via variable-bound colours), and **grid styles**. The rule: a value that a theme re-points → variable; a composite the tool applies as one named bundle → style, with its themeable parts variable-bound underneath. Recording this seam is what keeps dark mode and multi-brand free. See `references/figma-conventions.md` §Styles vs variables. 4. **Build every component on auto-layout.** Auto-layout is non-negotiable for a system component: it gives real padding/gap (bound to space variables), hug/fill sizing, direction, and wrap, so the component reflows to content and breakpoint instead of being pixel-pushed. Bind padding and gap to the space variables; never type raw pixel padding into a system component. Nested auto-layout + min/max width is how one component handles the longest localized string and the empty state without a separate frame. 5. **Use component properties + variants for the API, not duplicated layers.** Express the component model from `component-library-architecture` with Figma's property types: - **Variant properties** for the orthogonal axes — `intent` (primary/secondary/ghost/destructive), `size` (sm/md/lg), `state` (default/hover/focus/active/disabled/loading/selected/error). Keep axes *separate* properties, not one `primary-lg-loading` variant name — the same orthogonality rule the component skill enforces. - **Boolean** properties for optional parts (leading icon, full-width), **instance-swap** for slotted content (the icon, an avatar), **text** properties for labels. This is composition over a wall of duplicated component copies. - Cover the **full state set** as variant values, including **focus-visible** with a real ring bound to a focus token (≥3:1, WCAG 2.4.7/1.4.11) — an empty state cell is a bug, per doctrine's a11y floor (`doctrine/references/wcag-2.2-criteria.md`). See `references/figma-conventions.md` §Component properties & variants. 6. **Name everything to one scheme and hold it.** Layers, components, variables, styles, pages, and branches all follow a stated convention: components and variant props in a `Group/Name`, slash-nested form (`Button`, property `size=md`); variables dot/slash-pathed to their tier and role (`color/text/default`, `space/inset/md`, `radius/200`) so the name *says its tier* exactly as the token naming rule requires; layers named by role not `Frame 47`. Auto-generated names (`Rectangle 12`, `Group 5`) in a published library are the Figma form of drift. See `references/figma-conventions.md` §Naming. 7. **Operate the library through branching and disciplined publishing.** Make non-trivial changes on a **branch** of the library file (review → merge), never live on `main` where every subscriber sees half-finished work. **Publish** deliberately: review the change list, write a publish description, bump a stated version, and let product files **update** the subscribed library on their own cadence. A token/variable rename ripples to every consumer — treat publishes as releases, not autosaves. See `references/figma-conventions.md` §Branching & publishing. 8. **Set the file up so Dev Mode handoff is clean.** Dev Mode is where engineering reads the design: - Mark frames **Ready for Dev**; add **annotations** (measurements, behaviour notes, the token/ variable name on each value) and **dev resources** (links to the component in code, the PR, the spec). Use **Dev Mode focus / compare** for what changed. - Because values are **variable-bound**, the inspect panel surfaces the *semantic variable name* (`color/action/primary/bg`) rather than a raw hex — which is exactly the token reference the written handoff (`design-handoff-and-dev-spec`) cites. Hardcoded values inspect as bare hex/px and force the developer to hardcode too. - Keep **Code Connect** / component-to-code mapping where it exists, so the inspected Figma component names the real code component. Dev Mode does not replace the written redline + acceptance criteria — it makes them trivially accurate. See `references/figma-conventions.md` §Dev Mode. 9. **Keep the anti-slop posture in-tool.** The convergent default is a file full of detached instances, raw hexes, and a generic blue flat-fill Button. The authored alternative is one variable-driven system where the one strong choice (a deliberate radius, a brand focus ring) is set once in a semantic variable and inherited everywhere. Component instances stay *attached*; overrides are deliberate, not accidental detaches. (`doctrine/design-doctrine.md` §0, §2.) ## Decision Rules | Condition | Figma construct | Wrong-choice failure | |---|---|---| | Value changes by theme, brand, or density | Variable with an explicit mode | Duplicated styles and frames drift | | Visual recipe has no runtime semantic role | Style referencing variables | Forcing everything into variables obscures intent | | Property is an orthogonal consumer choice | Component property or variant axis | Detached component copies proliferate | | Structural experiment is not release-ready | Branch with named review owner | Editing the main library destabilises consumers | ## Capability Contract Read access is required to current files, libraries, tokens, and consumers. Editing is allowed only for authorised setup or remediation. Tool execution is required for variable, component, publication, and Dev Mode evidence; library publication and branch merge require separate authority. ## Degraded Mode If required evidence or tooling is unavailable, use the scoped fallback below and mark the result unverified. Without Figma access, deliver a file architecture, variable schema, naming map, and migration plan, all marked proposed. Without publication or consumer access, stop before release and do not claim library compatibility; provide the exact checks and owners needed for verification. ## Anti-Patterns - **One giant file of loose frames** with no page/section structure and no library split — un-findable, un-publishable, and impossible to theme as a unit. - **Theming with styles instead of variable modes** (or duplicating the whole UI as a "dark" page). Modes on the semantic collection are the seam; copies drift the instant a token changes. - **Semantic variables holding raw hex** instead of aliasing a primitive — the Figma form of a component reaching past the semantic layer; nothing re-themes. - **One mega-variant** (`variant = primary-lg-loading`) instead of separate `intent` / `size` / `state` properties — combinatorial, un-composable, un-reviewable. - **Pixel-pushed components with no auto-layout** — they break at the next content length and can't bind padding to space tokens. - **Missing state variants**, especially **focus-visible**, disabled, loading, and error — an empty cell in the variant matrix is a defect, not a default (WCAG 2.4.7). - **Auto-named layers/components** (`Rectangle 12`, `Component 4`) and ad-hoc variable names that don't encode their tier — drift made visible. - **Editing the library live on `main`** and **publishing without a description/version** — subscribers inherit half-finished work and can't tell what changed. - **Detached instances and hardcoded values** that inspect as bare hex/px in Dev Mode, forcing engineering to hardcode and forking the system. - Reproducing a **Sketch/XD/Axure** workflow (shared symbol-only theming, plugin-driven redlines, paper-first) in Figma instead of using variables/modes, component properties, and Dev Mode. ## Outputs | Artefact | Consumer | Evidence and acceptance condition | |---|---|---| | File, page, and library architecture | Design-system team | Ownership, purpose, and publication boundary are explicit | | Variable, mode, component-property, and naming specification | Designers and engineers | Aliases preserve token tiers and supported themes render correctly | | Branch, publication, and Dev Mode handoff record | Reviewers and consumers | Review authority, change notes, and inspected-code evidence are recorded | - A **Figma file/page/library architecture**: the Foundations/Components/Product split, the page and section scheme, and the naming convention, all stated. - **Variable collections and modes** implementing the token tiers — `Primitives` + `Semantic`, with a `Theme` mode axis (light/dark/brand) and a `Breakpoint`/density number-mode axis — aliased, not duplicated, with the themed pairs holding the WCAG gate. - A **styles-vs-variables decision record** for colour/type/effect/grid. - **Components on auto-layout** with the property/variant API (variant axes + boolean + instance-swap + text) covering the full state set including focus-visible. - A **branching + publishing convention** and a **Dev-Mode-ready** setup (Ready-for-Dev statuses, annotations, variable-surfaced inspect, dev resources / Code Connect) that feeds the written handoff. ## Examples - `examples/sample-design-system-figma-setup.md` — a complete worked setup for a sample design system: the file/page/library split, the `Primitives` + `Semantic` variable collections with a `Theme` (Light/Dark/Brand-B) mode axis and a `Breakpoint` number-mode axis, the styles-vs-variables split, a Button built on auto-layout with its component-property/variant API, and the naming + branching + Dev-Mode conventions — every value mapping to the tokens from `design-tokens-and-naming`. Never lorem. ## References - `doctrine/design-doctrine.md` — Mission §0 (one authored system beats five hedged copies; attached variable-driven components over a detached, hardcoded canvas) and Anti-Slop Charter §2 (state the choice first; the sourcing-authority asymmetry — what we build in Figma traces to the token system and human design authority, never to an AI tool's defaults). - `doctrine/references/wcag-2.2-criteria.md` — the contrast floors (4.5:1 / 3:1) the themed variable modes must hold per theme, and focus-visible (2.4.7, 2.4.11, 1.4.11) required as a state variant. - `references/figma-conventions.md` — the canonical in-tool conventions: file/page structure, variables & modes (theming + breakpoints), styles vs variables, component properties & variants, auto-layout, naming, branching & publishing, and Dev Mode handoff. - Upstream: `09-…/design-tokens-and-naming` — the token tiers and semantic role map that Figma variables and modes carry (a Figma variable *is* a token's in-tool home; the name encodes its tier). - Feeds: `09-…/design-handoff-and-dev-spec` (Dev Mode surfaces the variable/token names its redlines cite) and `09-…/component-library-architecture` (the variant/state/API model this skill builds in Figma). - Standards/tooling (named for provenance, not in-repo): current Figma — variables & modes, component properties, auto-layout, Dev Mode, Code Connect, branching, team libraries; W3C Design Tokens Format Module (the token model the variables mirror).