docs(ui): require central component reuse
This commit is contained in:
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user