| 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:
- Color — palette with roles (background/surface/primary/accent/semantic), light +
dark, WCAG-AA contrast checked.
- Typography — 1–2 families, a modular size scale, line-height and weight rules.
- Spacing & box model — one spacing scale (e.g. 4px base), consistent
margin/border/padding discipline, grid + auto-layout container rules.
- 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 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.
- 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.
- Responsive rules — breakpoints, and a genuinely distinct mobile design where the
SRS calls for mobile (not a shrunken desktop).
- Motion & interaction — states (hover/focus/active/disabled/loading/error), timing.
- 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.
