# ADR-0008 — A UI change ships an app flow, drawn in Mermaid (/docs/maintain/adr/ADR-0008-a-ui-change-ships-an-app-flow)

- **Status:** Approved
- **Date:** 2026-10-31
- **Deciders:** [@puncoz](https://github.com/puncoz)
- **Approved by:** [@puncoz](https://github.com/puncoz)
- **Approved on:** 2026-11-01
- **Supersedes:** —
- **Superseded by:** —
- **Design documents:** `content/docs/maintain/app-flow/index.mdx`, `content/docs/maintain/_templates/app-flow.mdx`, `AGENTS.md` §2

## Context [#context]

An ADR's text says what is decided. It rarely shows what a reader will see, and UI mistakes
(a missing state, a confusing navigation, a buried install command) are cheapest to catch
before code. A documentation site lives or dies on how fast a reader gets from a search or a
package name to the snippet they need.

The owner wants diagrams, flows and screens drawn in **Mermaid**: flowcharts for flows and
`block-beta` diagrams for wireframes.

## Decision [#decision]

1. **Any ADR that adds or changes something a person sees ships
   `content/docs/maintain/app-flow/<feature-slug>.mdx`**, reviewed together with the ADR.
2. It contains:
   - **entry points**, and who does not see the feature;
   - **the flow** as a Mermaid flowchart;
   - **one wireframe per screen** as a Mermaid `block-beta` diagram, phone width first, with
     invented sample values;
   - **each screen's states**: empty, loading, not found, refused, error, degraded, success.
3. **One file per feature, living** (ADR-0002): later ADRs that change the feature's UI edit it
   in place.
4. Not required for bug fixes, for content within the approved conventions, or for ADRs that
   change nothing visible. If unsure, write it.

## Options considered [#options-considered]

| Option | Pros | Cons | Verdict |
|---|---|---|---|
| A — Mermaid flow + `block-beta` wireframes | Matches the owner's instruction; renders on GitHub; diffs as text | `block-beta` is coarse for detailed layout | Chosen |
| B — Plain-text ASCII mockups | Precise layout; no renderer needed | Doesn't match the owner's instruction | Rejected |
| C — Design tool images | High fidelity | Binary, external, don't diff, drift | Rejected |

## Consequences [#consequences]

**Positive**

- The owner reviews what readers will see, not just what will be built.

**Negative / accepted trade-offs**

- Wireframes are approximate; visual design is decided in its own ADR(s).

## Content invariants [#content-invariants]

Supports §6.5 (every page readable as Markdown) by putting each page type's Markdown entry
points up for review with the screens.

## Security considerations [#security-considerations]

Wireframes use invented values only — never a private project's name or details.

## Implementation notes [#implementation-notes]

- [x] `content/docs/maintain/app-flow/index.mdx` and `content/docs/maintain/_templates/app-flow.mdx` exist.
- [x] `AGENTS.md` §2 describes the requirement.
- Tests: not applicable (process only).

> Approved as written on 2026-11-01, by the owner's choice. `AGENTS.md` §2 and §8 add, by the
> owner's standing choice, that the flow is made with Archify with its Mermaid version kept in
> the page; HTML prototypes are not made.

## Docs to update on implementation [#docs-to-update-on-implementation]

- [x] `content/docs/maintain/adr/index.mdx` — status.