Task: Start the UX language documentation: colours, icons, entity window anatomy

Table of Contents

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

  1. Create the doc. doc/knowledge/ui/ux_language.org, #+type: knowledge, title "UX Language" — sitting alongside ui_design_principles.org and icon_guidelines.org in doc/knowledge/ui/.
  2. 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).
  3. Iconography section. Link to Icon Guidelines (which carries the icon inventory); summarise the semantic rules only.
  4. Entity window anatomy section. Using the existing screenshots (tmp/ and doc/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.
  5. 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.org exists 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.

Emacs 29.1 (Org mode 9.6.6)