git:20260808.f8e2149 to git:20260809.3b65826

---

name: octopus-ui-ux-design

aliases:

- design-ui-ux

- ui-ux-design

- design

- ui-design

- ux-design

description: "Design UI/UX systems with style guides, palettes, typography, and component specs for new interfaces"

context: fork

agent: Explore

task_management: true

execution_mode: enforced

pre_execution_contract:

- interactive_questions_answered

- visual_indicators_displayed

- design_intelligence_checked

validation_gates:

- search_py_executed

- design_spec_produced

invocation: human_only

trigger: |

Use this skill when the user wants to "design a UI", "create a design system",

"pick a color palette", "choose fonts for", "design a dashboard", "create component specs",

"style guide for", or "UI/UX for my app".

Execution: BM25 search via search.py + Claude synthesis with ui-ux-designer persona

paths:

- "**/*.tsx"

- "**/*.jsx"

- "**/*.vue"

- "**/*.svelte"

- "**/components/**"

---

## EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)

<HARD-GATE>

**CRITICAL: You MUST call the BM25 search engine (search.py) via Bash tool before producing

any design recommendations. Do NOT rely solely on your own design knowledge. The search engine

provides curated, data-driven design intelligence. If you produce a design system without

at least 3 search.py calls, you have violated this contract.**

</HARD-GATE>

This skill uses **ENFORCED execution mode**. You MUST follow this exact sequence.

### STEP 1: Interactive Questions (BLOCKING)

**You MUST call AskUserQuestion before any other action.**

```javascript

AskUserQuestion({

questions: [

{

question: "What type of product are you designing for?",

header: "Product Type",

multiSelect: false,

options: [

{label: "SaaS/Dashboard", description: "Analytics, admin panels, B2B tools"},

{label: "E-commerce", description: "Shopping, marketplace, product pages"},

{label: "Landing page", description: "Marketing, conversion, product launch"},

{label: "Mobile app", description: "iOS/Android native or responsive"}

]

},

{

question: "What tech stack are you using?",

header: "Stack",

multiSelect: false,

options: [

{label: "React + Tailwind (Recommended)", description: "React/Next.js with Tailwind CSS"},

{label: "React + shadcn/ui", description: "React with shadcn component library"},

{label: "HTML + Tailwind", description: "Static or server-rendered HTML"},

{label: "Vue/Nuxt", description: "Vue.js or Nuxt framework"}

]

},

{

question: "What design deliverables do you need?",

header: "Deliverables",

multiSelect: true,

options: [

{label: "Design tokens", description: "Colors, spacing, typography as CSS/Tailwind config"},

{label: "Component specs", description: "Component anatomy, states, props"},

{label: "Page layouts", description: "Wireframe-level layout specifications"},

{label: "Style guide", description: "Visual style direction with rationale"}

]

}

]

})

```

### STEP 2: Display Banner

**MANDATORY: You MUST use the Bash tool to run this provider check BEFORE displaying the banner. Do NOT skip it. Do NOT assume availability.**

```bash

bash "${HOME}/.claude-octopus/plugin/scripts/helpers/check-providers.sh"

```

**Use the ACTUAL results below. PROHIBITED: Showing only "🔵 Claude: Available ✓" without listing all providers.**

```

🐙 **CLAUDE OCTOPUS ACTIVATED** - UI/UX Design Mode

🎨 Design: [Brief description from user prompt]

Pipeline:

🔍 Phase 1: Design Research (BM25 search + context detection)

🎯 Phase 2: Design Direction (synthesis + style selection)

🐙 Phase 2b: Design Critique (adversarial review before committing)

🛠️ Phase 3: Design System (tokens, components, layouts)

✅ Phase 4: Validation (accessibility, handoff specs)

Providers:

🔴 Codex CLI: [Available ✓ / Not installed ✗] — Implementation critique

🟡 Gemini CLI: [Available ✓ / Not installed ✗] — Ecosystem critique

🧭 Antigravity CLI: [Available ✓ / Not installed ✗] — Additional external-model challenge

🔵 Claude (Sonnet): Available ✓ — Design + independent critique

Tools:

🔍 BM25 Design Intelligence: [checking...]

🎨 Figma MCP: [Available / Not configured]

🧩 shadcn MCP: [Available / Not configured]

```

### STEP 3: Check Design Intelligence

```bash

SEARCH_PY="${HOME}/.claude-octopus/plugin/vendors/ui-ux-pro-max-skill/src/ui-ux-pro-max/scripts/search.py"

if [ -f "$SEARCH_PY" ]; then

python3 -c "import csv, re, math" 2>/dev/null && echo "READY" || echo "MISSING_PYTHON"

else

echo "MISSING_SEARCH_PY"

fi

```

**If MISSING_PYTHON**: Tell user python3 is required for design intelligence.

### STEP 4: Phase 1 — Discover (Design Research)

**You MUST execute at least 3 of these searches. This is NOT optional.**

```bash

SEARCH_PY="${HOME}/.claude-octopus/plugin/vendors/ui-ux-pro-max-skill/src/ui-ux-pro-max/scripts/search.py"

# 1. Product type search — what design patterns fit this product?

python3 "$SEARCH_PY" "<user's product description>" --domain product

# 2. Style search — what visual styles match?

python3 "$SEARCH_PY" "<user's aesthetic or product type>" --domain style

# 3. Color palette search — data-driven palette selection

python3 "$SEARCH_PY" "<user's product type or mood>" --domain color

# 4. Typography search — font pairings

python3 "$SEARCH_PY" "<user's product type>" --domain typography

# 5. UX guidelines search — relevant best practices

python3 "$SEARCH_PY" "<key user flow>" --domain ux

# 6. Stack-specific search (if user specified a stack)

python3 "$SEARCH_PY" "<user's requirements>" --stack <stack>

```

**If user provided a Figma URL**, also pull design context:

- Use `get_design_context` from Figma MCP to pull existing designs

- Use `get_screenshot` for visual reference

**Collect all search results before proceeding to Phase 2.**

### STEP 4b: Design Shotgun Mode (Auto-Activated When 3+ Providers Available)

**This step runs automatically when the provider check in Step 2 detected 3 or more available providers (counting Claude as always available).** When fewer than 3 providers are available, skip to Step 5 and use standard single-direction mode.

Dispatch the same design brief to multiple providers in parallel. Each provider generates an independent design direction without seeing the others' work.

**Launch 3+ variant agents in parallel using the Agent tool with `run_in_background: true`:**

Each agent receives:

```

Design a visual direction for: [user's product description]

Product type: [from Step 1]

Stack: [from Step 1]

Search context: [key findings from Step 4 BM25 searches]

Produce:

2. Primary color palette (3-5 colors with hex values)

3. Font pairing (heading + body)

4. Layout philosophy (e.g., "generous whitespace with card-based content")

5. One paragraph describing the overall feel

Be distinctive — take a clear position rather than playing it safe.

```

**Dispatch to different providers for maximum diversity:**

- 🔴 Codex: implementation-pragmatic direction (what builds fast and scales)

- 🟡 Gemini: trend-aware direction (what's current in the design ecosystem)

- 🔵 Claude: user-centered direction (what serves the audience best)

- 🟤 OpenCode / 🟢 Copilot / 🟣 Qwen: additional variants if available

**After all variants return, present a comparison board:**

```

🎨 **Design Shotgun — 3 Variants**

━━━ Variant A: "Warm Minimalism" (🔴 Codex) ━━━

Colors: #F5F0EB, #2D2A26, #E07A5F, #81B29A, #F2CC8F

Fonts: Inter + Source Serif 4

Feel: Clean, approachable, content-first with warm accent touches

━━━ Variant B: "Bold Industrial" (🟡 Gemini) ━━━

Feel: High-contrast, technical authority, strong hierarchy

```

**Then ask the user to choose:**

```javascript

AskUserQuestion({

questions: [{

question: "Which design direction do you prefer?",

header: "Pick",

multiSelect: false,

options: [

{label: "Variant A", description: "[style name] — [one-line feel]"},

{label: "Variant B", description: "[style name] — [one-line feel]"},

{label: "Variant C", description: "[style name] — [one-line feel]"},

{label: "Mix & match", description: "Take elements from multiple variants"}

]

}]

})

```

**After selection, proceed to Step 5 using the chosen variant as the design direction.** If "Mix & match", ask which elements to combine before proceeding.

---

### STEP 5: Phase 2 — Define (Design Direction)

Synthesize search results (and chosen variant if shotgun mode) into a design direction document:

1. **Style recommendation** — which visual style best fits the product (cite search results)

2. **Color palette** — selected palette with hex values and contrast ratios

3. **Typography** — heading + body font pairing with Google Fonts import

4. **Layout approach** — grid system, spacing scale, responsive strategy

5. **Design principles** — 3-5 guiding principles derived from UX search results

**Output: Write the design direction as a structured section you can reference in the next step.**

### STEP 5b: Design Critique — Three-Way Adversarial Review (MANDATORY)

**This step runs by default.** Before committing to the design direction, it must survive adversarial critique from up to three independent perspectives. This catches accessibility failures, impractical choices, and BM25 blind spots before they get baked into tokens and components.

**Critique prompt** (sent to all participants):

```

Review this proposed design direction and find problems. Be adversarial — your job is to catch flaws, not validate choices.

[The full design direction from Step 5]

Critique dimensions:

1. ACCESSIBILITY — Do the proposed colors meet WCAG AA contrast ratios (4.5:1 text, 3:1 large text)? Are the font sizes readable at the proposed scale? Are touch targets viable?

2. PRACTICALITY — Does this typography actually render well on the stated tech stack? Are the fonts available and performant (file size, loading)? Does the spacing scale work with the layout system?

3. FIT — Does the visual style actually match the product type and audience? Would a user of [product type] feel comfortable with this aesthetic?

4. GAPS — What did the research miss? Are there common UX patterns for this product type that aren't addressed? Are there competitive norms being ignored?

For each issue found, state: what's wrong, why it matters, and what to do instead.

```

**Three participants, run in parallel:**

```bash

# Check provider availability

providers=()

command -v codex >/dev/null 2>&1 && providers+=(codex)

command -v agy >/dev/null 2>&1 && providers+=(agy)

command -v gemini >/dev/null 2>&1 && providers+=(gemini)

for provider in "${providers[@]}"; do

safe_provider=$(printf '%s' "$provider" | tr -c '[:alnum:]_-' '_')

"${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" spawn "$provider" \

"<critique prompt>" > "/tmp/design-critique-${safe_provider}.md" &

done

wait

```

**🔵 Claude (Sonnet) — independent design critique.** You MUST also write your own adversarial critique. Do NOT just summarize what external providers said. Approach the design direction as if you didn't create it — actively look for problems across all four dimensions. This is your independent synthesis perspective, same as in `/octo:debate`.

**Display all critiques with provider indicators:**

```

🔴/🧭/🟡 **External Provider Critique:** [implementation, ecosystem, accessibility, and alternative approach concerns]

🔵 **Claude Critique:** [design concerns — accessibility gaps, fit issues, missing patterns]

```

If only 1-2 providers are available, run with what you have. Even Claude-only critique (minimum case) is valuable because you're explicitly switching from "designer who made the choices" to "reviewer finding problems."

**After collecting all critiques, synthesize and revise:**

1. **Triage issues** — group by severity (must-fix, should-fix, acknowledged trade-off)

2. **Fix must-fix items** — adjust colors for contrast, swap impractical fonts, add missing patterns

3. **Address should-fix items** — incorporate where feasible, note rationale for deferrals

4. **Log trade-offs** — document what you're keeping despite critique and why

5. **Show the diff** — present what changed between original and revised direction:

```

📋 **Design Direction Revisions:**

- [Changed] Primary blue #2563EB → #1D4ED8 (contrast ratio 4.2:1 → 5.8:1, per external critique)

- [Added] Fallback font stack for body text (per external critique)

- [Kept] Glassmorphism style despite provider concern — appropriate for SaaS dashboard audience

```

**The revised design direction feeds into Phase 3. Do NOT proceed with an uncritiqued direction.**

### STEP 6: Phase 3 — Develop (Design System)

Generate the design system based on user's requested deliverables:

**Design Tokens** (if requested):

- CSS custom properties or Tailwind config

- Color scales (50-950)

- Spacing scale (4px base)

- Typography scale with line heights

- Shadow, border-radius, and transition tokens

**Component Specs** (if requested):

- Component anatomy diagrams (ASCII)

- Props/variants table

- State variants (default, hover, active, disabled, error, loading)

- Accessibility requirements (ARIA, keyboard, focus)

**Page Layouts** (if requested):

- Grid-based layout with responsive breakpoints

- Content hierarchy and visual flow

- Above-the-fold content strategy

- Navigation and interaction patterns

**Style Guide** (if requested):

- Visual style rationale with evidence from search results

- Do's and don'ts with examples

- Icon and illustration guidelines

- Motion and animation principles

If shadcn MCP is available, search for matching components:

```javascript

// Search shadcn registries for components matching the design system

mcp__shadcn__search_items_in_registries({ query: "<component name>" })

```

### STEP 7: Phase 4 — Deliver (Validation)

### STEP 7b: AI Surface Audit (when the interface calls a model)

Run this whenever the thing being designed sends input to a model and shows the

result, and especially when it then **acts** on that result. Style guides and

component specs do not answer what an AI feature must show and let the user

control; this step does. Skip it entirely for interfaces with no model in the

loop.

Ask each question and record an explicit answer. "Not applicable" is a valid

answer; silence is not.

**1. Uncertainty.** Does the surface distinguish a confident answer from a

guess? If it cannot, say so plainly rather than implying uniform reliability.

Do not invent a numeric threshold — pick a representation the underlying system

can actually justify.

**2. Provenance.** Can the user see what the answer was derived from? Retrieval

and search features need citations; a summariser needs the source it summarised.

An answer with no traceable origin is unreviewable.

**3. Interruption.** If output streams or the task is long-running, is there a

cancel affordance, and does cancelling actually stop the work rather than just

hiding it? A stop button that abandons a still-running job is worse than none,

because it misreports the system's state.

**4. The review gate.** Where does a human check the output, and is that

placement load-bearing? A gate after an irreversible action is decoration.

`skill-intent-contract` already elicits initiative, control, and decision rights

separately — reuse those answers here rather than re-deriving them, and if they

disagree with the placement, the contract wins.

**5. Failure and degradation.** What does the surface show when the model is

slow, unavailable, rate-limited, or returns something unusable? Each needs a

distinct state. Collapsing them into one generic error teaches users to ignore

it.

**6. Consent and data use.** Does the user know what is sent, where, and whether

it is retained? Required wherever input may contain someone else's data.

**7. Rollback.** If the feature takes a real-world action — files, sends, pays,

deletes — what undoes it, and is that path visible before the action, not only

after it fails?

**Output contract.** Answer all seven in the delivered document, each with the

decision and its rationale. Where a question is unanswerable because the

underlying system cannot support it, record that as a finding rather than

leaving the row blank: an unanswerable question about rollback is a design

constraint, not an omission.

**Attribution.** The framing follows the AI Interaction Atlas by Brandon Harwood

(ai-interaction.com). Depend on it, do not copy it: the Atlas deliberately ships

no thresholds — no confidence cutoffs, no latency budgets — and inventing them

here would attribute numbers to a source that does not publish them. State

direction, cite the source, and let the product supply its own values.

Format the final design system as a structured document with:

- Executive summary (style direction + rationale)

- Design tokens (copy-paste ready)

- Component inventory

- Page layouts

- Implementation notes for the development team

- Sources (which search results informed each decision)

**Offer next steps:**

- "Want me to implement these specs?" → hand off to frontend-developer persona

- "Want to refine the palette?" → re-run color search with adjusted query

- "Want a full embrace workflow?" → transition to `/octo:embrace`