Design Check

argument: $ARGUMENTS

Claude Command: Design Check

이 커맨드는 Figma 디자인과 구현된 컴포넌트를 자동 비교하여 Markdown 보고서를 생성합니다.

워크플로우 (병렬화 아키텍처)

Phase 1: 입력 파싱
    ↓
┌───────────────────────────────────────────────────────────┐
│         Stage 1: 병렬 데이터 수집 + Story 준비              │
├─────────────────┬─────────────────┬───────────────────────┤
│   Task A        │   Task B        │   Main Agent          │
│   (background)  │   (background)  │   (동시 진행)          │
├─────────────────┼─────────────────┼───────────────────────┤
│ REST API        │ MCP             │ Phase 3 준비:         │
│ 스크린샷 캡처    │ get_design_ctx  │ - 컴포넌트 분석       │
│                 │ get_var_defs    │ - props/imports 파악  │
│ 출력:           │                 │ - Story 틀 생성       │
│ - figma.png     │ 출력:           │   (bbox placeholder)  │
│ - .meta.json    │ - 디자인 속성    │                       │
│ - bbox 정보     │ - 토큰 목록      │                       │
└─────────────────┴─────────────────┴───────────────────────┘
    ↓ (Task A 완료 대기 - bbox 필요)
┌───────────────────────────────────────────────────────────┐
│         Stage 2: bbox 주입 + 구현 스크린샷                  │
├───────────────────────────────────────────────────────────┤
│ - Story 파일에 bbox 크기 주입 (Edit tool)                  │
│ - Storybook 빌드 (--rebuild)                              │
│ - 구현 스크린샷 캡처 (--container-width {bboxWidth})       │
└───────────────────────────────────────────────────────────┘
    ↓
Phase 5 → Phase 6 → Phase 7 (순차 실행)

Phase 1. 입력 파싱

사용자 인자에서 Figma URL과 컴포넌트 경로를 추출합니다.

Figma URL → fileKey, node ID 변환:

1. URL에서 node-id=(\d+-\d+) 패턴 추출
2. -를 :로 치환하여 MCP 호출용 ID 생성
   • 예: node-id=1-2 → 1:2
3. URL에서 fileKey 추출: /design/:fileKey/:fileName → fileKey
4. URL이 https://figma.com/design/:fileKey/branch/:branchKey/:fileName 형식이면 branchKey를 fileKey로 사용
5. 원본 Figma URL을 {figmaUrl}로 보존 (Stage 1에서 스크립트에 전달)

컴포넌트 경로 → 메타데이터 추출:

1. 파일명에서 컴포넌트 이름 추출: Card.tsx → Card
2. FSD 레이어 추출: src/shared/... → Shared, src/features/... → Features 등
3. 중첩 경로 처리: src/features/widget-builder/ui/ColumnHeader.tsx → Features/WidgetBuilder/ColumnHeader

Stage 1. 병렬 데이터 수집 + Story 준비

다음 작업을 동시에 실행합니다.

Task A: Figma 스크린샷 캡처 (run_in_background: true)

Agent: Task tool with subagent_type: Bash

Figma REST API를 통해 노드 스크린샷을 PNG 파일로 저장합니다.

pnpm exec tsx .claude/skills/design-check/scripts/capture-figma-screenshot.ts \
  --url "{figmaUrl}" \
  --output "artifacts/screenshots/figma/{Name}.png" \
  --scale 2

CLI 옵션:

필수 환경변수: FIGMA_TOKEN (.env 파일 또는 환경변수로 설정)

출력물:

스크립트 실행 시 PNG 파일과 함께 .meta.json 파일이 자동 생성됩니다:

• 경로: artifacts/screenshots/figma/{Name}.meta.json
• 내용: { "bbox": { "width", "height" }, "image": { "width", "height" }, "scale" }
• bbox는 Figma 노드의 CSS 논리 크기 (absoluteBoundingBox)
• image는 실제 PNG 픽셀 크기 (= bbox × scale)

stdout 필드:

• nodeWidth / nodeHeight: Figma 노드 CSS 크기 → Stage 2에서 --container-width 값으로 사용
• imageSize: 실제 PNG 픽셀 크기
• 4096px 이상일 경우 경고 출력 (Figma 하드 리미트)

Task B: 디자인 데이터 수집 (run_in_background: true)

Agent: Task tool with subagent_type: general-purpose

MCP Figma Desktop 도구를 사용하여 디자인 데이터를 수집합니다.

B-1. 디자인 컨텍스트 수집:

get_design_context MCP 도구를 호출하여 노드의 구조 정보를 얻습니다.

mcp__figma-desktop__get_design_context(nodeId: "{nodeId}")

응답에서 다음을 추출합니다:

• width, height → 뷰포트 크기 및 wrapper div 크기로 활용
• 레이아웃, 색상, 타이포그래피 등 디자인 속성

B-2. 디자인 토큰 수집:

get_variable_defs MCP 도구를 호출하여 변수 정의를 얻습니다.

mcp__figma-desktop__get_variable_defs(nodeId: "{nodeId}")

색상, 간격, 타이포그래피 토큰을 보고서에 포함합니다.

Main Agent: Story 준비 (동시 진행)

Task A, B가 백그라운드에서 실행되는 동안 Main Agent가 직접 수행합니다.

3-1. 컴포넌트 분석:

컴포넌트 파일을 읽고 다음을 파악합니다:

• export된 컴포넌트 (default/named)
• Props 타입/인터페이스
• import 의존성 (Context, Store, API 호출 여부)

3-2. 렌더링 요구사항 분류:

3-3. 기존 Story 참조:

컴포넌트와 같은 디렉토리 또는 __screenshots__/ 디렉토리에 .stories.tsx 파일이 있는지 확인합니다.

• 있으면: args, decorators, parameters, render 함수 패턴을 참조
• 없으면: 컴포넌트 분석 결과만으로 구성

3-4. Story 틀 생성 (bbox placeholder):

파일 위치: __screenshots__/{ComponentName}.stories.tsx

중요: bbox 값을 아직 모르므로 placeholder를 사용합니다.

import type { Meta, StoryObj } from '@storybook/react'
import { ComponentName } from '@/{path}'

const meta: Meta<typeof ComponentName> = {
  title: 'Screenshots/{Layer}/{ComponentName}',
  component: ComponentName,
  parameters: { layout: 'centered' },
}

export default meta
type Story = StoryObj<typeof meta>

export const Default: Story = {
  render: () => (
    <div style={{ width: '{BBOX_WIDTH}px' }}>
      <ComponentName {...props} />
    </div>
  ),
}

• {BBOX_WIDTH}는 placeholder로, Stage 2에서 실제 값으로 교체됩니다.
• height는 주입하지 않습니다 — height 차이는 실제 구현 차이이므로 diff로 잡혀야 합니다.
• title은 Screenshots/{Layer}/{ComponentName} 형식을 따릅니다.
• import 경로는 항상 @/ alias를 사용합니다.
• render 함수는 반드시 단일 루트 엘리먼트를 반환해야 합니다 (캡처 스크립트가 #storybook-root > * 선택자 사용).

기존 파일 처리:

• __screenshots__/ 디렉토리에 같은 이름의 Story가 이미 있으면 사용자에게 덮어쓸지 확인합니다.

Stage 1 완료 게이트

Task A의 bbox 정보 수집 (TaskOutput tool로 대기)

Task A가 완료되면 stdout에서 nodeWidth 값을 추출합니다. 이 값이 Stage 2의 핵심 입력입니다.

Task B의 결과는 Phase 7(보고서 생성)에서 사용되므로, Stage 2 진입 전에 완료되지 않아도 됩니다.

Stage 1 에러 처리

Task A 에러 처리 상세:

• FIGMA_TOKEN 미설정 시: 토큰 생성 안내 (https://www.figma.com/developers/api#access-tokens)
• API 403 Forbidden: 파일 접근 권한 확인 안내
• API 404 Not Found: fileKey 또는 nodeId 확인 안내
• 이미지 URL null: 노드가 렌더링 불가능한 경우 안내 (Frame, Component, Instance 등만 가능)

Task B 에러 처리 상세:

• MCP 도구 호출 실패 시: Figma Desktop 앱이 실행 중인지 확인하라고 안내합니다.
• 경고만 출력하고 워크플로우는 계속 진행합니다.

Stage 2. bbox 주입 + 구현 스크린샷

Task A에서 받은 bbox 값을 Story 파일에 주입하고 구현 스크린샷을 캡처합니다.

2-1. Story 파일에 bbox 주입

Edit tool을 사용하여 placeholder를 실제 값으로 교체합니다:

old_string: "width: '{BBOX_WIDTH}px'"
new_string: "width: '{실제_bboxWidth}px'"

예: {BBOX_WIDTH} → 384

2-2. Story ID 변환

title: "Screenshots/Shared/Card" + export: "Default"
→ 소문자: "screenshots/shared/card"
→ / → -: "screenshots-shared-card"
→ + "--" + kebab(export): "screenshots-shared-card--default"

PascalCase → kebab-case 변환:

• Default → default
• WithIcon → with-icon

2-3. 캡처 실행

Task A에서 얻은 Figma bbox width를 --container-width로 전달하여, Storybook 컨테이너 크기를 Figma 디자인에 맞춥니다:

pnpm exec tsx .claude/skills/component-screenshot/scripts/capture-screenshot.ts \
  --story-id "{story-id}" \
  --output "artifacts/screenshots/impl/{Name}.png" \
  --width {width} --height {height} \
  --scale 2 \
  --container-width {bboxWidth} \
  --rebuild

• {bboxWidth}는 Task A의 stdout에서 nodeWidth 값 또는 .meta.json의 bbox.width 값을 사용합니다.
• --container-width는 #storybook-root > *:first-child에 CSS width: {N}px !important를 주입합니다.
• width만 주입하고 height는 주입하지 않습니다 — height 차이는 실제 구현 차이이므로 diff로 잡혀야 합니다.

주의: 새로 생성한 Story 파일은 기존 Storybook 빌드에 포함되지 않으므로 --rebuild 플래그를 반드시 사용합니다.

CLI 옵션:

결과 검증:

• PNG 파일이 생성되었는지 확인
• 파일 크기가 0보다 큰지 확인

Stage 2 에러 처리

Phase 5. 정량 비교 (Pixel Diff)

두 스크린샷의 픽셀 단위 차이를 비교합니다.

pnpm exec tsx .claude/skills/design-check/scripts/compare-screenshots.ts \
  --base "artifacts/screenshots/figma/{Name}.png" \
  --current "artifacts/screenshots/impl/{Name}.png" \
  --output "artifacts/screenshots/diff/{Name}.png"

stdout 파싱:

스크립트 출력에서 다음 값을 추출합니다:

• baseSize / currentSize: 각 이미지의 픽셀 크기
• Size mismatch 경고 (있을 경우): 크기 불일치 시 리사이즈 폴백이 작동했음을 의미
• diffPixels: 차이 픽셀 수
• diffRatio: 차이 비율 (%)
• result: pass 또는 fail

이 값들을 보고서의 정량 분석 섹션에 포함합니다. Size mismatch 경고가 있으면 보고서에 크기 불일치 사실을 명시합니다.

Phase 6. 정성 비교 (시각 분석)

Claude의 시각 분석 능력을 활용하여 디자인 차이를 정성적으로 평가합니다.

6-1. 이미지 로드:

Read tool로 다음 이미지를 로드합니다 (MCP get_screenshot 호출 불필요, Task A에서 파일로 저장됨):

• artifacts/screenshots/figma/{Name}.png (Figma 디자인 - REST API로 저장됨)
• artifacts/screenshots/impl/{Name}.png (구현 결과)

6-2. 비교 항목:

6-3. 발견사항 분류:

각 차이점에 severity를 부여합니다:

Phase 7. 보고서 생성

최종 Markdown 보고서를 생성합니다.

파일 위치: artifacts/design-check/{Name}-report.md

보고서 구조:

# Design Check Report: {ComponentName}

**Date:** {YYYY-MM-DD}
**Figma Node:** {nodeId}
**Component:** {componentPath}

---

## Executive Summary

{전체 요약: 일치도 수준, 주요 발견사항 수}

## Quantitative Analysis

| Metric      | Value        |
| ----------- | ------------ |
| Diff Pixels | {diffPixels} |
| Diff Ratio  | {diffRatio}% |
| Result      | {pass/fail}  |

## Qualitative Analysis

### Critical Issues

{없으면 "None" 표시}

### Major Issues

{없으면 "None" 표시}

### Minor Issues

{없으면 "None" 표시}

### Nitpicks

{없으면 "None" 표시}

## Design Tokens

{Task B에서 수집한 디자인 토큰 목록. Task B 실패 시 "Not available" 표시}

## Recommendations

{개선 제안 사항: 코드 수정 방향, 우선순위}

## Artifacts

| Artifact                  | Path                                         |
| ------------------------- | -------------------------------------------- |
| Figma Screenshot          | artifacts/screenshots/figma/{Name}.png       |
| Figma Metadata            | artifacts/screenshots/figma/{Name}.meta.json |
| Implementation Screenshot | artifacts/screenshots/impl/{Name}.png        |
| Diff Image                | artifacts/screenshots/diff/{Name}.png        |
| Story File                | **screenshots**/{Name}.stories.tsx           |

에러 처리 (전체)

예시

입력

/design-check https://figma.com/design/abc123/MyProject?node-id=1-2 src/shared/ui/card/Card.tsx

실행 과정

1. 입력 파싱: nodeId=1:2, Name=Card, Layer=Shared
2. Stage 1 병렬 실행:
   • Task A (background): Figma 스크린샷 → artifacts/screenshots/figma/Card.png, bbox: 384×256
   • Task B (background): MCP get_design_context + get_variable_defs
   • Main Agent: 컴포넌트 분석 + Story 틀 생성 ({BBOX_WIDTH} placeholder)
3. Stage 2 bbox 주입: Story 파일의 {BBOX_WIDTH} → 384 교체
4. Stage 2 구현 캡처: artifacts/screenshots/impl/Card.png (--rebuild --container-width 384 사용)
5. Phase 5 정량 비교: diffRatio=2.3%, result=pass
6. Phase 6 정성 비교: Minor - 하단 padding 2px 차이
7. Phase 7 보고서: artifacts/design-check/Card-report.md 생성

출력

Design Check 완료: Card

📊 정량 결과: 2.3% 차이 (PASS)
📋 정성 결과: 1 Minor issue
📄 보고서: artifacts/design-check/Card-report.md

Converted and distributed by TomeVault — claim your Tome and manage your conversions.