agentleFS
PMDevSolutionsPMDevSolutions/Aurelius/.claude/skills/design-brief-to-figma/SKILL.md

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

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
  1. Very specific:

    Run it in the background and verify each page responds (e.g.

    line 54
  2. Very specific:

    When conversation.designGeneration.reviewBeforeHandoff is true (default):

    line 111
  3. Very specific:

    Stop the static server. Return the Figma file URL — /build-from-conversation passes it to /build-from-figma, whose Phase 1 (figma-intake) …

    line 124
  4. Very specific:

    Figma MCP unavailable / unauthenticated: Stop before generating anything.

    line 134
  5. Very specific:

    Multiple plans and no answer: Do not guess a planKey; a file created in the wrong org is outward-facing.

    line 135

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 after conversation-intake
  • Any time a confirmed design-brief.json + build-spec.json pair exists and a Figma file needs to be generated from it

Inputs

  • Required: .claude/plans/design-brief.json and .claude/plans/build-spec.json (with "source": "conversation")
  • Reads: .claude/pipeline.config.json → conversation.designGeneration (mockupDir, mockupServerPort, reviewBeforeHandoff, maxRegenerationAttempts, capturePollIntervalMs, capturePollMaxAttempts) and conversation.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 resume

Step 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 4173

Run 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 URL

Step 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 spent

Each 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): proceed

Step 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.retry with 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 documented figma-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-designer agent, 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.