modu-ai
diff --git a/‎.claude/agents/moai/expert-frontend.md‎
Lines changed: 62 additions & 0 deletions b/‎.claude/agents/moai/expert-frontend.md‎
Lines changed: 62 additions & 0 deletions
diff --git a/‎.claude/rules/moai/design/constitution.md‎
Lines changed: 4 additions & 1 deletion b/‎.claude/rules/moai/design/constitution.md‎
Lines changed: 4 additions & 1 deletion
diff --git a/‎.claude/skills/moai-design-system/SKILL.md‎
Lines changed: 75 additions & 0 deletions b/‎.claude/skills/moai-design-system/SKILL.md‎
Lines changed: 75 additions & 0 deletions
diff --git a/‎.claude/skills/moai-workflow-design-import/SKILL.md‎
Lines changed: 110 additions & 14 deletions b/‎.claude/skills/moai-workflow-design-import/SKILL.md‎
Lines changed: 110 additions & 14 deletions
diff --git a/‎.claude/skills/moai/SKILL.md‎
Lines changed: 1 addition & 1 deletion b/‎.claude/skills/moai/SKILL.md‎
Lines changed: 1 addition & 1 deletion
@@ -118,6 +118,68 @@ Create `.moai/docs/frontend-architecture-{SPEC-ID}.md` with component hierarchy,
 - expert-devops: Deployment platform (Vercel, Netlify), env vars, build strategy
 - manager-ddd: Component test structure, mock strategy (MSW), coverage
 
+## DTCG Validator Integration
+
+SPEC: SPEC-V3R3-DESIGN-PIPELINE-001 REQ-DPL-010 / AC-DPL-06
+Validator package: `internal/design/dtcg/` (SPEC.md 참조)
+
+### 코드 생성 전 필수 검증 게이트
+
+[HARD] **컴포넌트 생성, 스타일 파일 출력, JSX/TSX 렌더 등 모든 프론트엔드 코드 생성 단계 이전에**
+반드시 DTCG 검증기를 실행해야 한다.
+
+```go
+import "github.com/modu-ai/moai-adk/internal/design/dtcg"
+
+// tokens: tokens.json을 파싱한 map[string]any
+report, err := dtcg.Validate(tokens)
+if err != nil {
+    // 검증 실행 자체 실패 (nil 입력 등) — 오케스트레이터에 반환
+    return fmt.Errorf("DTCG 검증기 실행 실패: %w", err)
+}
+```
+
+### 실패 처리 (report.Valid == false)
+
+[HARD] `report.Valid == false`이면 **코드 생성을 중단**하고, 아래 구조화된 오류를 오케스트레이터에 반환한다.
+`report.Errors` 슬라이스 전체를 포함해야 오케스트레이터가 사용자에게 surfacing할 수 있다.
+
+```go
+if !report.Valid {
+    // 코드 생성 절대 금지 — 구조화된 오류 반환
+    return &DTCGValidationFailure{
+        TokenCount:  report.TokenCount,
+        ErrorCount:  len(report.Errors),
+        Errors:      report.Errors,   // []*dtcg.ValidationError — 경로, 카테고리, 규칙 포함
+        Warnings:    report.Warnings, // []*dtcg.ValidationWarning — 브랜드 충돌 등
+    }
+}
+```
+
+`ValidationError`에는 다음 필드가 포함된다:
+- `TokenPath`: 오류 토큰 경로 (예: `"colors.primary"`)
+- `Category`: DTCG $type (예: `"color"`, `"dimension"`)
+- `Rule`: 위반 규칙 설명
+- `Value`: 오류 유발 값
+
+### 브랜드 컨텍스트 우선순위 (design constitution §3.1)
+
+토큰이 DTCG 검증을 통과하더라도, `.moai/project/brand/visual-identity.md`에 정의된
+브랜드 색상과 충돌하는 경우 `report.Warnings`에 `category: "brand-conflict"` 경고가 포함된다.
+[HARD] 브랜드 제약이 항상 우선한다 — 토큰 값이 아닌 브랜드 값을 사용해야 한다.
+
+### 경고 처리 (Warnings만 있는 경우)
+
+`report.Valid == true`이지만 `report.Warnings`가 있는 경우, 오케스트레이터에 경고를 surfacing하고
+사용자 결정을 기다린다. 경고만으로는 코드 생성을 차단하지 않는다.
+
+### DTCG 지원 카테고리 (2025.10)
+
+14개 카테고리: color, dimension, fontFamily, fontWeight, font, typography,
+duration, cubicBezier, number, strokeStyle, border, transition, shadow, gradient.
+
+알 수 없는 카테고리는 오류로 처리된다 — 사용자가 DTCG 2025.10으로 토큰을 업그레이드해야 한다.
+
 ## @MX Tag Obligations
 
 When creating or modifying source code, add @MX tags for the following patterns:
 
@@ -2,6 +2,7 @@
 
 ## HISTORY
 
+- 2026-04-26 (SPEC-V3R3-DESIGN-PIPELINE-001): §4 Phase Contracts table extended with Path B1 (figma-extractor) and Path B2 (pencil-mcp) rows. Version 3.3.1 → 3.4.0.
 - 2026-04-26 (SPEC-V3R3-DESIGN-FOLDER-FIX-001): §3.2 footnote 추가 — Reserved name violation은 `moai update` (update path)에서 warning + skip, `moai init` (scaffold path)에서 hard error. v3.3.0 → 3.3.1.
 - 2026-04-20 (SPEC-DESIGN-CONST-AMEND-001): Section 3 expanded to tripartite structure (3.1/3.2/3.3). Version 3.2.0 → 3.3.0 (v3.3.0). FROZEN zone extended to cover each subsection individually.
 - 2026-04-20: Relocated from `.claude/rules/agency/constitution.md` (v3.2.0) to `.claude/rules/moai/design/constitution.md` as part of SPEC-AGENCY-ABSORB-001 M1. Original path: `.claude/rules/agency/constitution.md`. No content changes. FROZEN zone and EVOLVABLE zone definitions are preserved verbatim.
@@ -114,6 +115,8 @@ Each phase produces typed artifacts consumed by downstream phases:
 | moai-workflow-design-import | Handoff bundle path | .moai/design/ reserved artifacts (see Section 3.2) | Path A |
 | expert-frontend | Copy JSON + design tokens | Working code (pages, components, styles) | Always |
 | evaluator-active | Built code + BRIEF | Score card + feedback | Always |
+| figma-extractor (Path B1) | BRIEF + Figma file ID + page selectors | tokens.json + components.json | Path B1 |
+| pencil-mcp (Path B2) | BRIEF + .pen files | tokens.json + components.json | Path B2 |
 
 ---
 
@@ -399,7 +402,7 @@ If a graduated learning causes regression:
 
 ---
 
-Version: 3.3.1
+Version: 3.4.0
 Classification: FROZEN_AMENDMENT
 Original Source: agency/constitution.md v3.2.0
 Last Updated: 2026-04-26
 
@@ -133,6 +133,78 @@ Pencil designs export to React + Tailwind via `moai-workflow-design-import`. The
 
 For Figma MCP integration (fetching Figma design context), see moai-design-tools full skill.
 
+---
+
+## DTCG 2025.10 Token Specification (SPEC-V3R3-DESIGN-PIPELINE-001)
+
+### Specification Reference
+
+The W3C Design Tokens Community Group (DTCG) 2025.10 snapshot defines the canonical token
+format for MoAI design pipelines. A Go validator (`internal/design/dtcg/`) enforces schema
+compliance before `expert-frontend` consumes any `tokens.json` produced by Path A, B1, or B2.
+
+> **Forward reference**: `internal/design/dtcg/SPEC.md` will be created in Phase 3 of
+> SPEC-V3R3-DESIGN-PIPELINE-001. Until then, the spec snapshot date is 2025-10 and the
+> supported categories are as listed below.
+
+### Supported Token Categories (2025.10)
+
+All 14 categories below MUST be validated by `internal/design/dtcg.Validate` before code
+generation:
+
+| Category | Description | Example value format |
+|----------|-------------|----------------------|
+| `color` | Color values | `"#RRGGBB"`, CSS color string |
+| `dimension` | Length values with units | `"16px"`, `"1rem"` |
+| `font` | Font shorthand | CSS font shorthand string |
+| `fontFamily` | Font family stack | `"Inter, sans-serif"` |
+| `fontWeight` | Font weight | `400`, `"bold"` |
+| `duration` | Time values | `"200ms"`, `"0.2s"` |
+| `cubicBezier` | Easing curve | `[0.4, 0, 0.2, 1]` (4-number array) |
+| `number` | Unitless number | `1.5`, `16` |
+| `strokeStyle` | Stroke style keyword | `"solid"`, `"dashed"` |
+| `border` | Border composite | `{ color, width, style }` |
+| `transition` | Transition composite | `{ duration, timingFunction, delay }` |
+| `shadow` | Shadow composite | `{ color, offsetX, offsetY, blur, spread }` |
+| `gradient` | Gradient composite | `{ type, stops }` |
+| `typography` | Typography composite | `{ fontFamily, fontSize, fontWeight, lineHeight }` |
+
+### Validator Invocation Guidance
+
+`expert-frontend` MUST call `internal/design/dtcg.Validate(tokensJSON)` before generating
+any frontend code from a `tokens.json` file. This applies to all three paths (A, B1, B2).
+
+Validation failure produces a structured error report:
+
+```
+dtcg.ValidationError{
+  TokenPath: "colors.primary",    // DTCG token path
+  Category:  "color",             // Expected category
+  Rule:      "invalid_format",    // Violated rule
+  Got:       "PRIMARY_BLUE",      // Actual value found
+}
+```
+
+On validation failure: surface the structured error report to the orchestrator and block
+code generation. Do not attempt to auto-correct token values.
+
+### Brand Context Priority
+
+Design constitution §3.1 (FROZEN): brand context (`.moai/project/brand/visual-identity.md`)
+is the constitutional parent. Token values from any path that conflict with brand constraints
+MUST be flagged as warnings and presented for user resolution — not silently overridden.
+
+The DTCG validator gate runs AFTER brand context is loaded and BEFORE frontend code
+generation. The validation order is:
+
+1. Load brand context (`.moai/project/brand/`)
+2. Run DTCG validator on `tokens.json`
+3. Cross-check DTCG-valid tokens against brand constraints
+4. Surface conflicts as warnings
+5. Proceed to `expert-frontend` code generation
+
+---
+
 <!-- moai:evolvable-start id="verification" -->
 ## Verification
 
@@ -142,5 +214,8 @@ For Figma MCP integration (fetching Figma design context), see moai-design-tools
 - [ ] Color contrast ratios verified (4.5:1 normal text, 3:1 UI components)
 - [ ] Web copy free of AI-generic filler phrases
 - [ ] Pencil MCP tools used via batch operations (not individual calls) for performance
+- [ ] DTCG 2025.10 validator invoked before expert-frontend code generation (REQ-DPL-010)
+- [ ] Brand context loaded before DTCG validation (design constitution §3.1)
+- [ ] Validation errors surface structured report (not silent auto-correction)
 
 <!-- moai:evolvable-end -->
@@ -1,21 +1,21 @@
 ---
 name: moai-workflow-design-import
 description: >
-  Parses Claude Design handoff bundle (ZIP or HTML) and extracts design tokens,
-  component manifests, and static assets for expert-frontend delegation. Validates
-  bundle version against the supported_bundle_versions whitelist and returns
-  structured error codes on failure with path B fallback guidance.
+  Handles /moai design 3-path routing: Path A (Claude Design handoff bundle), Path B1
+  (Figma extractor via meta-harness), Path B2 (Pencil MCP via meta-harness). Validates
+  bundle version against supported_bundle_versions whitelist and returns structured error
+  codes on failure. Depends on SPEC-V3R3-HARNESS-001 for Path B1/B2.
 license: Apache-2.0
 compatibility: Designed for Claude Code
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash
 user-invocable: false
 metadata:
-  version: "1.0.0"
+  version: "1.1.0"
   category: "workflow"
   status: "active"
-  updated: "2026-04-20"
-  tags: "design import, handoff bundle, claude design, design tokens, components"
-  related-skills: "moai-domain-brand-design, moai-workflow-gan-loop"
+  updated: "2026-04-27"
+  tags: "design import, handoff bundle, claude design, design tokens, components, figma, pencil, meta-harness"
+  related-skills: "moai-domain-brand-design, moai-workflow-gan-loop, moai-meta-harness"
 
 # MoAI Extension: Progressive Disclosure
 progressive_disclosure:
@@ -25,20 +25,44 @@ progressive_disclosure:
 
 # MoAI Extension: Triggers
 triggers:
-  keywords: ["design import", "handoff bundle", "claude design", "bundle path", "design zip", "import bundle"]
+  keywords: ["design import", "handoff bundle", "claude design", "bundle path", "design zip", "import bundle", "figma extractor", "pencil mcp", "path b1", "path b2"]
   agents: ["expert-frontend"]
   phases: ["run"]
 ---
 
 # moai-workflow-design-import
 
-Handles Claude Design handoff bundle ingestion for the `/moai design` path A workflow. Validates bundle format, extracts design artifacts, and prepares structured output for `expert-frontend` delegation.
+Handles `/moai design` 3-path routing for design artifact ingestion. Each path produces
+DTCG-validated design tokens at `.moai/design/tokens.json` for `expert-frontend` consumption.
 
-This skill is invoked only when the user selects path A (Claude Design) in `/moai design` and provides a local bundle file path.
+**Path A** (Claude Design): Existing handoff bundle import — preserved verbatim.
+**Path B1** (Figma): Meta-harness generates a project-scoped figma-extractor skill.
+**Path B2** (Pencil): Meta-harness generates a project-scoped pencil-mcp skill.
+
+Reserved output paths (design constitution §3.2): `tokens.json`, `components.json`,
+`assets/`, `import-warnings.json`, `brief/BRIEF-*.md` — all written to `.moai/design/`.
 
 ---
 
-## Quick Reference
+## Path Selection
+
+When `/moai design` requires path selection, present via AskUserQuestion:
+1. **Path A — Claude Design** (권장): Handoff bundle (ZIP or HTML) from Claude Design.
+2. **Path B1 — Figma**: Figma file access; meta-harness generates `my-harness-figma-extractor`.
+3. **Path B2 — Pencil**: `.pen` files; meta-harness generates `my-harness-pencil-mcp`.
+
+Selection is persisted to `.moai/design/path-selection.json` for audit.
+
+Brand context (`.moai/project/brand/`) is the constitutional parent across all paths — no
+path may override brand constraints (design constitution §3.1, §3.3).
+
+---
+
+---
+
+## Path A — Claude Design Handoff Bundle
+
+*This section is preserved verbatim from v1.0.0. Path A behavior is unchanged.*
 
 ### Supported Bundle Formats (Phase 1)
 
@@ -231,13 +255,85 @@ When extracting assets:
 
 ---
 
+---
+
+## Path B1 — Figma Extractor (via Meta-Harness)
+
+**Prerequisite**: SPEC-V3R3-HARNESS-001 meta-harness skill (`moai-meta-harness`) must be
+available. Path B1 does NOT ship a static Figma skill — it is generated dynamically.
+
+### Invocation
+
+When the user selects Path B1, invoke `moai-meta-harness` to generate:
+
+```
+.claude/skills/my-harness-figma-extractor/SKILL.md
+```
+
+The generated skill is project-scoped and user-owned (`my-harness-*` prefix). It will never
+be overwritten by `moai update`.
+
+### Generation Contract
+
+`moai-meta-harness` Phase 5 (Customization) produces `my-harness-figma-extractor` with:
+
+- **Figma file ID**: project-specific file identifier (collected during Socratic interview)
+- **Page selectors**: which Figma pages map to which token categories
+- **Credential reference**: environment variable name holding the Figma API token
+  (e.g., `FIGMA_TOKEN`). The token value is NEVER stored in the skill file.
+
+The generated extractor skill produces `tokens.json` + `components.json` at `.moai/design/`
+matching the reserved file paths in design constitution §3.2.
+
+### Output
+
+After `my-harness-figma-extractor` runs, this skill receives the produced artifacts at
+`.moai/design/` and proceeds to DTCG validation before `expert-frontend` consumption.
+
+---
+
+## Path B2 — Pencil MCP (via Meta-Harness)
+
+**Prerequisite**: SPEC-V3R3-HARNESS-001 meta-harness skill (`moai-meta-harness`) must be
+available. Path B2 is implemented via dynamically generated `my-harness-pencil-mcp` skill
+(SPEC-V3R3-HARNESS-001 BC-V3R3-007 16-skill removal — legacy static skill archived).
+
+### Invocation
+
+When the user selects Path B2, invoke `moai-meta-harness` to generate:
+
+```
+.claude/skills/my-harness-pencil-mcp/SKILL.md
+```
+
+### Generation Contract
+
+`moai-meta-harness` Phase 5 produces `my-harness-pencil-mcp` with:
+
+- **`.pen` file locations**: glob patterns for the project's Pencil design files
+- **Pencil MCP server endpoint**: local server URL (default: `http://localhost:11111`)
+- **Export configuration**: which Pencil frames/pages map to token categories
+
+The generated skill uses `mcp__pencil__*` tools (already listed in `moai-design-system`
+allowed-tools) to extract design data and write to `.moai/design/`.
+
+### Output
+
+After `my-harness-pencil-mcp` runs, this skill receives artifacts at `.moai/design/` and
+proceeds to DTCG validation before `expert-frontend` consumption.
+
+---
+
 ## Works Well With
 
 - `moai-domain-brand-design`: Fallback path when bundle import fails
 - `moai-workflow-gan-loop`: Receives extracted tokens for quality evaluation
 - `expert-frontend`: Primary consumer of extracted design artifacts
+- `moai-meta-harness`: Generates `my-harness-figma-extractor` and `my-harness-pencil-mcp`
+  for Path B1/B2 (SPEC-V3R3-HARNESS-001)
+- `moai-design-system`: DTCG token validation guidance and design system context
 
 ---
 
-REQ coverage: REQ-SKILL-007, REQ-SKILL-008, REQ-SKILL-009, REQ-SKILL-010, REQ-SKILL-015
-Version: 1.0.0
+REQ coverage: REQ-DPL-001, REQ-DPL-002, REQ-DPL-003, REQ-SKILL-007, REQ-SKILL-008, REQ-SKILL-009, REQ-SKILL-010, REQ-SKILL-015
+Version: 1.1.0 (SPEC-V3R3-DESIGN-PIPELINE-001 Wave C.1)
@@ -199,7 +199,7 @@ For detailed orchestration: Read ${CLAUDE_SKILL_DIR}/workflows/e2e.md
 
 Purpose: Produce web/brand design artifacts via Claude Design import (path A) or code-based skill pipeline (path B). Integrates brand context from `.moai/project/brand/` and design briefs from `.moai/design/`.
 Agents: manager-spec (BRIEF), expert-frontend (implementation), evaluator-active (GAN loop scoring)
-Skills: moai-domain-copywriting, moai-domain-brand-design, moai-workflow-design-import, moai-workflow-gan-loop, moai-workflow-design-context, moai-workflow-pencil-integration
+Skills: moai-domain-copywriting, moai-domain-brand-design, moai-workflow-design-import, moai-workflow-gan-loop, moai-workflow-design-context, my-harness-pencil-mcp (Path B2, generated by meta-harness)
 Flags: --path A|B, --harness thorough|standard, --brief BRIEF-XXX
 For detailed orchestration: Read ${CLAUDE_SKILL_DIR}/workflows/design.md