딸깍 (ddalkak)

Ddalkak

Ddalkak은 Figma URL을 입력하면 디자인 정보를 추출해 Bridge JSON으로 정리하고, 이를 기반으로 구현 계획, 코드 생성, 화면 검증까지 이어지도록 만든 퍼블리싱 자동화 플러그인입니다.

현재 기본 목표는 사람이 반복해서 퍼블리싱하지 않도록, Figma 디자인을 코드 생성 가능한 중간 표현으로 안정적으로 바꾸는 것입니다.

전체 흐름

flowchart LR
  A["Figma URL"] --> B["Bridge"]
  B --> C["bridge.json"]
  C --> D["Plan"]
  D --> E["plan.md"]
  E --> F["Code"]
  F --> G["React/Web/Native code"]
  G --> H["Verify"]
  H --> I{"통과?"}
  I -- "예" --> J["Finalize"]
  I -- "아니오" --> K["Fix only diffs"]
  K --> H

단계	명령	입력	출력	설명
0	/ddalkak:design-md	프로젝트 코드베이스	design.md	기술 스택과 구현 기준을 정리합니다.
1	/ddalkak:bridge	Figma URL 1개 이상	.ddalkak/bridge/<name>.bridge.json	Figma 디자인을 플랫폼 중립 Bridge JSON으로 변환합니다. 같은 화면의 상태 변형 프레임이면 여러 URL을 하나의 bridge로 병합합니다.
2	/ddalkak:plan	Bridge JSON, design.md	.ddalkak/plan/<name>.plan.md	구현 계획을 만듭니다.
3	/ddalkak:code	Plan, design.md	프로젝트 코드	실제 코드를 생성합니다.
4	/ddalkak:verify	코드, Bridge JSON	.ddalkak/reports/<name>.verify.md	생성 화면을 디자인 기준과 비교합니다.
5	/ddalkak:finalize	Verify 결과	최종 요약	완료 상태와 남은 이슈를 정리합니다.

자세한 사용자 흐름은 docs/ddalkak-user-flow.md를 참고합니다.

앱 검증까지 확장하는 방식은 docs/platform-verify.md를 참고합니다. 현재 구현된 캡처 provider는 Web과 Flutter(웹 빌드)이며 둘 다 Playwright로 캡처합니다. Flutter는 canvas 렌더링이라 DOM 스냅샷 없이 픽셀 비교만으로 판정합니다. Android Native, iOS Native, React Native는 verify.targets 계약을 먼저 정의하고 provider를 추가하는 구조입니다.

Bridge가 하는 일

Bridge는 Figma와 코드 생성 단계 사이의 번역 계층입니다. Figma 원본을 그대로 코드로 만들면 Web, React Native, iOS, Android 같은 대상 환경마다 해석이 달라질 수 있으므로, 먼저 공통으로 읽을 수 있는 Bridge JSON으로 정리합니다.

Bridge JSON에는 다음 정보가 들어갑니다.

분류	포함 정보
구조	page, section, frame, group, component, instance
레이아웃	bbox, size, auto layout, grid, gap, padding
반응형	constraints, sizing, adaptive group, breakpoint, matchKey
스타일	color, typography, radius, shadow, stroke, opacity
텍스트	content, font, line height, wrapping, overflow
에셋	image, icon, screenshot, export path, asset fit
의미	hero, card, button, input, navigation, list 같은 semantic role
검증	schema version, completeness, errors, confidence

앱 검증 방향

Web과 Flutter(웹 빌드)는 브라우저에서 바로 스크린샷을 찍을 수 있지만, Android Native, iOS Native, React Native는 각 플랫폼의 실행 환경이 필요합니다. Ddalkak은 이를 verify.targets로 표현합니다.

{
  "verify": {
    "defaultTarget": "web",
    "targets": [
      {
        "id": "web",
        "platform": "web",
        "screenshotProvider": "playwright",
        "entry": { "type": "url", "url": "http://localhost:5173" }
      },
      {
        "id": "ios-preview",
        "platform": "ios-native",
        "screenshotProvider": "simctl",
        "entry": { "type": "deepLink", "url": "ddalkak://preview?screen=home" }
      }
    ]
  }
}

즉 비교 엔진은 공통으로 유지하고, 화면을 띄워 스크린샷을 가져오는 부분만 플랫폼별 provider로 분리합니다. 앱 검증을 하려면 코드 생성 단계에서 ddalkak://preview?screen=<name> 같은 검수용 진입점도 함께 만들어야 합니다.

요구 사항

• Node.js 22 이상
• npm
• Claude Code
• Figma MCP 연결은 live 캡처를 할 때만 필요합니다.

캐시 기반 테스트만 돌릴 때는 Figma MCP가 없어도 됩니다.

빠른 시작

저장소를 받은 뒤 루트에서 의존성을 설치합니다.

npm install

샌드박스 앱 의존성도 설치합니다.

cd sandbox
npm install
cd ..

캐시 기반 Bridge 회귀 테스트를 실행합니다.

npm run test:bridge:cache

정상이라면 다음과 비슷한 결과가 나옵니다.

bridge cache regression passed: 204 nodes, 10 assets

저장된 Figma 캐시를 사용해 샌드박스 프로젝트에 Bridge JSON을 생성합니다.

npm run bridge:cache -- --cache fixtures/figma/untitled-1-858 --project sandbox --name pc-home --force

정상 결과 예시는 다음과 같습니다.

{
  "source": "cache",
  "mcpCalls": 0,
  "nodes": 204,
  "validation": "pass",
  "warnings": 0
}

생성된 파일은 다음 위치에서 확인할 수 있습니다.

sandbox/.ddalkak/bridge/pc-home.bridge.json

샌드박스 화면을 실행하려면 다음 명령을 사용합니다.

cd sandbox
npm run dev

Vite가 출력하는 로컬 URL을 브라우저에서 열어 결과 화면을 확인합니다.

Claude Code 플러그인으로 사용하기

Claude Code에서 이 저장소를 플러그인 디렉터리로 직접 로드할 수 있습니다. <repo-path>는 각자 clone 받은 Ddalkak 저장소의 절대 경로로 바꿉니다.

claude --plugin-dir <repo-path>

Claude Code 안에서 플러그인이 보이는지 확인합니다.

/ddalkak

또는 마켓플레이스 방식으로 등록해 설치할 수 있습니다.

/plugin marketplace add <repo-path>
/plugin install ddalkak@ddalkak-marketplace

스킬이나 agent 파일을 수정한 뒤에는 Claude Code에서 다시 로드합니다.

/reload-plugins

Figma MCP 연결

새 Figma 페이지를 live로 캡처하려면 Figma MCP가 필요합니다.

claude mcp add --transport http figma https://mcp.figma.com/mcp

Claude Code 안에서 연결 상태를 확인합니다.

/mcp

Figma MCP 호출 한도 때문에 개발 중에는 다음 원칙을 사용합니다.

1. 처음 한 번만 live로 필요한 응답을 캡처합니다.
2. 모든 MCP 응답을 fixtures/figma/<name>/ 또는 .ddalkak/mcp-cache/<name>/에 저장합니다.
3. 이후 extractor, schema, bridge 로직은 cache 모드로 반복 검증합니다.

캐시 기반 작업 방식

캐시가 완전한지 확인합니다.

node scripts/mcp-cache.mjs check fixtures/figma/untitled-1-858

캐시에서 Bridge JSON을 생성합니다.

npm run bridge:cache -- --cache fixtures/figma/untitled-1-858 --project sandbox --name pc-home --force

생성된 Bridge JSON을 검증합니다.