Ux Design

ux-design — the other half of beauty

Beautiful screens are half the story; how users move between them and get things done is the other half. This skill designs the experience architecture: journeys → flows → navigation → states → habit loops. Screens come FROM flows — /ios-design renders what this skill decides, and /journey-qa verifies the same journey ids at ship time. The failure mode this skill exists to prevent: beautiful screens nobody can traverse.

Read CANON.md (council-distilled experience laws) at Phase 1 and audit every artifact against it before handoff. The laws are medium-agnostic; for a WEB target also read ~/.claude/skills/web-design/WEB.md — the delta that changes thresholds, drops the laws that do not port (tab bar, sheet-vs-stack) and adds the web-only ones (URL is state, URL is the repeat path, the spinner window, keyboard operability).

Phase 0 — Read first

1. Resolve the repo (~/.claude/repo-map.md). Inventory what exists:

product spec/ADRs, an existing journeys doc (docs/journeys.md, docs/journeys/*.yaml), personas, analytics, an existing design system (docs/design/*/DESIGN.md). An existing ratified journey set is EXTENDED, never re-invented (the example-app pattern: journeys are decided before client code and each becomes a testable contract).

1. Establish the product's ONE hero loop candidate from the spec — the job

the product lives on. If it isn't obvious, that's the first interview question, not something to guess.

Phase 1 — Jobs & journeys

1. Interview (AskUserQuestion, ≤4): who is the daily user; the hero job in

their words; session shape (glance / decide / browse / create); what brings them back tomorrow (the honest answer, not the aspirational one).

1. Write the journey set, tiered: HERO (the loop the product lives on —

exactly one or two) · DAILY · SETUP (first-run to first value) · PERIODIC. Each journey: persona, trigger, steps, surfaces, and ONE measurable acceptance criterion ("first governed action in /journeys.yaml` in /journey-qa's schema (stable ids J1..Jn) — designed here, verified there, same file. Gate: user ratifies the journey set before flows are drawn.

Phase 2 — Flow architecture

1. For each HERO + DAILY journey: entry triggers first — sessions start

OUTSIDE the app. iOS: push, widget, Live Activity, Siri, cold open. Web: the entry URL, a shared/bookmarked deep link, email, browser notification, search. Either way the trigger lands on the decision, never on home. Then the screen graph (mermaid, nodes = screens/sheets/routes, edges = user actions), then the budget per journey measured on the graph: taps on iOS (300ms without shape), error (always names the way forward), offline (what still works). First-run blank-slate states are WAYFINDERS: they demonstrate the hero loop with one-tap adoptable examples (Streaks' sample habits) rather than describing it. Every edge lands on a defined treatment — a state without a design is a defect, and NO DEAD ENDS: every screen has an exit toward the hero loop.

Phase 4 — Habit loop (ethical by construction)

1. For each HERO journey, name the loop: external/internal trigger →

simplest action → reward → investment (what the user deposits that makes tomorrow's session better). The reward IS the drama budget: the signature moment (TASTE.md law 13) sits exactly here — celebrate the job done, nothing else.

1. The ethical line (hard law, from the canon): habit through genuine

value delivered fast — never guilt, streak-shaming, fake urgency, variable rewards detached from real outcomes, or exit traps. Deliberate friction is ADDED only in the user's own interest (confirmations on consequential/irreversible actions). If retention requires a trick, the journey is wrong — redesign the journey.

Phase 5 — Validate & hand off

1. Audit: every screen in the graph belongs to ≥1 journey (orphan screens

are cut or justified); every journey meets its tap budget; every flow has its states; the hero loop's acceptance criterion is measurable.

1. Fresh-eyes walk (VERIFY.md protocol): a subagent that sees ONLY

journeys.yaml + the flow graphs role-plays each persona cold ("you got this notification — get the job done") and reports where it gets lost. needs_work → fix the architecture, not the prose.

1. Persist EXPERIENCE.md (journey set, flow graphs, navigation model,

state matrix, habit loops, tap-budget table) next to DESIGN.md. Hand off: /ios-design renders the screens (every mockup names its flow node); /journey-qa verifies the same ids before distribution.

Output format

• journeys.yaml (journey-qa schema, stable ids) + EXPERIENCE.md with

mermaid flow graphs and the tap-budget table. Progress messages show the graphs and budgets, not prose summaries.

Does not do

• Screen visuals, tokens, mockups — /ios-design or /web-design (both

consume this skill's output). Navigation implementation idioms — /swiftui-craft or /web-craft. End-to-end verification — /journey-qa (it consumes journeys.yaml). Functional QA — /dogfood. Notification/Live Activity implementation — /activitykit.

• Dark-pattern retention design — refused outright, with the reason stated.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.