figma-workflow
Runs the hands-on round trip between this kit and Figma through the official Figma MCP server: imports kit tokens as variables, builds variant components bound to them, pushes stylescapes or React screens into Figma, maps components with Code Connect, pulls frames back into code and prepares Dev Mode handoff, with a fallback when no Figma connector is available. Use when a task names Figma, a figma.com link, Dev Mode or Code Connect. Token and library architecture stay in design-system.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- figma-workflow
- license
- MIT
- metadata
- { "agent-attribution": "computer=vm; tool=Claude Code; version=2.1.304; timestamp=2026-10-20 10:35:33 UTC", "version-timestamp": "2026-10-20 10:35:33 UTC" }
- description
- Runs the hands-on round trip between this kit and Figma through the official Figma MCP server: imports kit tokens as variables, builds variant components bound to them, pushes stylescapes or React screens into Figma, maps components with Code Connect, pulls frames back into code and prepares Dev Mode handoff, with a fallback when no Figma connector is available. Use when a task names Figma, a figma.com link, Dev Mode or Code Connect. Token and library architecture stay in design-system.
02 资源文件 4
- 参考文档references/code-connect-map.md6.2 KB
- 参考文档references/no-connector.md4.3 KB
- 参考文档references/push-and-pull.md7.4 KB
- 参考文档references/tokens-and-components.md6.7 KB
03 SKILL.md 正文
Figma workflow
A good round trip leaves one source of truth (the DTCG tokens and the coded components), a Figma library that mirrors it exactly, and a screenshot proving each hop. Conventions for variables, styles, components and Code Connect live in design-system's Figma reference; this skill is the procedure.
Defaults
| Decision | Default | Change when |
|---|---|---|
| Direction of authority | Code and tokens lead; Figma mirrors | Exploration with no code: Figma first, then export once and flip authority |
| Skill gate | Load the matching figma skill before its tool, every session (table below) | Never skip; the skills carry API rules the tools assume |
| Target file | A file the user names; otherwise create_new_file after loading figma-create-new-file |
Never write into a client file without its link in the brief |
| Token import | tokens.py figma-script output run once through use_figma |
Plan or connector blocks it: no-connector fallback |
| Collections | Primitives (modes Meridian, Ember; hidden, no scopes) and Semantic (Light, Dark, High contrast, aliases only) |
Client brands replace the kit brands as Primitives modes |
| Components | Auto layout, every padding, gap, radius and fill bound to a variable; props named like the React props | |
| Reuse | search_design_system before creating anything |
|
| Write size | Batch related, safely retryable work per use_figma call, as figma-use sizes it; one screenshot per finished phase |
Split only at page boundaries or after a real failure |
| Verification | get_screenshot per finished phase, checked at 100%, every mode and brand |
|
| Pull to code | Reuse library/examples/react-system/ components and kit tokens; MCP code is a reference |
|
| Fidelity proof | Figma frame PNG vs build with compare_build.mjs |
|
| Unverified items | Plan limits and new Figma features marked "verify" | Confirm on figma.com pricing and help pages before quoting to a client |
Skill gate
| Before calling | Load | Purpose |
|---|---|---|
use_figma (any write or scripted read) |
figma-use |
Plugin API rules, call sizing, recovery |
| Variables, component sets, theming in Figma | figma-generate-library with figma-use |
Build order: foundations, then components |
| Pages, screens or composed UI in Figma | figma-generate-design with figma-use |
Library discovery, section-by-section assembly, image capture |
get_code_connect_suggestions, send_code_connect_mappings, .figma.ts files |
figma-code-connect |
Template format and publishing rules |
get_design_context |
figma-design-to-code |
Screenshot target, asset handling, reuse rules |
create_new_file |
figma-create-new-file |
File type and plan selection |
| Static HTML import, Code Layers | figma-code-workflows |
Output choice: editable layers or runnable code |
If a listed skill is not available on the host, read the server's fallback (skill://figma/<name>/SKILL.md) before calling the tool.
Workflow
- Confirm access. Call
whoami; note the plan and seat. Code Connect needs Organization or Enterprise and published components; mode counts per collection are plan-limited (verify on Figma's pricing page). If Figma tools are missing, switch to the fallback. - Parse the link.
figma.com/design/<fileKey>/<name>?node-id=1-2givesfileKeyand node1:2; a branch URL uses the branch key. - Import tokens. Run
python3 ../../library/scripts/tokens.py build, thentokens.py figma-script, and pass the printed script touse_figma. It is idempotent; read the returned report (created,updated,skipped). Steps and post-import checks: tokens and components. - Finish foundations by hand. Text styles bound to font variables, effect styles for shadows, grid styles, iOS and Android code syntax when native apps ship.
- Build components. Variant sets whose properties match the React props (
variant,size,tone), every state the coded component has, bindings checked withget_variable_defs. Order and naming: tokens and components. - Push a screen. For a chosen stylescape or a React screen, capture a reference (
html_to_figmafor static HTML,generate_figma_designfor a running app), rebuild it from library instances withuse_figma, compare, then delete the capture. Details: push and pull. - Connect code. Map each published component to
library/examples/react-system/src/components/with.figma.tstemplates; the prop table is in Code Connect map. - Pull a frame back.
get_design_contextwith a screenshot, map layers to existing components and tokens, build, then runnode ../design-critique/scripts/compare_build.mjsagainst the exported frame. - Hand off. Mark frames Ready for dev only when states, breakpoints and annotations are complete; Dev Mode should show variables with code syntax and Code Connect snippets, not raw CSS.
- Inspect. Screenshot every touched node in every mode. A script that returned without error is not a verified design.
Naming conventions
- Variables: slash paths that mirror token names:
color/bg/surface-raisedis--color-bg-surface-raised. Never rename in Figma only. - Components: PascalCase matching the React export (
Button,TextField,Badge); properties lowercase like props (size), values like code values (sm,md,lg). - Layers: roles, not defaults:
Label,Icon/Leading,Supporting text; noFrame 12. - Pages:
Cover,Foundations,Components/<Name>,Patterns,Screens/<Flow>,Archive. - Frames:
<Screen> / <width> / <theme>, for exampleBilling / 390 / Dark.
Decisions that change the answer
- Plan tier. Starter and Professional: no Code Connect, fewer modes; put brands in separate files or reduce modes, and hand off with Dev Mode variables only (verify current limits).
- Existing client library. Reconcile into it (the reconciliation path in
figma-generate-library) instead of importing a parallel kit library; map client names to kit tokens in a table first. - Native apps. Add iOS and Android code syntax and use
figma-swiftuifor SwiftUI in either direction. - Many brands. Over five brands, consider extended collections (Enterprise, verify) rather than one mode per brand.
- Images in the screen.
use_figmacannot fetch image URLs; run thegenerate_figma_designcapture and copy its image fills, asfigma-generate-designrequires.
Common failures
- Calling
use_figmawithoutfigma-useloaded -> load it; most failed scripts break a rule it states. - Hex values pasted into fills -> bind to semantic variables;
get_variable_defsshould list no raw colors. - Semantic variables holding values instead of aliases -> re-run the import; never patch in Figma.
- Variant values that differ from code (
Primaryvsprimary) -> rename in Figma to the code value, or map every value in Code Connect. - Screens built from detached frames -> rebuild from library instances; detached screens drift on the next token release.
- Pulled code with absolute positioning and raw hex -> refactor to flex or grid and tokens before review.
- "Done" after one mode -> check Light, Dark and High contrast in both brands.
References
- Tokens and components: import, foundations, component build order, binding checks.
- Push and pull: stylescape or React screen into Figma; frame back to code; fidelity check.
- Code Connect map: react-system components to Figma properties, template example, publishing.
- No connector: token JSON export, development-plugin import, handoff package.
- Figma conventions: variables, styles, auto layout, properties, libraries, Dev Mode.
- Build fidelity: thresholds and masks for
compare_build.mjs. - Deep process for client files: Figma production, stage handoff, web fidelity.
Catalog IDs covered: production, handoff, web-fidelity, web-system-assembly, ui
04 同仓库更多 Skills
web-design
Load before planning, designing, auditing or launching any website, landing page, cinematic hero, microsite or above-the-fold layout, or a prompt for Lovable, Bolt or v0 to build one, including regulated (prescription drug, health, finance), multilingual or market-specific launches. Covers page types (home, product, pricing, about, blog), conversion and ethical persuasion, responsive and fluid layouts, Core Web Vitals, SEO and structured data, localization and language-law requirements, stack and CMS choice (Astro, Next.js, WordPress, Webflow, Framer) and launch QA.
ux-design
Load before designing or reviewing any flow, form, onboarding, navigation or content for real users, especially low-literacy, older, neurodivergent, child or other specific audiences. Covers research and usability tests, heuristic reviews, personas and jobs to be done, journeys and service blueprints, information architecture, UX laws, SUS, SEQ and HEART metrics, plain language and reading level, and microcopy and error messages.
ui-design
Load before designing or specifying any interface screen or component, even a quick one: forms, tables, navigation, dashboards, onboarding, auth and passkeys, pricing, checkout, search and filters, settings, empty, loading and error states, notifications, consent and age-appropriate flows, and AI chat and agent interfaces, all to WCAG 2.2 AA. Also picks React UI libraries (toasts, drawers, command menus). Gives component specs, state matrices, sizes, density and keyboard and accessibility behavior.
typography
Choose, pair, size and set type for brand, web, app, print, slides, signage and motion: modular scales, fluid clamp() type, measure, leading, tracking, OpenType features, font licensing and web font loading, and multiscript setting for CJK, Arabic, Hebrew, Devanagari and Thai. Use when selecting or pairing fonts, building a type scale or type tokens, fixing weak hierarchy or bad line breaks, setting long-form text or numbers, loading web fonts, or localizing type for another market.
reference-reconstruction
Reconstructs the observed interface and behavior of a supplied app, site or screenshot set using a screen index, measurements, state and command maps, reusable components and matched-condition comparisons. Use when asked to reverse engineer, clone, reproduce or match a reference product, then adapt it if requested.
print-packaging-social
Load before any print, packaging, label, barcode, social, out-of-home, slide-deck or email design question, even a quick one, and before making finished collateral files. Specs: bleed, safe zones, 300ppi, CMYK, PDF/X preflight, dielines, barcodes, social formats with 9:16 safe areas, billboard letter heights, 16:9 decks, bulletproof email. Renders token-driven brand books, sell sheets, cards, carousels and decks to PDF and PNG with a Canva editable twin.