From 1678602fd63a9b24091467103df7b914cf9574dc Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Mon, 20 Jul 2026 17:56:18 +0200 Subject: [PATCH] docs(ui): bind interfaces to central components --- docs/UI_UX_DECISION_LEDGER.md | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/UI_UX_DECISION_LEDGER.md b/docs/UI_UX_DECISION_LEDGER.md index 0b5a9ba..dae30f3 100644 --- a/docs/UI_UX_DECISION_LEDGER.md +++ b/docs/UI_UX_DECISION_LEDGER.md @@ -43,6 +43,9 @@ contestability, responsibility, and traceability at the point of action. | UX-017 | Table row actions use icon-only controls in a stable rightmost column and intent order: inspect/open, edit, copy, transfer/share/download, retry/restore, destructive action last. Every icon requires a translated accessible name and tooltip. | Accepted | All structured tables | | UX-018 | A collapsible card containing only one table gives the table the card's full available body, without decorative inner wrappers, duplicate padding, max-widths, or nested scrolling. | Accepted | List, detail, workflow, and configuration surfaces | | UX-019 | Focused-view precedence is manual session pin, current-task suggestion, user default, role/tenant default, then the full interface. The active source and a full-interface escape remain visible; a suggested view never changes authorization or implies consent. | Accepted | Shell, modules, future workflow composition | +| UX-020 | Centrally exported Core components are mandatory wherever their contract covers the interaction. A custom reusable control, presentation primitive, or module-local substitute requires explicit product-owner authorization, a narrowly specific purpose, and documented rationale and scope; it must not duplicate a central component. | Accepted | Core WebUI and all module WebUIs | +| UX-021 | A collection-wide create action belongs in that collection's page heading and is not duplicated in a persistent side panel. When a side panel is the creation surface, it is present for the creation view only. | Accepted | List-detail, directory, and create surfaces | +| UX-022 | Use central `Card` components for logical sections, `DataGrid` for tabular row collections and their ordered actions, and `ToggleSwitch` for boolean settings. Repeatable people/contact editors use one structured row per person with name, email address, and actions; free-form address parsing is reserved for an explicitly designed bulk-import flow. | Accepted | All WebUI forms and collection editors | ## Confirmed Implementation Decisions @@ -160,6 +163,50 @@ shared CSS tokens and persisted user preference selection. - Visual preview in settings is illustrative; it must reflect token families, not become a second theme implementation. +### DUE-009: Central Component And Exception Contract + +Decision: module interfaces are compositions of the components exported by +`@govoplan/core-webui`. When Core already owns the matching interaction, using +the central component is required rather than preferred. + +A route or domain-specific page composed from central components is ordinary +module composition. A new reusable UI control, presentation primitive, or +module-local substitute is a custom component. Before one is implemented, the +product owner must explicitly authorize it and the owning decision or issue must +record: + +- its single, narrowly defined purpose and intended consumers +- why central components or their composition cannot meet that purpose +- the permitted scope and the boundary it must not grow beyond +- accessibility, reachable states, theme behavior, and test expectations +- whether the component remains domain-owned or is a candidate for Core + +Custom components must not duplicate, fork, or cosmetically replace a central +component. An existing local implementation does not grant an exception. If a +central contract later covers the need, migrate to it unless the product owner +explicitly retains the exception. + +### DUE-010: Scheduling Request Reference Composition + +Decision: Scheduling requests provide a concrete reference application of the +universal placement and component rules. + +- The `Scheduling requests` header owns one `Add` action. +- Its left panel is used for the creation view only, not as a permanent second + creation affordance. +- Basic information, Calendar integration, candidate slots, and participants + use the central `Card` component as four logical sections. +- Candidate slots and participants use the central `DataGrid`, including its + standard row-action placement and order. +- Calendar integration uses the central `ToggleSwitch`, with its dependent + controls shown when enabled. +- Each participant is edited as one structured row with name, email address, + and actions. The normal editor does not parse a free-form list of addresses; + that interaction requires a separate, explicitly designed bulk-import flow. + +Equivalent list/create/edit surfaces use the same underlying rules. These are +not Scheduling-local component variants. + ## Implementation Sequence | Phase | Scope | Output | @@ -222,6 +269,14 @@ Every new or changed admin/configuration surface should answer: - Does the action surface show consequence, reversibility, and audit evidence when rights, duties, records, money, communication, external systems, or workflow state are affected? +- Does the surface use every applicable central Core component? If it contains + a custom component, is the product-owner authorization, narrow purpose, + rationale, scope, and non-duplication evidence recorded? +- Is a collection-wide create action in the collection heading rather than + duplicated in a persistent side panel? +- Are logical sections, tabular collections, boolean settings, and repeatable + people/contact rows composed with `Card`, `DataGrid`, `ToggleSwitch`, and one + structured row per person respectively? - If automation is involved, can the user see the trigger, system actor, observed effects, and failure/manual-intervention state? - Are technical details available without being the first thing the user sees?