Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Design Workflow (design-workflow) · modu-ai | DecimalAI

modu-ai/design-workflow

SkillScore55Maintained

통합 디자인 워크플로 스킬 — Path A(Claude Design 핸드오프 번들 가져오기, 필요시 Figma 추출기 경유)와 .moai/design/(research·system·spec)에서 design-brief 컨텍스트 로딩을 처리합니다. DTCG 토큰을 검증하고 브랜드 컨텍스트 헌법 우선순위를 보장합니다. /moai design 워크플로에 사용 — 일반 디자인 시스템 문서용이 아닙니다.

design-mediaby modu-ai

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Design & UX Review pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/modu-ai-design-workflow/SKILL.md

decimalai skills pull modu-ai-design-workflow --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/modu-ai-design-workflow/SKILL.md https://app.decimal.ai/s/modu-ai-design-workflow/SKILL.md

Raw file: /s/modu-ai-design-workflow/SKILL.md ↗ · machine-readable summary at /s/modu-ai-design-workflow.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 17d ago

—+137% tokens0% turns55% of whole cases pass with skill (12/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-06	✗→✓	▲ Improved	64%	0%
case-11	✗→✓	▲ Improved	182%	0%
case-12	✗→✓	▲ Improved	161%	0%
case-13	✗→✓	▲ Improved	830%	0%
case-17	✗→✓	▲ Improved	122%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/10/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

modu-ai / cowork-plugins

plugins/moai-designer/skills/design-workflow/SKILL.md

View on GitHub ↗

License Apache-2.0Imported 8/10/2026Version v1

Skill contents

SKILL.md

> ⚠️ 개발 런타임 전용 — 이 스킬은 MoAI-ADK(Claude Code) 환경을 전제한다. Claude Cowork(Desktop)에서는 .moai/config 의존으로 동작하지 않을 수 있다. Desktop 사용자는 cd-* 체인(design-brief → design-prompt-builder → design-slop-check)을 사용한다.

Design Workflow (`design-workflow`)

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

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.

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 design-brand-system 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):

Path A — Claude Design (권장) — handoff bundle (ZIP or HTML)
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:

Receive bundle file path from orchestrator
Validate file existence → DESIGN_IMPORT_NOT_FOUND if missing
Validate format (extension + magic bytes: PK\x03\x04 for ZIP, DOCTYPE/<html for HTML)
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

Read manifest.json, validate version
Extract: tokens.json → .moai/design/tokens.json; components/ → components.json;

assets/** → .moai/design/assets/; copy.json → .moai/design/copy.json

Validate token structure (required keys: colors, typography, spacing); missing

keys → warning, not failure

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: the harness policy 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/harness-figma-extractor/SKILL.md (project-scoped and user-owned via 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:

Directory check: Glob <dir>/. Missing → emit header only and log

design docs not initialized — run /moai init or SPEC-DESIGN-DOCS-001 to create.

Auto-load gate: From Phase B2.5, check auto_load_on_design_command. False → skip.
Parallel Read: Issue all candidate file Reads in a single batched parallel tool-call set.
Filter _TBD_ files: A file with only scaffold content (lines blank, _TBD_,

headings without bodies, or <!--/> comments) is skipped. Log skip: <token> — _TBD_ only.

Token budget enforcement: Include in priority order until cumulative

estimated_tokens would exceed budget. Overflow → drop lowest priority (research first, then system; never spec). Single file too large → truncate at nearest ##/### boundary and append > truncated: <filename> at char_offset=N.

Build output block — first non-empty line MUST be exactly ## Design Context (from

.moai/design/). For each file, prepend > source: .moai/design/<filename> then content (or truncated).

Warnings section (when unreadable files encountered): append

> warnings: [<token1> unreadable: <reason>, ...] after the content.

All-_TBD_ case: header-only output + log design docs present but all are _TBD_ — no content loaded.

Error Codes (Path A)

DESIGN_IMPORT_NOT_FOUND — bundle path missing → guide to Path B
DESIGN_IMPORT_UNSUPPORTED_FORMAT — non-ZIP/HTML → guide to Path B
DESIGN_IMPORT_UNSUPPORTED_VERSION — version not in whitelist. Required stderr (all 3

lines mandatory): Detected bundle version: v<N>; Supported versions: <list from design.yaml>; Switch to path B: run /moai design and select 'Code-based brand design'.

DESIGN_IMPORT_SECURITY_REJECT — executables/symlinks/traversal/absolute paths

detected. List offending entries. Do NOT create .moai/design/ directory.

DESIGN_IMPORT_MISSING_MANIFEST — ZIP without manifest.json → guide to Path B

Fallback guidance appended to every error: instruct user to run /moai design and select "Code-based brand design (design-brand-system)" after ensuring .moai/project/brand/visual-identity.md is complete.

Partial Bundle Recovery

Valid bundle missing optional components → extract what's available, log warnings to .moai/design/import-warnings.json, proceed with partial output. Never silent failure.

Works Well With

design-brand-system (Path B fallback / context consumer), design-handoff (produces claude-design-handoff/ for Path A), design-iteration-loop (uses tokens + context as baseline), moai-meta-harness (generates figma extractor for Path B1), expert-frontend (primary consumer), .claude/rules/moai/design/constitution.md (brand priority + reserved paths).

Common Rationalizations

"Skip security scan for trusted bundles" — "trusted" is unverifiable. Scan every bundle, no exceptions.
"Drop spec.md when budget tight" — spec.md is priority 1, never dropped. Drop research → system → escalate.
"_TBD_ files contain useful context" — _TBD_ means scaffold-only. Skip to avoid polluting the prompt.
"Path B1 needs a hardcoded Figma extractor" — Path B1 uses meta-harness generation. Static Figma skill prohibited.
"Brand context is one input among many" — brand context is the constitutional parent; conflicts resolve in favor of brand.

Red Flags

Bundle parse proceeds without security scan
ZIP entries containing ../, symlinks, or executables accepted
manifest.json version validation bypassed
Design context block missing canonical header ## Design Context (from .moai/design/)
spec.md dropped when budget exceeded (priority violation)
Figma API token value stored inside skill file (only env var name allowed)
Output written outside .moai/design/ reserved path set

Verification

] Path A security scan rejects fixture with .. and symlinks
] Path A produces .moai/design/tokens.json with normalized schema
] Path B1 invocation triggers moai-meta-harness (no static skill)
] Context-load output starts with ## Design Context (from .moai/design/)
] Budget truncation appends > truncated: <filename> at char_offset=N
] All-_TBD_ case emits header + log only
] DTCG validation runs on Path A and Path B1 outputs
] the DTCG frozen-guard CI test references this skill name

REQ coverage: (internal provenance omitted)..003, (Path A); REQ-1..16 (context).

Illustrative Want to see what modu-ai/design-workflow would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

9/3/2026, 23:45 UTC · 22 cases

Measured on 13 comparable cases — below the 22 needed to publish a lift, so this result is shown here but not on the registry card or leaderboard.

Lift

+27%

55% vs 27%

Agent turns

1.0 vs 1.0

Tokens

+137%

4,123.62 vs 1,740.77

fail → pass · 6pass → pass · 6fail → fail · 10

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-10 Our design folder contains `spec.md` requiring 15,000 tokens, `system.md` requiring 10,000 tokens, and `research.md` requiring 8,000 tokens. The configured token ceiling is 20,000 tokens. Load context documentation into prompt memory within budget.	fail→fail	12,137	14,990	+24%	1	1	0%	1,397	3,745	+168%	0	0	—
case-01 I have a Claude Design export file located at `./imports/ui-handoff.zip`. Please process this handoff bundle to extract our design tokens, component specifications, assets, and copy content into our `.moai/design/` directory so the frontend engine can use them. Make sure to run standard bundle validation and security scanning on all entries before unzipping, standardizing the resulting color, spacing, and typography token structure while writing any non-fatal parsing anomalies to an import warning log.	fail→fail	10,834	19,600	+81%	1	1	0%	335	3,619	+980%	0	0	—
case-02 Please gather and assemble our existing human-written design documentation files from the design folder so we can pass them to the frontend generator. Collect any functional specifications, design system guidelines, and user research notes found there, omitting empty template placeholders. Format the final output as a structured markdown block starting with an appropriate context header, keeping the total size within allowable token constraints by trimming lower-priority documents at section boundaries if necessary.	fail→fail	20,830	20,442	-2%	1	1	0%	3,038	3,974	+31%	0	0	—
case-03 We don't have a ZIP bundle for this feature and need to pull tokens directly from our team's Figma file. Please trigger the dynamic Figma extractor setup to help us map our design file's pages to design token categories and set up environment variable credentials. Once configured, extract the colors, typography, and spacing tokens into normalized design token files in `.moai/design/` so our frontend tools can read them.	fail→fail	65,577	15,993	-76%	1	1	0%	3,368	3,495	+4%	0	0	—
case-04 Our team received an external design archive file at `./imports/vendor-spec.zip` containing UI tokens and asset icons. Before extracting files into our design folder, run security checks against all archive entries to detect path traversal attempts like `../` or embedded scripts like `.sh` or `.exe` binaries, and reject the bundle if suspicious files are detected.	fail→fail	11,785	20,463	+74%	1	1	0%	2,245	4,036	+80%	0	0	—
case-05 We have a ZIP archive located at `./imports/v2-design.zip` whose manifest lists format_version as 2.0, whereas our design configuration file only supports version 1.0. Process this file and trigger the proper error handling and redirection message.	fail→fail	14,360	11,322	-21%	1	1	0%	1,827	3,317	+82%	0	0	—
case-06 Our product designer sent us a Canva URL `https://canva.com/design/DAFxxx/edit` and a PDF document `./docs/design.pdf` containing our color palette. Attempt to import tokens directly from these source formats into our system.	fail→pass	18,548	14,466	-22%	1	1	0%	2,423	3,980	+64%	0	0	—
case-07 We received a legacy design token bundle that contains field names `primary_color` set to `#1E293B` and `heading_font` set to `Inter`. Import this bundle into our system token destination, standardizing field names while keeping track of any field remapping.	fail→fail	12,386	11,898	-4%	1	1	0%	1,330	3,456	+160%	0	0	—
case-08 An incoming ZIP file contains SVG icon files with embedded `<script>` tag blocks alongside TTF font files. Process the asset extraction safely according to asset validation guidelines.	pass→pass	17,454	13,598	-22%	1	1	0%	3,198	4,452	+39%	0	0	—
case-09 The ZIP file `./imports/tokens-only.zip` contains `tokens.json` and icons but does not include a `manifest.json` file. Attempt to extract the tokens into our design directory.	fail→fail	9,043	10,628	+18%	1	1	0%	183	3,297	+1702%	0	0	—
case-11 All documentation files in our design folder (`spec.md`, `system.md`, `research.md`) contain only `_TBD_` scaffold placeholders. Perform context loading on these files and format the result.	fail→pass	13,027	10,936	-16%	1	1	0%	1,477	4,166	+182%	0	0	—
case-12 We are setting up dynamic Figma integration for our design tokens. The setup process asks for the Figma personal access token string `figd_987654321`. Configure the skill setup while protecting authentication credentials.	fail→pass	12,702	11,073	-13%	1	1	0%	1,498	3,916	+161%	0	0	—
case-13 Process the Claude Design bundle located at `./imports/nonexistent-bundle.zip` to extract design tokens into `.moai/design/tokens.json`.	fail→pass	8,835	21,258	+141%	1	1	0%	452	4,202	+830%	0	0	—
case-14 Our configuration lists document loading priority as `[spec, system, research]`. Resolve these token identifiers to their concrete file paths under `.moai/design/`.	pass→pass	10,028	6,896	-31%	1	1	0%	980	3,262	+233%	0	0	—
case-15 We have a bundle file `./imports/handoff.html` containing plain binary junk without doctype or HTML structure tags. Validate and parse this HTML handoff bundle.	fail→fail	31,148	16,549	-47%	1	1	0%	5,112	3,274	-36%	0	0	—
case-16 An import ZIP contains valid `manifest.json` and `tokens.json` files, but lacks `copy.json` and asset folders. Extract available items into our design directory.	fail→fail	17,825	35,628	+100%	1	1	0%	2,527	3,384	+34%	0	0	—
case-17 Calculate the estimated prompt token budget consumed by a design specification file `spec.md` that contains exactly 10,000 text characters.	fail→pass	13,800	8,612	-38%	1	1	0%	1,607	3,563	+122%	0	0	—
case-18 During parallel reading of design brief files, `system.md` throws a permission denied read error while `spec.md` reads successfully. Assemble the context output block.	fail→pass	6,557	11,088	+69%	1	1	0%	1,234	4,080	+231%	0	0	—
case-19 An imported Claude Design ZIP specifies primary accent color `#FF0000`, but our brand visual identity document in `.moai/project/brand/visual-identity.md` specifies primary color `#0000FF`. Determine which token value takes precedence.	pass→pass	10,205	8,572	-16%	1	1	0%	836	3,506	+319%	0	0	—
case-20 Write a responsive React navigation bar component in TypeScript using Tailwind CSS styling, including mobile menu toggling.	pass→pass	21,567	16,208	-25%	1	1	0%	3,751	5,483	+46%	0	0	—
case-21 Write a cURL command to fetch node details from the Figma REST API endpoint `GET /v1/files/:key/nodes` using personal access token authentication.	pass→pass	9,211	10,198	+11%	1	1	0%	826	3,898	+372%	0	0	—
case-22 Draft a product design brief document for an e-commerce shopping cart checkout flow outlining user persona objectives, edge cases, and conversion metrics.	pass→pass	17,864	22,059	+23%	1	1	0%	2,951	5,354	+81%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 13 counted toward the lift figure. The other 9 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +27 percentage points is the difference between those two pass rates over the 13 comparable cases. 3 cases got worse with the skill loaded, and they are included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 27.3%
Pass rate with the skill: 54.6%
Cases attempted: 22
Cases counted toward lift: 13
Cases that regressed: 3
Skill version measured: v1
Run completed: 9/3/2026, 23:45 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-06

Prompt

Our product designer sent us a Canva URL `https://canva.com/design/DAFxxx/edit` and a PDF document `./docs/design.pdf` containing our color palette. Attempt to import tokens directly from these source formats into our system.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run55

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+107% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 17 days ago

Other measured skills in the registry, with their headline benchmark lift.