docs(ui): codify universal interaction patterns
This commit is contained in:
@@ -23,6 +23,10 @@ Principles:
|
|||||||
panels, calendar list panels, or mailbox folder panels.
|
panels, calendar list panels, or mailbox folder panels.
|
||||||
- Keep collection navigation and collection-level actions close to the relevant
|
- Keep collection navigation and collection-level actions close to the relevant
|
||||||
pane header.
|
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
|
- Use bounded widths for navigation/list panes and let the main detail/content
|
||||||
pane take the remaining space.
|
pane take the remaining space.
|
||||||
- Keep filtering controls inside the pane they affect.
|
- 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
|
When a module-specific component becomes generally useful, promote it to core
|
||||||
with a parameterized API before reusing it elsewhere.
|
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.
|
||||||
|
|||||||
@@ -110,7 +110,10 @@ one.
|
|||||||
upper-right of the page heading. `Discard` comes before `Save …`, with the
|
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
|
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
|
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
|
- 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
|
secondary actions beside it. Separate destructive actions and name their real
|
||||||
effect.
|
effect.
|
||||||
@@ -125,10 +128,16 @@ one.
|
|||||||
- Row actions in tables are icon-only controls in a stable rightmost action
|
- Row actions in tables are icon-only controls in a stable rightmost action
|
||||||
column. Order them by intent: inspect/open, edit, copy/duplicate,
|
column. Order them by intent: inspect/open, edit, copy/duplicate,
|
||||||
transfer/share/download, retry/restore, then remove/delete last. Omit actions
|
transfer/share/download, retry/restore, then remove/delete last. Omit actions
|
||||||
that do not apply without closing the gap or changing the relative order.
|
only when they are structurally irrelevant to the entire table. An action
|
||||||
Every icon has a translated accessible name and matching tooltip. Separate
|
that belongs to the table but is unavailable for one row remains in its
|
||||||
destructive actions visually, and use a named confirmation/review surface
|
normal position and is disabled; when the reason is not obvious from row
|
||||||
when the consequence cannot be understood from the icon and row context.
|
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
|
- Transient feedback should not shift the workspace. Durable failures, partial
|
||||||
results, and blockers remain attached to the affected item or operation.
|
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
|
- Keep the selected object's identity and material status visible while its
|
||||||
detail changes.
|
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
|
diagnostics, or provenance belongs in an expandable area, detail panel, or
|
||||||
review step.
|
review step.
|
||||||
- Empty space is not an error. An empty state states what is empty, why that can
|
- 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
|
effects may already exist. Never expose raw exception text as the only user
|
||||||
message.
|
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
|
## State Contract
|
||||||
|
|
||||||
Every surface implements the states it can reach; it does not render a blank
|
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
|
The Scheduling request surface is the first explicit reference composition for
|
||||||
these rules:
|
these rules:
|
||||||
|
|
||||||
- The `Scheduling requests` page heading owns one `Add` action.
|
- The persistent left panel contains `My scheduling requests` and `Scheduling
|
||||||
- The left panel is shown for the creation view; it is not a second permanent
|
requests for me` as two stacked lists. It preserves list context like mailbox
|
||||||
creation launcher beside the request list.
|
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
|
- `Basic information`, `Calendar integration`, `Candidate slots`, and
|
||||||
`Participants` are logical sections rendered with the central `Card`.
|
`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
|
- Candidate slots and participants are row collections rendered with the
|
||||||
central `DataGrid`, including its stable action column.
|
central `DataGrid`, including its stable action column.
|
||||||
- Calendar integration is a boolean choice rendered with the central
|
- 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;
|
ordered row actions. An address-parsing text area is not the ordinary editor;
|
||||||
parsing pasted address lists belongs only in an explicitly designed bulk
|
parsing pasted address lists belongs only in an explicitly designed bulk
|
||||||
import flow.
|
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
|
Apply the underlying placement and component rules to equivalent collection and
|
||||||
create/edit surfaces throughout the system; the Scheduling domain names are an
|
create/edit surfaces throughout the system; the Scheduling domain names are an
|
||||||
|
|||||||
Reference in New Issue
Block a user