Task: Start the UX language documentation: colours, icons, entity window anatomy
This page documents a task in the Badge colour semantics: reserve gray for inactive states story. It captures the goal, current status, acceptance, and any notes or results.
Goal
Start the project's UX language documentation: a single umbrella doc that states the visual-language rules (colours, icons, window anatomy) and links to the existing per-aspect documents. Today the icon inventory lives in Icon Guidelines and badge mechanics in the badge-system design plan, but there is no place that documents the language: what colours mean, what a typical entity window looks like, and how the pieces relate.
Scope
- Create the doc.
doc/knowledge/ui/ux_language.org,#+type: knowledge, title "UX Language" — sitting alongsideui_design_principles.organdicon_guidelines.orgindoc/knowledge/ui/. - Colour semantics section. The rules established in this story:
- Gray (
#6b7280) is reserved for inactive, off, "no", never-used or otherwise negative/dormant states. No positive or neutral-active badge may be gray. - Orange (
#f97316) is the fallback for unresolved badge definitions — a visible "definition missing" signal, never a semantic colour. - A catalogue table of all badge definitions with hex colours and
semantics, mirroring
dq_badge_system_populate.sql(note the populate script is the source of truth; the table documents intent).
- Gray (
- Iconography section. Link to Icon Guidelines (which carries the icon inventory); summarise the semantic rules only.
- Entity window anatomy section. Using the existing screenshots
(
tmp/anddoc/assets/images/), document the standard windows of a typical entity: MDI list window (toolbar: Reload/Add/Edit/Delete/History; badge columns; "Showing all records (N)" footer; paging controls and page size), detail dialog (form, provenance, badges, change-reason flow), and history dialog. Describe paging behaviour. - Link it in.
ui_design_principles.org→ link to UX Language.- Badge design plan doc → note pointing at UX Language for colour rules.
icon_guidelines.org→ backlink.- Developer Links page (
doc/developer.org) → add a UX Language entry.
Acceptance
doc/knowledge/ui/ux_language.orgexists with the four sections above.- Gray and orange rules stated; badge colour catalogue present.
- Entity window anatomy documented with at least one annotated screenshot per window type, including paging.
- Links present in ui_design_principles, badge design doc, icon guidelines and the Developer Links page.
- Site builds cleanly.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent story | Badge colour semantics: reserve gray for inactive states |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing — task closed. |
| Last touched | 2026-06-04 |
Plan
(Transient implementation strategy. Written when work starts;
distilled into the parent story's * Decisions and cleared when the
task closes. Plans do not outlive their task.)
Notes
PRs
| PR | Title |
|---|---|
| #1051 | [doc] UX Language: colour semantics, badge catalogue, entity window anatomy |
Review
| # | Comment summary | File | Decision | Notes |
|---|---|---|---|---|
| 1-4 | Image paths should be ../../ not ../../../ | ux_language.org | Declined | Images live in assets/images/ at repo root; doc/assets does not exist. Verified on disk + green site build. |
Result
Created doc/knowledge/ui/ux_language.org (UX Language) with the four
sections: colour semantics (the gray and orange rules plus a ten-colour
vocabulary table), the badge colour catalogue (all 36 definitions, with
the populate script noted as source of truth), iconography (linking the
Icon Guidelines inventory), and entity window anatomy (MDI list window
with toolbar/badges/paging, detail dialog with provenance and
change-reason flow, history dialog — illustrated with four screenshots).
Inbound links added from ui_design_principles, icon_guidelines, the
badge system design plan (note box) and a new Design and UX section on
the Developer Links page. Site build green locally.