docs(ui): require central component reuse

This commit is contained in:
2026-07-20 17:56:14 +02:00
parent 8b80afbd60
commit 4b217c7aba

View File

@@ -47,6 +47,9 @@ rules:
decoration.
- Keep optional modules optional. Compose through core route and UI-capability
contracts, never sibling-private components.
- Use the centrally exported core components wherever a matching contract
exists. A module-local replacement is not an implementation choice: it is a
product exception that requires explicit product-owner authorization.
- Preserve a stable way back to the containing object and the broader system.
- Do not let navigation, selection, or a view switch imply consent.
@@ -95,6 +98,11 @@ one.
- Workflow, configuration, dashboard, and explanatory pages may use a heading.
The heading names the task or scoped object and contains only route-level
actions.
- Put a collection-wide create action in the heading of the collection it
affects. Use a short, specific label such as `Add` when the heading already
names the object. Do not duplicate that action in a permanently visible side
panel. A side panel used as the creation surface appears for creation and is
otherwise absent or returns to its documented non-creation purpose.
- Put filters beside the list or pane they affect. Put bulk actions immediately
above or beside the current selection. Put object actions with the object
detail, not in the global title bar.
@@ -311,7 +319,30 @@ implementation.
Core already exports shell, navigation, access-boundary, form, dialog, loading,
status, policy/provenance, blocker, review, table, tree, message-display, and
unsaved-change primitives. Reuse them when their contract fits.
unsaved-change primitives. These centrally exported components are mandatory
across GovOPlaN wherever their contract covers the interaction. In particular,
use the core `Card` for logical sections, `DataGrid` for tabular collections and
row actions, and `ToggleSwitch` (the standard Toggle control) for boolean
settings. Styling a native element or a module-local component to imitate one
of these controls is duplication, not reuse.
A route or domain composition assembled from central primitives is not a custom
control. Any new reusable UI control, presentation primitive, or module-local
substitute is a custom component and requires explicit product-owner
authorization before implementation. Record the authorization in the owning
decision or issue together with:
- the narrowly defined purpose and consumers
- why no central component or composition satisfies the need
- the exact scope in which the exception may be used
- its accessibility, state, theme, and test contract
- whether it should remain domain-specific or later become a core component
An authorized custom component serves only that specific purpose. It must not
duplicate, fork, restyle into a substitute for, or silently broaden beyond a
central component. Code review convenience, an existing local implementation,
or a small visual difference is not authorization. When core gains the required
contract, migrate the exception unless the product owner explicitly retains it.
Do not promote a component only because two screens look similar. Promote it to
`@govoplan/core-webui` after a second consumer or a clear platform contract has
@@ -319,6 +350,29 @@ proved shared behavior, accessibility, state, and extension needs. Modules own
domain composition, wording, and policy semantics; core owns generic contracts
and appearance.
### Scheduling Request Composition Reference
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.
- `Basic information`, `Calendar integration`, `Candidate slots`, and
`Participants` are logical sections rendered with the central `Card`.
- 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
`ToggleSwitch`; dependent calendar controls are disclosed only when enabled.
- Each participant is one structured row containing name, email address, and
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.
Apply the underlying placement and component rules to equivalent collection and
create/edit surfaces throughout the system; the Scheduling domain names are an
example, not a module-local convention.
## Test Expectations
For every changed surface, select tests from each applicable layer:
@@ -355,6 +409,9 @@ reason to infer that a pattern is satisfied.
- Keyboard, focus, announcement, responsive, theme, density, motion, and i18n
behavior are covered in proportion to the surface.
- Optional modules remain optional and no sibling-private UI import was added.
- Every matching central component is reused. Any custom-component exception
has recorded product-owner authorization, narrow scope, rationale, and tests,
and does not duplicate a central component.
- Behavioral/accessibility evidence is linked from the rollout matrix and issue.
- Configured-system help can reach the applicable pattern or reference topic
when [Docs #15](https://git.add-ideas.de/add-ideas/govoplan-docs/issues/15)