ss-flow git:20260813.f5ff2b5A

Immutable. This exact content is served forever at /api/v1/blob/f4c16d0daa05b4cc.

---
name: ss-flow
description: Design user flows and navigation structure following proven UX patterns
argument-hint: "[flow-name] [description]"
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---

# UX Flow Designer
## Registry-first artifact boundary

When `.styleseed/project.json` and `.styleseed/artifacts/index.json` exist, resolve the requested artifact ID first, then read only `.styleseed/bundles/<artifact-id>.md` and `.styleseed/manifests/<artifact-id>.json`. Never fall back to the global legacy bundle for a registry project. Legacy projects may use `.styleseed/effective-rules.md` only when no registry exists.

## When NOT to use

- For implementing a single page → use `/ss-page` after the flow is settled
- For copy on each step → use `/ss-copy` after the structure is settled
- For information architecture of an entire product — narrow scope to one flow first
- For high-fidelity mockups — this produces a flow map, not pixel-perfect designs

Design a user flow: **$0**
Description: $ARGUMENTS

## Instructions

1. Read the design system reference:
   - `CLAUDE.md` for component inventory
   - `DESIGN-LANGUAGE.md` for layout patterns (sections 13-14, 19-20)
   - `components/patterns/` for available building blocks

2. Apply these UX principles:

### Information Architecture
- **Progressive Disclosure**: Show only what's needed at each step. Hide complexity behind logical drill-downs.
- **Cognitive load**: Chunk information around the user's decision; the resolved grammar and content
  density decide the grouping rather than a universal item count.
- **Hick's Law**: Minimize choices per screen while preserving the product's real task vocabulary.

### Navigation Patterns
- **Hub & Spoke**: Dashboard → detail pages → back to dashboard (default for mobile apps)
- **Linear Flow**: Step 1 → Step 2 → Step 3 (for forms, onboarding, checkout)
- **Navigation**: use the resolved surface adapter; BottomNav is only one possible mobile pattern.

### Screen Flow Rules
- Every flow must have a **clear entry point** and **clear exit point**
- Key features should be reachable with an appropriate number of steps for the product and platform;
  do not impose a universal tap count.
- Back navigation must always be available (except root screens)
- Error states must provide **recovery paths** (retry, go back, contact support)
- Loading states must use skeleton screens (never spinners in cards)

### Page Composition (from DESIGN-LANGUAGE.md)
- Follow the selected output grammar's information hierarchy; do not impose a Hero → KPI Grid →
  Details → Lists template on unrelated products.
- Each screen should answer ONE primary question when the task calls for it.
- Above the fold: the most important metric or action
- Use the 4 section types: Full Card (A), Grid (B), Carousel (C), Hero (D)

3. Output format:
   - **Flow diagram** in ASCII showing screen connections
   - **Screen inventory** listing each screen's purpose and key components
   - **Edge cases** (empty states, errors, loading) for each screen
   - **Scaffolded pages** using primitives selected by the artifact's adapter and grammar

4. Generate the actual page files using `/ss-page` conventions.