Figma To Static 2.0.5

Convert Figma design files to pixel-level mobile-first static HTML/CSS pages. Use when: (1) user provides a Figma file link and wants a static web page, (2) user sends design screenshots/assets and says "按设计图还原", (3) user asks to build a landing page from Figma, (4) iterating on Figma-to-code pixel accuracy. Handles: Figma MCP-first extraction (metadata/context/screenshots) with REST API fallback, layered DOM reconstruction (not whole-image paste), visual diff pipeline with region heatmap for quality validation, mobile-first responsive layout. NOT for: React/Vue/SPA frameworks, server-side rendering, interactive JS-heavy pages.

# 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**
```bash
# 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`