moai-workflow-design-import

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_bund

SKILL.md

GitHub

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.json
  • components/*.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):
    1. Detected version: "Detected bundle version: v<N>"
    2. Supported versions: "Supported versions: <list from design.yaml>"
    3. 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 fails
  • moai-workflow-gan-loop: Receives extracted tokens for quality evaluation
  • expert-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