design-brief-to-figma
Skill9 starsChanged 7 days agoMITView on GitHub
Generates a real Figma file from a design-brief.json. Renders the brief as one high-fidelity HTML mockup per page (via the conversation-designer agent), serves them locally, creates a new Figma file, and captures each mockup into it with the Figma MCP generate_figma_design tool. Outputs a Figma URL that /build-from-figma consumes. Phase C1 of /build-from-conversation. Keywords: design brief to Figma, generate Figma design, Figma file generation, HTML mockup capture, conversational design
In this repository32 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- animation-motionSkill
- auth-flowsSkill
- build-from-canvaSkill
- build-from-conversationSkill
- build-from-figmaSkill
- build-from-screenshotSkill
- canva-intakeSkill
- canva-token-inferenceSkill
- ciSkill
- conversation-intakeSkill
- design-token-lockSkill
- e2e-test-generatorSkill
- export-design-systemSkill
- figma-intakeSkill
- figma-to-react-workflowSkill
- form-handlingSkill
- indesign-conversionSkill
- lintSkill
- parallel-orchestrationSkill
- react-accessibilitySkill
- react-component-developmentSkill
- react-performance-optimizationSkill
- react-testing-workflowsSkill
- screenshot-intakeSkill
- seo-metadataSkill
- state-managementSkill
- storybook-story-generationSkill
- tdd-from-figmaSkill
- testSkill
- verify-allSkill
- visual-qa-verificationSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 54
Run it in the background and verify each page responds (e.g.
- Very specific: line 111
When conversation.designGeneration.reviewBeforeHandoff is true (default):
- Very specific: line 124
Stop the static server. Return the Figma file URL — /build-from-conversation passes it to /build-from-figma, whose Phase 1 (figma-intake) …
- Very specific: line 134
Figma MCP unavailable / unauthenticated: Stop before generating anything.
- Very specific: line 135
Multiple plans and no answer: Do not guess a planKey; a file created in the wrong org is outward-facing.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Design Brief to Figma — Generated Design Files
Purpose
Turn the design-brief.json produced by conversation-intake into an actual Figma file, so the standard /build-from-figma pipeline can run against it unchanged. The mechanism is HTML-mockup capture: mcp__figma__generate_figma_design imports a rendered web page into an existing Figma file pixel-perfectly, so this skill renders the brief as static HTML first, then captures each page. The generated file becomes the single visual source of truth — Phase 5 pixel-diffs the built app against frames created here.
When to Use
- Phase C1 of
/build-from-conversation, immediately afterconversation-intake - Any time a confirmed
design-brief.json+build-spec.jsonpair exists and a Figma file needs to be generated from it
Inputs
- Required:
.claude/plans/design-brief.jsonand.claude/plans/build-spec.json(with"source": "conversation") - Reads:
.claude/pipeline.config.json→conversation.designGeneration(mockupDir,mockupServerPort,reviewBeforeHandoff,maxRegenerationAttempts,capturePollIntervalMs,capturePollMaxAttempts) andconversation.retry
Process
Step 1: Preflight — Figma Auth and Plan
1. Call mcp__figma__whoami
→ Confirms authentication and returns the user's plans
2. Resolve planKey:
- Exactly one plan → use its `key` field verbatim
- Multiple plans → ask the user which team/organization to use (one question)
3. If the Figma MCP is unavailable or unauthenticated, stop here —
report it and leave the brief/spec artifacts intact for a later resumeStep 2: Render the Brief as HTML Mockups
Dispatch the conversation-designer agent to write one self-contained HTML mockup per page in build-spec.json > pages[] into conversation.designGeneration.mockupDir (default .claude/design-mockups/):
For each page: <mockupDir>/<route-slug>.html (e.g. dashboard.html, settings.html)The agent definition owns the mockup quality bar (deterministic, no JS, exact brief values, real text content, data-section landmarks). After generation, record each page's mockupPath in build-spec.json.
Step 3: Serve the Mockups Locally
generate_figma_design captures a served page, so host the mockup directory on a local static server:
npx serve <mockupDir> -l <mockupServerPort> # default port 4173Run it in the background and verify each page responds (e.g. http://localhost:4173/dashboard.html) before capturing. Any static server works; npx serve keeps it dependency-free.
Step 4: Create the Figma File
1. If the Figma MCP serves a figma-create-new-file skill, load it first
(resource: skill://figma/figma-create-new-file/SKILL.md) — its tool
description requires this when available
2. Call mcp__figma__create_new_file with:
- fileName: design-brief.json > appName
- planKey: from Step 1
- editorType: "design"
3. Record the returned fileKey and file URLStep 5: Capture Each Page (generate_figma_design)
Each capture is single-use and captures exactly one page — run this loop once per page in the build spec:
FOR each page IN build-spec.pages:
1. Call mcp__figma__generate_figma_design({ fileKey })
→ Returns a capture script + a captureId (single-use; do not reuse across pages)
2. Follow the returned capture-script instructions against the page's local
mockup URL (http://localhost:<port>/<page>.html). For local URLs this
typically means opening the URL with the capture fragment so the script
can snapshot the rendered DOM.
3. Poll: mcp__figma__generate_figma_design({ fileKey, captureId })
every conversation.designGeneration.capturePollIntervalMs (default 5000ms),
up to capturePollMaxAttempts (default 10), until status is "completed"
4. On timeout or failure: apply conversation.retry (exponential backoff) and
retry the page with a FRESH captureId — the old one is spentEach completed capture lands as a new page/frame in the Figma file.
Step 6: Map Generated Node IDs into the Build Spec
1. Call mcp__figma__get_metadata({ fileKey }) → top-level pages (guid + name)
2. For each captured page, drill in as needed to identify its root frame
3. Write the IDs back into build-spec.json:
- pages[].figmaNodeId = the captured frame's node ID (e.g. "1:2")
4. Populate the figma block and keep the source untouched:
{
"source": "conversation", // unchanged — this is how figma-intake fast-paths
"figma": {
"fileKey": "<fileKey>",
"fileName": "<appName>",
"url": "https://figma.com/design/<fileKey>/<appName>",
"generated": true
}
}Step 7: Review Gate (Conditional)
When conversation.designGeneration.reviewBeforeHandoff is true (default):
1. Capture a screenshot of each generated page (mcp__figma__get_screenshot)
2. Present the Figma URL + screenshots to the user
3. On rejection: route feedback to conversation-designer, regenerate only the
affected mockups, and re-capture only those pages (fresh captureIds).
Max loops: conversation.designGeneration.maxRegenerationAttempts (default 2)
4. On approval (or when the review gate is disabled): proceedStep 8: Cleanup and Output
Stop the static server. Return the Figma file URL — /build-from-conversation passes it to /build-from-figma, whose Phase 1 (figma-intake) fast-paths on the conversation-sourced build spec.
Output
Primary: Figma file URL (real, editable file in the user's account)
Secondary: Updated .claude/plans/build-spec.json (populated figma block, pages[].figmaNodeId, pages[].mockupPath)
Tertiary: <mockupDir>/*.html mockups (kept — they document the generated design and allow cheap re-capture)
Error Handling
- Figma MCP unavailable / unauthenticated: Stop before generating anything; the brief and spec survive for a later resume. Suggest checking Figma auth (
whoami). - Multiple plans and no answer: Do not guess a
planKey; a file created in the wrong org is outward-facing. Wait for the user. - Capture timeout (poll budget exhausted): Retry per
conversation.retrywith a fresh captureId. If a page still fails, continue capturing remaining pages and report the failed page for manual capture. - Mockup server port in use: Increment the port, retry once, and record the port actually used.
- Generated file has no Figma variables: Expected — captured designs carry styles, not variable definitions, so Phase 2 (
design-token-lock) falls back to computed styles. This is the documentedfigma-intake/token-lock fallback; the lockfile is still authoritative because the mockups were generated from the brief's exact values.
Integration
- Consumed by:
/build-from-conversation(Phase C1); its output URL feeds/build-from-figma - Uses:
conversation-designeragent,mcp__figma__whoami,mcp__figma__create_new_file,mcp__figma__generate_figma_design,mcp__figma__get_metadata,mcp__figma__get_screenshot, a local static server (npx serve) - Config keys read:
pipeline.config.json→conversation.designGeneration.*,conversation.retry
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

