Unified design workflow skill — handles Path A (Claude Design handoff bundle import, via Figma extractor when needed) and design-brief context loading from .moai/design/ (research, system, spec). Validates DTCG tokens, enforces brand-context constitutional priority. Use for /moai design workflow — NOT for general design system documentation.
Unified design workflow skill — handles Path A (Claude Design handoff bundle import, via Figma extractor when needed) and design-brief context loading from .moai/design/ (research, system, spec). Validates DTCG tokens, enforces brand-context constitutional priority. Use for /moai design workflow — NOT for general design system documentation.
when_to_use
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.
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 moai-domain-brand-design 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)
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.
Unsupported (Phase 2 roadmap): DOCX, PPTX, PDF, Canva link — return
DESIGN_IMPORT_UNSUPPORTED_FORMAT and guide to Path B.
Version whitelist: Check manifest.jsonformat_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
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/design
auto_load_on_design_command: true
token_budget: 20000
priority: [spec, system, research]
Log design_docs not configured — using defaults when key absent.
Bare-token → filename mapping:
spec → <dir>/spec.md
system → <dir>/system.md
research → <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 B
DESIGN_IMPORT_UNSUPPORTED_FORMAT — non-ZIP/HTML → guide to Path B
DESIGN_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 (moai-domain-brand-design)" 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.
Works Well With
moai-domain-brand-design (Path B fallback / context consumer), moai-domain-design-handoff
(produces claude-design-handoff/ for Path A), moai-workflow-gan-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.
