pi-ui-workflow

A UI design workflow for pi coding agent. A lead reviewer (main AI) orchestrates 7 specialized sub-agents (4 required + 3 optional) covering requirements, form, visuals, information architecture, interaction, and content — producing an executable UI design spec, with optional high-fidelity HTML prototypes.

📖 中文文档

30 Second Quickstart

For users who already have Pi installed and want to use /ui-workflow in any project.

1. Install the plugin

pi install npm:pi-ui-workflow

If Pi is already running, type /reload after installation.

2. Navigate to your project and launch Pi

cd /path/to/your-product
pi

3. Run the workflow command

/ui-workflow I want to build a minimalist time tracker for indie developers

What you'll see:

1. Choose execution mode: Fast / Standard / Deep;
2. Confirm product requirements;
3. Choose search method and extra analysis scope;
4. Finally generate docs/ui-design-spec.md, with intermediate reports archived to docs/ui-workflow/.

Partial Rerun

If you've already run the full workflow and docs/ui-workflow/ contains intermediate reports:

/ui-rerun redo visuals only
/ui-rerun redo interactions
/ui-rerun rebuild final spec

It reuses existing reports, only rerunning the specified part to save time and tokens.

This plugin bundles design-dna, all agents, and the sub-agent engine. Install once and use immediately. The only optional enhancement is TinyFish (for design reference search — you can skip it).

What This Is

Turn vague "I want to build an XXX product" descriptions into:

1. Reference material analysis (8 built-in high-quality design sites + optional TinyFish web search)
2. Structured requirements report (target users, core features, key scenarios)
3. UI form decisions (page types, layout paradigms, component selection, responsive strategy)
4. Information architecture (navigation structure, page hierarchy, routing logic)
5. Quantified visual spec (complete design tokens + design-dna invocation)
6. Interaction experience plan (micro-interactions, state transitions, gestures, accessibility)
7. Content & copywriting spec (UI copy, CTAs, error messages, brand tone)
8. Integrated design spec document (markdown) + (optional) high-fidelity HTML prototype

Workflow Overview

The workflow starts by letting users choose an execution mode, putting the trade-off of "wait time, token cost, output quality" in their hands:

| Mode | Est. Time | Agent Orchestration | Quality | Use Case | |------|-----------|---------------------|---------|----------| | Fast | ~2-4 min | Agents in parallel where possible | Medium | Rapid direction exploration, early idea validation | | Standard (recommended) | ~5-8 min | Two-stage analysis | High | Most UI design tasks | | Deep | ~8-15 min | Strict sequential / semi-sequential | Highest | Important products, critical pages, dev-ready specs |

Stage 0: Choose execution mode (main AI)
  ├─ Fast mode: quicker, good for initial direction
  ├─ Standard mode: balanced quality and speed, default recommended
  └─ Deep mode: most complete, for important products
       ↓
Stage 1: Align requirements (main AI)
  ├─ Scan project, ask key questions
  └─ Save docs/ui-need-summary.md
       ↓
Stage 1.5: Search materials + choose extra analysis (main AI + researcher)
  ├─ Pop-up: choose search method (TinyFish / custom API / skip)
  ├─ Pop-up: choose extra analysis (IA / interaction / content, all checked by default)
  ├─ Browse 8 built-in reference sites
  └─ Call ui-research-analyst → reference material analysis report
       ↓
Stage 2a: Requirements analysis
  └─ Call ui-need-analyst → requirements analysis report
       ↓
Stage 2b: Expert analysis (orchestrated by execution mode)
  ├─ Fast mode: form / visual / optional experts in parallel
  ├─ Standard mode: form + visual first, then optional experts
  └─ Deep mode: form → visual → ia → interaction → content strict handoff
       ↓
Stage 3: Final review (main AI)
  ├─ Detect conflicts
  ├─ Integrate docs/ui-design-spec.md
  └─ Archive docs/ui-workflow/99-ui-design-spec.md
       ↓
Stage 4: HTML prototype (optional, confirmed first)
  ├─ ask_user_question prompt
  └─ Call design-dna Generate → docs/prototype/*.html

Progress feedback follows a "stage number + current action + why + next step" format:

[1/6] ✅ Mode confirmed: Standard (~5-8 min)
[2/6] 🔎 Aligning requirements: confirming product goals, target users, and key pages...
[3/6] 🔍 Searching reference materials: to ground design decisions...
[4/6] 🧠 Running expert analysis: form + visual first, then downstream experts...
[5/6] 🧩 Integrating reports: checking for conflicts across form, visuals, interaction, content...
[6/6] ✅ Done: final spec saved, optionally generate HTML prototype next.

The workflow preserves two kinds of artifacts:

• Final artifacts: docs/ui-design-spec.md, docs/prototype/*.html (if generated)
• Intermediate report archive: docs/ui-workflow/, containing the requirements summary, reference material report, each expert report, and the final spec archive

Recommended archive structure:

docs/ui-workflow/
├── 00-need-summary.md
├── 01-research-report.md
├── 02-need-report.md
├── 03-form-report.md
├── 04-visual-report.md
├── 05-ia-report.md
├── 06-interaction-report.md
├── 07-content-report.md
└── 99-ui-design-spec.md

These files are generated artifacts each run and excluded from version control by default via .gitignore.

7 Sub-Agents

| # | Agent | Required | Responsibility | Key Upstream Input | |---|-------|----------|---------------|---------------------| | 1 | ui-research-analyst | Yes | Analyze reference materials, identify design trends | Requirements summary + search results | | 2 | ui-need-analyst | Yes | Product positioning, users, core features, key pages | Requirements summary + project context | | 3 | ui-form-analyst | Yes | Page types, layout paradigms, component selection, responsive strategy | need + research | | 4 | ui-visual-analyst | Yes | Color/font/spacing/animation + design-dna | need + research; form in standard/deep modes | | 5 | ui-ia-analyst | Optional | Navigation structure, info hierarchy, routing, search UX | need + research + form + visual | | 6 | ui-interaction-analyst | Optional | Micro-interactions, state transitions, gestures, accessibility | need + research + form + visual + ia (if available) | | 7 | ui-content-analyst | Optional | UI copy, empty states, error messages, brand tone | need + research + form + visual + interaction (if available) |

Four Workflow Commands

| Command | Purpose | |---------|---------| | /ui-workflow <description> | Full pipeline: choose mode → align → search → analyze → review → optional prototype | | /ui-align | Stage 1 only (align requirements), outputs requirements summary | | /ui-review | Stages 0+1.5+2+3+4 (skip alignment, go straight to analysis) | | /ui-rerun [scope] | Partial rerun based on docs/ui-workflow/: visuals, interactions, content, or final spec |

Manual Install (Fallback)

If not using npm, you can copy manually:

mkdir -p ~/.pi/agent/agents ~/.pi/agent/prompts
cp .pi/agents/*.md ~/.pi/agent/agents/
cp .pi/prompts/*.md ~/.pi/agent/prompts/

Manual install does not load the built-in extension; the official subagent extension is needed separately.

Security Defaults

To be safe for distribution, this workflow defaults to only calling user-globally-installed agents:

{
  "agentScope": "user"
}

This avoids auto-executing project-local .pi/agents in untrusted repos. If you explicitly trust a project's local agents, you can temporarily switch to:

{
  "agentScope": "both"
}

But do not disable the project agent safety confirmation — avoid defaulting confirmProjectAgents: false.

Package Manifest

The project uses Pi package manifest to declare prompts, extensions, and skills:

{
  "pi": {
    "prompts": [".pi/prompts/*.md"],
    "extensions": ["extensions/ui-workflow"],
    "skills": ["skills/design-dna", "skills/ui-workflow"]
  }
}

The built-in extension auto-loads the 7 UI sub-agents from the package's bundled .pi/agents/, requiring no manual copying.

The package also exposes a universal ui-workflow skill. This lets other Agent Skills-compatible agents use the same UI/UX workflow even when Pi slash commands are unavailable.

See also:

• skills/ui-workflow/SKILL.md: Universal skill entry point
• skills/ui-workflow/references/workflow-protocol.md: Shared source of truth for Pi and universal execution
• skills/ui-workflow/references/external-skill-sources.md: Related UI/UX skill source directory and routing map
• docs/package-plan.md: Packaging roadmap
• docs/progress-plan.md: Dynamic progress / TUI panel future plans

Use as a Skill

After installation, Pi users can still use the automated command:

/ui-workflow I want to build a minimalist time tracker for indie developers

They can also explicitly load the universal skill:

/skill:ui-workflow

Other Agent Skills-compatible agents can read:

skills/ui-workflow/SKILL.md

The universal skill follows the same workflow as the Pi command. The shared protocol lives in:

skills/ui-workflow/references/workflow-protocol.md

External UI/UX Skill Routing

The ui-workflow skill includes a source directory for related professional UI/UX skills:

skills/ui-workflow/references/external-skill-sources.md

Agents should consult it before each stage and use relevant skills when available. Examples include:

• anthropics/frontend-design for distinctive frontend UI and anti-generic visual direction
• vercel-labs/web-design-guidelines for UI review, accessibility, and web interface standards
• ui-ux-pro-max / ui-design for design-system recommendations
• typography-audit for typography decisions
• ui-animation / greensock/gsap-* for motion and interaction
• copywriting for product copy and microcopy
• design-md for long-lived DESIGN.md project context

These external skills are optional enhancements, not hard dependencies. If they are unavailable, the workflow continues with built-in guidance.

Built-in Reference Sites

During material search, regardless of method, these 8 high-quality design reference sites are prioritized:

• godly.website — Curated high-quality web design
• awwwards.com — Web design awards & trends
• mobbin.com — Real mobile product screenshots
• reactbits.dev/components/magic-bento — React component examples
• supahero.io — Design inspiration collection
• 60fps.design — High-quality UI animation reference
• ui-pocket.com/mobile — Mobile UI collection
• pinterest.com — Mood boards & style inspiration

Dependencies

This plugin bundles 7 UI analysis agents, the design-dna skill, and the sub-agent invocation engine — no additional dependencies required.

Optional enhancement:

TinyFish Search (optional)

If you want the workflow to automatically search for design reference materials:

pi install npm:pi-tinyfish-tools

Without it you can still use the workflow — just choose "Skip search" during the search phase.

Verify Installation

A check script is included to verify the plugin is correctly installed:

scripts/check-install.sh

Search Method Options

During stage 1.5, a pop-up lets users choose:

| Option | Description | |--------|-------------| | TinyFish Search (recommended) | Free, searches web + browses built-in sites | | Custom Search API | Provide endpoint and key, uses curl | | Skip Search | No search; researcher analyzes based on available descriptions |

HTML Prototype Confirmation

Stage 4 does not auto-generate HTML prototypes. The workflow prompts:

| Option | Meaning | |--------|---------| | Generate full HTML prototype | Higher token cost, high fidelity previewable | | Generate 1 key page only (recommended) | Check the look first, expand later | | Keep spec document only | No HTML generation | | Skip | Do nothing extra |

Project Structure

pi-ui-workflow/
├── .pi/
│   ├── agents/
│   │   ├── ui-research-analyst.md       Researcher
│   │   ├── ui-need-analyst.md           Requirements analyst
│   │   ├── ui-form-analyst.md           Form analyst
│   │   ├── ui-visual-analyst.md         Visual analyst
│   │   ├── ui-ia-analyst.md             Information architect (optional)
│   │   ├── ui-interaction-analyst.md    Interaction analyst (optional)
│   │   └── ui-content-analyst.md        Content strategist (optional)
│   └── prompts/
│       ├── ui-workflow.md               Full workflow command
│       ├── ui-align.md                  Align only
│       ├── ui-review.md                 Review mode
│       └── ui-rerun.md                  Partial rerun
├── extensions/
│   └── ui-workflow/
│       ├── agents.ts                    Agent discovery (incl. package agents)
│       └── index.ts                     ui_workflow_subagent tool
├── skills/
│   ├── design-dna/                      Bundled design-dna skill
│   └── ui-workflow/                     Universal UI workflow skill + external skill routing
│       ├── SKILL.md
│       └── references/
│           ├── workflow-protocol.md
│           ├── external-skill-sources.md
│           ├── agent-roles.md
│           ├── artifact-templates.md
│           └── quality-checklist.md
├── scripts/
│   └── check-install.sh                 Installation health check
├── docs/
│   ├── usage.md                         Detailed usage guide
│   ├── iteration-plan.md                Iteration roadmap
│   ├── package-plan.md                  Packaging plan
│   └── progress-plan.md                 Dynamic progress plan
├── README.md
├── README.zh-CN.md
├── CHANGELOG.md
├── package.json
└── LICENSE

License

MIT