Figma to Claude Code — Anthropic CLI를 위한 구조화된 디자인 컨텍스트

"이미 존재하는 컴포넌트를 재구현하지 마세요" 지시는 컴포넌트 인벤토리가 공유될 때 중요합니다. Claude Code는 design/components/inventory.json을 읽어 이미 구현된 컴포넌트를 식별하고 재생성하지 않고 import합니다.

디자인 토큰 연결

figmascope가 내보내는 tokens.json은 $value와 $type 필드가 있는 W3C 유사 중첩 구조를 사용합니다:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

화면 구현 전에 첫 번째 단계로 Claude Code에 이 파일에서 tailwind.config.ts theme extension 블록을 생성하도록 요청하세요. 그러면 이후 모든 화면 구현에서 Tailwind 토큰 별칭을 일관되게 사용할 수 있습니다:

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

토큰 형식과 figmascope가 Figma Variables가 설정되지 않은 경우 사용하는 빈도 추론 폴백에 대한 자세한 내용은 AI 에이전트를 위한 디자인 토큰 내보내기를 참고하세요.

문자열 레이어 처리

Figma 파일의 모든 텍스트 노드는 strings.json에 슬롯을 갖습니다. 키는 프레임 계층에서 파생된 점 표기법을 사용합니다:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

Claude Code에 이 키를 i18n 식별자로 사용하도록 지시하세요. JSX에 "Everything you need"를 하드코딩하는 대신 생성된 컴포넌트가 t('home.hero.title')(또는 i18n 라이브러리의 동등한 함수)을 호출합니다. 리소스 파일은 이미 strings.json에 있습니다 — i18n 설정에 import하거나 연결하기만 하면 됩니다.

figmascope가 충돌을 감지하면 — 같은 키로 해시되는 두 노드 — _meta.json에 strings-collision 경고를 발행하고 숫자 접미사를 추가하여 구분합니다. 세션 시작 전에 _meta.json을 확인하여 예상 상황을 파악하세요.

CLAUDE.md 통합

CLAUDE.md 프로젝트 컨텍스트 파일을 사용하신다면 design 디렉토리를 가리키는 짧은 섹션을 추가하세요. 이 방식은 AI 디자인 핸드오프에서 설명한 접근법과 잘 어울리며 figmascope가 Figma 인스펙터 플러그인과 다른 이유를 보완합니다.

다음과 같이 design 섹션을 추가하세요:

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

이렇게 하면 프로젝트의 모든 Claude Code 세션이 매번 반복하지 않아도 자동으로 design 컨텍스트를 작업 지식으로 갖게 됩니다.

에이전트가 실제로 잘 처리하는 것

구조화된 컨텍스트를 통해 Claude Code가 안정적으로 처리하는 항목:

• 간격 값 — 스크린샷을 눈으로 재는 것이 아닌 tokens.json의 spacing.4 → 16px에서 가져오기 때문
• 색상 — "따뜻한 주황색 같아 보임"이 아닌 정확한 hex 값
• 타이포그래피 — 폰트 패밀리, 크기, 굵기, 행간 모두 타입 명시
• 레이아웃 방향 — stack 노드에 명시적 direction과 gap 필드
• 컴포넌트 이름 — inventory.json이 정규 원천이므로 임의로 생성된 이름 없음
• 텍스트 — strings.json이 에이전트의 내용 재구성이나 플레이스홀더 텍스트 생성 방지

여전히 사람의 검토가 필요한 부분: 정적 Figma 프레임에서 보이지 않는 인터랙션 상태(호버, 포커스, 활성), 애니메이션 타이밍, 파일에 명시적으로 디자인되지 않은 반응형 브레이크포인트. IR은 정적 레이아웃을 캡처합니다. 동적 동작은 범위 밖입니다.

제어된 환경에서 --dangerously-skip-permissions 사용

자동화된 파이프라인에서 Claude Code가 대화형 승인 프롬프트 없이 작동하도록 하려는 경우 — 예를 들어 디자인 업데이트 후 컴포넌트 스텁을 생성하는 CI 단계 — --dangerously-skip-permissions를 사용할 수 있습니다. 프로덕션 자격 증명이 없는 샌드박스 환경에서만 적합합니다.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

프로덕션 개발 워크플로우에서는 권한을 대화형으로 유지하세요. 프롬프트는 타당한 이유로 존재합니다 — Claude Code는 파일을 작성할 수 있으며, 작성 전에 어떤 파일인지 알고 싶을 것입니다.

프롬프트 전에 내보내기 경고 확인

figmascope는 출력 품질에 영향을 줄 수 있는 조건에 대해 _meta.json에 경고를 발행합니다. Claude Code 세션 시작 전에 확인하세요:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

주목해야 할 두 가지 경고:

• layout-mode-none-inferred — 프레임에 auto-layout이 설정되지 않음. figmascope가 자식 절대 위치에서 레이아웃을 추론했는데, 신뢰도가 낮습니다. 프롬프트에서 해당 화면을 표시하세요: "이 화면은 절대 위치 지정을 사용합니다. 그에 맞게 생성하세요."
• strings-collision — 두 텍스트 노드가 같은 리소스 키를 생성했습니다. figmascope는 숫자 접미사로 구분하지만, 에이전트가 i18n 호출을 생성하기 전에 strings.json의 문자열이 올바른지 확인해야 합니다.

Android와 iOS 워크플로우

Claude Code는 웹 프레임워크에만 국한되지 않습니다. 컨텍스트 번들은 프레임워크 독립적입니다 — 레이아웃 IR과 토큰은 CSS가 아닌 데이터입니다. Jetpack Compose의 경우:

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

IR의 stack 노드는 Compose에서 Column(direction: vertical)과 Row(direction: horizontal)로 자연스럽게 매핑됩니다. type: "text"의 leaf 노드는 Text composable이 되고, type: "image"는 Image 또는 플레이스홀더가 됩니다. 전체 패턴은 Jetpack Compose from Figma를 참고하세요.

디자인 번들 버전 관리

design/ 디렉토리를 다른 프로젝트 의존성처럼 취급하세요. 디자인이 크게 변경되면 figmascope.dev에서 다시 내보내고, 커밋하고, PR에 변경 사항을 기록하세요:

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

오래된 번들은 에이전트가 구식 디자인을 기반으로 작업한다는 의미입니다. 타임스탬프 확인을 통해 구식 스펙에 기반한 코드젠 세션에 시간을 낭비하기 전에 이를 발견할 수 있습니다.