docs(ui): require central component reuse
This commit is contained in:
@@ -47,6 +47,9 @@ rules:
|
|||||||
decoration.
|
decoration.
|
||||||
- Keep optional modules optional. Compose through core route and UI-capability
|
- Keep optional modules optional. Compose through core route and UI-capability
|
||||||
contracts, never sibling-private components.
|
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.
|
- Preserve a stable way back to the containing object and the broader system.
|
||||||
- Do not let navigation, selection, or a view switch imply consent.
|
- 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.
|
- Workflow, configuration, dashboard, and explanatory pages may use a heading.
|
||||||
The heading names the task or scoped object and contains only route-level
|
The heading names the task or scoped object and contains only route-level
|
||||||
actions.
|
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
|
- 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
|
above or beside the current selection. Put object actions with the object
|
||||||
detail, not in the global title bar.
|
detail, not in the global title bar.
|
||||||
@@ -311,7 +319,30 @@ implementation.
|
|||||||
|
|
||||||
Core already exports shell, navigation, access-boundary, form, dialog, loading,
|
Core already exports shell, navigation, access-boundary, form, dialog, loading,
|
||||||
status, policy/provenance, blocker, review, table, tree, message-display, and
|
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
|
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
|
`@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
|
domain composition, wording, and policy semantics; core owns generic contracts
|
||||||
and appearance.
|
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
|
## Test Expectations
|
||||||
|
|
||||||
For every changed surface, select tests from each applicable layer:
|
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
|
- Keyboard, focus, announcement, responsive, theme, density, motion, and i18n
|
||||||
behavior are covered in proportion to the surface.
|
behavior are covered in proportion to the surface.
|
||||||
- Optional modules remain optional and no sibling-private UI import was added.
|
- 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.
|
- Behavioral/accessibility evidence is linked from the rollout matrix and issue.
|
||||||
- Configured-system help can reach the applicable pattern or reference topic
|
- 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)
|
when [Docs #15](https://git.add-ideas.de/add-ideas/govoplan-docs/issues/15)
|
||||||
|
|||||||
Reference in New Issue
Block a user