docs(ui): codify universal interaction patterns

This commit is contained in:
2026-07-21 20:48:55 +02:00
parent 89771d96fb
commit 097f9ca2f4
2 changed files with 51 additions and 9 deletions

View File

@@ -23,6 +23,10 @@ Principles:
panels, calendar list panels, or mailbox folder panels.
- Keep collection navigation and collection-level actions close to the relevant
pane header.
- In a list-detail workspace such as Scheduling, keep related lists stacked in
the left pane and use the remaining main pane for view/create/edit. A single
Add action stays in the relevant list-pane header and opens the common main
editor; it does not create an additional menu or launcher.
- Use bounded widths for navigation/list panes and let the main detail/content
pane take the remaining space.
- Keep filtering controls inside the pane they affect.
@@ -63,3 +67,11 @@ components directly.
When a module-specific component becomes generally useful, promote it to core
with a parameterized API before reusing it elsewhere.
Non-self-explanatory fields use Core `FieldLabel`; documented omissions must
name their accessible-label source. Explicit Discard and dirty navigation use
the same Core unsaved-changes dialog. Table action sets retain unavailable row
actions as disabled controls and reserve empty-state slots so Add remains
aligned. Use central feedback/dialog components; `window.alert` is not an
authorized product surface unless a product-owner-approved exception is first
recorded in the Core decision ledger.

View File

@@ -110,7 +110,10 @@ one.
upper-right of the page heading. `Discard` comes before `Save …`, with the
primary save action at the far right. Keep both controls in the same place
across validation, loading, and saved states; guard unsaved work when the
user discards or navigates away.
user discards or navigates away. Explicit Discard and dirty in-application
navigation use the same central unsaved-changes dialog and registered
save/discard callbacks. A browser-controlled tab/window unload warning is the
only unavoidable different surface.
- A page or panel has one visually primary action for its current state. Put
secondary actions beside it. Separate destructive actions and name their real
effect.
@@ -125,10 +128,16 @@ one.
- Row actions in tables are icon-only controls in a stable rightmost action
column. Order them by intent: inspect/open, edit, copy/duplicate,
transfer/share/download, retry/restore, then remove/delete last. Omit actions
that do not apply without closing the gap or changing the relative order.
Every icon has a translated accessible name and matching tooltip. Separate
destructive actions visually, and use a named confirmation/review surface
when the consequence cannot be understood from the icon and row context.
only when they are structurally irrelevant to the entire table. An action
that belongs to the table but is unavailable for one row remains in its
normal position and is disabled; when the reason is not obvious from row
state, provide it through the central focusable disabled-action explanation.
It does not disappear. Every icon has a translated accessible name and matching tooltip.
Separate destructive actions visually, and use a named confirmation/review
surface when the consequence cannot be understood from the icon and row
context. In an empty editable table, place Add in the same left-most action
slot it occupies in a populated row and reserve the remaining slots so the
column geometry does not move.
- Transient feedback should not shift the workspace. Durable failures, partial
results, and blockers remain attached to the affected item or operation.
@@ -136,7 +145,12 @@ one.
- Keep the selected object's identity and material status visible while its
detail changes.
- Short field help sits with the label. Longer "Why?", policy source,
- Every non-self-explanatory field uses the central `FieldLabel`; short field
help sits with that label. A field without `FieldLabel` is an explicit
documented omission whose register names the field, rationale, and accessible
label source. Users may hide inline help markers with their persisted
interface preference; the visible/accessibility label and validation remain.
Longer "Why?", policy source,
diagnostics, or provenance belongs in an expandable area, detail panel, or
review step.
- Empty space is not an error. An empty state states what is empty, why that can
@@ -199,6 +213,11 @@ Errors should identify the affected object and whether saved state or external
effects may already exist. Never expose raw exception text as the only user
message.
Use the central dialog, confirmation, alert, and attached-error components for
feedback. `window.alert` and the global `alert` function are prohibited. A
genuinely unavoidable exception requires explicit product-owner authorization
and an entry in the Core alert exception register before implementation.
## State Contract
Every surface implements the states it can reach; it does not render a blank
@@ -355,11 +374,18 @@ and appearance.
The Scheduling request surface is the first explicit reference composition for
these rules:
- The `Scheduling requests` page heading owns one `Add` action.
- The left panel is shown for the creation view; it is not a second permanent
creation launcher beside the request list.
- The persistent left panel contains `My scheduling requests` and `Scheduling
requests for me` as two stacked lists. It preserves list context like mailbox
folders but does not invent folders.
- The left pane's `Scheduling requests` heading owns one short `Add` action. It
opens a new request in the right pane without an extra menu or duplicate
launcher.
- The right main pane is the stable view/create/edit surface. Selecting a list
item opens its details; Add opens the same editor composition used for edit.
- `Basic information`, `Calendar integration`, `Candidate slots`, and
`Participants` are logical sections rendered with the central `Card`.
- Privacy and participation behavior is a separate settings `Card`; dependent
number/password fields are disclosed by their central `ToggleSwitch`.
- Candidate slots and participants are row collections rendered with the
central `DataGrid`, including its stable action column.
- Calendar integration is a boolean choice rendered with the central
@@ -368,6 +394,10 @@ these rules:
ordered row actions. An address-parsing text area is not the ordinary editor;
parsing pasted address lists belongs only in an explicitly designed bulk
import flow.
- View mode shows participation statistics and only state-valid quick actions.
Scheduling owns those current domain actions; a future Workflow module may
coordinate them through stable action contracts but is not a runtime
dependency of the surface.
Apply the underlying placement and component rules to equivalent collection and
create/edit surfaces throughout the system; the Scheduling domain names are an