| name | design-workflow |
| description | 통합 디자인 워크플로 스킬 — Path A(Claude Design 핸드오프 번들 가져오기, 필요시 Figma 추출기 경유)와 .moai/design/(research·system·spec)에서 design-brief 컨텍스트 로딩을 처리합니다. DTCG 토큰을 검증하고 브랜드 컨텍스트 헌법 우선순위를 보장합니다. /moai design 워크플로에 사용 — 일반 디자인 시스템 문서용이 아닙니다.
Use for the /moai design workflow: Path A Claude Design handoff-bundle import (via Figma extractor when needed), design-brief context loading from .moai/design/, DTCG token validation, and brand-context constitutional priority.
|
| user-invocable | false |
| version | 1.1.2 |
⚠️ 개발 런타임 전용 — 이 스킬은 MoAI-ADK(Claude Code) 환경을 전제한다. Claude Cowork(Desktop)에서는 .moai/config 의존으로 동작하지 않을 수 있다. Desktop 사용자는 cd-* 체인(design-brief → design-prompt-builder → design-slop-check)을 사용한다.
Design Workflow (design-workflow)
Unified /moai design workflow skill. Handles two complementary responsibilities:
- Design artifact import — Path A (Claude Design handoff bundle, ZIP/HTML) and Path
B1 (Figma extractor via meta-harness). Produces DTCG-validated design tokens at
.moai/design/tokens.json for expert-frontend consumption.
- Design-brief context loading — Auto-loads human-authored briefs from
.moai/design/
(spec.md, system.md, research.md) into the orchestrator prompt before
expert-frontend or design-brand-system runs.
Brand context (.moai/project/brand/) is the constitutional parent across all paths — no
path may override brand constraints (design constitution §3.1, §3.3).
Quick Reference
Reserved output paths (design constitution §3.2, must not collide with human files):
tokens.json, components.json, assets/, import-warnings.json, brief/BRIEF-*.md,
copy.json, path-selection.json — all under .moai/design/.
Path selection (presented via AskUserQuestion when /moai design needs choice):
- Path A — Claude Design (권장) — handoff bundle (ZIP or HTML)
- Path B1 — Figma — meta-harness generates
moai-harness-figma-extractor dynamically
Selection persisted to .moai/design/path-selection.json.
Context-loading priority order (REQ-2 / AC-4 from absorbed design-context skill):
spec > system > research. When token budget exceeded, drop in REVERSE priority — never
drop spec. Default token_budget: 20000 from design.yaml design_docs.token_budget.
Token estimation: estimated_tokens = ceiling(char_count / 4) * 1.10.
Implementation Guide
Part 1 — Path A: Claude Design Handoff Bundle
Supported formats (Phase 1):
ZIP — Claude Design export with manifest.json, tokens.json, components/, assets/HTML — single-file Claude Design export
Unsupported (Phase 2 roadmap): DOCX, PPTX, PDF, Canva link — return
DESIGN_IMPORT_UNSUPPORTED_FORMAT and guide to Path B.
Version whitelist: Check manifest.json format_version against
supported_bundle_versions in .moai/config/sections/design.yaml. Current default: ["1.0"].
Mismatch → DESIGN_IMPORT_UNSUPPORTED_VERSION.
Parsing flow:
- Receive bundle file path from orchestrator
- Validate file existence →
DESIGN_IMPORT_NOT_FOUND if missing
- Validate format (extension + magic bytes:
PK\x03\x04 for ZIP, DOCTYPE/<html for HTML)
- Security scan before extraction — list ZIP entries; reject executables (
.sh, .exe,
.bat, .cmd, .ps1, .py, .rb, .pl), symlinks, path traversal (../, ..\),
absolute paths → DESIGN_IMPORT_SECURITY_REJECT
- Read
manifest.json, validate version
- Extract:
tokens.json → .moai/design/tokens.json; components/ → components.json;
assets/** → .moai/design/assets/; copy.json → .moai/design/copy.json
- Validate token structure (required keys:
colors, typography, spacing); missing
keys → warning, not failure
- Report extraction results
Expected ZIP structure: manifest.json (format_version, claude_design_version,
created_at) + tokens.json (colors, typography, spacing, radii, shadows) + optional
components/ (HTML or JSON specs) + optional assets/ (images, fonts, icons) + optional
copy.json (structured copy).
Output token schema (normalized to MoAI): top-level keys colors, typography,
spacing, radii, shadows, plus source: "claude-design-bundle" and bundle_version.
Field normalization (silent rename, logged in import-warnings.json):
primary_color/brand_color → colors.primary; heading_font →
typography.fontFamily.heading; base_spacing → spacing.base.
Asset safety: Validate image MIME (png, jpg, gif, webp, svg, ico) and font formats
(woff2, woff, ttf, otf). Reject nested ZIPs. Strip script tags from SVG metadata.
Part 2 — Path B1: Figma Extractor (Meta-Harness)
Prerequisite: the harness policy moai-meta-harness. Path B1 does NOT ship a
static Figma skill — it is generated dynamically. When user selects Path B1, invoke
moai-meta-harness to generate .claude/skills/harness-figma-extractor/SKILL.md
(project-scoped and user-owned via harness-* prefix — moai update never
overwrites). Meta-harness Phase 5 (Customization) collects via Socratic interview:
Figma file ID, page selectors mapping pages to token categories, credential reference
(env var name like FIGMA_TOKEN; value NEVER stored in skill file). Generated extractor
produces tokens.json + components.json at .moai/design/; DTCG validation runs before
expert-frontend consumption.
Part 3 — Design-Brief Context Loading
Auto-loads human-authored briefs during Phase B2.5 of /moai design when
design_docs.auto_load_on_design_command: true. Can also be invoked standalone with
explicit dir argument.
Configuration resolution: Read design_docs from .moai/config/sections/design.yaml.
If absent, use compiled-in defaults:
dir: .moai/designauto_load_on_design_command: truetoken_budget: 20000priority: [spec, system, research]
Log design_docs not configured — using defaults when key absent.
Bare-token → filename mapping:
spec → <dir>/spec.mdsystem → <dir>/system.mdresearch → <dir>/research.md
Steps:
- Directory check: Glob
<dir>/. Missing → emit header only and log
design docs not initialized — run /moai init or SPEC-DESIGN-DOCS-001 to create.
- Auto-load gate: From Phase B2.5, check
auto_load_on_design_command. False → skip.
- Parallel Read: Issue all candidate file Reads in a single batched parallel tool-call set.
- Filter
_TBD_ files: A file with only scaffold content (lines blank, _TBD_,
headings without bodies, or <!--/> comments) is skipped. Log
skip: <token> — _TBD_ only.
- Token budget enforcement: Include in priority order until cumulative
estimated_tokens would exceed budget. Overflow → drop lowest priority (research
first, then system; never spec). Single file too large → truncate at nearest
##/### boundary and append > truncated: <filename> at char_offset=N.
- Build output block — first non-empty line MUST be exactly
## Design Context (from .moai/design/). For each file, prepend > source: .moai/design/<filename> then
content (or truncated).
- Warnings section (when unreadable files encountered): append
> warnings: [<token1> unreadable: <reason>, ...] after the content.
All-_TBD_ case: header-only output + log
design docs present but all are _TBD_ — no content loaded.
Error Codes (Path A)
DESIGN_IMPORT_NOT_FOUND — bundle path missing → guide to Path BDESIGN_IMPORT_UNSUPPORTED_FORMAT — non-ZIP/HTML → guide to Path BDESIGN_IMPORT_UNSUPPORTED_VERSION — version not in whitelist. Required stderr (all 3
lines mandatory): Detected bundle version: v<N>; Supported versions: <list from design.yaml>; Switch to path B: run /moai design and select 'Code-based brand design'.DESIGN_IMPORT_SECURITY_REJECT — executables/symlinks/traversal/absolute paths
detected. List offending entries. Do NOT create .moai/design/ directory.DESIGN_IMPORT_MISSING_MANIFEST — ZIP without manifest.json → guide to Path B
Fallback guidance appended to every error: instruct user to run /moai design and
select "Code-based brand design (design-brand-system)" after ensuring
.moai/project/brand/visual-identity.md is complete.
Partial Bundle Recovery
Valid bundle missing optional components → extract what's available, log warnings to
.moai/design/import-warnings.json, proceed with partial output. Never silent failure.
Part 4 — 번들 없이 브랜드에서 바로 시작하는 경로
핸드오프 번들도 Figma도 없이 브랜드 자산에서 곧장 디자인을 만드는 요청이면 아래 순서로 진행합니다.
design.yaml(.moai/config/sections/design.yaml) 값을 따르고 임계값을 코드에 박지 않습니다.
design-system-prep + design-brand-system — 브랜드 자산 → DESIGN.md + DTCG 토큰 (WCAG 2.1 AA)design-copywriting — 브랜드 톤에 맞춘 카피 (생성 시점부터 AI 슬롭 회피)design-iteration-loop — Builder-Evaluator 품질 루프 (최대 5회, pass_threshold 0.75, 4차원 채점)
UX 프롬프트 패턴이 필요하면 design-prompt-builder를 함께 씁니다.
Works Well With
design-brand-system (Path B fallback / context consumer), design-handoff
(produces claude-design-handoff/ for Path A), design-iteration-loop (uses tokens +
context as baseline), moai-meta-harness (generates figma extractor for Path B1),
expert-frontend (primary consumer), .claude/rules/moai/design/constitution.md (brand
priority + reserved paths).
Common Rationalizations
- "Skip security scan for trusted bundles" — "trusted" is unverifiable. Scan every bundle, no exceptions.
- "Drop spec.md when budget tight" — spec.md is priority 1, never dropped. Drop research → system → escalate.
- "TBD files contain useful context" —
_TBD_ means scaffold-only. Skip to avoid polluting the prompt.
- "Path B1 needs a hardcoded Figma extractor" — Path B1 uses meta-harness generation. Static Figma skill prohibited.
- "Brand context is one input among many" — brand context is the constitutional parent; conflicts resolve in favor of brand.
Red Flags
- Bundle parse proceeds without security scan
- ZIP entries containing
../, symlinks, or executables accepted
manifest.json version validation bypassed- Design context block missing canonical header
## Design Context (from .moai/design/)
spec.md dropped when budget exceeded (priority violation)- Figma API token value stored inside skill file (only env var name allowed)
- Output written outside
.moai/design/ reserved path set
Verification
REQ coverage: (internal provenance omitted)..003, (Path A); REQ-1..16 (context).
