figma-to-static（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.

1. 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

1. 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)

1. 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

1. 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.

1. 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.

0.3 Validate Figma Link (must run before rule intake)

Before asking custom rules, validate link/file/node first:

# Fast syntax check (no token required)
python3 scripts/validate_figma_input.py --figma-url "<figma-url>"

# Strong check (requires FIGMA_TOKEN): verify file accessibility + full-page heuristic
FIGMA_TOKEN=... python3 scripts/validate_figma_input.py --figma-url "<figma-url>" --check-api

Decision rules:

• INVALID_URL / FILE_INVALID_OR_UNAUTHORIZED / NODE_INVALID → stop and ask user for corrected link/access.
• FULL_PAGE_ASSESSMENT: likely partial/component → ask user to confirm whether they want component restore or provide page-level node-id.
• If no node-id, default target is whole file/page and continue.

0.5 Rule Intake Gate (Optional, Can Be Empty)

Before generating code, offer user an optional rule intake. If user leaves it blank, proceed with defaults.

Collect only these six fields:

1. Adaptive strategy

- User options: mobile-first / desktop-first / mobile-only / desktop-only - Default: mobile-first

1. Breakpoints

- User format example: 375, 768, 1200 - Default: 375, 768, 1200

1. Layout width strategy

- User options: fixed width / fluid / max-width centered - Default: max-width centered

1. Typography sizing strategy

- User options: px / rem / clamp - Default: clamp for responsive text, with pixel-accurate base ratio

1. Interactive states

- User options: none / basic (:hover,:active,:disabled) / full - Default: basic

1. Browser compatibility target

- User options: modern evergreen only / include Safari stable - Default: include Safari stable

If any field is empty, keep the default and continue execution without blocking.

Quick prompt template:

可选自定义生成规则（可留空，留空=默认）：
1) 端适配策略（mobile-first/desktop-first/mobile-only/desktop-only）：
2) 断点（例如 375,768,1200）：
3) 页面宽度策略（fixed/fluid/max-width centered）：
4) 字体策略（px/rem/clamp）：
5) 交互态（none/basic/full）：
6) 浏览器兼容目标（modern only/include Safari stable）：

1. Gather Inputs

Required (at least one):

• Figma file URL + fileKey
• User-provided ZIP of design assets (PNG/SVG)
• Design reference screenshots

If Figma MCP available (preferred):

# Choose auth mode once:
# A) export FIGMA_MCP_TOKEN=...
# B) MCP_AUTH="--allow-claude-credentials"

# Step 1: Batch pull metadata+screenshot+context in one MCP session
python3 scripts/fetch_figma_mcp.py ${MCP_AUTH:-} \
  --file-key FILE_KEY \
  --node-ids "NODE_ID NAV_NODE_ID COVER1 COVER2" \
  --action bundle \
  --out-dir ./mcp-assets

# Step 2: Parse/download context assets automatically (SVG normalization included)
python3 scripts/parse_design_context.py \
  --context-glob "./mcp-assets/context-*.txt" \
  --assets-dir ./assets \
  --manifest ./source/context-assets.json

# Step 3: Optional targeted screenshots for image-heavy sections
python3 scripts/fetch_figma_mcp.py ${MCP_AUTH:-} \
  --file-key FILE_KEY \
  --node-ids "BANNER1 FOOTER" \
  --action screenshot \
  --out-dir ./assets

If REST API available (for detailed CSS extraction):

• First run quota-aware small-batch pull:

- 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 image quota is blocked, switch to skeleton-safe metadata mode:

- python3 scripts/fetch_figma_rest.py --file-key FILE_KEY --nodes "NODE1,NODE2" --metadata-only

• Then run scripts/figma_to_css.py on the exported nodes.json.

If ZIP provided:

• Unzip to source/, rename files meaningfully, copy usable assets to assets/.

2. Analyze Structure → Layout First, Then Details

Critical rule: always build the skeleton before polishing pixels.

1. Identify sections from the full-page design:

- Scan top-to-bottom, name each visual block (hero, signin, feature-1, feature-2, footer…). - Output a section map with approximate vertical order and height ratios.

1. Build the skeleton — placeholder-only HTML/CSS:

- One <section> per block with a colored background or placeholder text. - Flex/grid layout structure in place (no absolute positioning). - Correct vertical stacking order and relative heights. - overflow-x: hidden on body, scrollable rows marked.

1. Take skeleton screenshot → send to user for confirmation.

- Ask: "布局结构和分段顺序对吗？" - Do NOT proceed to detail work until user confirms the layout.

1. Layer in details per confirmed section:

- Insert real assets (images, icons). - Build real DOM for text, buttons, status indicators, timelines. - Apply typography, colors, spacing, borders from Figma node data. - Take screenshot → send to user after each section completes. - Git commit after each section is done.

1. Missing assets? Try to fetch before asking:

- Check if the asset exists in assets/ or source/ (cache first). - If REST API is available, pull only the needed nodes in small batches: - python3 scripts/fetch_figma_rest.py --file-key FILE_KEY --nodes "<node-id>" --quota-aware --batch-size 1 - If the node ID is unknown, ask the user for the specific layer/node ID. - If REST API quota is blocked (quota-status.json shows degraded), continue skeleton and ask user for direct asset file.

1. NEVER generate fake assets.

- Do NOT screenshot a design and crop it to create an "asset". - Do NOT draw/create placeholder images to simulate missing design elements. - Do NOT use solid-color boxes or emoji to stand in for real icons/photos. - Every pixel must come from either: (a) Figma export, (b) user-provided file, or (c) CSS/SVG reconstruction of simple shapes (borders, backgrounds, gradients — NOT complex illustrations).

3. Build the Page

First apply resolved rule-intake profile (user values or defaults), then generate files.

Generate three directories:

html/index.html (or html/<page>.html for multi-page)

• Semantic <section> per design block.
• Real DOM elements for text, status, buttons, timelines.
• Images only for true visual assets (backgrounds, illustrations, photos).
• <meta viewport> with width=device-width, initial-scale=1.

css/styles.css

• :root variables for max-width and theme colors.
• overflow-x: hidden on html, body, .page-shell to prevent horizontal scroll.
• overflow-x: clip on .stage containers; only specific scrollable rows get overflow-x: auto.
• Percentage-based positioning for overlays (derived from Figma node coordinates).
• clamp() for responsive typography.
• @media (min-width: 801px) for PC centered layout.

**assets/***

• Named meaningfully (not figma-01.png).
• Prefer user-provided assets over Figma exports when available.

4. Auto-Extract CSS from Figma Nodes

After fetching nodes.json, run the auto-extraction script:

python3 scripts/figma_to_css.py --nodes rest-assets/nodes.json --out source/figma-extracted.css

This parses every node and outputs CSS property blocks for:

• Colors, fonts, spacing, shadows, borders, border-radius
• Auto-layout: flex-direction, gap, justify-content, align-items, padding

Use the extracted CSS as a reference when writing styles.css. Do NOT copy-paste blindly — adapt to the actual DOM structure.

5. Extract Exact Properties from Figma Nodes

Do not guess. Read nodes.json, then map values to CSS.

Use this reference for full mapping table + strict rules:

• references/css-extraction-rules.md

6. Visual Diff Validation (with Region Heatmap)

After each major iteration:

# 1. Screenshot current render
google-chrome --headless=new --disable-gpu --no-sandbox \
  --window-size=800,5338 \
  --screenshot=compare/current.png \
  http://127.0.0.1:PORT/html/

# 2. Compare with region heatmap + structure metrics (default 5x5 grid)
python3 scripts/visual_diff.py \
  --current compare/current.png \
  --target assets/design-main.png \
  --diff compare/diff.png \
  --regions 5 \
  --threshold 30 \
  --json-out compare/metrics.json

The tool outputs:

• MAE similarity (pixel-level)
• SSIM similarity (structure-level)
• Composite similarity (weighted MAE + SSIM)
• Heatmap overlay (green/yellow/red), plus labeled bad regions by MAE threshold

Focus iteration on red regions first, then raise composite similarity.

7. Preview Server

When running on a cloud server, start a temporary HTTP server for public preview:

# Find an available port (e.g. 8090 if 8080 is taken)
python3 -m http.server PORT --bind 0.0.0.0

• Run in background so it persists across iterations.
• Bind to 0.0.0.0 (not 127.0.0.1) so it's accessible via public IP.
• Check for port conflicts before starting (lsof -i :PORT or ss -tlnp).
• Provide user with http://<PUBLIC_IP>:PORT/html/ link.
• If running behind a firewall, ensure the port is open.

8. Screenshot & Send to User (Every Iteration)

After each code generation iteration, before reporting results:

1. Take a screenshot of the current render:

google-chrome --headless=new --disable-gpu --no-sandbox \
  --window-size=800,5338 \
  --screenshot=compare/current.png \
  http://127.0.0.1:PORT/html/

1. Send the screenshot to the user via the messaging platform (Telegram/Discord/etc.) using the media/file sending tool — do NOT just send a URL, send the actual image.

1. Then optionally run visual diff against target and mention the similarity score.

This ensures the user can verify visual quality without opening a browser on every iteration.

Anti-Patterns (Shortlist)

1. Never use a full-section screenshot when real DOM is required.
2. Never invent content or fake assets.
3. Never skip mobile overflow controls (overflow-x: hidden where needed).
4. Never guess properties that exist in Figma JSON.
5. Never build nav/menu/timeline as image slices when interactive DOM is expected.

Full checklist: references/anti-patterns.md

Scripts

• scripts/validate_figma_input.py — Validate Figma URL/file/node; optionally classify whether target is full-page vs component (--check-api).
• scripts/fetch_figma_mcp.py — Primary. MCP fetcher with token auto-refresh, batch node extraction (--node-ids), and bundle mode (--action bundle).
• scripts/auth_session_guard.py — Detect conflicting Claude sessions and refuse fresh login attempts while an active auth lock or existing Claude process is present.
• scripts/claude_auth_lock.py — Persist the one active Claude auth state (sessionId + authorize URL/state) and validate incoming code#state or callback URLs before submission.
• scripts/claude_repl_state.py — Classify raw Claude REPL output (theme picker / login method picker / waiting-for-code / ambiguous) and block auth handoff unless the REPL is actually waiting for code.
• scripts/extract_auth_url.py — Extract an unbroken Claude OAuth authorize URL from raw terminal output; use instead of hand-copying wrapped URLs.
• scripts/parse_claude_oauth_callback.py — Validate callback URL or code#state against the active authorize URL to detect stale/invalid callbacks.
• scripts/parse_design_context.py — Parse MCP context files, download asset URLs, and normalize SVG stretch issues.
• scripts/fetch_figma_rest.py — Extract node metadata + images via Figma REST API (needs FIGMA_TOKEN), with quota-aware batching, retry-after guardrail, metadata-only degradation, and local cache reuse.
• scripts/figma_to_css.py — Auto-parse REST nodes.json → CSS property blocks.
• scripts/visual_diff.py — Compare render vs target with MAE + SSIM + heatmap.

References

• references/figma-mcp-usage.md — Figma MCP tools reference, setup, auth modes, and batch usage.
• references/css-extraction-rules.md — Strict property mapping and non-negotiable CSS extraction rules.
• references/file-structure.md — Standard project directory layout.
• references/css-patterns.md — Reusable CSS patterns for common design elements.
• references/anti-patterns.md — Full anti-pattern checklist for QA passes.