/swarm-design-ui

name: swarm-design-ui
description: UI/UX design phase — propose an intentional design system (pattern, brand, color, typography, spacing, atomic components) with the user, offering distinct directions and per-page layout options, for any interface type: Web, Mobile, Desktop, TUI, or CLI. Use when the SRS declares a user interface, when defining a design system or visual identity, choosing layouts, or reviewing UI work against UX laws.

swarm-design-ui — UI/UX design phase

**Gate:** validated SRS declaring a user interface. Runs alongside swarm-design. The goal is intentional, consistent design decided *with* the user — not templated defaults.

**Load only what you need** (token economy): the per-interface reference for the type at hand (`references/web.md`, `references/mobile.md`, `references/desktop.md`, `references/tui-cli.md`), and — for graphical UIs — `references/style-menu.md`, the on-demand catalog of product categories, style families, layout patterns, and design resources (checklist.design, UX laws, color/type/psychology tools).

1. Interview first

Audience and context of use; brand personality; platform conventions to honor; accessibility requirements; existing brand assets. Keep it light and options-first — the point is to understand the product, not to quiz.

2. Propose a design system (offer ≥2 directions)

Don't jump to one look. Using the product's category and personality (see `references/style-menu.md` for the vocabulary), synthesize a **recommended design system** and at least **one distinct alternative** — e.g. "clinical precision" vs "warm craft" — so the user chooses with something concrete in front of them. Present each as a compact panel:

DESIGN SYSTEM — <recommended | alternative>
  Pattern/layout : <e.g. Hero-centric + social proof>   why: <conversion/trust rationale>
  Style          : <e.g. Soft UI evolution>             best for: <fit>
  Colors         : primary / surface / accent / semantic / bg / text  (WCAG-AA checked)
  Typography     : <display / body pairing>             mood: <…>
  Effects        : <shadows, motion timing, hover>
  Avoid          : <anti-patterns for this domain — see style-menu>

The style/category menu is a **guide, not a cage**: if the product's needs point elsewhere, design for them. Resolve the picked direction into the tokens below.

3. Produce the design-system doc (`docs/design-ui.md`)

Everything as **tokens and scales**, never per-screen ad-hoc values:

1. **Color** — palette with roles (background/surface/primary/accent/semantic), light + dark, WCAG-AA contrast checked. 2. **Typography** — 1–2 families, a modular size scale, line-height and weight rules. 3. **Spacing & box model** — one spacing scale (e.g. 4px base), consistent margin/border/padding discipline, grid + auto-layout container rules. 4. **Atomic inventory** — atoms → components → templates → pages; every screen implied by an FR appears here, traced to its FR-ID. Use the *correct component names* ([namethatui.com](https://namethatui.com) is the dictionary): "drawer", "segmented control", "combobox" — not "that sliding panel". Precise names in specs and tickets mean every agent builds the same thing; resolve vague descriptions to the proper name and confirm. 5. **Per-page layout** — for each key screen, offer a couple of layout options (`references/style-menu.md` lists landing-page and dashboard patterns) and record the choice with its rationale, not just a single default. 6. **Responsive rules** — breakpoints, and a genuinely distinct mobile design where the SRS calls for mobile (not a shrunken desktop). 7. **Motion & interaction** — states (hover/focus/active/disabled/loading/error), timing. 8. **Voice** — the design system is half the identity; how the product *sounds* is the other half. Every string in the inventory (labels, errors, empty states, tooltips, onboarding) goes through **swarm-write**, against the project's `voice.md`. Copy is interface, not decoration applied afterwards.

4. Review against the UX-laws checklist (apply as review, not jargon)

Fitts (targets big and near) · Hick (fewer choices at decision points) · Jakob (follow platform conventions) · Miller (chunk information) · proximity/common-region (group related things) · Doherty (feedback < 400 ms) · error prevention over error messages. Run the pre-delivery checklist in `references/style-menu.md` before calling UI work done.

Rules

• Accessibility is explicit for graphical UIs: contrast ratios, focus order, touch

targets, reduced-motion.

• TUI/CLI projects: skip all graphical guidance and the style menu; help text, flags, exit

codes, and error style ARE the design (see `references/tui-cli.md`).

• End with user validation (gated) or FR-coverage self-check (auto); update flow-state.

--- *Influences: Laws of UX (Yablonski); Atomic Design (Frost); roadmap.sh/design-system; checklist.design; Figma typography guide; NameThatUI (component vocabulary); Anthropic frontend-design skill — see CREDITS.md.*