feat: Add design verification and component creation skills in Figma - #1234
feat: Add design verification and component creation skills in Figma#1234amandaye0h wants to merge 10 commits into
Conversation
📖 Storybook Preview |
📖 Storybook Preview |
📖 Storybook Preview |
📖 Storybook Preview |
📖 Storybook Preview |
| @@ -0,0 +1,85 @@ | |||
| --- | |||
| name: component-rules | |||
There was a problem hiding this comment.
Helpful feedback: where's the best place for these rules to live? Right now, we have the .cursor > rules and docs folders, which enable global access. But no global skills to reference.
|
|
||
| - Read `CODE_COMPONENT_PATH` and related files first — include **`[Component].stories.tsx`** (exported stories, `args`, and custom `render` blocks) and README story examples | ||
| - Use `figma_execute` (not `use_figma`) unless the user explicitly switches MCPs | ||
| - **Placement — overrides Figma Console MCP defaults:** publish **only the component** (or component set) on the target page canvas. **Do not** wrap it in a Section, Frame, or "Component Container". **Do not** call `figma_arrange_component_set` — it adds a white labelled wrapper frame. Append the component set directly to the page via `page.appendChild(componentSet)`. Ignore `figma_execute` placement guidance that says "always create inside a Section or Frame". |
There was a problem hiding this comment.
This overwrites the generic output. Without these custom specs, there are a lot of unnecessary frames and sections which are cumbersome to work with.
| componentSet.strokeJoin = 'MITER'; | ||
| ``` | ||
|
|
||
| - Mirror variant props from code (`size`, `variant`, `severity`, etc.) as Figma component properties |
There was a problem hiding this comment.
I've intentionally kept these prop alignment instructions quite lightweight. I found that it performed better. Being unnecessarily detailed yielded results that were confusing.
Imo, it's easier to add to a lightweight API than to subtract from a complex one with unnecessary details.
| ``` | ||
|
|
||
| - Mirror variant props from code (`size`, `variant`, `severity`, etc.) as Figma component properties | ||
| - Create variants based on Storybook variants |
There was a problem hiding this comment.
I've included this because it's a helpful start for visualizing the API of a component, and for designers to have the same mental model for what developers are seeing.
| - @.cursor/rules/component-enum-union-migration.md | ||
| - @.cursor/rules/component-migration.md | ||
| - @.cursor/rules/figma-integration.md | ||
| - @.cursor/design-verification/README.md |
There was a problem hiding this comment.
We might be able to leave this out — I'm not sure an engineer would need to access this regularly.
There was a problem hiding this comment.
I think its fine to leave in, I'd like our team to become a bit more cross functional so engineers can at least get the component started in figma
| - @.cursor/design-verification/README.md | ||
| - @.cursor/rules/release-workflow.md | ||
|
|
||
| See @docs/ai-agents.md for comprehensive strategy explanation. |
There was a problem hiding this comment.
Right now, I believe we only have system-wide rules and docs, but no skills. It could be worth including docs in ai-agent.md and this CLAUDE.md file. But this would be better off as a follow up PR to this one.
There was a problem hiding this comment.
Great point! This is likely more of a skill, fine to leave out for now disregard my comment about leaving this in I don't think it matters too much.
| @@ -0,0 +1,19 @@ | |||
| # Attribution | |||
There was a problem hiding this comment.
Personally, I am not sure whether we are comfortable adapting work by other creators into our DS.
There was a problem hiding this comment.
I think this is fine if the license is open source
|
Converting this to draft so George can review when he gets back |
📖 Storybook Preview |
📖 Storybook Preview |
There was a problem hiding this comment.
Great first draft — the preflight, token binding, and Desktop Bridge gate are solid foundations and this fills a real gap in the AI-assisted design workflow. I ran through the full skill manually using Claude Code against the test branch PXKLmxkKBVDlegyigjRCI6 and created a RadioButton component set end-to-end, which surfaced a few gaps worth addressing before this lands.
All variants are inside one State component property instead of matching code
Design matches well
figma.component.skill.test.mov
When running Check designs, I got spacing suggestions might be worth addings
A few structural notes against docs/ai-agents.md: the three-layer diagram currently only shows CLAUDE.md → .cursor/rules/ → docs/ but this PR adds two new directories (.cursor/design-verification/ and .cursor/skills/) that aren't documented there. Worth a small update so the layer model stays accurate for future contributors.
Also related: PR #1251 adds a Code Connect skill (skill/code-connect branch). Both skills operate in the same Figma-integration space and SKILL.md already points to figma-integration.md for the Code Connect follow-up step (line 233/268). Worth coordinating on landing order — if Code Connect skill lands first, the reference here to "Optional follow-up: add Code Connect per @.cursor/rules/figma-integration.md" could become a direct skill invocation (/figma-code-connect) instead.
| **Pass** when: | ||
|
|
||
| - `figma_get_status` reports a valid WebSocket connection (`setup.valid: true`) | ||
| - `figma_navigate` succeeds (`status: already_connected` or `switched_active_file`) — **not** `websocket_file_not_connected` |
There was a problem hiding this comment.
non-blocking: This gate fails when using a Figma branch URL. Tested against https://www.figma.com/design/1D6tnzXqWgnUC3spaAOELN/branch/PXKLmxkKBVDlegyigjRCI6/... — figma_navigate extracts the main file key (1D6tnzXqWgnUC3spaAOELN) instead of the branch key (PXKLmxkKBVDlegyigjRCI6), returning websocket_file_not_connected even though the Desktop Bridge IS connected to the branch. figma_list_open_files correctly shows the branch as the active file.
Suggestion: add a note that for branch URLs (/design/:mainKey/branch/:branchKey/), the operative file key is the branch key, not the main key — and the gate should compare against the connected file from figma_list_open_files rather than re-deriving the key from the URL.
|
|
||
| **Do not** fall back to `use_figma` or official Figma MCP for component creation unless the user explicitly asks to switch MCPs. | ||
|
|
||
| ### MMDS token mapping (code → Figma) |
There was a problem hiding this comment.
suggestion: The token map is sparse — 8 entries covering the most common cases, but a real component creation session needs significantly more (e.g. border/default, icon/alternative, error/default, hover/pressed tokens, icon/muted, radius tokens). In testing I had to look these up manually from figma_get_variables output.
Consider replacing the static table with a directive to build the token map dynamically during Step C by filtering figma_get_variables output by scopes (e.g. FRAME_FILL → background tokens, TEXT_FILL → text tokens, STROKE_COLOR → border tokens). The figma-preflight.md Token Map section already defines this mapping — the SKILL.md table could just reference that instead of duplicating a subset of it.
| componentSet.strokeJoin = 'MITER'; | ||
| ``` | ||
|
|
||
| - Mirror variant props from code (`size`, `variant`, `severity`, etc.) as Figma component properties |
There was a problem hiding this comment.
suggestion: "Mirror variant props from code as Figma component properties" is ambiguous and leads agents to collapse everything into a single State variant enum (tested: RadioButton's isChecked, isDisabled, isDanger, isReadOnly all became State=Default/Checked/Disabled/ReadOnly/Danger instead of independent boolean properties).
Suggest making the mapping explicit:
- Boolean props (
isChecked,isDisabled,isDanger) → Figma boolean component properties (independently composable) - String union / enum props (
variant,size,severity) → Figma variant properties - String content props (
label,loadingText) → Figma text component properties
A golden path example here (or a link to an existing MMDS component set like Button or BadgeStatus that already uses this correctly) would help agents get this right. The existing @.cursor/rules/figma-integration.md has good prop-mapping examples — a cross-reference there would reinforce the pattern.
| descriptionMarkdown: <optional — props, usage, a11y notes> | ||
| ``` | ||
|
|
||
| Pull description content from the component README and prop types. Follow `@.cursor/rules/component-documentation.md`. |
There was a problem hiding this comment.
non-blocking: "Pull description content from the component README and prop types" is a good direction, but in practice agents summarise from prop types and miss the README's consumer-facing opening line. In testing the generated description was implementation-focused rather than matching the README.
Suggestion: be explicit — pull the first sentence from the component README as the description opening (e.g. RadioButton is a graphical element that allows users to select one option from a set of choices.), then append states/props/token summary.
| 3. Build from scratch — ONLY if nothing matches | ||
| ``` | ||
|
|
||
| Never rebuild primitives the DS provides: Button, Input, Checkbox, Toggle, Badge, Tag, Avatar, Icon, Tab, Header, TextField, etc. |
There was a problem hiding this comment.
suggestion: This static list will go stale and is already ambiguous — Header alone matches HeaderRoot, HeaderSearch, HeaderStandard, and TitleHub/TitleSubpage/TitleStandard. An agent following this literally might skip searching for the right header component because it sees "Header" on the no-rebuild list.
A more durable pattern: replace the list with a search-first directive — run figma_search_components (or search_design_system) before building anything, and only build from scratch if the search returns no match. The MMDS Components file has 70+ component pages; the search is reliable. The static list could be dropped entirely or reduced to a short illustrative note (e.g. Button, Icon, Avatar — always check first).
| Session defaults for design-verification preflight. Update per task. | ||
|
|
||
| - **MMDS Components file:** https://www.figma.com/design/1D6tnzXqWgnUC3spaAOELN/%F0%9F%A6%8A-MMDS-Components | ||
| - **Local working file (optional):** `https://www.figma.com/design/YOUR_FILE_KEY/Your-File-Name` |
There was a problem hiding this comment.
non-blocking: Worth clarifying that "local working file" means a Figma branch or personal scratch file — not a separate unrelated project. In testing, the MMDS Components branch (/branch/:branchKey/) is the natural target for this field, but the placeholder (YOUR_FILE_KEY) doesn't make that obvious. A comment like # Use a Figma branch URL here when working off main MMDS Components would help.
📖 Storybook Preview |
3 participants
Description
What is the reason for the change?
What are the goals of these skills?
What is the improvement/solution?
figma-component-creationskill to generate components that are built in code but do not exist in Figma. Variants are placed within a page, with56pxpadding and a32pxgap for visual consistency.What are the prerequisites for this to work?
What is the impact of this solution?
What principles should be considered when reviewing this PR?
figmaskills from MMDS-specific skills?Research
The structure of the skills folder is based on rough research of industry and MetaMask-specific conventions:
Attribution
The verification rules have been adapted from this repo by senlindesign. Attribution has been added.
Related issues
Fixes: NA
Manual testing steps
Prerequisites
Prompt
/figma-component-creation. You do not need to invokefigma-preflightas that has been included in the creation skill..tsxcomponent and Figma pagelinkwhere you want the component to renderNote
Screenshots/Recordings
Before
N/A
After
Step 1: Connect Figma Desktop Bridge, then generate the component
0-create-component.mov
Step 2: Read the final report
1-component-complete.mov
Step 3: Verify that design tokens are linked and props match
Screen.Recording.2026-06-16.at.8.47.34.PM.mov
Step 4: Check developer docs
Screen.Recording.2026-06-16.at.8.59.38.PM.mov
Error handling: Figma Bridge Desktop not connected
Designers/devs are given appropriate feedback
Pre-merge author checklist
Pre-merge reviewer checklist