| name | moai-workflow-design |
| description | 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.
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 | 0.2.0 |
Design Workflow (moai-workflow-design)
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)
- 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 (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.
- "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).
