# Figma2design

> Figma design link → complete .design/ directory (DESIGN.md, PAGES.md, COMPONENTS.md, CODE_PATTERNS.md, ICONS.md, brand/, icons/, screenshots)

- Skill: `yugasun/figma2design` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add yugasun/figma2design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yugasun/figma2design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: yugasun (https://skillmd.com/u/yugasun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yugasun/figma2design

---


# /figma2design

Turn a Figma design link into a complete design system extraction — producing a `.design/` directory with structured markdown specs, brand assets, and screenshots, ready for AI-driven UI generation.

## Usage

```text
/figma2design <figma-url>                       # full extraction
/figma2design <figma-url> --pages home,skills    # extract specific pages only
/figma2design <figma-url> --screenshots-only     # only screenshots, no docs
/figma2design <figma-url> --update               # re-extract, keep existing files as reference
```

**URL formats supported:**
- `https://www.figma.com/design/:fileKey/:fileName?node-id=:int1-:int2`
- `https://figma.com/design/:fileKey/:fileName`
- `https://www.figma.com/file/:fileKey/:fileName?node-id=:int1-:int2`

## What This Skill Produces

Given a Figma design file, this skill generates:

```
.design/
├── DESIGN.md            # Design tokens (colors, typography, spacing, shapes, components)
├── CODE_PATTERNS.md     # Tech stack + code conventions + layout patterns
├── COMPONENTS.md        # Component behavior specs (props, states, interactions)
├── PAGES.md             # Page-level specs (layout, data flow, interactions, states)
├── ICONS.md             # Icon inventory with sources and sizes
├── brand/               # Brand assets extracted from Figma
│   ├── logo-mark.svg    # Logo / brand mark
│   ├── app-icon.png     # App icon
│   ├── mascot.png       # Mascot / character (if present)
│   └── ...
├── icons/               # Custom icon SVGs extracted from Figma
│   ├── icon-name.svg
│   └── ...
└── screenshots/         # All key screens as PNG (named after Figma frames)
    ├── index.md         # 截图目录：按功能模块分组，文件名 ↔ 说明
    ├── 首页.png
    ├── 技能库.png
    └── ...
```

Each file answers a different question for the UI generator:

| File | Question it answers |
|---|---|
| DESIGN.md | What colors, fonts, spacing, and shapes? |
| CODE_PATTERNS.md | What tech stack? How to organize code? |
| COMPONENTS.md | What props does this component take? What states? |
| PAGES.md | What components go where? What data flows? |
| ICONS.md | What icon is that? Where to import it from? |
| brand/ | What are the actual logo/app-icon/mascot files? |
| icons/ | What custom SVG icons does the design use? |
| screenshots/ | What should it look like? (visual fallback + index) |

## Prerequisites

- Figma MCP plugin (`figma@claude-plugins-official`) installed and authenticated
- Edit access to the target Figma file (view-only will fail)
- The `figma:figma-use` skill available

If the Figma MCP tools are not available, prompt the user:
> "需要安装 Figma MCP 插件。请运行: `/plugin` 安装 figma@claude-plugins-official, 然后 `/reload-plugins --force`"

If authentication is needed, initiate OAuth:
> Call `mcp__plugin_figma_figma__authenticate` and wait for the user to confirm authorization.

## What You Must Do When Invoked

Follow these steps in order. Do not skip steps.

---

### Step 1 — Parse URL and validate access

Extract `fileKey` and optional `nodeId` from the URL:

```
URL pattern: https://figma.com/design/{fileKey}/{fileName}?node-id={int1}-{int2}
- fileKey: 22-char alphanumeric string (e.g., "YSNZIphFjVjMWMPd4RhCLA")
- nodeId: "{int1}:{int2}" (e.g., "0:1" for root, "230:8494" for specific frame)
```

If node-id is absent, use root node `0:1`.

Validate access by calling:

```
mcp__plugin_figma_figma__get_metadata({ fileKey })
```

If this fails with permission error, tell the user they need edit access and stop.

---

### Step 2 — Discover page structure and key frames

Call `get_metadata` to get the full page tree. From the metadata, identify:

1. **Full-screen frames** — frames with width ≥ 1200px and height ≥ 700px (typical desktop screens)
2. **Sub-frames** — smaller frames that represent UI components or sections
3. **Page organization** — how frames are grouped (by flow, by feature, etc.)

For each full-screen frame, record:
- `id` (node ID)
- `name` (frame name)
- `position` (x, y — for ordering)
- `size` (width × height)

Sort frames by position (left-to-right, top-to-bottom) to establish reading order.

```
Example output:
  id=1:2      name="首页"     pos=(2377,0)     size=1440×900
  id=230:8494 name="技能库"    pos=(2377,1252)  size=1440×900
  id=235:10138 name="自动化"   pos=(2377,3756)  size=1440×900
  id=26:3543  name="任务执行"  pos=(11848,0)    size=1440×900
```

Present a summary to the user:
```
发现 N 个全屏 frame:
  1. 首页 (1:2)
  2. 技能库 (230:8494)
  3. 自动化 (235:10138)
  4. 任务执行 (26:3543)
开始提取...
```

---

### Step 3 — Capture screenshots

Create the output directory:

```bash
mkdir -p .design/screenshots
```

For each key frame identified in Step 2, call `get_screenshot`:

```
mcp__plugin_figma_figma__get_screenshot({
  fileKey: "<fileKey>",
  nodeId: "<frame-id>",
  maxDimension: 1440
})
```

Download each screenshot using the returned URL:

```bash
curl -sL "<screenshot-url>" -o .design/screenshots/<descriptive-name>.png
```

**Naming rules — prioritize Figma frame names:**
- **Use the Figma frame name directly** as the filename, converted to lowercase kebab-case: frame name "首页" → `首页.png`, "Skill Library" → `skill-library.png`, "任务执行" → `任务执行.png`
- Preserve Chinese frame names as-is when the design is primarily in Chinese — do NOT translate to English slugs
- Only convert whitespace and special characters to hyphens: "Home - Default" → `home-default.png`
- For variant states, append the state: frame "首页" with variant "empty" → `首页-empty.png`
- For unnamed/ambiguous frames: `screen-N.png` (numbered by position order)
- If two frames share the same name (across different pages), disambiguate with page prefix: `page-name-frame-name.png`

> ⚠️ **IMPORTANT: Verify screenshot names match content.** After downloading each screenshot, read the image file back using the Read tool and visually inspect it. Ensure the filename accurately describes what the screenshot shows. Common mistake: confusing `skill-library-*` views (card grids, detail modals) with `task-execution-*` views (chat panels, deliverables, running states). If a name doesn't match, rename it immediately before proceeding.

After all screenshots are saved, list them with file sizes for verification.

---

### Step 3.1 — Generate screenshots index

After all screenshots are verified, generate `.design/screenshots/index.md` as a visual directory grouped by functional module.

For each screenshot, read the image file and write an accurate description of what it shows. This file is consumed by `/design2code` to quickly locate the right visual reference without opening every image.

**Format:**

```markdown
# 截图目录

> <Project Name> 全部页面截图，按功能模块分组，文件名直接对应 Figma frame 标签。

---

## 首页 (Home)

| 截图 | 说明 |
|------|------|
| ![首页](./首页.png) | 首页 — 居中输入区域、左侧最近项目列表、空聊天面板 |

---

## 技能库 (Skill Library)

| 截图 | 说明 |
|------|------|
| ![技能库](./技能库.png) | 技能库 — 技能卡片网格视图，含搜索栏和分类筛选 |
| ![技能详情](./技能详情.png) | 技能详情 — 点击技能卡片后打开的技能说明页 |

---

## 任务执行 (Task Execution)

| 截图 | 说明 |
|------|------|
| ![任务执行中](./任务执行中.png) | 任务执行中 — 运行中任务视图，聊天消息、步骤进度、输出面板 |

### Skill 调用

| 截图 | 说明 |
|------|------|
| ![查看调用了的Skill](./查看调用了的Skill.png) | 查看调用了的Skill — 展开查看任务中调用的 Skill 列表 |
```

**Rules:**
- Every screenshot MUST appear in the index — no missing files
- Group screenshots by **functional module** using `## 模块中文名 (English Name)` headings
- Sub-states or sub-views within a module use `###` sub-headings (e.g. `### Skill 调用`, `### 产出结果`)
- Each section is separated by a horizontal rule `---`
- Table columns are `截图` (inline image `![name](./file.png)`) and `说明` (content description)
- `说明` format: `模块名 — <具体页面内容描述>`
- Screenshot filenames must match the actual files on disk (Figma frame names per naming rules)
- Read each image to verify the description accurately reflects the content
- Sort by functional module grouping first, then by reading order within each group
- If a screenshot was renamed during verification, use the final filename

---

### Step 3.5 — Extract brand assets and icons

Extract visual brand assets and custom icons directly from Figma for use in the generated codebase.

#### Brand assets (`brand/`)

Look for these common brand asset types in the Figma file (usually on a "Brand", "Assets", or "Style Guide" page, or as standalone top-level frames):

1. **Logo / brand mark** — the primary logo, wordmark, or brand symbol
2. **App icon** — square app icon (usually 512×512 or similar)
3. **Mascot / character** — brand character or illustration (if present)
4. **Favicon** — browser tab icon (if present)

For each found brand asset:

```
mcp__plugin_figma_figma__download_assets({
  fileKey: "<fileKey>",
  nodeId: "<brand-node-id>",
  defaultFormat: "svg"   // SVG for logo/mark; use "png" for raster-only assets
})
```

Save to `.design/brand/`:
- `logo-mark.svg` or `logo-mark.png`
- `logo-wordmark.svg` (if separate)
- `app-icon.png`
- `favicon.png` or `favicon.svg`
- `mascot.png` (if present)

If a brand page is not found, search for nodes named "logo", "icon", "brand", "mark" across all pages using `get_metadata` and inspect their names.

#### Custom icons (`icons/`)

For custom SVG icons that are NOT standard Lucide icons (i.e., branded or unique icons):

1. Identify icon frames/components in Figma — usually small frames (16×16 to 48×48) grouped under "Icons" or "UI Kit" sections
2. Export each as SVG:

```
mcp__plugin_figma_figma__download_assets({
  fileKey: "<fileKey>",
  nodeId: "<icon-node-id>",
  defaultFormat: "svg"
})
```

3. Save to `.design/icons/` with descriptive kebab-case names:
   - `sparkle-brand.svg`
   - `nuo-logo.svg`
   - etc.

Document all extracted icons in `ICONS.md` under a "## Custom Icons" section, listing filename, purpose, and size.

> ⚠️ **This step is mandatory.** Even if there's no dedicated "Brand" or "Icons" page, search for custom icons within the main frames. Look for:
> - Nodes named "Icon/*" (e.g., `Icon/Arrow Left`, `Icon/历史会话`)
> - Brand marks near text like "NuoNuo", "logo", "品牌"
> - Small frames (16×16 to 48×48) grouped as icon components
> - Nodes with names like "Credit-rating", "Calendar / Alarm", "magic-tool" that represent custom icons
>
> Use `get_metadata` to search all nodes, then `download_assets` with `defaultFormat: "svg"` for each identified icon. If truly no custom icons exist, note it explicitly in the final report.

---

### Step 4 — Extract design context from key screens

For the **3–6 most information-dense screens**, call `get_design_context`:

```
mcp__plugin_figma_figma__get_design_context({
  fileKey: "<fileKey>",
  nodeId: "<frame-id>",
  clientFrameworks: "react",
  clientLanguages: "typescript,html,css"
})
```

This returns React + Tailwind code that reveals:
- Exact hex colors used (from Tailwind arbitrary values like `bg-[#FAFAFA]`)
- Font families, sizes, weights (from `font-['PingFang_SC']`, `text-[14px]`, `font-semibold`)
- Spacing values (from `gap-[24px]`, `p-[14px]`, `w-[264px]`)
- Border radius (from `rounded-[16px]`, `rounded-[8px]`)
- Shadows (from `shadow-[...]`)
- Component structure (how elements nest and relate)
- Layout patterns (flex, grid, fixed widths)

**Prioritize screens that show:**
1. The main landing/home page (reveals base layout, input patterns)
2. A page with cards/grid (reveals card components, spacing, shadows)
3. A complex page with multiple panels (reveals layout system, panel structure)
4. A page with controls/toggles (reveals interactive component patterns)

From the returned code, extract and tabulate:

#### Colors
Scan all Tailwind color values. Group into:
- **Backgrounds**: `bg-[#...]` values
- **Text**: `text-[#...]` values
- **Borders**: `border-[#...]` values
- **Accents**: unique colors used sparingly (brand, success, error)

#### Typography
Scan all text styling. Record:
- Font families (PingFang SC, Montserrat, Inter, etc.)
- Font sizes and which elements use them
- Font weights (400, 500, 600)
- Line heights

#### Spacing
Scan all spacing values. Group by magnitude:
- xs (2–4px), sm (6–8px), md (10–12px), lg (14–16px), xl (20–24px), 2xl (32px+)

#### Rounded
Scan all border-radius values:
- xs (3px), sm (6px), md (8px), lg (16px), pill (90px+)

#### Shadows
Extract exact shadow values from `shadow-[...]` classes.

#### Components
Identify distinct UI components and their visual properties.

---

### Step 4.5 — Extract animations and interactions

After extracting design tokens and components, extract animation definitions and interaction states from Figma.

#### Extract animations

Look for animation definitions in the Figma file:

1. **Identify animation components**:
   - Search for Smart Animate transitions
   - Look for prototype connections with animation effects
   - Find components with multiple states showing transitions

2. **Extract animation properties**:
   - Animation type (opacity, transform, scale, rotate)
   - Duration (ms)
   - Easing function (ease-in, ease-out, ease-in-out, spring, linear)
   - From/to values
   - Figma node IDs for reference

3. **Generate `.design/ANIMATIONS.md`**:

```markdown
# Animations and Transitions

## Extraction Info
- Figma file: <fileKey>
- Extracted: <timestamp>
- Animation count: <N>

## Transitions

### fade-in
- **Type**: opacity
- **From**: 0
- **To**: 1
- **Duration**: 200ms
- **Easing**: ease-out
- **Figma node**: 123:456
- **Usage**: Modal dialogs, dropdown menus

### slide-up
- **Type**: transform (translateY)
- **From**: 20px
- **To**: 0
- **Duration**: 300ms
- **Easing**: ease-out
- **Figma node**: 123:457
- **Usage**: Notifications, tooltips

## Keyframe Animations

### spinner
- **Property**: rotate
- **Keyframes**:
  - 0%: rotate(0deg)
  - 100%: rotate(360deg)
- **Duration**: 1s
- **Loop**: infinite
- **Easing**: linear
- **Figma node**: 234:567

## Easing Functions
- `ease-in`: cubic-bezier(0.4, 0, 1, 1)
- `ease-out`: cubic-bezier(0, 0, 0.2, 1)
- `ease-in-out`: cubic-bezier(0.4, 0, 0.2, 1)
- `spring`: cubic-bezier(0.34, 1.56, 0.64, 1)

## Duration Scale
- `fast`: 100ms — micro-interactions (button clicks)
- `normal`: 200ms — standard transitions (hover, focus)
- `slow`: 300ms — complex animations (modals, page transitions)
```

If no animations are found in Figma, generate a template with common defaults.

#### Extract interaction states

Look for component variants and interaction states:

1. **Identify component variants**:
   - Find components with multiple states (default, hover, active, disabled, loading)
   - Extract property changes for each state
   - Record transition effects between states

2. **Generate `.design/INTERACTIONS.md`**:

```markdown
# Interaction States

## Extraction Info
- Figma file: <fileKey>
- Extracted: <timestamp>
- Interactive components: <N>

## Button Interactions

### Hover State
- **Background**: primary-500 → primary-600
- **Shadow**: none → 0 4px 12px rgba(10, 108, 255, 0.3)
- **Transition**: fade-in 200ms
- **Figma component**: 20:1 (variant: primary)

### Active State
- **Background**: primary-600 → primary-700
- **Scale**: scale(0.98)
- **Transition**: scale 100ms

### Focus State
- **Outline**: 2px solid primary-500
- **Outline offset**: 2px
- **Usage**: Keyboard navigation (accessibility)

### Disabled State
- **Background**: gray-200
- **Text**: gray-400
- **Cursor**: not-allowed

### Loading State
- **Show**: spinner icon
- **Disable**: click events
- **Spinner animation**: spinner 1s linear infinite

## Card Interactions (hoverable)

### Hover State
- **Shadow**: card → enhanced 20%
- **Translate**: translateY(0) → translateY(-2px)
- **Transition**: slide-up 300ms

## Input Interactions

### Focus State
- **Border**: border-input → primary-500
- **Shadow**: 0 0 0 3px rgba(10, 108, 255, 0.1)
- **Transition**: fade-in 200ms

### Error State
- **Border**: error (#DB3543)
- **Shadow**: 0 0 0 3px rgba(219, 53, 67, 0.1)
- **Show**: error message text

## Interaction Matrix

| Component | Default | Hover | Active | Focus | Disabled | Loading |
|-----------|---------|-------|--------|-------|----------|---------|
| Button (primary) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Button (secondary) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Card | ✓ | ✓ (hoverable) | - | - | - | - |
| Input | ✓ | - | - | ✓ | ✓ | ✓ |
| Modal | ✓ | - | - | - | - | - |
```

If no interaction states are found, generate a template with common defaults.

#### Update MANIFEST.json

Add animation and interaction metadata to MANIFEST.json:

```json
{
  "animations": {
    "count": 8,
    "file": "ANIMATIONS.md",
    "types": ["transition", "keyframe"],
    "figmaNodeIds": ["123:456", "123:457", "234:567"]
  },
  "interactions": {
    "count": 6,
    "file": "INTERACTIONS.md",
    "components": ["button", "card", "input"],
    "states": ["default", "hover", "active", "focus", "disabled", "loading"]
  }
}
```

---

### Step 5 — Generate DESIGN.md

Write `.design/DESIGN.md` following the [design.md spec](https://github.com/google-labs-code/design.md):

```markdown
---
name: <Project Name>
colors:
  <token-name>: "<hex>"
  ...
typography:
  <token-name>:
    fontFamily: <family>
    fontWeight: <weight>
    fontSize: <size>
    lineHeight: <height>
  ...
rounded:
  <token>: <value>
  ...
spacing:
  <token>: <value>
  ...
shadows:
  <token>:
    offset: <value>
    blur: <value>
    color: <value>
  ...
components:
  <component-name>:
    backgroundColor: "{colors.<token>}"
    textColor: "{colors.<token>}"
    rounded: "{rounded.<token>}"
    ...
---

## Overview
<2-3 paragraphs: what the product is, core design principles, visual philosophy>

## Colors
### Neutrals
<table: token, hex, usage>
### Semantic colors
<table: token, hex, usage>

## Typography
### Scale
<table: token, family, weight, size, line-height, usage>
### Key rules
<bullets: font pairing rules, weight limits, language-specific guidance>

## Layout
### Page structure
<ASCII diagram of overall layout>
### Key dimensions
<table: element, dimensions>

## Elevation & Depth
<table: shadow token, value, usage>

## Shapes
<table: radius token, value, usage>

## Components
### <Component Name>
<visual spec for each component>

## Do's and Don'ts
### Do
<bullets>
### Don't
<bullets>
```

**Rules:**
- YAML front matter uses `{path.to.token}` references for component values
- All hex values must be uppercase: `#FAFAFA` not `#fafafa`
- Token names should be semantic: `bg-page`, `text-primary`, not `gray-100`
- Include a screenshot table in Overview with `![](./screenshots/<name>.png)` references

---

### Step 6 — Generate COMPONENTS.md

Write `.design/COMPONENTS.md` based on components identified in Step 4:

For each component, document:

```markdown
## <ComponentName>

<One-line description of what this component does>

**Props:**
```ts
interface <ComponentName>Props {
  prop1: type           // description
  prop2: type           // description
}
```

**States:**
| State | Visual change | Trigger |
|---|---|---|
| default | ... | initial |
| active | ... | user interaction |
| disabled | ... | condition |

**Interactions:**
| Trigger | Behavior |
|---|---|
| click | ... |
| hover | ... |
| keyboard | ... |

**Dimensions:**
- Container: WxH
- Padding: ...
- Radius: ...
```

**Rules:**
- Props must be TypeScript interfaces
- Every interactive component must list all states
- Dimensions must match values extracted from Figma
- Group related components (Sidebar → SidebarItem, InputArea → FileBadge)

---

### Step 7 — Generate PAGES.md

Write `.design/PAGES.md` with one section per page:

For each page, document:

```markdown
# Page: <pageName> (<Chinese Name>)

## Function
<What this page does, 1-2 sentences>

## Layout
<ASCII diagram showing component arrangement>
- Overall: <layout description>
- Main area: <content arrangement>

## Components
| Component | Position | Count | Notes |
|---|---|---|---|
| Sidebar | left fixed | 1 | route: /path |
| ... | ... | ... | ... |

## Data
```ts
interface <PageName>State {
  // page-level state
}
// API endpoints used
// Navigation: where does this page go?
```

## Interactions
| Trigger | Behavior |
|---|---|
| page load | ... |
| user action | ... |

## States
| State | Visual | Enter condition |
|---|---|---|
| loading | skeleton | initial |
| empty | illustration + CTA | no data |
| loaded | normal | data present |

## Screenshots
![](./screenshots/<name>.png)
```

**Rules:**
- Every page gets its own `# Page:` section
- ASCII layout diagram is mandatory — it's the most useful part for code generation
- Data section must include TypeScript interfaces for page state
- Screenshots referenced with relative paths from `.design/`

---

### Step 8 — Generate CODE_PATTERNS.md

Write `.design/CODE_PATTERNS.md` with project-specific code conventions:

```markdown
# Code Patterns — <Project Name>

## Tech Stack
| Layer | Choice |
|---|---|
| Framework | React 18 + TypeScript |
| Styling | Tailwind CSS 3 |
| State | Zustand |
| Router | React Router v6 |
| Icons | Lucide React |

## File Naming
<directory structure example>

## Naming Conventions
| Type | Rule | Example |
|---|---|---|
| Components | PascalCase | <SkillCard /> |
| Props | PascalCase + Props | SkillCardProps |
| Hooks | camelCase + use | useProjectList() |
| Events | on + Verb | onSend, onToggle |

## Layout Patterns
### App Shell
```tsx
<code example>
```
### Centered Content
```tsx
<code example>
```
### Multi-panel
```tsx
<code example>
```

## Tailwind Color Mapping
<inline vs config decision, with examples>

## Component Writing Pattern
```tsx
<standard component template>
```

## Interaction Patterns
<form submission, drag-drop, loading states>
```

**Rules:**
- Infer tech stack from context (if the user's project uses different tools, adapt)
- Layout code examples must match dimensions from DESIGN.md
- Use actual hex values from the design in code examples

---

### Step 9 — Generate ICONS.md

Write `.design/ICONS.md` by auditing all icons visible in screenshots and design context:

```markdown
# Icons — <Project Name>

## Icon Library
Primary: Lucide React (https://lucide.dev/icons/)

## Icon Inventory

### Navigation
| Icon (Lucide) | Usage | Location | Size |
|---|---|---|---|
| Plus | Create new | Sidebar | 20×20 |
| ... | ... | ... | ... |

### Actions
| Icon | Usage | Location | Size |
|---|---|---|---|
| Send | Submit | InputArea | 18×18 |
| ... | ... | ... | ... |

### Status
| Icon | Usage | Location | Size |
|---|---|---|---|
| Check | Completed | TaskStep | 14×14 |
| ... | ... | ... | ... |

## Usage Convention
```tsx
import { Sparkles } from 'lucide-react'
<Sparkles size={20} color="#181818" strokeWidth={1.5} />
```

## Size Specs
| Context | Size | strokeWidth |
|---|---|---|
| Navigation | 20×20 | 1.5 |
| Buttons | 16–18×18 | 1.5 |
| Status | 14×14 | 1.5 |
```

**Rules:**
- Map Figma icon shapes to closest Lucide equivalent
- Custom/branded icons go in a separate section with SVG export notes
- Size and strokeWidth must be consistent within each context

---

### Step 10 — Verify and report

Run final verification:

```bash
echo "=== .design/ structure ==="
find .design -type f | sort | while read f; do
  size=$(du -h "$f" | cut -f1)
  echo "  ${f#.design/} ($size)"
done
```

Report to the user:

```text
✅ 提取完成！生成了 .design/ 目录:

  DESIGN.md        (N行) 设计系统 token + 视觉规范
  CODE_PATTERNS.md (N行) 技术栈 + 代码约定
  COMPONENTS.md    (N行) N个组件行为规格
  PAGES.md         (N行) N个页面完整规格
  ICONS.md         (N行) 图标清单
  brand/           (N个) 品牌资源文件 (logo, app-icon, mascot)
  icons/           (N个) 自定义 SVG 图标
  screenshots/     (N张) 核心页面截图 + index.md 目录映射

生成 UI 时，在 prompt 中引用这些文件即可。
```

---

## Handling Edge Cases

### Figma MCP not installed
```
需要安装 Figma MCP 插件:
1. 运行 /plugin 安装 figma@claude-plugins-official
2. 运行 /reload-plugins --force
3. 再次运行 /figma2design <url>
```

### Authentication required
Call `mcp__plugin_figma_figma__authenticate`, present the auth URL to the user, wait for confirmation.

### View-only access
```
⚠️ Figma MCP 需要编辑权限。请在 Figma 中获取编辑权限后重试。
```

### Very large files (>50 frames)
If the file has more than 50 full-screen frames:
1. Show the frame list grouped by page
2. Ask the user which pages to extract (or `--all`)
3. Process only the selected pages

### Mixed languages in design
If the design contains both Chinese and English text:
- Note the primary language in DESIGN.md Overview
- Document font pairing rules (e.g., "PingFang SC for Chinese, Montserrat for Latin brand")
- Include language-specific Do's and Don'ts

### No recognizable page structure
If frames are small or don't represent full pages:
- Treat each frame as a component rather than a page
- Generate COMPONENTS.md with more detail
- Skip PAGES.md
- Note in DESIGN.md that the file contains component-level designs only

## Tips for Best Results

1. **Extract from the most complex screen first** — it reveals the most tokens and patterns
2. **Cross-reference multiple screens** — a color that appears once might be a one-off; appearing 3+ times means it's a token
3. **Name tokens semantically** — `bg-page` is better than `gray-50`; `text-primary` is better than `gray-900`
4. **Include ASCII layout diagrams** — they are the single most useful artifact for code generation
5. **Screenshot everything** — even ambiguous frames; the visual is a universal fallback
6. **Group related components** — Sidebar + SidebarItem, InputArea + FileBadge + ProjectBar
7. **Document empty states** — they are often forgotten but critical for complete UI generation