octopus-ui-ux-design

What this skill does

> **Host: Codex CLI** — This skill was designed for Claude Code and adapted for Codex.
> Cross-reference commands use installed skill names in Codex rather than `/octo:*` slash commands.
> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.
> For host tool equivalents, see `skills/blocks/codex-host-adapter.md`.


## EXECUTION CONTRACT (MANDATORY - CANNOT SKIP)

<HARD-GATE>
**CRITICAL: You MUST call the BM25 search engine (search.py) via native shell command 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 native shell command 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
🔵 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_SEARCH_PY**: Tell user to run `cd "${HOME}/.claude-octopus/plugin" && git submodule update --init vendors/ui-ux-pro-max-skill`
**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 host subagent tool with `background execution: 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:
1. A style name (2-3 words, e.g., "Warm Minimalism", "Bold Industrial", "Soft Gradient")
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) ━━━
Colors: #0A0A0A, #FFFFFF, #FF6B35, #004E89, #1A936F
Fonts: Space Grotesk + IBM Plex Sans
Feel: High-contrast, technical authority, strong hierarchy

━━━ Variant C: "Soft Gradient" (🔵 Claude) ━━━
Colors: #667EEA, #764BA2, #F093FB, #F5F7FA, #1A202C
Fonts: Satoshi + General Sans
Feel: Modern, approachable, subtle depth through gradients
```

**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]"},