zuvo:design — Intent-First Interface Design

Build UI with conscious, traceable design decisions. Every visual choice must be explainable: traced from user intent through domain exploration to specific token values. Persists decisions in .interface-design/system.md and system.json for cross-session consistency.

Scope: New interface creation, existing UI improvement, design system extraction, component construction within an established system. Out of scope: Auditing existing UI against checklists (zuvo:design-review), multi-agent visual inspection (zuvo:ui-design-team), code quality (zuvo:review).

Mandatory File Loading

Read these files before any work begins:

Dispatch follows ../../shared/includes/execution-policy.md through env-compat. Reuse existing authorization within that policy; session restrictions take precedence. Run each required gate and report its actual independence or an unmet requirement.

1. ../../shared/includes/codesift-setup.md -- CodeSift discovery and tool selection
2. ../../shared/includes/env-compat.md -- Agent dispatch and environment adaptation

Print the checklist:

CORE FILES LOADED:
  1. codesift-setup.md   -- [READ | MISSING -> STOP]
  2. env-compat.md       -- [READ | MISSING -> STOP]
  3. ../../shared/includes/run-logger.md -- [READ | MISSING -> STOP]
  4. ../../shared/includes/retrospective.md -- [READ | MISSING -> STOP]

If any file is missing, STOP.

Environment Compatibility

Read ../../shared/includes/env-compat.md for agent dispatch patterns, path resolution, and progress tracking across all supported platforms.

CodeSift Integration

Read ../../shared/includes/codesift-setup.md for the full initialization sequence.

Design-specific CodeSift usage:

• get_file_tree(repo, path_prefix="src/components/ui") -- instant design system inventory
• find_references(repo, symbol_name="Dialog") -- usage patterns of UI primitives
• search_symbols(repo, query, kind="function", file_pattern="*.tsx") -- check for existing similar components
• search_text(repo, query="cn\\(", file_pattern="*.tsx") -- Tailwind composition patterns
• assemble_context(repo, query="<component>", token_budget=4000) -- gather component + types + imports

Step 0: Parse $ARGUMENTS

Default: init

Step 0.5: Prerequisites Check

Run these checks before starting. Print status for each.

Required

Recommended

For improve/extract mode: no UI files = STOP.

Phase 1: Context

Step 1: Check for Existing Design System

cat .interface-design/system.md 2>/dev/null

If system.md exists:

• Read and load all tokens, patterns, decisions
• Extract INTENT from the Direction section
• Print: Design system loaded: [personality], [N] tokens, [N] patterns, last updated [date]
• --quick mode: go directly to Phase 4 (build), skip craft validation, auto-save
• Normal mode: skip Phase 2-3, go to Phase 4

If system.md does NOT exist:

• If argument is [component] or --quick: warn "No design system found. Run zuvo:design init first."
• If argument is init, improve, or extract: proceed to Phase 2

Phase 2: Intent Exploration

Step 3: Intent Questions

Present three questions. If the environment is interactive, ask inline; otherwise make the safest reasonable decision and annotate it.

Q1: Who is the person using this? Not "users" -- specific context. Example: "Marketing manager reviewing campaign performance before Monday standup."

Q2: What must they accomplish? Verb-based tasks, not features. Example: "Scan 20 campaigns, compare week-over-week, flag underperformers, share report."

Q3: How should this feel? Offer 3-4 options based on product type:

• "Calm authority" -- quiet confidence, the user trusts the tool
• "Energetic efficiency" -- fast, snappy, dense with info
• "Warm guidance" -- approachable, helps without overwhelming
• "Precise control" -- technical, every detail accessible

Capture answers as INTENT for all subsequent decisions.

Phase 3: Domain Exploration

Step 4: Product Domain

Based on intent answers and project code, produce 4 outputs:

1. Domain Concepts (5+) -- the vocabulary and mental model of the product domain
2. Color World (5+) -- emotions and associations that inform palette selection
3. Signature (1) -- a unique design element that makes this product recognizable
4. Defaults to Avoid (3) -- generic patterns that would make this feel like every other product

Match the user's domain to industry patterns if applicable (SaaS Dashboard, Fintech, Healthcare, E-Commerce, Admin Panels, Data Visualization, AI/Chat, Landing Pages, Developer Tools, Onboarding). Use industry-specific layout rules, color presets, and anti-patterns as starting constraints.

Present to user for confirmation. Adjust based on feedback.

Step 5: Design Direction

1. Select the closest design direction (or blend 2) based on intent and domain
2. Adapt tokens to the domain (do not copy presets verbatim)
3. Present proposal with: Personality, Foundation palette, Depth (elevation), Accent color, Spacing scale, Border radius system, Typography -- each tied to intent

Ask for confirmation:

• "Looks good, build it"
• "Adjust tokens" -- user specifies changes
• "Try different direction" -- restart Phase 3

Phase 4: Build

Step 6: Per-Component Construction

For EACH component, declare a mandatory checkpoint:

COMPONENT: [name]
  Intent:      [why this exists, what user accomplishes]
  Palette:     [which colors from system, why]
  Depth:       [which elevation level, why]
  Surfaces:    [background, border treatment, why]
  Typography:  [sizes, weights, why]
  Spacing:     [which scale values, why]
  Motion:      [transitions, tier (micro/standard/emphasis), reduced-motion fallback]
  Responsive:  [layout adaptation, content priority, touch targets, typography scaling]

Build the component code with these decisions applied.

For improve mode:

1. Read existing component
2. Identify defaults (generic values, inconsistent tokens)
3. Propose specific changes tied to design direction
4. Apply changes preserving functionality

For extract mode:

1. Scan all UI files in scope
2. Catalog: colors (frequency), spacing values, radius values, font sizes, motion durations, component patterns
3. Build Mutations vs Standard table: for each token category, list every variant found alongside the proposed canonical value
4. Identify implicit direction: map findings to closest design direction
5. Propose system.md + system.json based on actual usage
6. Skip Phase 5 -- extract produces a proposal, not built components. Go to Phase 6.

Phase 5: Craft Validation

Skip if --quick mode or extract mode.

Step 7: Run 4 Tests

After building, run ALL validation tests:

1. Swap Test: Replace design tokens with neutral alternatives. Does the component still communicate the intended personality? If it looks the same with generic tokens, the design is not intentional enough. (3 meaningful swaps required.)

2. Squint Test: Blur your mental image of the component. Is the visual hierarchy still clear? Primary action obvious? Sections distinguishable? (4 checks.)

3. Signature Test: Is the unique design element from Step 4 present? Count touchpoints across the component. (5 touchpoints required.)

4. Token Test: Trace every visual value back to a design token. No magic numbers, no hardcoded hex values, no arbitrary spacing. (Track traceable vs total.)

Print pass/fail for each with evidence. If ANY test fails, iterate before showing to user.

Persist gate: At least 3/4 craft tests must PASS before proceeding.

If fewer than 3 pass after iteration, do NOT stop and wait for approval — record and continue, per no-pause-protocol.md's Post-Cap Autonomous Disposition:

[CRAFT-GATE: BELOW-BAR] <n>/4 passed after <k> iterations
  failing: <test> — <what specifically failed, with the value>
  persisted anyway: <file>   (marked PROVISIONAL in the craft-validation report)

Then proceed and surface every [CRAFT-GATE: BELOW-BAR] line in the final summary. Until 2026-08-06 this read "warn user and require explicit approval", which made design the only one of 57 skills with an approval gate — against no-pause-protocol.md and against the convention skill-eval states outright ("No approval gates. Execute end-to-end; only --dry-run gates output"). A design run left half-finished waiting on a human is the friction that rule exists to kill; the honest alternative is to persist it clearly labelled as below-bar, not to block on a question nobody is awake to answer.

Step 7.5: Save Craft Validation Report

Save to .interface-design/craft-validation-[YYYY-MM-DD].md with per-test results and per-component checkpoints.

Phase 6: Persist

Step 8: Save Design System

--dry-run: Print proposed diff, do not write files. End here.

--quick: Print brief diff (max 10 lines), auto-save.

Normal mode: After user approves:

1. Create .interface-design/ directory
2. Generate system.md with all sections: Direction, Domain, Tokens, Motion, Patterns, Decisions
3. Generate system.json alongside -- machine-readable artifact for zuvo:design-review

Ask for confirmation:

• "Save" -- persist for future sessions
• "Save + commit" -- save and create git commit
• "Skip" -- do not save

If .interface-design/ NOT in .gitignore, ask if user wants to track in git.

Step 9: Post-Design Recommendation

Suggest running zuvo:design-review on the built components for a structured DX1-DX20 audit.

status Mode

1. Check for .interface-design/system.md
2. If exists: print Personality, Foundation, Depth, Token count, Pattern count, Decision count, Last updated
3. If not exists: "No design system found. Run zuvo:design init or zuvo:design extract [path]."

Contract: zuvo:design <-> zuvo:design-review

This skill produces two artifacts in .interface-design/:

zuvo:design-review reads JSON first for stable token comparison, falls back to MD if JSON missing.

No artifacts: zuvo:design-review runs purely structural (DX1-DX20). With artifacts: adds craft validation + intent-aware token matching.

Completion Gate Check

Before printing the final output block, verify every item. Unfinished items = pipeline incomplete.

COMPLETION GATE CHECK
[ ] Intent questions answered (Q1/Q2/Q3) before any token decisions
[ ] Domain exploration produced: Concepts, Color World, Signature, Defaults to Avoid
[ ] Per-component checkpoint filled for EACH component
[ ] All 4 craft validation tests ran (Swap, Squint, Signature, Token)
[ ] system.md and system.json saved to .interface-design/
[ ] Run: line printed and appended to log

Completion

After completing any mode, print:

DESIGN COMPLETE
-----
Mode: [init | component | improve | extract]
Run: <ISO-8601-Z>	design	<project>	-	-	<VERDICT>	-	<DURATION>	<NOTES>	<BRANCH>	<SHA7>	<INCLUDES>	<TIER>
-----

Retrospective (REQUIRED)

Follow the retrospective protocol from retrospective.md. Gate check → structured questions → TSV emit → markdown append. If gate check skips: print "RETRO: skipped (trivial session)" and proceed.

Append via wrapper (REQUIRED). Never >> directly to ~/.zuvo/runs.log — the wrapper is the gate that verifies a retro entry exists for this run. Order: retro bash executed → wrapper invoked → completion claimed.

printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog

Expected stdout: OK: appended to runs.log (retro verified for <skill> on <project>). If exit 2 with RETRO_REQUIRED — go execute the retro bash from retrospective.md first; never bypass with ZUVO_SKIP_RETRO_GATE=1. After the wrapper succeeds, print a Logs: evidence line (tail -1 ~/.zuvo/retros.log, grep -c "^<!-- RETRO -->" ~/.zuvo/retros.md, tail -1 ~/.zuvo/runs.log) before claiming completion. Printing the markdown retro section without executing the bash leaves all three log files empty.

<DURATION>: use init, component, improve, or extract.

Execution Notes

• Present results, not process. Do not narrate exploration steps.
• Suggest and ask. Explore, recommend, present options. Never dictate without user input.
• Every choice traceable. If asked "why this color?" trace to intent -> domain -> token.
• Build for the detected stack. Adapt to what exists in the project.
• When improving existing UI, preserve all functionality. Only change visual/interaction design.