Skip to content

Wireframe

Purpose

Wireframe is the view-level layout and state artifact. Its unique job is to record what is in one view, where, what each element does, and which states the view moves through, so builders and reviewers share one picture. States left implicit are the states that ship broken, so the wireframe names them all. The solution or technical design links the wireframe by ID.

Example

Show a worked example of this artifact
---
ddx:
  id: example.wireframe.depositmatch.mapping-review
  type: wireframe
  authoring:
    home: repo
  depends_on:
    - example.user-flow.depositmatch.csv-import
---

# UF-001-02-mapping-review: Mapping Review

**User flow**: [[UF-001]] view `mapping review` | **Stories**: [[US-002]]

## Scope and Fidelity

- **View**: Confirm which columns hold amount, date and identifier in each file before rows are validated.
- **Modality**: screen
- **Fidelity**: mid
- **Size classes**: compact, expanded
- **Pattern**: Form with a mapping table

## Layouts

### Expanded

```text
┌─────────────────────────────────────────────────────────────┐
│ [Back to client]   Acme Dental · Import 2026-05-08          │
├──────────────────────────────┬──────────────────────────────┤
│ [Bank file mapping]          │ [Invoice file mapping]       │
│  Amount  → [column picker]   │  Amount  → [column picker]   │
│  Date    → [column picker]   │  Date    → [column picker]   │
│  ID      → [column picker]   │  ID      → [column picker]   │
│ [Sample rows]                │ [Sample rows]                │
├──────────────────────────────┴──────────────────────────────┤
│ [Saved mapping note]                      [Confirm mapping] │
└─────────────────────────────────────────────────────────────┘
```

### Compact

```text
┌──────────────────────────┐
│ [Back to client]         │
│ [File tabs: Bank|Invoice]│
│ [Bank file mapping]      │
│  Amount → [column picker]│
│  Date   → [column picker]│
│  ID     → [column picker]│
│ [Sample rows]            │
├──────────────────────────┤
│ [Confirm mapping]        │
└──────────────────────────┘
```

### Annotations

| Element | Kind | Annotation | Size classes | Links |
|---|---|---|---|---|
| Back to client | control | Returns to the client workspace; the draft session is kept. | all | none |
| File tabs | control | Switches between the bank and invoice mappings. | compact | none |
| Bank file mapping | region | One column picker per required field, preselected from the saved mapping when there is one. | all | US-002-AC1 |
| Invoice file mapping | region | As for the bank file. Beside it on expanded; behind the tab on compact. | differs | US-002-AC1 |
| Column picker | control | Lists the file's column headers. A required field left empty is flagged when the mapping is confirmed. | all | US-002-AC2 |
| Sample rows | content | The first five rows under the chosen columns, so a wrong pick is visible before import. | all | none |
| Saved mapping note | content | "Using the mapping saved on 2026-05-01. Changes are saved when you confirm." | expanded | US-002-AC1 |
| Confirm mapping | control | Checks the required fields and starts validation. Busy while checking; blocks a second click. | all | UF-001 Confirm mapping |

## States and Events

### States

| State | Applies | Entered when | Person sees | Available actions | Announcement | Exit |
|---|---|---|---|---|---|---|
| ideal | yes | Columns read from both files | Pickers, sample rows | Pick columns, Confirm mapping, Back to client | none; focus on the heading | CONFIRM |
| empty | no: both files are already attached when this view opens | | | | | |
| loading | yes | View opens | Skeleton pickers | Back to client | none; focus on the heading "Loading columns" | COLUMNS_READ, READ_FAILED |
| partial | no: both files' columns are read together | | | | | |
| error | yes | A file's columns cannot be read | "We couldn't read the invoice file's columns" and the reason | Upload again, Back to client | "Couldn't read the file's columns" (assertive) | REUPLOAD |
| offline | yes | Connection lost | Banner "You're offline; mappings are kept"; Confirm mapping disabled | Pick columns, Back to client | "You're offline" (polite) | CONNECTION_RESTORED |
| slow | yes | Loading takes longer than 3 s | Skeleton and "Still reading columns" | Back to client | "Still reading the files" (polite) | COLUMNS_READ, READ_FAILED |
| permission-denied | no: anyone who can open the workspace can import | | | | | |
| success | no: a confirmed mapping moves straight to validation results | | | | | |
| checking | yes | Confirm mapping pressed | Confirm mapping busy | none; checking takes under a second | "Checking the mapping" (polite) | COMPLETE, MISSING |
| missing | yes | A required field is unmapped | Inline error naming each missing field; picks kept | Pick columns, Confirm mapping | "Amount is not mapped in the invoice file" (assertive) | CONFIRM |

### Statechart

```mermaid
stateDiagram-v2
  [*] --> loading
  loading --> slow: AFTER_3S
  loading --> ideal: COLUMNS_READ
  slow --> ideal: COLUMNS_READ
  loading --> error: READ_FAILED
  slow --> error: READ_FAILED
  error --> [*]: REUPLOAD
  ideal --> checking: CONFIRM
  missing --> checking: CONFIRM
  checking --> missing: MISSING
  checking --> [*]: COMPLETE
  ideal --> offline: CONNECTION_LOST
  offline --> ideal: CONNECTION_RESTORED
```

### Events

| Event | From | Guard | To | Effect |
|---|---|---|---|---|
| AFTER_3S | loading | none | slow | Show "Still reading columns" |
| COLUMNS_READ | loading, slow | none | ideal | Preselect the saved mapping |
| READ_FAILED | loading, slow | none | error | Focus moves to the error message |
| REUPLOAD | error | none | final | User flow returns to upload |
| CONFIRM | ideal, missing | none | checking | Check required fields |
| MISSING | checking | a required field is unmapped | missing | Focus moves to the first missing picker; picks kept |
| COMPLETE | checking | every required field is mapped | final | Save the mapping; user flow goes to validation results |
| CONNECTION_LOST | ideal | none | offline | Disable Confirm mapping |
| CONNECTION_RESTORED | offline | none | ideal | Enable Confirm mapping |

## Accessibility

- **Focus order**: Back to client, File tabs (compact), each column picker in the bank file then the invoice file, Confirm mapping.
- **Accessible names**: each picker is named by field and file ("Invoice file: amount column").
- **Headings and landmarks**: h1 "Map columns for Acme Dental"; each file's mapping is a labelled region.
- **Target size and input**: pickers and Confirm mapping at least 44 × 44 px on coarse input.

## Open Questions

- Should the saved mapping note appear on compact? Product decides; it is hidden there today to keep the pickers above the fold.

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}-{nn}-{view}.md
RequiresNone
EnablesNone
InformsTechnical Design
Story Test Plan
Generation prompt
Show the full generation prompt
# Wireframe Generation Prompt

Lay out one view of a user flow at each size class it supports, annotate every
element a person can act on, and name every state the view can be in.

## Purpose

Wireframe is the **view-level layout and state artifact**. Its unique job is
to record what is in one view, where, what each element does, and which states
the view moves through, so builders and reviewers share one picture. States
left implicit are the states that ship broken, so the wireframe names them
all. The solution or technical design links the wireframe by ID.

## Focus

- Create `docs/helix/02-design/flows/UF-XXX-[feature]/UF-XXX-NN-[view].md`
  beside its user flow. NN is a two-digit number given once, when the
  wireframe is created: the next number not yet used in that folder. Keep it
  when views are added, removed or reordered; never renumber an existing
  wireframe, and do not reuse a retired number. Put images in the folder's
  `assets/`. Set `ddx.type: wireframe`.
- Take the view's name, actions and transitions from the user flow.
- State the modality (screen, voice or chat) and the fidelity first, and
  annotate to the fidelity's depth:
  - **sketch**: the idea each region serves;
  - **low**: layout decisions: regions, order, what is primary;
  - **mid**: functionality: what each control does, validation, destination;
  - **high**: interaction, exact content, every state, accessibility.
- Draw one layout per supported size class. For voice or chat, the layout is
  the turn: what the system says, what the person can say or choose, and the
  confirmation.
- Label elements on the drawing by name and keep the words in the Annotations
  table. Give every interactive element a row that names the transition it
  triggers. Do not number rows.
- Fill the States table first. Each of ideal, empty, loading, partial, error,
  offline, slow, permission-denied and success either applies or is excluded
  with a concrete reason. Add view-specific states such as saving or
  streaming.
- For every state, give what the person sees, the available actions, the
  announcement (text and politeness, or the focus move that carries it) and the
  events that leave it. Say whether an error keeps what the person entered.
- Draw a Mermaid `stateDiagram-v2`, and keep it, the States table and the
  Events table in agreement.
- Note focus order, accessible names, headings and landmarks, and target size.
- Reference DESIGN.md tokens; do not define colors, type or spacing.

## Boundary Test

| If you are writing... | Put it in... |
|---|---|
| Layout, element purpose, states, events, announcements of one view | Wireframe |
| Movement between views | User Flow |
| The app-wide convention for how a loading or error state looks | DESIGN.md |
| Exact error codes or payloads that trigger a state | Contract |
| Component props, files, state management | Technical Design |
| Which test drives which state | Story Test Plan |

## Completion Criteria

- Modality and fidelity stated; annotation depth matches the fidelity.
- One layout per supported size class.
- Every interactive element annotated and linked to the flow.
- Every standard state applies or is excluded with a reason.
- Every state has an exit, and an announcement where focus does not carry it.
- Statechart and tables agree.
- Accessibility notes present.
Template
Show the template structure
---
ddx:
  id: UF-XXX-NN-view-name
  type: wireframe
  authoring:
    home: repo
  depends_on:
    - UF-XXX
    - US-XXX
---

# UF-XXX-NN-view-name: [View Name]

**User flow**: [[UF-XXX]] view `[view name]` | **Stories**: [[US-XXX]]

## Scope and Fidelity

- **View**: [What this view is for: its one task]
- **Modality**: [screen | voice | chat]
- **Fidelity**: [sketch | low | mid | high]
- **Size classes**: [compact, medium, expanded]
- **Pattern**: [Design-system or SDK pattern, if one is used]

<!-- Annotation depth by fidelity:
sketch: the idea each region serves.
low: layout decisions: regions, order, what is primary.
mid: functionality: what each control does, validation, where it goes.
high: interaction, exact content, every state, accessibility. -->

## Layouts

<!-- One layout per size class. Label elements on the drawing by name and keep
the words in the Annotations table. Use an image under assets/ or a box
drawing. For voice or chat, the layout is the turn: what the system says, what
the person can say or choose, and the confirmation. -->

### [Size class]

```text
┌──────────────────────────────┐
│ [Header]                     │
├──────────────────────────────┤
│ [Main region]                │
│                              │
│ [Primary action]             │
└──────────────────────────────┘
```

### Annotations

<!-- One row per element, named as on the drawing. Kind: region | control |
content | feedback. Every interactive element has a row. Links: the user-flow
transition it triggers, an acceptance criterion, or a DESIGN.md token. -->

| Element | Kind | Annotation | Size classes | Links |
|---|---|---|---|---|
| [Element] | [region / control / content / feedback] | [What it is for or does, at the stated fidelity] | [all, or which] | [transition, US-XXX-ACn, token] |

## States and Events

### States

<!-- Every standard state either applies or is excluded with a concrete
reason. Add view-specific states (saving, streaming, editing) as needed.
Announcement: the text a screen reader hears and its politeness (polite or
assertive), or the focus move that carries the change. -->

| State | Applies | Entered when | Person sees | Available actions | Announcement | Exit |
|---|---|---|---|---|---|---|
| ideal | yes | [event or condition] | [What is shown] | [Actions, or "none" and why] | ["Text" (polite)] | [Events that leave] |
| empty | [yes / no: reason] | | | | | |
| loading | | | | | | |
| partial | | | | | | |
| error | | | | | | |
| offline | | | | | | |
| slow | | | | | | |
| permission-denied | | | | | | |
| success | | | | | | |

### Statechart

```mermaid
stateDiagram-v2
  [*] --> loading
  loading --> ideal: LOADED
  loading --> error: FAILED
  error --> loading: RETRY
```

### Events

| Event | From | Guard | To | Effect |
|---|---|---|---|---|
| [EVENT] | [state] | [condition or none] | [state] | [What the system does: request, focus move, input kept] |

## Accessibility

- **Focus order**: [Elements in order]
- **Accessible names**: [Icon-only and ambiguous controls with their names]
- **Headings and landmarks**: [View heading, regions]
- **Target size and input**: [Touch targets on coarse input; keyboard shortcuts]

## Open Questions

- [A layout, content or state decision still open, and who decides, 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/wireframe.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:73d23803…6bbc7905

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/wireframe/",
        "digest": {
          "alg": "sha256",
          "value": "73d238036aab97212f36e8bb0edf986a876220015ee061152fbee02b6bbc7905"
        }
      }
    ],
    "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": "eqn6S6AeswlefX_qSC2WpkCcTmH2zNPRyH8m2PS4hAzwgm1xtotNzN9W4NfuEIlF52pgQLdOGpakP26caUcTAQ",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}