SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdesign-handoff-reader

design-handoff-reader

Design & creation

View repository

Updated 10-15 21:35

About this skill

design-handoff-reader — handoff bundle analysis

Overview

Claude Design의 Export → "Handoff to Claude Code"(local terminal or Claude Code Web) creates a bundle containing the project's design files + chat + README 3 elements (officially confirmed fact). Anthropic defines design as "code under the hood (HTML/CSS/JS)", and the structured DTCG JSON format is not an official specification. This skill defensively analyzes that bundle to generate a summary report that lets a person grasp the handoff state within 5 minutesand a one-line instruction that can be pasted directly into Claude Code.

Official specification vs inference (anti-hallucination — docs 03 §5.4): What the official documentation guarantees is only the 3-element triad (design files + chat + README). design-tokens.json/tokens.json, components.json, layout-hierarchy.json, chat-history.md such as specific filenames are MoAI working assumptions and not an Anthropic documentation specification. Therefore, instead of performing a hard 5-file existence check, it parses only what exists on a best-effort basis, and if absent, derives it from the code (HTML/CSS).

Handoff direction + entry mode (2026-06): The bundle is generated from the Claude Design canvas's Export → Handoff to Claude Code(local/web). The reverse direction (code → design) uses the Claude Code terminal's design-workflow skill to import the codebase design system into Claude Design — handoff is bidirectional. Two entry modes are supported: (1) .zip download(fixed offline container), (2) paste prompt + bundle URL(the actual main flow — Claude Code fetches the URL).

Trigger keywords

Claude Design handoff, handoff bundle, design-tokens analysis, components.json, Claude Code handoff, design token extraction

Input

One of the following:

Input form
ZIP archive ./handoff-bundle.zip
Directory ./handoff-bundle/
URL Bundle URL provided at Claude Design Export

Workflow

Step 1 — README-first parsing + defensive glob (graceful degradation)

Does not perform a hard 5-file existence check. Since the exact bundle format is officially undocumented, it is handled defensively in the following order.

  1. README first (source of truth): From the bundle, README is read first to grasp the structure and intent. It is the only officially documented element that Anthropic designed "to give the model design interpretation instructions." README.mdis common, but extensionless READMEis also accepted.
  2. Optional best-effort glob (do not make hard requirements): The files below are used if present, and do not fail if absent Discover from the input. The filename is inferred, so all variants are accepted.
Concept Accepted filenames (inferred — not an official spec) Fallback when absent
Design tokens design-tokens.json or tokens.json (both accepted) Derive tokens from CSS custom properties / standalone HTML
Components components.json Infer the component tree from the HTML DOM structure
Layout layout-hierarchy.json Infer responsive patterns from HTML/CSS
chat context chat-history.md (or a chat summary in the README) Derive decision context from code comments and the README
Assets assets/ Omit if absent
  1. Filename split normalization: Accept the token file whether it is design-tokens.jsonor tokens.json, and .moai/design/ when outputting, normalize to a single name (tokens.json) (design-workflowconsistent with ).
  2. Relaxed version gating: Unknown or missing bundle versions are not hard-rejected but handled with best-effort parsing + a warning (no official version-stamp evidence — supported_bundle_versionsis a MoAI-internal placeholder).
  3. 2 entry modes: .zip download(the above procedure after unzip) + paste prompt + bundle URL(Claude Code fetches the URL and analyzes what was loaded into context).

Step 2 — Analyze existing files (best-effort)

The per-file analysis below is performed only when the file exists . If absent, substitute the fallback from the Step 1 table (code/HTML derivation); the omission itself is not a failure.

Analyze README (source of truth)

  • Project goals and scope
  • Component mapping guide
  • Intended user flows
  • Known constraints and incomplete parts

Analyze design-tokens.json

- 색 토큰 N개 (primary·secondary·semantic 구분)
- 타이포 N개 (family·size·weight 스케일)
- 간격 N개 (spacing scale)
- 모서리·그림자·전환 등
- 시맨틱 매핑 정확도 (예: primary/500 → #2a8a8c)

Analyze components.json

- 사용된 컴포넌트 N개
- 컴포넌트 트리 (depth·중첩)
- variants·states 명시 여부
- 기존 코드베이스 컴포넌트와 매칭 가능성

Analyze layout-hierarchy.json

- 페이지 수
- 반응형 변형 정의 여부 (mobile·tablet·desktop)
- 그리드·간격 일관성
- 인터랙티브 요소 (호버·클릭·드래그) 목록

Analyze chat-history.md

- 주요 디자인 결정과 이유 추출
- 사용자가 명시한 제약·우선순위
- 거부된 대안 (왜 안 했는가)
- 미해결 질문

Step 3 — Generate summary report

# 핸드오프 번들 분석 — [프로젝트명]

## 한눈에 보기

| 항목 | 내용 |
|---|---|
| 페이지 수 | N |
| 컴포넌트 수 | N (그중 기존 코드와 매칭 가능: M) |
| 디자인 토큰 | 색 N·타이포 N·간격 N |
| 인터랙티브 요소 | N (호버·클릭·드래그) |
| 반응형 정의 | mobile·tablet·desktop 모두 / 일부 / 없음 |
| 엣지 상태 | empty·error·loading 정의 여부 |

## 디자인 토큰 요약

### 색
- primary/500: #[hex] (기존 토큰과 일치 / 새로움)
- ...

### 타이포
- Display: [폰트] [size]
- ...

## 컴포넌트 트리

Page ├─ Hero │ ├─ Headline (h1) │ ├─ Subheadline (h2) │ └─ CTA Button (primary, large) ├─ FeatureGrid (3-col) │ ├─ FeatureCard × 6 │ └─ ... └─ Footer


## 디자인 결정 맥락 (chat-history.md에서 추출)

1. 사이드바 대신 탭 선택 — 이유: 사용자가 모든 섹션 동시 인지 필요
2. 흰 배경 + 단일 강조색 — 이유: 기존 마케팅 사이트 톤 유지
3. ...

## 미해결 질문

- [ ] 결제 페이지의 카드 위젯이 기존 ChargeCard와 호환되는가?
- [ ] 다크 모드 변형이 정의되어 있지 않음
- [ ] ...

## 구현 우선순위 (추천)

1. P0: Hero · CTA (전환 핵심)
2. P1: FeatureGrid (스크롤 다음 영역)
3. P2: Footer · 보조 페이지
4. P3: 다크 모드 변형 (정의 후 추가)

## Claude Code 핸드오프 지시 (복붙용)

Take this handoff bundle and implement it as production code. Bundle URL: [URL] Use the existing design system tokens as-is. Map components to our React library ([matching components such as ChargeCard, FeatureGrid, CTA]). Make the result previewable locally (npm run dev). Respect the design decision context in chat-history.md. Dark mode to be defined and handled in a separate round later.

Step 4 — Follow-up recommendations

Two path branches

Path When to use Role of this skill
Claude Code build path (primary purpose) When it must be implemented as production code Bundle analysis + automatic generation of a one-line Claude Code instruction (workflow below)
Canva marketing follow-up path (Anthropic ↔ Canva official partnership) When the marketing team needs to further edit SNS, event, and ad variations The analysis in this skill is for reference only. The actual Canva export is executed directly from the Export → Canva menu in the Claude Design canvas

Running both paths at the same time will cause the design to be modified in both tools simultaneously, breaking consistency. Only one path per draft operate it.

## 다음 단계 (Claude Code 빌드 경로)

1. 위 Claude Code 핸드오프 지시를 복사
2. Claude Code 터미널 또는 Web에서 붙여넣기
3. 첫 빌드 후 로컬 미리보기 확인
4. 코드와 디자인 차이가 있으면:
   - 작은 차이: Claude Code에서 수정 지시
   - 큰 차이: Claude Design으로 돌아가 재디자인 → 새 핸드오프

## 주의

- 핸드오프 후 디자인을 또 수정하지 마세요 — 코드와 어긋납니다
- 큰 디자인 변경은 새 핸드오프 번들 작성 후 부분 인계
- 마케팅 후속(Canva 경로)이 필요하면 핸드오프 번들과 별개로 Claude Design 캔버스에서 직접 Export → Canva

Usage examples

Example 1 — Complete bundle

입력: ./handoff-bundle/ (5개 파일 모두 존재)

결과:
- 페이지 4개, 컴포넌트 18개 (기존 매칭 14)
- 색 8개, 타이포 5개, 간격 8개
- 디자인 결정 5개 추출
- 미해결 질문 3개
- Claude Code 지시 1줄 생성

Example 2 — Partial bundle (chat-history.md missing)

입력: ./handoff-bundle/ (chat-history.md 없음)

결과:
- 다른 파일 정상 분석
- chat-history.md 누락 경고 — 디자인 의도가 코드로만 추론됨
- Claude Code 지시는 생성 (맥락이 약해진 점 명시)
- 후속 권장: Claude Design 채팅 화면을 캡처해 별도 참고 자료로

Example 3 — ZIP-compressed bundle

입력: ./handoff-bundle.zip

처리:
1. unzip으로 ./handoff-bundle/ 추출
2. 위 예시 1·2와 동일 절차
3. 분석 후 ZIP 원본은 백업 용도로 보존

Output format

## 핸드오프 번들 분석 결과

### 번들 상태
- 위치: [경로]
- 포함 파일: [목록]
- 누락 파일: [있다면]

### 한눈에 보기 테이블
[페이지·컴포넌트·토큰·인터랙티브·반응형·엣지]

### 디자인 토큰 요약
[색·타이포·간격]

### 컴포넌트 트리
[ASCII 트리]

### 디자인 결정 맥락
[chat-history에서 추출한 결정 5-10개]

### 미해결 질문
[체크리스트]

### 구현 우선순위
[P0-P3]

### Claude Code 지시 (복붙용)
[1단락 지시문]

Precautions

Do

  • Parse the README first (source of truth), then best-effort analyze only the files that exist (no hard 5-file requirement)
  • Specify whether component names match existing code — determines the quality of Claude Code's output
  • Compress the context of design decisions — extract 5-10
  • Separate unresolved questions — decisions needed before implementation begins

Don't

  • Do not use bundle analysis as a substitute for the handoff procedure — always hand off the bundle directly to Claude Code
  • Do not arbitrarily change design tokens — consistency requires Claude Code to use them as-is
  • Do not arbitrarily interpret the decision context in chat-history.md — preserve it in quote form

Related skills

Skill When to use
moai-designer:design-brief Prerequisite: when creating the draft itself to hand off
moai-designer:design-system-prep Prerequisite: design system setup
moai-pm:project Follow-up: initialize the Claude Code working folder
moai-coworker:collab-spec Auxiliary: writing the code SPEC after handoff