Skip to content
user

experience-design

Walkable design method. Outcome to independently-reviewed screens.

13 skills 3 human gates 45–90 min/session
Install this pack Read the reference

The contract

Use it when
A product team needs a full design thread — from outcome to independently-reviewed screens — before build begins.
You type
Map the customer journey for this feature.
You provide
The feature, user, and intended outcome, plus any existing brand or design-system constraints.
You receive
A complete, independently-reviewed design set — journey map, screen inventory, interaction specs, and accessibility-clean designs.

Where you decide

The agent pauses at these points. You choose whether to continue, redirect, or stop.

Approve the journeyDecision 1 of 3Approve the aesthetic directionDecision 2 of 3Review the experience designsDecision 3 of 3

What changes when you install this

After installing experience-design, every design task runs a thread: journey-mapping anchors user outcomes, user-flow derives the screen inventory, creative-direction sets the aesthetic constraint, design-system runs when its condition requires it — when a direction exists and neither a completed design system nor a coherent incumbent system supplies every concrete value the surface needs — then information-architecture and interaction-design design each screen, and an independent experience-reviewer pass reads design artifacts cold. information-architecture selects a genre method when the brief declares a surface genre. The quality floor — handle-all-states, WCAG 2.2 AA, reduced-motion — is non-negotiable at every step. You decide at three gates: the journey and screen list, the aesthetic direction, and the post-review pass before design feeds the build loop. experience-status orients to the thread at the start of any session.

The journey

Say this What happens Needed?
experience-status Orient — where the design thread is, what’s next Optional
journey-mapping Map the user’s outcome: stages, emotions, pains Required
content-design Set surface intent — what this screen says and for whom, plus per-surface copy goals and the brand register in its other two modes Required
user-flow Build the screen inventory with per-screen state briefs Required
creative-direction Anchor the aesthetic in persona and precedent Required
design-system Resolve the system’s relationships and values from the direction and the incumbent system Conditional
information-architecture Decide what goes where on each screen and how users stay oriented Required
interaction-design Design states, feedback, and animation per screen Required
ux-writing Characterize the product voice and write per-state UI copy keyed to the state matrix Optional
experience-reviewer Independent cold review — forked context, read-only. A reviewer agent the design thread dispatches, described here rather than run like the skills above Required

1. Map the customer journey

Type journey-mapping and describe the outcome you’re designing for — the user, the goal, and where the current experience breaks down.

journey-mapping

  journey  docs/design/journeys/onboarding.md

  Stage 1  Aware          finds product, expectations vague
  Stage 2  First-session  blank state, no direction, high drop-off
  Stage 3  Value          first export, relief, converts
  • You decide: read the journey and redirect it now — a one-sentence correction here is cheaper than one after screens exist. The approve-journey gate itself covers the journey and the screens derived from it, so it closes at the end of step 2.
  • Output: a journey map with the outcome, the key failure modes, and the peak, dip, and end moments marked. Screens are derived next, by user-flow.
  • State: draft

The minimal viable thread

Four steps make the output coherent. Everything else in the pack sharpens them.

  1. journey-mapping — the outcome and the failure modes
  2. user-flow — the screen list and the per-screen briefs
  3. one craft pass per screen — at minimum information-architecture, then interaction-design
  4. experience-reviewer — the cold review

experience-status tells you where you are on it. Walking the shorter thread is a real choice, not a corner cut: what a skipped step costs is that its input travels forward as an assumption nobody decided, which is why the four above are the ones that stay.

Required in the say-this table above is not the same claim as membership here. There it means the step is required for a complete thread — skipping it leaves a named gap in the output. Here it means nothing downstream can reconstruct the step’s input, so dropping it breaks the thread rather than thinning it. content-design and creative-direction are Required in that first sense and absent from this list in the second.

Pick the depth — explore is the default

The surface’s risk-tier decides how much of the shared experience contract the thread owes and how many states each per-screen brief must handle. It is a per-run choice: the same thread runs at one depth for a prototype and another for a checkout flow.

  • explore — the default. 10 of the contract’s 32 fields. States: loading, empty, error, success, content, partial, disabled, keyboard-only, reduced-motion, high-zoom.
  • pilot — 25 fields. Adds first-run, no-results, blocked, large-data-set.
  • production — 32 fields. Adds offline, long-content.

Two states sit outside the ladder and bind at every tier once their trigger fires: permission/denied on a surface behind authorization, and destructive-confirmation on a primary action that is irreversible or destroys data the user controls.

What explore drops, and what it never drops. Against production, explore drops 22 contract fields and 6 states. It drops no state the shared state-coverage map records as failing WCAG 2.2 AA when absent: all seven banded accessibility-bearing states are already in the explore set, and the eighth is destructive-confirmation, which is conditional. The quality floor’s accessibility commitments hold at every tier — depth changes how much evidence a surface owes, never whether someone can use it.

2. Derive the screen flow

Type user-flow. The agent sequences the screens implied by the journey and builds a per-screen brief for each, including the full state matrix.

user-flow

  screens  docs/design/screens/onboarding-flow.md

  /onboarding/welcome  →  /onboarding/connect  →  /onboarding/done
  States per screen: loading · empty · error · success · content · partial · disabled

Approve the journey and screen list? ›
  • You decide: the approve-journey gate closes here — you approve the journey and the screen list together, because the check that earns it is whether every screen traces to a moment in the journey.
  • Output: an approved screen inventory with per-screen briefs, ready for the craft sequence.
  • State: draft

3. Establish design intent

Type creative-direction to anchor the visual direction in persona, precedent, and platform conventions. Type design-system to resolve that direction into a buildable system.

design-system is conditional: run it when a direction exists and neither a completed design system nor a coherent incumbent system supplies every concrete value the surface needs.

creative-direction

  direction  docs/design/direction/onboarding.md

  Goals   Calm confidence, platform-native trust
  Ref     Linear's focused workspace; Notion's quiet hierarchy

Approve the aesthetic direction? ›
  • You decide: approve the direction before screens are designed — a vague direction (“clean and modern”) is a rejection.
  • Output: a named aesthetic direction and a resolved design system derived from it.
  • State: draft

4. Design each screen

Type information-architecture; when the brief declares a surface genre, it loads that genre’s method. Then type interaction-design per screen.

interaction-design [/onboarding/welcome]

  screen  docs/design/screens/onboarding/welcome.md
  States: loading · empty · error · success · content · partial · disabled ✓
  Motion: entrance · field-focus · submit-feedback ✓
  • Output: a designed screen set with all states handled and quality floor met.
  • State: draft

5. Write the screen copy

Type ux-writing to characterize the product’s voice and write the per-state strings for each screen, keyed to the state matrix user-flow produced. It loads the brand register from content-design when one exists.

ux-writing

  voice    docs/product/voice/onboarding.md

  Connect screen / error   "We couldn't reach your account. Check the address and try again."
  Connect screen / empty   "No accounts yet. Connect your first one to get started."
  • You decide: read the voice and the strings now — a stiff or blaming error message is cheaper to fix before review than after.
  • Output: a voice chart and one string per screen × state cell, blame-free and actionable.
  • State: draft

6. Review independently

Ask for an independent review of the finished design set. The experience-reviewer agent is dispatched to do it — a reviewer role rather than a skill you type. It reads your design artifacts cold, with no authoring context, and returns findings across handle-all-states, accessibility, aesthetic fit, and cross-screen coherence.

independent review — findings returned in session

  Blocker  Welcome screen: empty state not designed
  Concern  Connect screen: error text has no recovery action
  Nit      "Get started" → "Connect your first account"
  • You decide: act on Blockers before design feeds the build loop.
  • Output: a review-clean design set ready for build.
  • State: confirmed-write

What crosses to frontend engineering

Three artifacts leave this pack and are read by the frontend-engineering pre-flight. Each path is relative to the design output directory this pack is configured to write to.

Artifact Path Written by
Aesthetic direction direction/<slug>.md creative-direction
Per-screen brief screens/<slug>/<screen>.md user-flow, enriched by interaction-design
Token taxonomy tokens/<slug>.md design-system

A slot no artifact fills is not an error: the frontend pre-flight resolves that axis from a lower rung of its visual-authority precedence and records which rung supplied it.

Exception: a resolved direction beside a named-skipped token taxonomy, with no incumbent system supplying the axis, holds and routes that axis upstream. Ordinary genuinely open axes may still resolve from lower rungs.

Human gates

For each gate, everything you need to make a confident decision.

  • Approve the journey

    Trigger
    After journey-mapping and user-flow complete
    Time
    10–15 minutes
    What to check, good, bad, consequence

    What to check

    • Does the journey capture the outcome the user is trying to achieve — not just the tasks they perform in the current product?
    • Does the journey provide a clear basis for the derived screen list, rather than the existing implementation or a wish list?
    • Are the key failure modes named — the moments the current journey breaks down, and why?
    • Is every screen in the list implied by the journey? (Remove screens that aren't.)

    What good looks like

    A journey map that names the outcome, the failure modes, and a screen list with a clear derivation — each screen traceable to a moment in the journey.

    What bad looks like

    A screen list that maps to the current implementation screen-by-screen. This means the agent documented the status quo instead of designing for the outcome.

    Consequence of skipping

    The screen list is the contract for all design work that follows. A screen list derived from the wrong model means the design thread designs the wrong product — faithfully.

  • Approve the aesthetic direction

    Trigger
    After creative-direction, and after design-system when its condition requires it
    Time
    5–10 minutes
    What to check, good, bad, consequence

    What to check

    • Does the aesthetic direction name a specific visual character — not just 'clean and modern'?
    • Are the contrast ratios in the token set verified at WCAG 2.2 AA minimum?
    • Is the palette constrained to a small number of semantic roles — does adding a new color require a decision?
    • Are the values derived from the aesthetic direction, not borrowed from a generic design system?
    • Is every domain the direction reached actually resolved, rather than left for whoever writes the code?

    What good looks like

    A named aesthetic reference with a resolved system that derives directly from it, passes the contrast floor, records which authority supplied each decision, and could be handed to a developer without ambiguity.

    What bad looks like

    An aesthetic direction that could apply to any product, a system that names categories and leaves the visual decisions to implementation, or one that introduces hardcoded values outside the semantic roles.

    Consequence of skipping

    The aesthetic direction is the constraint every subsequent screen must satisfy. Approving a vague direction means screens drift with no shared reference to hold them together — and the experience-reviewer will flag every screen for the same missing constraint.

  • Review the experience designs

    Trigger
    After the experience-reviewer subagent returns findings on the completed screen designs
    Time
    15–25 minutes
    What to check, good, bad, consequence

    What to check

    • Did the reviewer flag any handle-all-states violations? (Missing empty, loading, error, or success states are the most common finding.)
    • Are all WCAG 2.2 AA requirements met — color contrast, label associations, focus order?
    • Is reduced-motion handled — are transitions guarded for users who have requested reduced animation?
    • Are the screens consistent with the approved aesthetic direction — or did any screen introduce its own visual language?

    What good looks like

    A design set that the independent reviewer marks clean — all states handled, accessibility floor met, aesthetic direction consistently applied across every screen.

    What bad looks like

    Screens that look good in the happy-path state but have no designed empty state, loading state, or error recovery. Or screens that pass visually but fail the accessibility audit.

    Consequence of skipping

    The experience-reviewer is the design analogue of adversarial-reviewer in the build loop. Its findings are the last check before design intent feeds the build. An unreviewed design is a set of unverified assumptions about how the product behaves when things go wrong.

Typical session

Agent turns
8–15
Human gates
3
Wall-clock time
45–90 min

Install

agentbundle install --pack experience-design --scope user

Skills in this pack

  • journey-mapping1 gate

    Maps the current and desired customer journey to derive the key touchpoints and failure modes a product must address.

  • content-design

    The copy layer in three modes: a content brief for a surface, per-surface acquisition copy goals, or the brand-level register every per-surface goal references.

  • user-flow1 gate

    Derives the screen inventory and flow from the customer journey — what screens exist, what state each handles, what the transitions are.

  • service-blueprint

    Maps front-stage screen flows to the back-stage processes and human actors that support them — the service blueprint.

  • process-mapping

    Documents the internal processes that run behind user-facing screens — the APQC/BPMN model of what people do.

  • design-principles

    Converts journey-map insights into 3–5 named design principles — decision rules that resolve disputes and persist across sprints, each grounded in a journey moment.

  • creative-direction1 gate

    Establishes the visual direction for a surface — named emotional and brand goals grounded in stable referents — as the aesthetic reference all subsequent screens must satisfy.

  • design-system

    Resolves the design system from the creative direction and whatever system the product already has — the relationships that must hold and the values that make them buildable.

  • information-architecture

    Designs the layout zones and information hierarchy for a screen, selecting the analytical, marketing, documentation, informational, marketplace, or workspace genre method when the brief declares one.

  • interaction-design

    Designs the interactive behaviors for a screen — states, transitions, feedback patterns — against WCAG 2.2 AA.

  • design-review

    Reviews an existing screen design against the quality floor — handle-all-states, accessibility, reduced-motion — before the independent review.

  • ux-writing1 gate

    Characterizes the product voice and writes blame-free, actionable per-state UI copy keyed to the screen flow's state matrix.

  • experience-status

    Orients to the current design thread at a glance — reads design artifacts from the configured output directory and surfaces what exists, what's missing, and which skill to run next.

Technical reference & next steps