moai-workflow-design

# Design Workflow (`moai-workflow-design`)

Unified `/moai design` workflow skill. Handles two complementary responsibilities:

1. **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.
2. **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):
1. **Path A — Claude Design** (권장) — handoff bundle (ZIP or HTML)
2. **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**:
1. Receive bundle file path from orchestrator
2. Validate file existence → `DESIGN_IMPORT_NOT_FOUND` if missing
3. Validate format (extension + magic bytes: `PK\x03\x04` for ZIP, DOCTYPE/`<html` for HTML)
4. **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`
5. Read `manifest.json`, validate version
6. Extract: `tokens.json` → `.moai/design/tokens.json`; `components/` → `components.json`;
   `assets/**` → `.moai/design/assets/`; `copy.json` → `.moai/design/copy.json`
7. Validate token structure (required keys: `colors`, `typography`, `spacing`); missing
   keys → warning, not failure
8. 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**: SPEC-V3R3-HARNESS-001 `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/moai-harness-figma-extractor/SKILL.md`
(project-scoped and user-owned via `moai-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**:
1. **Directory check**: Glob `<dir>/`. Missing → emit header only and log
   `design docs not initialized — run /moai init or SPEC-DESIGN-DOCS-001 to create`.
2. **Auto-load gate**: From Phase B2.5, check `auto_load_on_design_command`. False → skip.
3. **Parallel Read**: Issue all candidate file Reads in a single batched parallel tool-call set.
4. **Filter `_TBD_` files**: A file with only scaffold content (lines blank, `_TBD_`,
   headings without bodies, or `<!--`/`>` comments) is skipped. Log
   `skip: <token> — _TBD_ only`.
5. **Token budget enforcement**: Include in priority order until cumulative
   `estimat