Figma To Static

Figma → Static HTML/CSS

Recommended Runtime Profile

• Preferred model: anthropic/claude-opus-4-6
• Preferred thinking level: high
• Use this profile for full-page restoration, asset extraction planning, and multi-section iteration.
• If only doing quick environment checks or tiny CSS tweaks, lower-cost models are acceptable.

MCP Auth Non-Negotiables

When handling Claude/Figma MCP authentication, follow these rules with zero improvisation:

1. Keep exactly one live auth session.
2. Never start a second Claude/Figma auth flow until the first one is explicitly killed or succeeds.
3. Never manually retype or reconstruct long OAuth URLs in chat.
4. In remote/chat/headless handoff, prefer receiving Authentication Code (code#state) over full callback URL.
5. Use full callback URL only for state-mismatch diagnostics or localhost redirect recovery.
6. Treat vague confirmations (done / 好了 / 完成 / ok) as invalid auth evidence.
7. After Claude login succeeds, do not assume Figma MCP is authenticated; verify separately.
8. If a state/session mismatch is suspected, stop immediately, kill stale flow(s), and restart from one clean session.

Remote Chat Handoff Rule

In chat/remote/headless environments:

• Prefer asking the user to return code#state.
• Request the full callback URL only when debugging state mismatch or localhost redirect failures.
• If the CLI already displayed an authorize URL, copy it exactly from tool output or extract it with scripts/extract_auth_url.py; never hand-retype long URLs.
• Before opening a fresh login flow, run scripts/auth_session_guard.py to detect conflicts or stale state.
• Do not ask the user for code#state until REPL state is explicitly verified as waiting-for-code.
  • Scrape the current REPL output.
  • Classify it with python3 scripts/claude_repl_state.py --stdin.
  • Only if safeForCodeSubmission=true, lock the auth URL/state and ask the user for code.

Abort Conditions

Stop immediately and explain the issue if any of the following is true:

• another live Claude auth/login process already exists
• callback/code belongs to an older session
• callback state does not match the active auth state
• a previous auth session is still waiting for input
• an OAuth URL appears truncated, wrapped, or whitespace-corrupted

When an abort condition is met, do not “try one more thing” inside the same flow. Kill or abandon stale session(s), start one clean session, and ask for only one auth artifact.

Auth Status Reply Template

During auth, report progress in this shape:

• 阶段：Claude 登录 / Figma MCP 配置 / Figma MCP 授权 / MCP 工具验证
• 状态：成功 / 阻塞 / 需用户操作
• 原因：一句话具体原因
• 下一步：一句话具体动作
• 需要用户提供：code#state / callback URL / nothing

Constraints

• Only native HTML + CSS. No React, Vue, or any framework.
• Mobile-first. PC: centered max-width, background stretches.
• Directory structure: assets/ css/ html/
• Layered UI structure. Never paste a whole section as a single <img> unless the design element is truly an image (photo/illustration). Text, buttons, status indicators → real DOM. Navigation bars and menus must always be real DOM — they need to align with content width and have interactive states.
• MCP screenshots for component images only. Use MCP get_screenshot for visual assets (video covers, banners, illustrations). Use MCP get_design_context for components that need real DOM (nav, menus, footers) — it returns structured data with asset URLs for individual icons/logos.
• Avoid absolute positioning. Prefer flexbox, grid, margin, padding, and normal document flow. Only use position: absolute as last resort (e.g., decorative badges on cards, small floating labels).
• Image dimensions must be declared. Every <img> must have explicit width/height attributes or CSS aspect-ratio to prevent layout shift (CLS).
• BEM-like semantic class names. Use .block__element--modifier (e.g. .signin-card__label, .hero-topbar__brand). Never use .s1, .btn2, .c-red abbreviations.
• 1:1 pixel-level restoration target. Use visual diff pipeline to validate.

Multi-Page Strategy

• If the user specifies multiple pages (e.g., "首页 + 活动页 + 个人中心"), create separate HTML files: html/index.html, html/activity.html, html/profile.html, etc.
• If the user does not specify, default to single page (html/index.html).
• Each page shares the same css/styles.css and assets/ directory.
• If Figma file has multiple pages (top-level Page nodes), ask user which pages to implement.

Version Control

• Commit after each completed section (not after every CSS tweak).
• Commit message format: feat: add <section-name> section or fix: adjust <section-name> <what>
• Never push unless user explicitly asks.
• Small, reversible commits. If unsure about a change, commit current state first, then experiment.

Completion Criteria

The page is "done" when ALL of the following are met:

1. Layout confirmed by user (skeleton step).
2. All sections implemented with real DOM and real assets (no placeholders).
3. Visual diff similarity ≥ 90% against the full-page design reference.
4. No horizontal scroll on mobile viewport (375px-414px test).
5. User explicitly confirms final result.
6. If custom generation rules were provided, output satisfies those rules.

Workflow

0. Environment Check

Check Figma access in strict priority order (must attempt MCP first):

Priority 1 (required first attempt): Claude CLI + Figma MCP

# Explicit token mode (recommended)
export FIGMA_MCP_TOKEN=...
python3 scripts/fetch_figma_mcp.py --action tools

# OR opt-in read from Claude credential file
python3 scripts/fetch_figma_mcp.py --allow-claude-credentials --action tools

• Lists tools → MCP authenticated, proceed with MCP workflow.
• If it fails with "No Figma MCP token found", must first try one-click bootstrap:
  • bash scripts/setup_claude_mcp.sh
    • safe default = preflight/status only; does not auto-start a login flow
    • explicit opt-in to start login: bash scripts/setup_claude_mcp.sh --start-login
  • Before any fresh login flow, run:
    • python3 scripts/auth_session_guard.py --mode claude-login
    • if a user-facing authorize URL is created, immediately persist the active state:
      • python3 scripts/claude_auth_lock.py acquire --session-id <session-id> --auth-url "<authorize-url>"
  • In remote/chat/headless environments, prefer one persistent claude REPL session over repeated claude auth login attempts.
  • Login rule: once a Claude auth prompt has produced an authorize URL, do not create a second login flow until the first one either succeeds or is explicitly abandoned.
  • During remote/chat handoff, ask for Authentication Code (code#state) first.
  • Before asking for it, prove the REPL is actually waiting for code:
    • scrape current terminal output
    • classify with python3 scripts/claude_repl_state.py --stdin
    • proceed only when state=waiting-for-code and safeForCodeSubmission=true
  • Request full callback URL only for stale-state diagnostics or localhost redirect failures:
    • https://platform.claude.com/oauth/code/callback?code=...&state=...
  • Do not accept only "好了/完成/ok" as auth completion signal.
• If one-click bootstrap is unavailable, use manual onboarding:
  1. Install Claude CLI: npm install -g @anthropic-ai/claude-code
  2. Login:
     • Local interactive shell: try claude auth login
     • Remote/headless/chat handoff (preferred): run claude, then /login, keep that same REPL session alive, and paste Authentication Code (code#state) when prompted.
     • Do not bounce between claude auth login and claude REPL during the same auth attempt.
  3. Add server: claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
  4. Open Claude UI and finish MCP auth in one session:
     • run claude
     • run /mcp
     • select figma and complete Authenticate/Connect flow
     • if Figma browser redirects to localhost and fails, paste the full localhost callback URL back into Claude
  5. Verify: claude mcp list (expect figma ... Connected)
• After step 5, retry python3 scripts/fetch_figma_mcp.py --allow-claude-credentials --action tools.
• See references/figma-mcp-usage.md for details.

Priority 2: Figma REST API (fallback, detailed CSS properties)

curl -s -o /dev/null -w "%{http_code}" \
  -H "X-Figma-Token: $FIGMA_TOKEN" \
  "https://api.figma.com/v1/me"

• 200 → Token valid. Use quota-aware REST mode first:
  • python3 scripts/fetch_figma_rest.py --file-key FILE_KEY --nodes "NODE1,NODE2" --quota-aware --batch-size 3 --max-retry-after 60
• 401/403 → Guide user to generate token at Figma → Account Settings → Personal access tokens.
• 429 → Do not tight-retry. Reduce batch size (--batch-size 1~2) or switch to --metadata-only skeleton flow.

Priority 3: User-provided assets (fallback)

• ZIP of design assets + design screenshots.

Quick Troubleshooting

Before troubleshooting remote/chat/headless MCP auth, read:

• references/mcp-auth-state-machine.md

When MCP is not ready, guide the user in this exact order:

Auth policy while replying:

• be terse and procedural
• do not improvise or summarize partial auth as success
• do not reassure unless a verification command passed
• always state: current stage, blocker, exact next action, exact artifact needed from user

1. One-click setup (recommended first, default path)

   • Run a single command:
     • bash scripts/setup_claude_mcp.sh
   • Preflight guard (must pass before new flow):
     • python3 scripts/auth_session_guard.py --mode claude-login
   • This script handles: install Claude CLI → login preflight → add figma MCP → status verification.
   • Safe default: it does not auto-start a fresh login flow.
   • Start login only with explicit opt-in:
     • bash scripts/setup_claude_mcp.sh --start-login
   • If an authorize URL is generated, persist the active state before asking the user for auth data:
     • python3 scripts/claude_auth_lock.py acquire --session-id <session-id> --auth-url "<authorize-url>"
   • In remote/headless/chat flows, prefer one persistent claude REPL session:
     • run claude
     • complete any first-run setup screens first (theme / login method)
     • scrape the visible REPL output and classify with python3 scripts/claude_repl_state.py --stdin
     • if state is not waiting-for-code, do not ask user for auth data yet
     • run /login if needed
     • open the authorize URL shown by Claude
     • if you need to pass the URL through chat, first extract it exactly with python3 scripts/extract_auth_url.py --stdin
     • persist the active state via python3 scripts/claude_auth_lock.py acquire --session-id <session-id> --auth-url "<authorize-url>"
     • paste Authentication Code (code#state) into Paste code here if prompted >
     • keep that same Claude session alive until login succeeds
   • Reject vague confirmations ("好了/完成"). Require exact auth handoff text (code#state, callback URL, or localhost callback URL).
   • Before asking for auth data, classify the live REPL output with python3 scripts/claude_repl_state.py --stdin; only continue when it reports waiting-for-code.
   • Validate user-returned auth data against the active lock before submission:
     • python3 scripts/claude_auth_lock.py verify-code --code-state "<code#state>"
     • or python3 scripts/claude_auth_lock.py verify-callback --callback-url "<callback-url>"
   • Never start another login attempt while one Claude session is already waiting for callback/code.

2. Check Claude usage quota early (avoid dead-end loops)

   • Quick probe:
     • claude --print "quota-check"
   • If output contains phrases like You've hit your limit / reset time:
     • Stop MCP auth retry loop (this is quota, not auth wiring)
     • Wait for reset, or switch/upgrade Claude account
     • Continue delivery via REST fallback (FIGMA_TOKEN) with skeleton-first + quota-aware pulling

3. If one-click setup fails, use manual checks

   • Follow references/mcp-auth-state-machine.md strictly; do not improvise auth retries.
   • claude command not found:
     • npm install -g @anthropic-ai/claude-code
     • Re-check: claude --version
   • Not logged in:
     • local shell: claude auth login
     • remote/headless/chat: claude → /login → keep the same REPL alive → paste Authentication Code (code#state)
   • Figma MCP server missing:
     • claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp
   • Figma MCP shows Needs authentication:
     • open claude → /mcp → figma → Authenticate/Connect
     • if browser redirects to localhost and fails, paste the full localhost callback URL back into the same Claude session
     • verify with claude mcp list (must be Connected)

4. Script cannot find token

   • Preferred explicit mode:
     • export FIGMA_MCP_TOKEN=...
     • python3 scripts/fetch_figma_mcp.py --action tools
   • Optional credential-file mode:
     • python3 scripts/fetch_figma_mcp.py --allow-claude-credentials --action tools

5. Still blocked after MCP auth is truly stabilized

   • Do not recommend PAT/REST just because Claude auth handoff was messy once.
   • First confirm all of the following:
     • claude auth status shows logged in
     • claude mcp list shows figma ... Connected
     • the MCP whoami result matches the intended Figma account
     • only then test fetch_figma_mcp.py
   • Only if MCP is authenticated yet the target file remains inaccessible or the user explicitly wants fallback, use REST API mode (quota-aware, low burst):
     • export FIGMA_TOKEN=...
     • python3 scripts/fetch_figma_rest.py --file-key FILE_KEY --nodes "NODE1,NODE2" --quota-aware --batch-size 2 --sleep-ms 1500 --max-retry-after 60
   • If 429 persists with long Retry-After, stop image pull and continue with metadata-only skeleton:
     • python3 scripts/fetch_figma_rest.py --file-key FILE_KEY --nodes "NODE1,NODE2" --metadata-only
   • Or continue with user-provided ZIP/screenshots.

6. Callback invalid / stale diagnostics (must check before retry loop)

   • Most common causes:
     1. stale callback from an older auth attempt (state mismatch)
     2. multiple concurrent claude auth login sessions created different states
     3. waiting login process was terminated (timeout/SIGTERM) before callback handoff
     4. authorize URL was copied through chat with truncation/whitespace corruption
   • Enforce single-session rule: keep only one active Claude login process at a time.
   • Run guard first:
     • python3 scripts/auth_session_guard.py --mode claude-login
   • Extract the authorize URL from raw CLI output instead of hand-copying:
     • python3 scripts/extract_auth_url.py --stdin
   • Validate callback state against current authorize URL:
     • python3 scripts/parse_claude_oauth_callback.py --auth-url "<latest_auth_url>" --callback-url "<user_callback_url>"
   • If mismatch, stop immediately, kill stale flow(s), and use only one new authorize URL.