| 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.
|
| 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","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"} |
| progressive_disclosure | {"enabled":true,"level1_tokens":100,"level2_tokens":5000} |
| triggers | {"keywords":["design import","handoff bundle","claude design","bundle path","design zip","import bundle"],"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.
This skill is invoked only when the user selects path A (Claude Design) in /moai design and provides a local bundle file path.
Quick Reference
Supported Bundle Formats (Phase 1)
Primary supported formats:
ZIP: Claude Design export containing manifest.json, tokens.json, components/, and assets/HTML: Single-file HTML export from Claude Design
Unsupported formats (Phase 2 roadmap):
- DOCX, PPTX, PDF, Canva link — return
DESIGN_IMPORT_UNSUPPORTED_FORMAT and guide to path B.
Version Whitelist
Before parsing, check the bundle's declared format version against supported_bundle_versions in .moai/config/sections/design.yaml.
Current default whitelist: ["1.0"]
If the detected bundle version is not in the whitelist, return DESIGN_IMPORT_UNSUPPORTED_VERSION with the three required stderr fields (see Error Codes).
Implementation Guide
Bundle Parsing Flow
Step 1: Receive the bundle file path from the orchestrator.
Step 2: Validate file existence. If the path does not exist or is not readable, return DESIGN_IMPORT_NOT_FOUND immediately with manual path guidance.
Step 3: Validate file format. Inspect the file extension and magic bytes:
.zip: ZIP magic bytes PK\x03\x04.html: HTML DOCTYPE or <html tag at start
If neither matches, return DESIGN_IMPORT_UNSUPPORTED_FORMAT.
Step 4: Security scan (before any extraction):
- List all ZIP entries (for ZIP bundles) without extracting
- Reject if any entry contains: executable extensions (
.sh, .exe, .bat, .cmd, .ps1, .py, .rb, .pl), symbolic links, path traversal sequences (../, ..\), or absolute paths
- If any security issue detected, return
DESIGN_IMPORT_SECURITY_REJECT without extracting any content
Step 5: Read manifest.json from the bundle root:
- Extract
format_version field
- Compare against
supported_bundle_versions from design.yaml
- If version not in whitelist, return
DESIGN_IMPORT_UNSUPPORTED_VERSION
Step 6: Extract and parse:
tokens.json → .moai/design/tokens.jsoncomponents/*.html or components/*.json → .moai/design/components.json (component manifest)assets/** → .moai/design/assets/ (images, fonts, icons)copy.json (if present) → .moai/design/copy.json
Step 7: Validate extracted tokens structure:
- Required keys:
colors, typography, spacing
- If any required key is missing, add a warning to the output but do not fail
Step 8: Report extraction results to the orchestrator.
ZIP Bundle Expected Structure
bundle.zip
manifest.json # Required: format_version, claude_design_version, created_at
tokens.json # Required: colors, typography, spacing, radii, shadows
components/ # Optional: component HTML or JSON specs
hero.html
navigation.html
card.html
assets/ # Optional: images, fonts, icons
images/
fonts/
icons/
copy.json # Optional: structured copy output
HTML Bundle Expected Structure
Single-file HTML export. Extract:
- Inline
<style> CSS custom properties as color and spacing tokens
- Inline
<script> JSON blocks tagged with data-design-tokens
<link> tags referencing external assets (list only, do not fetch)
Output Artifacts
All output is written to .moai/design/:
.moai/design/tokens.json — Normalized design tokens:
{
"colors": { "primary": "...", "secondary": "...", ... },
"typography": { "fontFamily": {...}, "fontSize": {...}, ... },
"spacing": { "base": 4, "scale": {...} },
"radii": { "sm": "4px", ... },
"shadows": { "sm": "...", ... },
"source": "claude-design-bundle",
"bundle_version": "1.0"
}
.moai/design/components.json — Component manifest:
{
"components": [
{ "name": "Hero", "file": "hero.html", "variants": [...] },
...
]
}
.moai/design/assets/ — Static assets directory (images, fonts, icons extracted verbatim).
Error Codes
All errors are returned as structured responses with an error code and human-readable message.
DESIGN_IMPORT_NOT_FOUND
- Trigger: Bundle file path does not exist or is not readable.
- Action: Return error immediately. Output manual guidance: "Provide the correct local file path, or switch to path B (moai-domain-brand-design)."
DESIGN_IMPORT_UNSUPPORTED_FORMAT
- Trigger: File is not ZIP, HTML, or magic bytes do not match.
- Action: Return error with supported format list. Guide to path B.
DESIGN_IMPORT_UNSUPPORTED_VERSION
- Trigger: Bundle
manifest.json format_version is not in supported_bundle_versions whitelist.
- Required stderr output (all three fields mandatory):
- Detected version:
"Detected bundle version: v<N>"
- Supported versions:
"Supported versions: <list from design.yaml>"
- Fallback guidance:
"Switch to path B: run /moai design and select 'Code-based brand design'"
- Do not create any partial output files.
DESIGN_IMPORT_SECURITY_REJECT
- Trigger: Bundle contains executable files, symbolic links, path traversal sequences, or absolute paths.
- Action: Reject without extracting any content. List the offending entries in the error message.
- Do not create
.moai/design/ directory.
DESIGN_IMPORT_MISSING_MANIFEST
- Trigger: ZIP bundle does not contain
manifest.json.
- Action: Return error. Cannot determine bundle version without manifest. Guide to path B.
Fallback Guidance
When any error code is returned, always append this guidance:
To continue with code-based design (path B):
1. Run /moai design
2. Select "Code-based brand design (moai-domain-brand-design)"
3. Ensure .moai/project/brand/visual-identity.md is complete
Advanced Patterns
Partial Bundle Recovery
If the bundle is valid but missing optional components (e.g., no components/ directory):
- Extract what is available
- Add warnings to the output manifest
- Do not fail — proceed with partial output
- Note missing sections in
.moai/design/import-warnings.json
Token Normalization
Input bundles may use different naming conventions. Normalize to the MoAI token schema:
| Bundle field | Normalized token |
|---|
primary_color | colors.primary |
brand_color | colors.primary |
heading_font | typography.fontFamily.heading |
base_spacing | spacing.base |
Normalization rules are applied silently. Log all renamed fields in the import warnings.
Asset Safety
When extracting assets:
- Validate image MIME types (accept: png, jpg, gif, webp, svg, ico)
- Validate font formats (accept: woff2, woff, ttf, otf)
- Reject archives within archives (no nested ZIPs)
- Strip metadata from SVG files that contains script tags
Works Well With
moai-domain-brand-design: Fallback path when bundle import failsmoai-workflow-gan-loop: Receives extracted tokens for quality evaluationexpert-frontend: Primary consumer of extracted design artifacts
REQ coverage: REQ-SKILL-007, REQ-SKILL-008, REQ-SKILL-009, REQ-SKILL-010, REQ-SKILL-015
Version: 1.0.0
