---
name: figma-component-system
description: "Figma component variants, auto-layout, tokens, and the publish-to-library workflow — design at scale. Designs Figma component libraries: variants matrices, auto-layout patterns, style tokens, and the publish workflow for team libraries."
license: MIT
---

# Figma Component System Builder

Build production-grade Figma component libraries the way a design-systems team would: variant matrices with clean property sets, auto-layout that actually reflows, variables wired to component states, and a publish cycle that doesn't break consumer files. This skill is for designers and design engineers who maintain a shared library across multiple product files and are tired of one-off, ungoverned components.

## When to use it

- You're consolidating loose frames into a real component set (a Button with size/variant/state/icon properties instead of 30 detached copies).
- A component's variant grid has gaps or duplicate property names and Figma is silently merging the wrong ones.
- You need responsive cards/list rows that grow with content using auto-layout instead of fixed sizes.
- You're about to publish a library update and want to scope the change so downstream "Updates available" diffs stay reviewable.

## What it does

The skill works against Figma's component model directly: **Component Sets** with **Variant properties**, plus **Boolean**, **Text**, and **Instance Swap** component properties exposed on the main component. It lays out variants on a clean grid so Figma's matrix parser maps each `Property=Value` name correctly, and applies **Auto Layout** with the right primary/counter-axis sizing (Hug / Fill / Fixed), spacing, and padding so nested instances resize predictably.

For theming it uses **Variables** (color, number, string, boolean) organized into **Collections** with **Modes** (e.g., Light/Dark, Compact/Comfortable), binding fills, radii, and spacing to tokens rather than raw values. Legacy **Styles** are handled where variables don't yet apply (text/effect styles). The publish workflow covers naming with `/` for folder grouping, description and documentation links on the main component, and structuring updates so the **Publish** dialog produces a tight changelog.

## Usage example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/figma-component-system/SKILL.md https://claudeskil.com/skills/figma-component-system/SKILL.md

# Then, in your Figma file:
"Turn my selection of 6 button frames into a component set with
 properties: Variant (Primary/Secondary/Ghost), Size (sm/md/lg),
 State (Default/Hover/Disabled), and a Boolean 'Has icon'.
 Use auto-layout, bind fills to my Color/Brand variables,
 and prep it for publishing."
```

The skill returns the variant matrix plan, the property schema, the token bindings to apply, and a pre-publish checklist.

## Tips & gotchas

- **Variant property names are case-sensitive and whitespace-sensitive.** `State=Hover` and `state=Hover ` create separate, conflicting properties. Normalize before combining.
- Set the **counter-axis to Hug** before Fill, or text truncation flips on unexpectedly when an instance is dropped into a fixed-width parent.
- Bind **radius and spacing to number variables**, not just color — that's where mode-switching libraries usually leak hardcoded values.
- Publish from the **main library file only**; editing a component inside a consuming file detaches it from updates.

## FAQ

**Does this edit my Figma file automatically?** It plans the structure and, where the Figma integration is connected, applies component/variable/auto-layout changes; otherwise it gives you exact step-by-step instructions and property schemas.

**Variants vs. Boolean properties — which should I use?** Use variants for mutually exclusive visual states (Size, Variant). Use Boolean/Instance Swap for additive toggles (Has icon, leading element) to avoid an exploding matrix.

**Will publishing break existing instances?** No, as long as you keep property names stable. Renaming a variant property is what triggers detach-and-reset for consumers, so the skill flags renames before you publish.