moai-workflow-design-import

星标11

分支2

更新时间2026年7月7日 09:34

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.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

GetKlai

GetKlai/klai

打开 GitHub 仓库查看创作者相关仓库

下载

相关职业SOC

基于 SOC 职业分类

网页与数字界面设计师计算机与数学类职业·SOC 15-1255

SKILL.md

readonly

同仓库更多 Skills

同仓库

moai-design-craft

GetKlai/klai

Intent-First design craft specialist covering design direction, domain vocabulary, design memory, and post-build critique. Use when establishing design intent or auditing code against design principles.

2026-07-0711

moai-design-tools

GetKlai/klai

Design tool integration specialist covering Figma MCP, Pencil renderer, and Pencil-to-code export. Use when fetching design context from Figma, rendering Pencil designs, or exporting to React/Tailwind code.

2026-07-0711

moai-docs-generation

GetKlai/klai

Documentation generation patterns for technical specs, API docs, user guides, and knowledge bases using real tools like Sphinx, MkDocs, TypeDoc, and Nextra. Use when creating docs from code, building doc sites, or automating documentation workflows.

2026-07-0711

moai-domain-backend

GetKlai/klai

Backend development specialist covering API design, database integration, microservices architecture, and modern backend patterns. Use when designing APIs, implementing server logic, authentication, or authorization.

2026-07-0711

moai-domain-brand-design

GetKlai/klai

Brand-aligned visual design system specialist for web projects. Enforces hero-first layout chaining, WCAG 2.1 AA accessibility, Lighthouse >= 80, and design token extraction from brand identity files. Covers color palettes, typography, spacing, and component specifications.

2026-07-0711

moai-domain-copywriting

GetKlai/klai

Brand-aligned copywriting specialist for marketing and product text. Enforces brand voice, anti-AI-slop rules, concrete numbers, and JSON section structure for downstream agent consumption. Covers hero, features, social_proof, cta, and footer sections with A/B variant output.

2026-07-0711

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.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