bridge

[1] 디자인 브릿지(JSON) 산출 (닉·초록)

Figma 원본을 무손실 플랫폼 중립 Bridge IR로 정규화해 후속 단계(plan/code)가 쓰기 좋은 단일 JSON으로 만든다. 토큰을 쓰되 원본값이 항상 복원 가능하고(§4), 스크린샷과 교차검증해 누락을 잡고(§8), 적응형 동작까지 담고(§5), 스크린샷 비전 분석으로 의미 레이어(semanticRole — hero/cta-button/card-list …)를 얹는다(§11).

• 스키마 SSOT: ${CLAUDE_PLUGIN_ROOT}/shared/bridge.schema.json (v2.1)
• 추출 규칙 SSOT: ${CLAUDE_PLUGIN_ROOT}/shared/figma-extraction-rules.md

입력

• Figma URL — 하나 또는 여러 개(필수). 여러 개를 주면 각각 추출해 한 bridge의 screens[]로 병합한다.
  • 여러 URL이 같은 화면의 상태/인터랙션 변형(예: 로그인 빈→입력중→에러→활성)이면 adaptive.group으로 묶고, adaptive.variant에 상태 이름을 보존하며, 상태 간 동일 노드에 matchKey를 붙인다(§5). plan/code가 이 상태 묶음을 하나의 화면(+상태 전환) 으로 합성할 수 있게 된다.
  • 서로 다른 화면(예: 온보딩 + 로그인)이면 그룹핑하지 않고 각각 별도 screen으로 둔다.
  • 경계: 상태 전환을 일으키는 트리거/로직(입력 검증·서버 응답·네비게이션)은 정적 디자인에 없다 — bridge는 상태와 matchKey만 담고, 전환 배선은 plan/code에서 정한다(Figma 프로토타입 reaction이 있으면 근거로 활용).
• 모드: section (프레임/섹션 단위) | page (페이지 전체) — 기본 page (URL의 node-id 유무로 자동 판별. 규칙: rules §1)
• fidelity: lossless(기본) | summary — lossless는 구조 접기 외 축약 금지 (rules §2)
• source: live(기본, MCP 호출 + 원시응답 캐시 기록) | cache(캐시 재생, 호출 0회) — rules §10
• cacheDir: 캐시 위치. 개발용 골든 픽스처는 fixtures/figma/<name>/, 런타임 기본은 .ddalkak/mcp-cache/<name>/
• enrich: on(기본) | off — off면 §11 비전 의미 레이어·§12 구조 추론을 건너뛴 순수 MCP 브릿지. 로직 반복 디버깅 등 빠른 이터레이션용 (§8 교차검증은 안전망이므로 off여도 수행)

MCP 호출 한도 절약: 라이브 실행은 모든 원시 응답을 캐시에 즉시 기록한다(record-always). 이후 source: cache로 호출 0회 개발·디버깅. 상세: rules §10.

사용하는 Figma MCP 도구

• get_metadata — 노드 트리/구조/bbox (structure 패스)
• get_design_context — 노드별 상세 스타일: fills/strokes/effects/cornerRadius/layout/constraints/typography (detail 패스, rules §7)
• get_variable_defs — 디자인 토큰(변수) — tokens 1차 소스, @ref로 치환 (rules §4)
• get_code_connect_map — 컴포넌트 ↔ 코드 매핑 (rules §3)
• download_assets — 장식 벡터/이미지 fill 실제 파일 export (rules §2, 자산 무손실)
• get_screenshot — 화면 스크린샷 → 교차검증(§8) + verify 재사용

실제 추출은 ddalkak:figma-extractor 서브에이전트에 위임해 컨텍스트를 격리한다. 서브에이전트는 7개 패스(structure/detail/tokens/component-map/assets/screenshots/semantic)를 병렬 실행 후 병합 (rules §6). semantic 패스는 캡처된 스크린샷을 비전 분석하는 것이라 MCP 호출을 추가로 쓰지 않는다 (§11).

출력

캐시 입력 사전검사

source: cache에서는 변환 전에 반드시 node scripts/mcp-cache.mjs check <cacheDir>를 실행한다. 섹션 응답이 codeSummary인 경우 get_metadata의 모든 metadataLeaf에 대응하는 개별 get_design_context(nodeId) 상세 응답이 있어야 한다. 하나라도 없으면 bridge, plan, code를 생성하지 않고 누락된 leaf 이름과 node ID를 보고한다. 자연어 요약이나 스크린샷 추정으로 누락 좌표를 채워 성공 처리하지 않는다.

• .ddalkak/bridge/<name>.bridge.json (스키마 v2.1 준수, meta.schemaVersion: "2.1")
• compact 저장(rules §14 — pretty는 토큰 4배). 사람 검토: scripts/bridge-format.mjs <file> --pretty
• meta.sourceFingerprint와 meta.extractorFingerprint를 함께 기록한다. 캐시와 추출기 지문이 모두 같을 때만 기존 브릿지를 재사용한다. 스키마·규칙·변환기가 바뀌면 같은 캐시에서도 다시 생성한다(rules §10).
• meta.coordinateSpace와 meta.completeness를 기록하고, 부분 실패면 meta.errors[]에 실패 패스를 남긴다(rules §15).
• 저장 전 scripts/validate-bridge.mjs로 검증 → 미해결 @ref/불일치 있으면 자가 수정 1회 재시도 (rules §9) — 검증기는 불변식·bbox↔스크린샷 edge 대조(rules §9-1)까지 수행한다

절차

1. URL(들) 파싱 → 각 URL의 file key / node id 추출, node-id 유무로 section/page 모드 확정. 여러 URL이면 각 URL을 순회하며 2~7을 적용해 추출하고, 결과 screens를 한 bridge로 병합한다.
2. figma-extractor에게 위임 (source 전달) → 7개 패스 결과 병합.
   • live: MCP 호출하며 원시 응답을 cacheDir에 기록. cache: cacheDir에서 원시 응답 읽어 재생 (rules §10).
   • cache final 생성은 npm run bridge:cache -- --cache <cacheDir> --project <project> --name <name>을 실행한다. 노드 컴파일, 자산 로컬 적재, compact 저장, JSON Schema·스크린샷 검증까지 원자적으로 끝낸다.
   • 병합의 수치·구조·텍스트는 기계 산출물을 그대로 쓴다: bridge-skeleton.mjs(metadata → bbox 트리, §8-2)
     • design-context-to-bridge.mjs(코드 응답 → 노드 초안: 스타일·텍스트·에셋·앵커 원형 §8-3). LLM은 두 산출물의 병합(instance 판별, 스켈레톤 bbox 우선)만 담당 — 전사 금지.
3. 가지치기(rules §2, 무손실 자산화) + 컴포넌트 판별(§3) + 플랫폼 중립 layout/sizing/behavior(§7) 적용. 같은 논리 화면 변형은 adaptive.group으로 묶고, 확실한 동일 노드에만 matchKey를 붙인다(§5). 여러 URL로 받은 것이 한 화면의 상태들이면 그 상태 변형도 여기서 같은 방식으로 그룹핑한다.
4. 비전 의미 레이어(§11) — 주요 컨테이너에 semanticRole 부여, 반복 패턴 인식. MCP 수치는 절대 덮어쓰지 않음.
5. 구조 추론(§12) — Figma에 없어도 코드에 필요한 구조 제안: 반복 서브트리 → suggestedComponent(+suggestedProps), 흩어진 절대배치 덩어리 → source: "inferred" 합성 그룹 + flex 추론. plan/code가 이걸 근거로 컴포넌트화·중첩을 구현.
6. 스크린샷 ↔ 구조 교차검증(§8) — 누락·불일치를 reconciliation에 기록. 재추출(leaf 노드 ID로 개별 get_design_context 재호출)이 항상 1순위이고(rules §8-1), 호출이 실패/한도초과일 때만 scripts/bridge-autofix.mjs(스크린샷 색상영역 매칭, §9-1)로 차선 보정 — 이때 보정한 노드는 confidence: 0.7로 남겨 한도가 풀리면 재확인 대상임을 표시한다. 그래도 안 되는 것만 비전 backfill(source: "vision" + confidence 태깅, §11-2).
7. 토큰 매핑: 값이 변수에 대응하면 @color.primary처럼 참조, 아니면 raw 리터럴 (§4 무손실 규약).
8. JSON Schema + 적응형 그룹 검증(§9/§15) → 저장 → 요약 보고 (screens 수, adaptive 그룹, completeness, 컴포넌트 판별, 교차검증 결과, semanticRole/vision 노드 수, suggestedComponent 제안 목록).