Skip to content

User Flow

Purpose

User Flow is the feature-level flow artifact. Its unique job is to record the views (screens, modals, panels, voice or chat turns), the actions that connect them, the decision points, the entry and exit points and every alternate path, with the feedback the person sees on each transition.

HELIX retired ux-design as a monolithic artifact. User Flow does not revive it: it carries only the flow, in a shape a tool can generate and check. The solution design links UF-XXX instead of restating views and transitions, and the rationale for choosing this flow over another stays in the solution design.

Example

Show a worked example of this artifact
---
ddx:
  id: example.user-flow.depositmatch.csv-import
  authoring:
    home: repo
  depends_on:
    - example.feature-specification.depositmatch.csv-import
    - example.user-story.depositmatch.upload-csv
---

# UF-001: CSV Import User Flow

**Feature**: [[FEAT-001]] CSV Import and Column Mapping | **Solution design**: [[SD-001]] | **Journey maps**: [[UJM-001]]

## Scope

- **Covers**: Upload, mapping review, validation results and the import summary for one client's import session.
- **Entry points**: "New import" on a client's reconciliation workspace; "Resume import" on a draft session.
- **Exits**: Match review (FEAT-002) after the summary is confirmed; back to the client workspace.
- **Size classes**: compact, expanded. On compact, validation results show one rejected row per card instead of a table.
- **Out of scope**: Match review (UF-002).

## Views

| View | Kind | Purpose | Stories | Wireframe |
|---|---|---|---|---|
| upload | screen | Attach this week's bank and invoice CSV files | US-001 | [[UF-001-01-upload]] |
| mapping review | screen | Confirm or adjust which columns hold amount, date and identifier | US-002 | [[UF-001-02-mapping-review]] |
| columns complete? | decision | Check every required column is mapped | US-002 | none |
| validation results | screen | See which rows were rejected and why | US-003 | [[UF-001-03-validation-results]] |
| import summary | screen | Confirm what will be imported before matching starts | US-003 | [[UF-001-04-import-summary]] |
| match review | external | FEAT-002 takes over | none | none |

## Flow Diagram

```mermaid
flowchart LR
  entry([New import / Resume import]) --> upload[upload]
  upload -- "Upload files" --> mapping[mapping review]
  mapping -- "Confirm mapping" --> complete{columns complete?}
  complete -- "Columns missing" --> mapping
  complete -- "Columns complete" --> results[validation results]
  results -- "Back to mapping" --> mapping
  results -- "Continue to summary" --> summary[import summary]
  summary -- "Discard import" --> upload
  summary -- "Confirm import" --> exit([match review])
```

## Transitions

| Action | From | Control | Guard | To | Feedback | Changed region |
|---|---|---|---|---|---|---|
| Upload files | upload | "Upload" button | both files are CSV | mapping review | Progress per file; a non-CSV file is rejected inline before parsing | full view |
| Confirm mapping | mapping review | "Confirm mapping" button | none | columns complete? | Button busy; second click blocked | action bar |
| Columns missing | columns complete? | none (system) | a required column is unmapped | mapping review | Inline error names each missing column; chosen mappings kept | mapping table |
| Columns complete | columns complete? | none (system) | every required column is mapped | validation results | Validation progress, then the rejected-row count | full view |
| Back to mapping | validation results | "Back to mapping" link | none | mapping review | Mappings shown as last confirmed | full view |
| Continue to summary | validation results | "Continue" button | none | import summary | Summary counts | full view |
| Discard import | import summary | "Discard import" button | none | upload | Toast "Import discarded" with Undo for 10 s | full view |
| Confirm import | import summary | "Confirm import" button | not already confirmed | match review | Button busy; toast "Import confirmed"; match suggestions start | full view |

## Alternate Paths

| Path | Trigger | Transitions | Recovery |
|---|---|---|---|
| Error | A required column is not mapped | Confirm mapping → Columns missing | Map the column and confirm again; other mappings kept |
| Error | Confirming the import fails to save | Confirm import | Inline error with "Try again"; nothing is imported until it succeeds |
| Cancel | The reviewer abandons the import | Discard import | Undo in the toast restores the draft session |
| Empty | Every row is rejected | Columns complete → validation results | "Continue" is disabled with the reason; "Back to mapping" stays available |
| Permission denied | Cannot occur: anyone who can open a client's workspace can import for it | none | none |

## Story Traceability

| Journey | Task | Stories / ACs | Path |
|---|---|---|---|
| import weekly files | Import a client's weekly files | US-001-AC1, US-002-AC1, US-003-AC1 | Upload files → Confirm mapping → Columns complete → Continue to summary → Confirm import |
| import weekly files, wrong file type | Import a client's weekly files | US-001-AC2 | Upload files rejected; stays on upload |
| import weekly files, missing column | Import a client's weekly files | US-002-AC2 | Upload files → Confirm mapping → Columns missing → Confirm mapping |

## Dead Ends

- None. Match review is FEAT-002's flow (UF-002).

Reference

ActivityDesign — Decide how to build it. Capture trade-offs, contracts, and architecture decisions.
Default locationdocs/helix/02-design/flows/UF-{n}-{feature}/UF-{n}.md
RequiresNone
EnablesNone
InformsWireframe
Solution Design
Story Test Plan
Generation prompt
Show the full generation prompt
# User Flow Generation Prompt

Describe how people move through one feature's views: what each action does,
what they see while it happens, and every way it can go wrong.

## Purpose

User Flow is the **feature-level flow artifact**. Its unique job is to record
the views (screens, modals, panels, voice or chat turns), the actions that
connect them, the decision points, the entry and exit points and every
alternate path, with the feedback the person sees on each transition.

HELIX retired `ux-design` as a monolithic artifact. User Flow does not revive
it: it carries only the flow, in a shape a tool can generate and check. The
solution design links `UF-XXX` instead of restating views and transitions, and
the rationale for choosing this flow over another stays in the solution design.

## Focus

- Create `docs/helix/02-design/flows/UF-XXX-[feature]/UF-XXX.md`, numbered
  after the governing feature. The feature's wireframes go in the same folder.
- List every view once, named by what it is. A modal or panel is its own view.
  A state of a view (loading, empty, error) is not a view; its wireframe's
  States and Events section holds it.
- Name each transition by its action. For each, give the control that triggers
  it, any guard, the target view, the feedback and the changed region. Do not
  number rows; paths and links use the action names.
- Name a decision view for every branch the person or the system takes.
- Give every action that can fail, be cancelled, return nothing or be denied
  its alternate path. If one cannot occur, say why.
- Keep the Mermaid diagram and the Transitions table identical in content.
- Trace every journey to a path of named transitions and the `US-<n>-AC<m>`
  IDs it proves. Name the Task Model row the journey carries out.
- Do not specify layout (the wireframe owns it) or visual values (DESIGN.md
  owns them).

## Boundary Test

| If you are writing... | Put it in... |
|---|---|
| Views, actions, controls, guards, feedback, alternate paths | User Flow |
| Why this flow was chosen over another; component decomposition | Solution Design |
| Exact route, API or event surface behind a transition | Contract |
| Layout, states and events of one view | Wireframe |
| One person's experience across several stories | User Journey Map |
| Which test walks which path | Story Test Plan |

## Completion Criteria

- Entry and exit points named; every view reachable.
- Every transition names its action, control, feedback and target.
- Every action that can fail, be cancelled or return nothing has an alternate
  path.
- Diagram and table agree.
- Every journey traced to named transitions and acceptance criteria.
Template
Show the template structure
---
ddx:
  id: UF-XXX
  authoring:
    home: repo
  depends_on:
    - FEAT-XXX
    - US-XXX
---

# UF-XXX: [Feature Name] User Flow

**Feature**: [[FEAT-XXX]] | **Solution design**: [[SD-XXX]] | **Journey maps**: [[UJM-XXX]] or none

## Scope

- **Covers**: [The views this feature owns]
- **Entry points**: [Where people arrive from: a navigation destination, a deep link, a notification]
- **Exits**: [Where the flow hands off: another feature, an external system, sign-out]
- **Size classes**: [compact, medium, expanded] [Note where the flow differs by size class]
- **Out of scope**: [Adjacent flows owned elsewhere, by UF ID]

## Views

<!-- Kind: screen | modal | panel | turn (voice or chat) | external | decision.
One row per view, named by what it is. Each view other than external and
decision gets a wireframe, UF-XXX-NN-view, in this folder. -->

| View | Kind | Purpose | Stories | Wireframe |
|---|---|---|---|---|
| [view name] | screen | [The one task this view serves] | [US-XXX] | [[UF-XXX-01-view-name]] |

## Flow Diagram

<!-- Views and transitions match the tables. Label each edge with its action.
Use a diamond for decisions and a stadium for entry and exit. -->

```mermaid
flowchart LR
  start([Entry]) --> a[View A]
  a -- "Action" --> b[View B]
  b -- "Action" --> d{Decision}
  d -- "yes" --> c[View C]
  d -- "no" --> a
```

## Transitions

<!-- One row per transition, named by its action. Control: what the person
activates. Guard: the condition, or none. Feedback: what the person sees during
and after. Changed region: full view, or the part that changes. -->

| Action | From | Control | Guard | To | Feedback | Changed region |
|---|---|---|---|---|---|---|
| [Action] | [view] | [control] | [condition or none] | [view] | [progress / success / error / undo] | [full view or region] |

## Alternate Paths

<!-- Every action that can fail, be cancelled, return nothing or be denied.
Name the transitions the path uses, or say why it cannot occur. -->

| Path | Trigger | Transitions | Recovery |
|---|---|---|---|
| Error | [What fails] | [Action → Action] | [How the person recovers; is their input kept?] |
| Cancel | | | |
| Empty | | | |
| Permission denied | | | |

## Story Traceability

<!-- Journey: the journey's name. Task: the feature specification's Task Model
row it carries out. Path: the named transitions in order. -->

| Journey | Task | Stories / ACs | Path |
|---|---|---|---|
| [journey name] | [task name] | [US-XXX-AC1, US-XXX-AC2] | [Action → Action → view] |

## Dead Ends

- [A view with no exit, an unreachable view or an unresolved branch, or "None"]
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/design/user-flow.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:f8176dd2…ce003039

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/design/user-flow/",
        "digest": {
          "alg": "sha256",
          "value": "f8176dd22bf8a4d76a9ecec6fa8f9e6b100e1e3ec2728f4b0d3a5e74ce003039"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "iZiX7yrsqZKH1wEU5nzxmCMqD_jhN5vYWOzvJf3MO2hNtGX3mHpCDFtGXDoGvU8LpiZfqcqdwr_LPBtgGdhyCg",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}