Skip to content

UI Documentation

Scope: the documentation surface for every user-facing UI in the CVNTrade platform. Bound by ADR-0066 — the UI stack decision.

This page is the entry point for anyone (operator, designer, developer, committee reviewer) who needs to understand where the UI artefacts live, how they cross-link, and what the workflow is for adding or changing a screen.

Six-tool stack (ADR-0066)

Tool Single responsibility
Figma Visual experience — mockups, interactions, screens, states, mobile breakpoints
MkDocs (this folder) Project UI documentation — per-screen pages, flows, design-system catalogue, acceptance criteria
Structurizr (workspace.dsl) System architecture — where UI containers fit. Not pixels
Mermaid (inside MkDocs pages) Flows — user journeys, sequences, approval workflows
Storybook (under console-next/, bootstrapped by CVN-N008-EA) Coded components — live states, a11y notes, props
Next.js (same folder) Implementation — App Router pages, API integration

ID scheme

Four prefixes, shared across every tool:

Prefix Meaning Example
UI-<area>-<nnn> Screen UI-CONFIG-001
FLOW-<area>-<nnn> User flow FLOW-CONFIG-003
CMP-<area>-<nnn> Coded component CMP-CONFIG-005
ADR-UI-<nnn> UI-level decision ADR-UI-001

<area> is the top-level surface: CONFIG, TRADING, ADMIN, RUNS, DASHBOARD, etc. IDs are append-only — retirement via Deprecated status, never renumbering.

Workflow (normative)

flowchart LR
  A[Need / Story
created] --> B[Wireframe
in Figma]
  B --> C[MkDocs page
per-screen template]
  C --> D{Architecture
impact?}
  D -->|yes| E[Update
workspace.dsl]
  D -->|no| F[Storybook story
per component]
  E --> F
  F --> G[Next.js
implementation]
  G --> H[PR with links
Figma + Docs + Storybook]
  H --> I[MkDocs page
marked Implemented]
  1. Need / story — filed in OpenProject or GitHub. Carries the first UI-<area>-<nnn> if a new screen, or references existing IDs
  2. Figma frame — wireframe + screens + states. Frame name includes the UI-<area>-<nnn>. Frame status tag: Draft / Ready for Dev / Implemented / Deprecated
  3. MkDocs page — created at documentation/ui/<area>-<slug>.md using the canonical template (§below)
  4. Architecture impact — if a new container / API / relationship is introduced, update documentation/architecture/workspace.dsl in the same PR
  5. Storybook story — one .stories.tsx per component in the screen. States: default / loading / error / disabled at minimum
  6. Next.js implementation — wired to the Storybook story, routes in App Router
  7. PR — body carries links to Figma frame, MkDocs page, Storybook story
  8. Docs updated — MkDocs page's frontmatter or top block flipped from Draft to Implemented after the PR merges

Canonical per-screen template

Every screen under documentation/ui/ follows this structure:

# <Screen name>

**UI ID**: `UI-<area>-<nnn>`
**Status**: `Draft | Ready for Dev | Implemented | Deprecated`
**Introduced by**: `CVN-N<nnn>-US<m>`
**Figma frame**: <link>

## Purpose
<Why this screen exists, who uses it, when.>

## User flow
```mermaid
flowchart LR
  Start --> Step1 --> Decision{…} --> End
```

## Components
- `CMP-<area>-<nnn>` — ComponentName (Storybook story link)
- ...

## Implementation
- **Next.js route**: `/admin/config`
- **Storybook stories**: `ComponentName.stories.tsx`
- **API contract**: `<link to spec>`

## Acceptance criteria
- [ ] <criterion 1>
- [ ] <criterion 2>

Current coverage

Surface Status Source
Configuration Console Draft — first screen from CVN-N008-EA placeholder
Design System Draft — component catalogue placeholder
User Flows Draft — operator flows for CVN-N008 placeholder

References