ui-mirror-skill 1.0.0

package/skill/SKILL.md

@@ -0,0 +1,751 @@
+---
+name: ui-mirror
+description: "벤치마킹 사이트 UI 분석 및 재현 스킬. 대상 웹사이트의 스크린샷을 캡처하고 디자인 토큰(색상, 타이포, 간격, 컴포넌트)을 추출하여 현재 프로젝트 UI와 7축 비교 분석 후 CSS 토큰 오버라이드 + 컴포넌트 코드 스니펫 + 마이그레이션 플랜을 자동 생성한다. '/ui-mirror', '/mirror', 'UI 미러', '디자인 미러', '벤치마크 분석', '이 사이트처럼 만들어줘' 시 트리거."
+allowed-tools: "Bash(python3:*), Bash(agent-browser:*), mcp__jina__capture_screenshot_url, mcp__jina__read_url, mcp__chrome-devtools__take_screenshot, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__evaluate_script, mcp__sequential-thinking__sequentialthinking"
+---
+
+# ui-mirror
+
+## 1. Overview
+
+Capture screenshots and extract design tokens (colors, typography, spacing, border-radius, shadows, components, layout) from a benchmark website, then compare them against the current project's UI across 7 analysis axes. Produce a comprehensive analysis report together with directly usable code artifacts: a CSS token override file, component TSX snippets, and a prioritized migration plan.
+
+**Input**: One or more benchmark URLs provided by the user.
+**Output**: A self-contained analysis directory at `docs/ui-mirror/{name}/` containing `analysis.md`, `tokens-override.css`, `components/*.tsx`, `migration-plan.md`, and all captured screenshots.
+
+## 2. Trigger Patterns
+
+Activate this skill when the user issues any of the following:
+
+- `/ui-mirror <url>` or `/mirror <url>`
+- Natural language containing: "이 사이트처럼 만들어줘", "벤치마크 분석", "UI 미러", "디자인 미러", "디자인 캡처"
+- Any request that provides a URL and asks to copy, match, emulate, reproduce, or benchmark against the design of that site
+- "이 디자인 따라해줘", "이 사이트 분석해줘", "여기 UI 참고해서 만들어줘"
+
+## 3. Prerequisites
+
+Check for available browser/capture tools in this priority order:
+
+1. **agent-browser** — `which agent-browser` or attempt `agent-browser --version`
+2. **Chrome DevTools MCP** — verify `mcp__chrome-devtools__take_screenshot` is callable
+3. **Jina MCP** — verify `mcp__jina__capture_screenshot_url` is callable
+
+At least one tool must be available. If none are reachable, **HARD STOP** with this message:
+
+```
+HARD STOP: 스크린샷 도구를 찾을 수 없습니다.
+다음 중 하나를 설치/활성화하세요:
+  1. agent-browser (권장): npm install -g @anthropic/agent-browser
+  2. Chrome DevTools MCP: .claude/settings.json에 MCP 설정 추가
+  3. Jina MCP: .claude/settings.json에 Jina MCP 설정 추가
+```
+
+Also verify Python 3.10+ is available (`python3 --version`) for token extraction and comparison scripts.
+
+## 4. Phase 0: Input & Scope
+
+### Step 0A — Parse User Input
+
+Extract the following from the user's message:
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `BENCHMARK_URL` | Yes | — | The primary URL to analyze |
+| `--depth N` | No | `1` | How many levels of subpages to crawl (0 = landing only) |
+| `--name` | No | Auto-derived from URL hostname | Output directory name under `docs/ui-mirror/` |
+| `--pages` | No | Auto-discovered | Comma-separated list of specific subpage paths |
+
+Auto-derive `--name` from the URL hostname: strip `www.`, take the domain name before TLD, lowercase, kebab-case. Example: `https://www.notion.so/product` becomes `notion`.
+
+### Step 0B — URL Validation
+
+- Jina MCP requires HTTPS URLs. If the URL is HTTP-only and Jina is the only available tool, warn the user.
+- agent-browser and Chrome DevTools MCP accept both HTTP and HTTPS.
+- Reject obviously invalid URLs (no protocol, localhost references for benchmark).
+
+### Step 0C — Subpage Discovery
+
+When `--depth >= 1`, discover subpages:
+
+```
+mcp__jina__read_url(url: BENCHMARK_URL, withAllLinks: true)
+```
+
+Filter the returned links:
+- Same-origin only (matching hostname)
+- Exclude anchors (#), query-only variants, asset URLs (.css, .js, .png, .jpg, .svg, .ico)
+- Exclude duplicate paths that differ only by trailing slash
+- Limit to the top **5** most structurally distinct pages (prioritize paths with different first segments)
+
+### Step 0D — Scope Confirmation
+
+Present the discovered scope to the user before proceeding:
+
+```
+── ui-mirror 범위 확인 ──
+벤치마크: {name} ({BENCHMARK_URL})
+분석 페이지:
+  1. / (메인)
+  2. /features
+  3. /pricing
+  4. /docs/getting-started
+  5. /blog
+
+총 {N}장 캡처 예정. 진행할까요? (Y/n)
+```
+
+Wait for user confirmation. If the user modifies the list, accept the changes.
+
+### Step 0E — Create Output Directory
+
+```bash
+mkdir -p docs/ui-mirror/{name}/screenshots
+mkdir -p docs/ui-mirror/{name}/components
+mkdir -p docs/ui-mirror/{name}/raw
+```
+
+## 5. Phase 1: Benchmark Capture
+
+Execute the following steps for each page in scope. Parallelize Step 1A and Step 1B where tool capabilities allow.
+
+### Step 1A — Visual Capture
+
+Derive a `{slug}` from each page path: `/features/pricing` becomes `features-pricing`, `/` becomes `index`.
+
+**Primary (Jina MCP)**:
+```
+mcp__jina__capture_screenshot_url(url: PAGE_URL, firstScreenOnly: false)
+```
+
+If the Jina MCP returns a URL (not inline binary), download it to a local file:
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/download_screenshot.py \
+  --url "RETURNED_URL" \
+  --output "docs/ui-mirror/{name}/screenshots/benchmark-{slug}-full.png"
+```
+
+If it returns a base64 data URL (`data:image/png;base64,...`), the same script handles decoding:
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/download_screenshot.py \
+  --url "data:image/png;base64,..." \
+  --output "docs/ui-mirror/{name}/screenshots/benchmark-{slug}-full.png"
+```
+
+If neither URL nor data URL is returned (inline binary via MCP), write the binary data directly to `screenshots/benchmark-{slug}-full.png`.
+
+**Fallback 1 (agent-browser)**:
+```bash
+agent-browser open "{PAGE_URL}"
+agent-browser wait --load networkidle
+agent-browser screenshot --full "screenshots/benchmark-{slug}-full.png"
+```
+
+Also capture an annotated screenshot if agent-browser is available:
+```bash
+agent-browser screenshot --annotate "screenshots/benchmark-{slug}-annotated.png"
+```
+
+**Fallback 2 (Chrome DevTools MCP)**:
+```
+mcp__chrome-devtools__navigate_page(url: PAGE_URL)
+mcp__chrome-devtools__take_screenshot(fullPage: true)
+```
+Save returned screenshot data to `screenshots/benchmark-{slug}-full.png`.
+
+### Step 1B — Content Extraction (parallel with 1A)
+
+```
+mcp__jina__read_url(url: PAGE_URL, withAllImages: true, withAllLinks: true)
+```
+
+Save the structured content output to `raw/benchmark-{slug}-content.md` for reference during analysis.
+
+### Step 1C — CSS Extraction
+
+Execute the following JavaScript on each page to extract computed styles. Use the appropriate tool based on availability:
+
+**agent-browser**:
+```bash
+agent-browser eval --stdin <<'JSEOF'
+(function() {
+  const result = {};
+
+  /* Body */
+  const body = document.body;
+  const bs = getComputedStyle(body);
+  result.body = {
+    fontFamily: bs.fontFamily,
+    fontSize: bs.fontSize,
+    lineHeight: bs.lineHeight,
+    color: bs.color,
+    backgroundColor: bs.backgroundColor,
+    letterSpacing: bs.letterSpacing
+  };
+
+  /* Headings — first 20 */
+  result.headings = [];
+  document.querySelectorAll('h1,h2,h3,h4,h5,h6').forEach((el, i) => {
+    if (i >= 20) return;
+    const s = getComputedStyle(el);
+    result.headings.push({
+      tag: el.tagName, text: el.textContent.slice(0, 60),
+      fontSize: s.fontSize, fontWeight: s.fontWeight, lineHeight: s.lineHeight,
+      color: s.color, letterSpacing: s.letterSpacing, marginBottom: s.marginBottom
+    });
+  });
+
+  /* Buttons — first 15 */
+  result.buttons = [];
+  document.querySelectorAll('button, [role="button"], a.btn, .button, [class*="btn"]').forEach((el, i) => {
+    if (i >= 15) return;
+    const s = getComputedStyle(el);
+    result.buttons.push({
+      text: el.textContent.trim().slice(0, 40),
+      fontSize: s.fontSize, fontWeight: s.fontWeight, padding: s.padding,
+      borderRadius: s.borderRadius, backgroundColor: s.backgroundColor,
+      color: s.color, border: s.border, boxShadow: s.boxShadow,
+      height: s.height, minHeight: s.minHeight
+    });
+  });
+
+  /* Cards — first 10 */
+  result.cards = [];
+  document.querySelectorAll('[class*="card"], [class*="Card"], article, .panel, [class*="tile"]').forEach((el, i) => {
+    if (i >= 10) return;
+    const s = getComputedStyle(el);
+    result.cards.push({
+      tagName: el.tagName, className: el.className.toString().slice(0, 80),
+      padding: s.padding, borderRadius: s.borderRadius, border: s.border,
+      backgroundColor: s.backgroundColor, boxShadow: s.boxShadow,
+      gap: s.gap, width: s.width
+    });
+  });
+
+  /* Inputs — first 10 */
+  result.inputs = [];
+  document.querySelectorAll('input, textarea, select').forEach((el, i) => {
+    if (i >= 10) return;
+    const s = getComputedStyle(el);
+    result.inputs.push({
+      type: el.type || el.tagName.toLowerCase(),
+      fontSize: s.fontSize, padding: s.padding, borderRadius: s.borderRadius,
+      border: s.border, backgroundColor: s.backgroundColor,
+      height: s.height, boxShadow: s.boxShadow
+    });
+  });
+
+  /* Nav */
+  const nav = document.querySelector('nav, [role="navigation"], header');
+  if (nav) {
+    const ns = getComputedStyle(nav);
+    result.nav = {
+      height: ns.height, backgroundColor: ns.backgroundColor,
+      padding: ns.padding, position: ns.position, boxShadow: ns.boxShadow,
+      borderBottom: ns.borderBottom, backdropFilter: ns.backdropFilter
+    };
+  }
+
+  /* Color inventory — first 500 elements */
+  const bgColors = new Map();
+  const textColors = new Map();
+  document.querySelectorAll('*').forEach((el, i) => {
+    if (i >= 500) return;
+    const s = getComputedStyle(el);
+    const bg = s.backgroundColor;
+    if (bg && bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent') {
+      bgColors.set(bg, (bgColors.get(bg) || 0) + 1);
+    }
+    const tc = s.color;
+    if (tc) {
+      textColors.set(tc, (textColors.get(tc) || 0) + 1);
+    }
+  });
+  result.colorInventory = {
+    backgrounds: Object.fromEntries([...bgColors.entries()].sort((a,b) => b[1]-a[1]).slice(0, 25)),
+    texts: Object.fromEntries([...textColors.entries()].sort((a,b) => b[1]-a[1]).slice(0, 25))
+  };
+
+  /* Layout info */
+  const main = document.querySelector('main, [role="main"], .main, #main, .container, .wrapper');
+  if (main) {
+    const ms = getComputedStyle(main);
+    result.layout = {
+      maxWidth: ms.maxWidth, width: ms.width, padding: ms.padding,
+      margin: ms.margin, display: ms.display,
+      gridTemplateColumns: ms.gridTemplateColumns || null,
+      gap: ms.gap
+    };
+  }
+
+  return JSON.stringify(result, null, 2);
+})()
+JSEOF
+```
+
+**Chrome DevTools MCP alternative**:
+```
+mcp__chrome-devtools__evaluate_script(expression: <same JS as above>)
+```
+
+Save the output to `raw/benchmark-styles.json`.
+
+### Step 1D — Token Processing
+
+Run the design token extraction script:
+
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/extract_design_tokens.py raw/benchmark-styles.json > raw/benchmark-tokens.json
+```
+
+If the Python script is not present or fails, perform inline token extraction: parse `raw/benchmark-styles.json`, deduplicate colors, normalize font stacks, convert px values to rem, and produce a structured token JSON manually. Save to `raw/benchmark-tokens.json`.
+
+## 6. Phase 2: Current Site Capture
+
+### Step 2A — Page Mapping
+
+Auto-map benchmark page types to equivalent routes in the current project. Detect the project's framework and route structure:
+
+1. **Route Discovery**: Scan `src/app/` (Next.js App Router), `pages/` (Next.js Pages Router), `src/routes/` (SvelteKit/Remix), or `src/views/` (Vue) to identify available routes.
+2. **Map by page type**:
+
+| Benchmark Page Type | How to Find Equivalent |
+|--------------------|------------------------|
+| Landing / Home | Root route (`/` or `/dashboard`) |
+| Content / Article | Content-heavy routes (blog, docs, wiki) |
+| Admin / Dashboard / Settings | Routes under `/admin`, `/settings`, `/dashboard` |
+| Form / Input-heavy | Routes with forms (creation pages, auth pages) |
+| List / Table | Routes with list/table views |
+| Profile / User | Routes under `/profile`, `/account`, `/me` |
+
+3. If no matching route is found for a benchmark page type, skip that mapping and note it in the analysis.
+
+### Step 2B — Dev Server Auto-Detection & Capture
+
+Perform multi-step dev server detection before capturing current project pages:
+
+**Step 2B-1: Port Discovery**
+
+Check ports in priority order:
+1. Read `.env.local` for `PORT` variable
+2. Parse `package.json` `scripts.dev` for `--port N` or `-p N`
+3. Try default ports in order: `3000 → 3001 → 5173 → 4321 → 8080`
+
+Detection method (run via Bash):
+```bash
+# macOS: check if port is listening
+lsof -i :3000 -sTCP:LISTEN -P -n 2>/dev/null | head -2
+
+# Cross-platform fallback: HTTP probe
+curl -s -o /dev/null -w '%{http_code}' --connect-timeout 3 http://localhost:3000/ 2>/dev/null
+```
+
+**Step 2B-2: Process Detection**
+
+If no port responds, check for running dev server processes:
+```bash
+ps aux | grep -E 'next dev|npm run dev|vercel dev|vite|turbopack' | grep -v grep | head -3
+```
+
+**Step 2B-3: Result Branching**
+
+| Scenario | Action |
+|----------|--------|
+| Port found responding | Use that port for Phase 2 capture |
+| Dev process running but port not responding | Wait 10 seconds, retry port probe once |
+| Nothing detected | Present user with options (see below) |
+
+When no dev server is detected, present the user with a choice:
+
+```
+INFO: Dev server가 감지되지 않습니다.
+
+  [1] 직접 `npm run dev` 실행 후 재시도 (권장)
+  [2] Phase 2 건너뛰고 벤치마크 전용 분석
+  [3] dev server 자동 시작 (background, npm run dev)
+```
+
+- Option 1: Pause and wait for user to confirm dev server is running, then re-probe
+- Option 2: Skip to Phase 3 with benchmark-only analysis (no current-site column in comparison tables)
+- Option 3: Run `npm run dev &` in background, wait 15 seconds, verify port responds
+
+**Step 2B-4: Capture Pages**
+
+Once a responding port `PORT` is confirmed, capture each mapped current project page:
+
+```
+mcp__chrome-devtools__navigate_page(url: "http://localhost:{PORT}/{mapped-route}")
+mcp__chrome-devtools__take_screenshot(fullPage: true)
+```
+
+Save to `screenshots/current-{slug}-full.png`.
+
+### Step 2C — CSS Extraction for Current Project
+
+Execute the same JavaScript extraction from Step 1C on each captured current project page. Save to `raw/current-styles.json`.
+
+### Step 2D — Read Authoritative Tokens
+
+Auto-detect the project's global CSS file containing CSS custom properties:
+1. Check `src/app/globals.css` (Next.js App Router)
+2. Check `src/styles/globals.css`, `src/index.css`, `src/global.css`
+3. Check `app/globals.css`, `styles/globals.css`
+4. Search for files matching `glob("**/globals.css")` or `glob("**/*.css")` containing `:root {`
+
+Read the found file to extract the canonical CSS custom properties (the `:root` block). This is the source of truth for the project's design tokens — computed styles may differ from declared tokens due to component overrides.
+
+Save parsed tokens to `raw/current-tokens.json`.
+
+## 7. Phase 3: 7-Axis Analysis
+
+### Step 3A — Load Analysis Rubric
+
+Read `references/analysis-dimensions.md` for the detailed scoring rubric and comparison criteria for each axis. If the file is missing, use the built-in 7-axis framework described below.
+
+### Step 3B — Structured Analysis via Sequential Thinking
+
+Invoke Sequential Thinking MCP with exactly 9 thoughts:
+
+| Thought # | Content |
+|-----------|---------|
+| 1 | **Setup**: Summarize benchmark identity (brand, target audience, design language) and the current project's design posture |
+| 2 | **Axis 1 — Color Palette**: Compare primary, secondary, accent, semantic, neutral palettes. Count unique hues. Map to OKLCH. |
+| 3 | **Axis 2 — Typography**: Font families, size scale, weight distribution, line-height ratios, letter-spacing. |
+| 4 | **Axis 3 — Spacing & Layout**: Grid system, max-width, padding rhythm, gap patterns, section spacing. |
+| 5 | **Axis 4 — Border Radius & Shape Language**: Radius scale, card vs button vs input differentiation, shape consistency. |
+| 6 | **Axis 5 — Shadows & Elevation**: Shadow layers, elevation hierarchy, blur/spread patterns, colored shadows. |
+| 7 | **Axis 6 — Components**: Button styles, card anatomy, input styling, navigation, badges, modals, empty states. |
+| 8 | **Axis 7 — Motion & Interaction**: Transitions, hover effects, animation library, duration/easing conventions. |
+| 9 | **Synthesis**: Overall design gap score (0-100), top 5 highest-impact changes, design system rule conflict inventory. |
+
+### Step 3C — Token Comparison Script
+
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/compare_tokens.py raw/benchmark-tokens.json raw/current-tokens.json > raw/token-diff.json
+```
+
+If the script is not present or fails, perform inline comparison: diff each token category, identify additions/removals/changes, compute delta magnitudes.
+
+### Step 3D — Per-Axis Comparison Tables
+
+For each of the 7 axes, produce a markdown table:
+
+```markdown
+| Property | Benchmark | Current Project | Gap | Action |
+|----------|-----------|---------------|-----|--------|
+| Primary color | oklch(0.65 0.28 264) | oklch(0.55 0.25 280) | Hue shift +16 | Override --primary |
+```
+
+### Step 3E — Design System Rule Conflict Detection
+
+Auto-detect the project's design system documentation:
+1. Check for `FRONTEND_CONSISTENCY.md` in project root
+2. Check for `DESIGN_SYSTEM.md`, `STYLE_GUIDE.md`, `docs/design-system.md`
+3. Check `CLAUDE.md` for frontend design rules section
+4. If no design system file found, skip conflict detection and note in analysis.md
+
+If found, cross-reference every proposed change against the documented design rules.
+
+For each conflict, document:
+- Rule ID and rule text (if rules are numbered)
+- What the benchmark requires
+- Whether the user has opted for "제약 무시, 완전 재현 우선" mode
+- Proposed rule amendment if full reproduction is requested
+
+### Step 3F — Write Analysis Report
+
+Write the full analysis to `docs/ui-mirror/{name}/analysis.md`. Use the template from `references/output-template.md` if available. The report must include:
+
+1. Executive summary (3-5 sentences)
+2. Screenshot gallery table (all captured pages in one overview table)
+3. Benchmark identity profile
+4. 7-axis comparison tables (from Step 3D), **each with inline screenshot evidence** (from Step 3F-3)
+5. Design system rule conflict inventory (from Step 3E)
+6. Overall gap score with visual charts (see below)
+7. Recommended implementation priority (P0/P1/P2)
+
+### Step 3F-2 — Generate Visual Charts
+
+Generate both SVG radar chart and Mermaid bar chart for the 7-axis scores.
+
+**SVG Radar Chart** (primary visualization):
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/generate_radar_chart.py \
+  --scores '{"color":SCORE,"typography":SCORE,"spacing":SCORE,"radius":SCORE,"shadows":SCORE,"components":SCORE,"motion":SCORE}' \
+  --max-score 5 \
+  --lang kr \
+  --output docs/ui-mirror/{name}/radar-chart.svg
+```
+
+Embed in analysis.md:
+```markdown
+### Score Radar Chart
+
+![7-Axis Radar](./radar-chart.svg)
+```
+
+**Mermaid Bar Chart** (fallback for markdown renderers without SVG support):
+
+Generate via script or inline. Use `--mermaid` flag for stdout output:
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/generate_radar_chart.py \
+  --scores '{"color":SCORE,...}' \
+  --mermaid
+```
+
+Embed the output in analysis.md as a fenced Mermaid code block. This renders natively on GitHub, GitLab, and most modern markdown viewers.
+
+### Step 3F-3 — Inline Screenshot Embedding
+
+Each axis section in analysis.md **must** include the most relevant benchmark screenshot(s) as inline markdown images, placed immediately after the axis heading and before the descriptive paragraph. This provides visual evidence for every comparison claim.
+
+**Page-to-axis mapping** — use the following default mapping to select which screenshot to embed in each axis section. If a page was not captured, skip that axis's screenshot.
+
+| Axis | Primary Screenshot | Secondary Screenshot | Rationale |
+|------|-------------------|---------------------|-----------|
+| 1. Color Palette | `benchmark-article-full.png` | — | Shows accent colors, link colors, navbar, body/content bg |
+| 2. Typography | `benchmark-article-full.png` | — | Shows heading scale, body text, font rendering |
+| 3. Spacing & Layout | `benchmark-main-full.png` | `benchmark-article-full.png` | Shows page chrome, column structure, padding |
+| 4. Border Radius | `benchmark-article-full.png` | — | Shows button/card/input radius in context |
+| 5. Shadows & Elevation | `benchmark-article-full.png` | — | Shows shadow presence/absence, border-based depth |
+| 6. Components | `benchmark-recentchanges-full.png` | `benchmark-history-full.png`, `benchmark-discussion-full.png` | Shows component anatomy, density, patterns |
+| 7. Interaction | `benchmark-article-full.png` | — | Shows hover targets, edit entry points |
+
+**Embedding format** — use blockquote + descriptive caption:
+
+```markdown
+### Axis N: Title (Score: X/5)
+
+> **참고 스크린샷**: {page name} — {what to observe in the screenshot}
+> ![{alt text}](./screenshots/{filename})
+
+{axis description paragraph...}
+```
+
+For axes with multiple screenshots (especially Components), embed all relevant screenshots with separate captions:
+
+```markdown
+> **참고 스크린샷**: 최근 변경 — action type + byte delta + 직접 링크 고밀도 테이블
+> ![최근 변경](./screenshots/benchmark-recentchanges-full.png)
+>
+> **참고 스크린샷**: 문서 역사 — 리비전 목록 + diff 링크
+> ![문서 역사](./screenshots/benchmark-history-full.png)
+```
+
+**Rules**:
+- Every axis section must have at least one screenshot. If no dedicated page maps to the axis, use the article page as default.
+- Use relative paths (`./screenshots/`) — never absolute paths.
+- Captions must describe **what to observe** in the screenshot for that specific axis, not just the page name.
+- The screenshot gallery table at the top of analysis.md (all screenshots in one table) is still included as an overview. The inline screenshots within axes provide contextual evidence.
+
+### Step 3F-4 — Human-Readable Token Diff
+
+In addition to the raw JSON diff, generate a human-readable summary:
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/compare_tokens.py \
+  raw/benchmark-tokens.json raw/current-tokens.json --format human \
+  > raw/token-diff-readable.txt
+```
+
+Include this text output as an appendix in analysis.md or as a standalone file for quick review.
+
+## 8. Phase 4: Code Artifact Generation
+
+### Step 4A — CSS Token Override (`tokens-override.css`)
+
+Generate a CSS file with `:root` block containing OKLCH token overrides:
+
+```css
+/* ui-mirror: {name} ({BENCHMARK_URL})
+ * Generated: {ISO date}
+ * Apply by importing after globals.css or merging into globals.css
+ */
+
+:root {
+  /* === Colors === */
+  --primary: oklch(0.65 0.28 264);      /* was: oklch(0.55 0.25 280) */
+  --primary-foreground: oklch(0.98 0 0); /* was: oklch(0.98 0.01 280) */
+
+  /* === Typography === */
+  --font-sans: "Inter", "Pretendard", sans-serif; /* was: "Pretendard", "Inter", sans-serif */
+
+  /* === Spacing (as reference — apply via Tailwind config) === */
+  /* card-padding: 20px (was: 16px) → p-5 instead of p-4 */
+
+  /* === New tokens (not in current project) === */
+  --accent-gradient: linear-gradient(135deg, oklch(0.65 0.28 264), oklch(0.70 0.20 300));
+}
+```
+
+Every line must include a `/* was: ... */` comment showing the current project value, or `/* NEW */` for tokens that do not exist in the current project.
+
+All colors must be in OKLCH format. Convert any RGB/HSL values from the benchmark extraction using the Python conversion utility or inline calculation.
+
+### Step 4B — Component Code Snippets (`components/`)
+
+For each major component where the benchmark significantly differs from the current project's implementation, generate a TSX file. Typical components:
+
+- `mirror-button.tsx` — Button variant matching benchmark style
+- `mirror-card.tsx` — Card component with benchmark proportions
+- `mirror-input.tsx` — Input styling
+- `mirror-nav.tsx` — Navigation bar structure
+
+Each TSX file should follow the project's component conventions. If the project uses shadcn/ui + CVA, use this pattern:
+
+```tsx
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+const mirrorButtonVariants = cva(
+  "inline-flex items-center justify-center font-medium transition-all",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground shadow-md",
+        outline: "border border-input bg-background hover:bg-accent",
+      },
+      size: {
+        default: "h-10 px-5 text-sm rounded-lg",  // benchmark: rounded-lg, h-10
+        sm: "h-8 px-3 text-xs rounded-md",
+        lg: "h-12 px-8 text-base rounded-lg",
+      },
+    },
+    defaultVariants: { variant: "default", size: "default" },
+  }
+)
+
+interface MirrorButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof mirrorButtonVariants> {}
+
+function MirrorButton({ className, variant, size, ...props }: MirrorButtonProps) {
+  return (
+    <button
+      data-slot="mirror-button"
+      className={cn(mirrorButtonVariants({ variant, size }), className)}
+      {...props}
+    />
+  )
+}
+
+export { MirrorButton, mirrorButtonVariants }
+```
+
+Include inline comments noting which benchmark property each class maps to. Prefix all component names with `Mirror` to avoid collisions with existing project components.
+
+### Step 4C — Migration Plan (`migration-plan.md`)
+
+Run the migration plan generator:
+
+```bash
+python3 $HOME/.agents/skills/ui-mirror/scripts/generate_migration.py raw/token-diff.json > migration-plan.md
+```
+
+If the script is unavailable, generate the migration plan inline with the following structure:
+
+```markdown
+# Migration Plan: {name}
+
+## Priority Matrix
+
+### P0 — Immediate (tokens-override.css import)
+Changes achievable by importing the generated CSS token file.
+No component code changes required.
+
+| Change | File | Effort | Risk |
+|--------|------|--------|------|
+| Primary color shift | globals.css | 1 line | Low |
+
+### P1 — Short-term (component updates)
+Changes requiring component-level modifications using generated snippets.
+
+| Change | File(s) | Effort | Risk | Design Rule Conflict |
+|--------|---------|--------|------|----------------------|
+
+### P2 — Medium-term (structural changes)
+Layout, grid, or navigation restructuring.
+
+### P3 — Deferred / Evaluated
+Changes that conflict with the project's design principles or require user decision.
+
+## Design System Rule Amendments
+If full reproduction is requested, list each rule that needs amendment:
+
+| Rule ID | Current Rule | Proposed Amendment | Justification |
+|---------|-------------|-------------------|---------------|
+
+## Estimated Total Effort
+- P0: ~{N} minutes
+- P1: ~{N} hours
+- P2: ~{N} hours
+- P3: Requires design decision
+```
+
+Copy the generated migration plan to `docs/ui-mirror/{name}/migration-plan.md`.
+
+## 9. Output Summary
+
+After all phases complete, present the completion summary:
+
+```
+── ui-mirror 완료 ──
+벤치마크: {name} ({BENCHMARK_URL})
+페이지: {N}장 분석 | 토큰: {N}개 비교
+규칙 충돌: {N}건 (제안 해결책 포함)
+전체 갭 스코어: {score}/100
+
+산출물:
+  docs/ui-mirror/{name}/analysis.md          — 7축 비교 분석 리포트
+  docs/ui-mirror/{name}/tokens-override.css  — CSS 토큰 오버라이드
+  docs/ui-mirror/{name}/components/          — {N}개 컴포넌트 스니펫
+  docs/ui-mirror/{name}/migration-plan.md    — 우선순위별 마이그레이션 계획
+  docs/ui-mirror/{name}/screenshots/         — {N}장 스크린샷
+  docs/ui-mirror/{name}/raw/                 — 원시 데이터 (JSON)
+
+다음 단계:
+  1. analysis.md 검토 후 적용 범위 결정
+  2. tokens-override.css를 globals.css에 병합 (P0)
+  3. components/ 스니펫을 src/components/ui/에 통합 (P1)
+```
+
+Do not automatically commit any generated artifacts. Wait for user review and explicit commit request.
+
+## 10. Error Handling & Fallback
+
+| Situation | Fallback |
+|-----------|----------|
+| Jina screenshot fails | agent-browser `screenshot --full` |
+| agent-browser unavailable | Chrome DevTools MCP `take_screenshot` |
+| All screenshot tools fail | **HARD STOP** + install instructions (see Section 3) |
+| Benchmark requires authentication | Guide user through agent-browser auth vault: `agent-browser auth add {domain}` |
+| Benchmark blocks bots / returns 403 | Suggest agent-browser `--headed` mode for manual navigation, then capture |
+| Python script not found or fails | Claude performs inline analysis (degraded mode — slower, no automated diffing) |
+| localhost:3000 not running | Skip Phase 2, produce benchmark-only analysis with WARN |
+| 10+ pages discovered | Confirm with user, then batch in groups of 5 with progress updates |
+| `raw/` JSON is malformed | Re-run CSS extraction with simplified JS (headings + buttons + colors only) |
+| Design system file not found | Warn user, skip conflict detection, note in analysis.md |
+| Output directory already exists | Ask user: overwrite / rename with timestamp suffix / abort |
+| Network timeout on capture | Retry once with 30s delay, then skip page with WARN |
+
+## 11. Safety Rules
+
+### NEVER
+
+- Modify existing source files (`src/`, `globals.css`, any `.tsx`/`.ts`) automatically. All generated code goes to `docs/ui-mirror/{name}/` only.
+- Commit generated artifacts without explicit user review and approval.
+- Send credentials, cookies, or auth tokens to Jina MCP. Use agent-browser for authenticated pages.
+- Process more than 10 pages without explicit user confirmation.
+- Overwrite an existing `docs/ui-mirror/{name}/` analysis directory without asking the user first.
+- Skip the scope confirmation step (Step 0D).
+- Use hardcoded HEX/RGB in generated `tokens-override.css` — always convert to OKLCH.
+
+### ALWAYS
+
+- Save all screenshots to the output directory before analysis (never analyze from memory alone).
+- Convert all color values to OKLCH format in generated artifacts.
+- Flag every conflict with the project's design system rules (if a design system file is found).
+- Use Sequential Thinking MCP for the 7-axis analysis (structured reasoning prevents skipped dimensions).
+- Present scope confirmation (Step 0D) before starting Phase 1 captures.
+- Clean up any `/tmp/ui-mirror-*` temporary files after copying results to the output directory.
+- Prefix generated component names with `Mirror` to avoid naming collisions.
+- Include `/* was: ... */` comments in every token override line.
+- Record the benchmark URL, capture date, and tool versions used in `analysis.md` metadata.