Overview
docs-site design system pageAs organized in, what most greatly determines the quality of Claude Design results is design system setup. This skill analyzes scattered brand assets and synthesizes them into what Claude Design can absorb in one pass as DESIGN.md.
Relationship with the native path (2026-06 update): Claude Design now directly imports design systems from a GitHub repo, design files, or uploads, and self-corrects its output against the registered system. In the Claude Code terminal, you can also send your codebase design system directly with the
design-workflowskill. If you have a clean code repo, that native path is the fastest. This skill is for when assets are scattered, there is no clean code repo, ordesign-system-libraryyou want to use the curated tokens of as a starting point and synthesizes them into DESIGN.md to complement the native path (complement, not replace).
Trigger keywords
Claude Design design system, design system assets, DESIGN.md, brand asset synthesis, design system setup, claude.ai/design system
Input — 5 types of assets
Provide as many of the following as possible (you can start with just one).
| Asset type | Form | What Claude extracts |
|---|---|---|
| Code | GitHub repo URL · local UI package directory | React/Vue/Svelte components, CSS tokens, Tailwind config |
| Design files | Figma .fig, Sketch, component screenshot PNGs |
Color palette, typography scale, component library |
| Brand assets | Logo SVG/PNG, color palette images, style guide PDF | Color, typography, and logo usage rules |
| Real thing | Live website URL, PPTX deck, well-made marketing page | Actual components, spacing, voice |
| Pre-built-in | Apple · Linear · Stripe systems (open license) | Starting point |
| Design system library | moai-designer:design-system-library75 systems (claude · clickhouse · clay, etc.) |
Tokens (color, typography, radius, spacing) + component mapping — an immediate source for DESIGN.md synthesis |
Priority (v2.21.0+): If the user specifies a particular brand mood or needs a system that fits the nature of the output, before collecting separate assets,
design-system-libraryfirst choose from the 75 systems in.design-system-prepuses the selectedsystems/<name>.mdtoken as the primary source for DESIGN.md synthesis. External assets (website URLs, Figma, etc.) are used only as supplementary material for the library system.
Workflow
Step 1 — Asset collection
Ask the user for the asset type and receive input. AskUserQuestion round 1.
가지고 있는 자산을 모두 알려 주세요 (복수 선택):
- 우리 웹사이트 URL
- 로고·이미지 파일
- 잘 만든 자사 페이지 (PPTX·PDF·캡처)
- GitHub repo (UI 컴포넌트)
- Figma 파일
- 사전 빌트인에서 시작
After selection, collect the path/URL of each asset in turn.
Step 2 — Asset analysis
| Asset | Processing method |
|---|---|
| Website URL | Analyze the live page with WebFetch — extract color, font, and component patterns |
| Image file | Extract color palette and logo shape through vision analysis |
| PPTX·PDF | Text, image, and background color analysis |
| GitHub repo URL | package.json · tailwind.config.* · UI directory analysis |
| Local folder | ls · ReadAnalyze the file structure with |
Step 3 — DESIGN.md synthesis
Library system selection priority path (v2.21.0+): If only the brand mood was specified in Step 1, moai-designer:design-system-library의 systems/registry.mdselect the matching system in systems/<name>.mdand directly reflect the YAML tokens from into the Color palette, Typography, and Spacing sections of DESIGN.md. This path skips asset analysis (Step 2) or uses it only as reinforcement, making it the fastest.
First, organize how each section is derived from the source assets. Because DESIGN.md is a document filled by extracting values from observed assets, each section is filled according to the following rules.
| # | Section | How it is derived from source assets |
|---|---|---|
| 1 | Brand voice & personality | Read About, landing copy, and PPTX wording to extract adjectives. If unclear, moai-coworker:collab-brand-identity first, then confirm with AskUserQuestion |
| 2 | Color palette | Collect hex values via vision analysis of images and screenshots + CSS/Tailwind token parsing → interpolate a 50–950 scale, separate state colors and signature assets. For each color, source notation |
| 3 | Typography | @font-faceExtract family/weight/size from ·CSS·Figma text styles. For Korean, assign letter-spacing rules and observe heading↔body weight contrast |
| 4 | Spacing/Radius/Shadow/Motion | Extract the scale from Tailwind config·CSS variables. If absent, present a 4px base standard scaffold |
| 5 | Token 3-layer mapping | Summarize the values confirmed in 2–4 into the three DTCG/CSS/semantic layers. The actual conversion is moai-designer:design-tokens-transformerdelegated to |
| 6 | FROZEN Rules | Extract prohibited items from style guide PDFs and brand regulations. If absent, query the user (no arbitrary invention). WCAG contrast is calculated automatically from the palette |
| 7 | Voice & copy patterns | Observe preferred/prohibited vocabulary, formal style, and emoji frequency from the actual copy corpus. moai-marketer:content-copywriting assist |
| 8 | Component recipes | Condense frequently used patterns from code repo components and the live DOM into token-variable-referencing CSS snippetscondensed to |
| 9 | Asset index | Classify logos and images by variant (horizontal/square/mascot/white knockout) and specify usage |
| 10 | Upload guide | Arrange the 2–9 outputs in upload order. The automatic/manual path is moai-designer:design-sync-uploaddelegated to |
Principle: from observed assets derivebut do not fill in values absent from the assets with guesses — unclear items are queried to the user or left as "undetermined".
Write DESIGN.md with the following 10-section structure.
# [브랜드명] Design System
## 1. Brand voice & personality
[형용사 5-7개 + 한 문단 — 브랜드 성격]
## 2. Color palette
### Primary scale (50–950)
- primary/500: #RRGGBB — [의미] (예: 600=라이트 주색, 500=다크 주색 명시)
- 50·100 … 900·950 (11단계 휘도 스케일)
### Secondary · Accent
- [보조·강조색]: #RRGGBB
### Semantic
- success · warning · error · info: #RRGGBB
### Signature asset
- [시그니처 그라디언트·패턴 등 브랜드 코어 자산] 예: linear-gradient(135deg, #A 0%, #B 100%)
## 3. Typography
- family: Display/Heading/Body/Mono [폰트 이름]
- weight: [사용 굵기 — 예 400/700/900]
- size / lineHeight: [스케일]
- Letter-spacing rules: display −0.05em · body −0.025em · caption 0 (한국어 자간)
- Weight-contrast pattern: [한 문장 안에서 굵기 대비로 핵심어를 강조하는 규칙]
## 4. Spacing / Radius / Shadow / Motion
- Spacing: 4px 베이스 — 4·8·12·16·24·32·48·64
- Radius: none/sm/md/lg/xl/full
- Shadow: sm/md/lg (+ 시그니처 글로우)
- Motion: duration(fast/normal/slow) + easing(default/bounce/smooth)
## 5. Token 3-layer mapping
- L1 DTCG SSOT: `$value`/`$type`/`$description` (provenance 기록)
- L2 CSS vars: `--color-*`·`--tracking-*`·`--space-*` …
- L3 semantic roles: `--base-*` (shadcn) + `.dark` 전환
> 변환·검증은 `moai-designer:design-tokens-transformer`로 수행
## 6. FROZEN Rules
- 금지 규칙: [소스가 선언한 것만 — 예: 특정 색/그라디언트/폰트 금지]
- Letter-spacing: [자간 규칙 준수 조건]
- WCAG contrast: 본문 ≥ 4.5:1(AA), 큰 텍스트 ≥ 3:1 (팔레트에서 자동 계산)
- Illustration/mascot policy: [허용/금지 영역 — 예: 정서 화면 허용, 데이터·결제 화면 금지]
## 7. Voice & copy patterns
- 선호 어휘 / 금지 어휘(AI 슬롭·진부 표현)
- 격식 레지스터: [존댓말·반말·친근체 정책]
- 이모지 정책: [사용/금지]
## 8. Component recipes
- Primary CTA / Card / Sticky nav / Empty state / Section eyebrow
— 토큰 변수 참조형 CSS 스니펫(아래 예시 참조)
## 9. Asset index
| 변형 | 용도 |
|---|---|
| 가로형(horizontal) | 헤더·네비 |
| 정사각(square) | 파비콘·앱 아이콘·소셜 |
| 마스코트(mascot) | 히어로·엠프티·404 (정서 영역) |
| 화이트 녹아웃(-WH) | 어두운/그라디언트 배경 위 |
## 10. Upload guide
- 업로드 순서: DESIGN.md → 토큰 → 로고 변형 → 참고 자산
- 자동/수동 이중 경로 → `moai-designer:design-sync-upload`
- Published 토글: 업로드 후 분석 대기 → 테스트 프롬프트 → 일치 시 ON
Section 8 — Component recipes snippets (examples, token variable reference style)
/* Primary CTA — pill + 시그니처 배경 */
padding: var(--space-3) var(--space-6); border-radius: var(--radius-full);
background: var(--gradient-signature); color: var(--fg-on-primary);
font-weight: var(--fw-bold); letter-spacing: var(--tracking-body);
/* hover: box-shadow: var(--shadow-signature) */
/* Card — surface */
background: var(--color-surface); border-radius: var(--radius-lg);
padding: var(--space-6); border: 1px solid var(--border-1);
box-shadow: var(--shadow-sm);
/* hover: translateY(-2px) + var(--shadow-md) */
/* Sticky nav (glassy) */
position: sticky; top: 0; backdrop-filter: blur(12px);
background: color-mix(in srgb, var(--color-bg) 85%, transparent);
border-bottom: 1px solid var(--border-1);
/* Empty state */
/* 일러스트/마스코트(정책 허용 영역) + 위트 카피 + CTA, text-align: center */
/* Section eyebrow */
font-family: var(--font-mono); font-size: var(--text-xs); font-weight: var(--fw-semibold);
color: var(--color-primary); letter-spacing: 0.08em; text-transform: uppercase;
Snippets reference token variables(var(--…)) instead of hardcoded values — brand values are injected from the 3-tier mapping in item 5, and recipes fix only structure and patterns.
Step 4 — Include an asset organization guide
Along with DESIGN.md, what and how to upload to claude.ai/design provide a guide. There are two upload paths: automatic (DesignSync MCP) and manual, and actual execution is handled by moai-designer:design-sync-upload, which handles it — here we only organize the priorities and cautions that the skill will consume.
## Claude Design 업로드 가이드
### 업로드 우선순위
1. `DESIGN.md` (이 파일) — 가장 먼저
2. [GitHub repo 또는 UI 패키지 디렉토리]
3. [잘 만든 자사 사이트 URL] — 웹 캡처 도구로
4. [경쟁사 참고 URL] — 톤 비교용
5. 로고 파일 (SVG 우선)
### 업로드 시 주의
- 모노레포 전체 X → UI 패키지 디렉토리만
- 고객 데이터·매출 박힌 PPTX는 익명화 후 업로드
- 폰트 파일은 라이선스 확인 후 업로드
### Published 토글
1. 위 자산 업로드 후 5-15분 대기 (분석 시간)
2. UI 키트 검토 후 테스트 프롬프트 실행:
- "마케팅 랜딩 페이지를 디자인해 줘"
- "사이드바와 3개 콘텐츠 섹션이 있는 설정 페이지"
3. 결과가 브랜드와 일치하면 → Published 토글 ON
4. 어긋나면 → Remix 또는 자산 추가 업로드 후 재시도
Step 5 — Save results
- Save to the path specified by the user or the default
./design-system-prep/directory DESIGN.md+UPLOAD-GUIDE.md+ organized asset copies- The user can upload the folder as-is to Claude Design
Output format
## 디자인 시스템 자산 합성 완료
### 분석한 자산
- [URL 또는 파일 경로 목록]
### 생성된 파일
- ./design-system-prep/DESIGN.md (XX줄)
- ./design-system-prep/UPLOAD-GUIDE.md
### 추출 요약
- Primary: #[hex] (출처: [자산])
- Typography: [폰트] (출처: [자산])
- Components 인식: N개
- Voice: [한 문단]
### 다음 단계
1. claude.ai/design 진입 → Organization settings → Design systems
2. 위 폴더 업로드 → 5-15분 대기
3. 테스트 프롬프트로 검증
4. Published 토글 ON
Usage examples
Example 1 — Operating SaaS company
입력 자산:
- 자사 웹사이트: https://example.com
- GitHub repo: github.com/example/web-ui
- 로고: ./brand/logo.svg
- 잘 만든 PPTX 덱: ./decks/q4-report.pptx
결과:
- DESIGN.md (자동 합성, 10섹션)
- 자산 정리 폴더
- 추출된 색 5개, 폰트 3개, 컴포넌트 12개
Example 2 — Early-stage startup (few assets)
입력 자산:
- 로고: ./logo.png
- 색 팔레트 이미지: ./colors.png
- 영감 사이트: linear.app
결과:
- DESIGN.md (Linear 기반 + 로고·색 커스터마이즈)
- UPLOAD-GUIDE.md
- 후속 권장: Linear 사전 빌트인에서 시작 → 우리 색·로고로 Remix
Example 3 — No assets (using pre-built-ins)
입력: "자산 없음 — Linear 톤으로 시작하고 싶다"
결과:
- DESIGN.md (Linear 시스템 기반 시작점)
- 자체 브랜드 점진 정의 가이드
- 권장: Claude Design에서 사전 빌트인 Linear 선택 후
3-5개 프로젝트 진행하며 자사 시스템 점진 추출
Cautions
Do
- Start even with insufficient assets — pre-built-ins + partial asset combinations are possible
- DESIGN.md를 Human-readable formatso that — both Claude and humans can understand
- Fonts as name + license note together — prevents disputes during handoff
- When analyzing a live site with WebFetch, check robots.txt and terms of use
Don't
- Do not attempt to analyze the entire monorepo — 5+ minute delays + system extraction misalignment
- Do not upload sensitive assets (PPTX with customer data or revenue figures) as-is → anonymize
- Do not fill DESIGN.md with only "the AI will figure it out" guesses — user confirmation required
- Do not include fonts in assets without knowing the font license
Related skills
| Skill | When to use |
|---|---|
moai-designer:design-tokens-transformer |
Follow-up: item 5 3-tier token generation and validation |
moai-designer:design-sync-upload |
Follow-up: item 10 automatic/manual upload execution |
moai-designer:design-brief |
Follow-up: first draft creation after system setup |
moai-designer:design-prompt-builder |
Follow-up: design for a specific area |
moai-coworker:collab-brand-identity |
Prerequisite: when brand identity is ambiguous |
moai-marketer:content-copywriting |
Auxiliary: organizing voice and copy patterns |
moai-officer:doc-pptx |
Auxiliary: when there is no well-made in-house PPTX |