ADR-0008 — A UI change ships an app flow, drawn in Mermaid

• Status: Approved
• Date: 2026-10-31
• Deciders: P@puncoz
• Approved by: P@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

ContextCopy Anchor Link

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.

DecisionCopy Anchor Link

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 consideredCopy Anchor Link

ConsequencesCopy Anchor Link

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 invariantsCopy Anchor Link

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

Security considerationsCopy Anchor Link

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

Implementation notesCopy Anchor Link

• content/docs/maintain/app-flow/index.mdx and content/docs/maintain/_templates/app-flow.mdx exist.
• 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 implementationCopy Anchor Link

• content/docs/maintain/adr/index.mdx — status.