Communitygithub.com

figma-library-binding

Bind Figma screens to a design system library — tokens only on exact value matches, swap icons and components for library versions, and list unmatched values for designers instead of snapping to the nearest token. Use when the user asks to "bind tokens", "use library components" or "find unbound colors".

What is figma-library-binding?

The `figma-library-binding` skill is a precise design system binding tool for Figma, designed to bridge product screens with a project's design tokens, icons, and components without guessing or modifying the original design. It enforces strict matching rules: colors, radii, strokes, spacing, and typography are only bound when values exactly match a token (including opacity), preventing unintended visual changes that can cause discrepancies between state boards and code. Icons and components are swapped only when an exact library counterpart exists with the same name or appearance; otherwise, they remain local and are reported for the designer to decide. The skill supports presets for common design systems, can be automated via `al-capture.cjs` and `al-pack.py`, and includes a standalone `al-bind.js` script for token-only binding on existing screens. It outputs detailed reports with binding ratios, unbound colors, and reasons for skipped swaps, empowering designers to fill gaps in the design system rather than relying on nearest-value approximations.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/figma-library-binding

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Binding to a design system library

Product screens must use the project's design system, not only local layers.

Pick a preset

Each design system has one preset, in presets/. Ask the user which one the project uses, or check the project's dependencies (e.g. if the project depends on a design token package, use the matching preset). See presets/README.md for the format. If there's no preset, look it up once following "How automatic binding works" below, then save the result as a new preset. If the project has no library, write "None" and say so in the report.

Before starting, use get_libraries to confirm every library is in libraries_added_to_file. For any that are missing, ask the user to add them in Figma under Assets › Libraries; don't continue until they're added.

Binding rules

Better to leave something unbound than to change the screen. The tool does only what's below; everything else stays local and is reported.

TypeRuleDon't
ColorBind only on an exact match, including opacity. Semi-transparent colors need a token with that transparency, because Figma resets opacity to 1 when bindingDon't snap to the nearest color
Radius, stroke, spacing, type sizeBind only when the value is exactly equalDon't change 3px to 2px or 4px
Alias tokensA token that points at another token (a semantic token over a primitive) counts with the value at the end of the chain. When a value has both, the token with its own value wins; the alias is used only for values nothing else hasDon't pick between two semantic tokens with the same value by guessing; report it
Text styleBind only when font, size and line height are all equalIf the font differs, bind only the size
IconSwap only when the library has a component with the same name; accept old names only for mappings confirmed to have the same purposeDon't use an icon with a similar meaning but a different look
ComponentSwap only when the library component looks the same as the product's; keep the product's sizeIf it looks different, keep the local component and don't change the product screen

Why not snap to the nearest value: a matching value doesn't mean a matching meaning, and it makes the state board disagree with the code. A value with no matching token is a gap in the design system; list it for design to decide, rather than letting the tool pick.

How automatic binding works

With a preset, set preset in the al-capture.cjs config and pass the preset name as the fourth argument to al-pack.py; screens are bound automatically when they're built. Only without a preset, follow the process below, then save the result as presets/<name>.json: libs is the binding config, and extract is the sprite mapping used during extraction.

  1. After extracting the layout tree, list every lib (icon name) in the JSON
  2. For each name, search the Icon System with search_design_system: system:cross maps to icon / system / cross. Accept exact name matches only
  3. Use search_design_system to find the component set, place a few instances, screenshot them, compare their look with the product, and decide buttons.rules
  4. Assemble opts.libs. Build 3–4 cards first and check log.drift and the screenshots; batch only if they look right
const libs = {
  tokens: ['My DS - Foundation'],        // read variables from these libraries
  icons: { 'system:cross': '<componentKey>' },
  buttons: {
    set: '<componentSetKey>',
    rules: { FFE13A: { Type: 'primary', Size: 'medium', Compact: 'false', Status: 'default' } }, // key is the button background color
  },
  words: { value: 'Price' },             // rename text properties to match the team's terms
};

The al-capture.cjs output includes unmappedIcons, listing icons used this time that the preset doesn't map yet. Look them up with search_design_system and add exact name matches to the preset; next time they bind automatically, so the preset gets more complete with use.

The stat returned by __alBuild has the binding results: boundColors, boundLayout, libIcons, dsButtons, unboundColors, localIcons.

Binding existing screens

al-bind.js can be used on its own. It binds tokens only and doesn't swap icons or components. Paste the whole script into use_figma (or load it with eval), then call:

return await __alBind(['<frame id>'], { tokens: ['<library name>'] });

It returns boundColors, boundLayout, and unboundColors (colors with no token). skippedText counts text whose font could not be loaded, so its size was left unbound.

When screens are built with __alBuild, the token table is cached in _registry so later screens don't import every variable again. It is rebuilt when the preset lists different token libraries. After the library publishes new or changed tokens, pass refreshTokens: true to the next __alBuild call.

Components

  • Center with Auto Layout: not with padding or text box width, so changing the text doesn't shift it
  • Containers aren't components: a repeated structure that already contains components is just a container
  • States are variants: selected and disabled must be switchable through properties, not by overriding instance colors
  • Split small components into properties: two variant properties, Type and State; make the text a component property
  • Main components must be complete: don't make elements cut off by the viewport into components

Report

Always list:

  • Binding ratio: colors, layout values
  • Number of icons and components swapped for library versions
  • Colors with no token (top few), for design to decide
  • Icons and components kept local, and why

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

code-to-figma

Rebuild screens from a running web app as native, editable Figma layers (Auto Layout, components, instances) and diff them against browser screenshots — not a screenshot import or a Code layer. Use when the user asks to "turn this page into Figma", "code to Figma", "push this screen to Figma" or "rebuild the UI in Figma". 把 Web 專案實際跑出來的畫面重建成 Figma 原生圖層:造狀態、抽 DOM 版面樹,建 Auto Layout 和 component/instance,再跟瀏覽器截圖比對。單一畫面或一批畫面都能用,不需要做情境稿。Use when 使用者要「code to figma」「把這頁轉成 Figma」「從程式重建畫面」「push 畫面到 Figma」,或 figma-state-board 走路線 B。產出是可編輯圖層,不是 Code layer 或截圖。

figma-state-board

Inventory every UI state of a feature from its code and lay them out on one Figma canvas (a state board) — real screens for states the prototype already handles, plus a gap check of missing error, empty and loading states, split into spec-required and suggested. Use when the user asks for a "state board", "all states of this feature in Figma", "which error screens are missing", or to update an existing board. 從任何產品專案的程式碼盤點一個功能的所有狀態,在 Figma 產出或更新「情境稿」:原型(通常是 mock data 做的)已經有的狀態畫真實畫面,原型缺的狀態全列進「缺漏檢查」,再分「規格有寫」(規格要求、原型漏做)和「建議補」(規格和原型都沒提的錯誤、空狀態、載入等)。Use when 使用者要「做情境稿」「把所有狀態/狀況畫到 Figma」「state board」「檢查缺了哪些 error 畫面」,或要依新規則增修既有情境稿。只要狀態清單用 state-discovery,只要把畫面轉進 Figma 用 code-to-figma。

Related Skills