diff --git a/docs/INTERFACE_PATTERN_LANGUAGE.md b/docs/INTERFACE_PATTERN_LANGUAGE.md index 148cece..945a3b4 100644 --- a/docs/INTERFACE_PATTERN_LANGUAGE.md +++ b/docs/INTERFACE_PATTERN_LANGUAGE.md @@ -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)