govoplan/docs/architecture/INTERFACE_PATTERN_LANGUAGE.md

# GovOPlaN Interface Pattern Language

This document is the cross-repository pattern language for GovOPlaN user
interfaces. It turns the existing ethical doctrine, binding UI/UX decisions,
layout rules, and module boundary into a common composition and review grammar.
This document also owns the former standalone frontend-layout principles.

The dated [interface surface inventory](../evidence/snapshots/INTERFACE_SURFACE_INVENTORY.md)
records the 2026-08-03 rollout snapshot. Current implementation state belongs
in Gitea and generated inventory evidence, not in this durable pattern
language.

## Source Of Truth And Precedence

Use the narrowest owning document when changing a rule:

1. `govoplan-core/docs/INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` owns why a
   consequential interface must preserve context, decision, consequence,
   responsibility, contestability, and traceability.
2. `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` owns accepted product decisions
   such as progressive disclosure, adaptive forms, blocker language, guided
   operations, and the platform theme contract.
3. `govoplan-core/docs/MODULE_ARCHITECTURE.md` owns the shell, route, navigation,
   UI-capability, and shared-component boundaries.
4. This document owns the high-level layout choice, common pattern names,
   placement grammar, wording and state conventions, focused-view composition,
   and definition of done across those sources.

If two rules appear to conflict, do not create a third local convention. Record
the conflict in the owning decision ledger, resolve it there, and update the
affected patterns and surfaces together.

## Product Contract

GovOPlaN should feel calm because it shows what is relevant to the task, not
because it hides authority, risk, or evidence. Every surface follows these
rules:

- Start with the user's current object and task.
- Show common actions before advanced controls.
- Keep context, status, problems, and the next action spatially connected.
- Make consequential effects explicit before execution and observed effects
  inspectable afterwards.
- Treat permissions, policy, privacy, and module availability as behavior, not
  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.

## Shared Component And Layout Architecture

Core owns the reusable WebUI vocabulary; modules own domain composition and
behavior. Centralization follows four layers:

| Layer | Owner | Examples | Rule |
| --- | --- | --- | --- |
| Foundation | Core | theme tokens, spacing, typography, focus and responsive breakpoints | Modules consume the contract and do not redefine it. |
| Primitives | Core | buttons, fields, dialogs, alerts, cards, tables, loading, empty and blocked states | A matching primitive is reused rather than copied locally. |
| Structural layouts | Core | page frame and header, action region, workspace panes, toolbars, grids, form sections and dialog anatomy | Layout owns geometry, scroll, responsive collapse and accessibility, but no domain decisions. |
| Domain compositions | Owning module | a campaign review, mailbox, records explorer or operations dashboard | Modules select shared pieces, bind data and permissions, and retain domain wording and consequences. |

A component belongs in Core when it is used or expected in more than one
module and central ownership materially protects accessibility, responsive
behavior, localization, contextual help, theming, or interaction consistency.
A component stays module-owned when its API would otherwise encode a domain
entity, permission, workflow state, endpoint, or policy decision. Reuse does
not justify moving domain semantics into Core.

`PageLayout` is the standard frame for headed workflow, dashboard,
configuration, monitoring and explanatory pages. It owns the content inset,
sticky responsive header, title and rich-description geometry, route-action
placement, transient and custom notices, loading boundary and page help
identity. Its modes make scroll ownership explicit: `standalone` owns a page
viewport, `workspace` defers scrolling to a full-canvas content pane while
retaining the standard inset, and `embedded` owns neither scroll nor inset.

`WorkspaceLayout` is the standard full-canvas shell. Its `navigation` variant
owns module/resource subnavigation plus content; its `split` variant owns
collection/detail panes. It centralizes pane sizing, internal scroll,
responsive collapse/stacking, accessible pane labels and workspace help
identity. `WorkspaceFrame` is the outer full-height module frame and owns
container or application-viewport height, overflow, surface, landmark, help,
and accessible-name behavior. `PageHeader` remains available when an
exceptional canvas needs only the shared heading. Specialized layouts such as
`AdminPageLayout` compose these lower-level Core contracts; they do not repeat
markup or responsive CSS.

`PageActionBar` is the semantic action contract for headed pages;
`WorkspaceActionBar` applies the identical ordering and lifecycle rules to a
full canvas and its collection, detail, and editor panes. Reload is always the
leading action on a refreshable projection. Help and ordinary task actions
follow contextual controls; Create is the far-right collection action;
destructive actions occupy a named separated group; an editor ends with
Discard and Save, with Save at the far right. Editor state is explicit:
`clean`, `dirty`, `invalid`, `saving`, `save-failed`, or `conflict`. Lower-level
`ActionToolbar` remains appropriate for a section-local view switch or compact
control group, but it must not recreate page or pane action placement.

Composite workspaces whose selected contribution supplies its own semantic
heading may use `PageLayout` with its visible header delegated. This preserves
the central inset, loading boundary, help identity, and content frame without
adding a duplicate heading. It is not permission to recreate the page header
locally on ordinary headed pages.

Module CSS may arrange domain content inside a shared layout. It must not
override Core layout internals or copy the outer page, dialog, toolbar, form or
state skeleton under a module-prefixed name. If an archetype cannot be
expressed by the central API, extend the central contract or record a bounded
exception before introducing local structure.

Migration is incremental and enforceable:

1. inventory copied structures and register existing debt;
2. introduce the smallest domain-neutral Core contract with accessibility,
   help, localization, theme and narrow-layout tests;
3. migrate representative Core and optional-module consumers;
4. reject new copies while removing registered debt in bounded module batches;
5. promote the next repeated structure only after its variants and extension
   points are understood.

The current page-frame and workspace migration has no legacy exceptions. New
raw frames fail the focused layout contract instead of entering a new baseline.

The current structural vocabulary is:

- `ActionToolbar`, `ToolbarGroup`, and `ToolbarSpacer` own action alignment,
  distribution, density, grouping, panel/section surfaces, accessible toolbar
  naming, help identity, and responsive wrapping. Modules may add
  domain-specific presentation; they do not recreate the flex/wrap skeleton.
- `PageActionBar` and `WorkspaceActionBar` own semantic ordering, Reload,
  editor persistence state, destructive separation, and page/pane scope. A
  module supplies action behavior, authority, blocker reasons, and wording;
  it does not assemble another panel-header action convention.
- `WorkspaceFrame` and `WorkspaceLayout` own application-viewport framing,
  surfaces, overflow, list/detail and navigation/content pane geometry,
  accessible region identity, and responsive pane behavior. Modules own only
  the domain regions placed inside those contracts.
- `FilterBar` owns submitted or live filter/search arrangement, wrapping,
  width and surface. `SelectionList`, `SelectionListItem`, and
  `SelectionListItemContent` own selectable resource navigation and its
  title/description/leading-icon geometry. `CountBadge` owns compact numeric
  emphasis. Modules retain filter behavior, selection state, and count meaning.
- `StatePanel` owns whole-surface, compact, inline and fill state presentation
  for empty, unavailable, blocked, warning and recoverable-error compositions.
  Modules provide the cause, consequence, permitted action and authority.
- `ContentGrid`, `FormGrid`, `FormLayout`, and `GridItem` own equal-column
  geometry, standard gaps, alignment, spans, native form semantics, and named
  responsive collapse points. A module-local grid remains appropriate only
  when unequal tracks or domain visualization semantics are material.
- `ContentSection` owns repeated bordered or subtle content-section surfaces,
  density, stacked flow and surrounding rhythm without prescribing a domain
  heading or body schema.
- `FormSection` owns form-section heading, description, actions, content flow,
  separation, and panel presentation. It does not own field values,
  validation, permissions, or domain wording.
- `MetricGrid` owns the responsive grouping around `MetricCard`: fixed one-to-five
  columns or auto-fit, minimum card width, density, surrounding rhythm, and a
  named collapse point. `MetricCard.drilldown` provides an explicit link or
  in-page action when an authorized underlying detail helps the user act; it
  names that destination and preserves the current scope and filters. The card
  itself is never the hidden click target. Derived, privacy-suppressed,
  non-enumerable, and purely informational aggregates remain inert. Modules
  provide the metric, tone, destination, and consequence; they do not recreate
  the group grid or reach across module CSS to size it.
- `DescriptionList` and `DescriptionItem` own semantic property presentation.
  The stacked variant supports compact multi-column facts; the inline variant
  supports one-column term/value rows with a standard term width. Both own
  density, wrapping, and responsive collapse while modules retain the terms,
  values, provenance, and actions.
- `Dialog` owns size and administration variants, body padding, description,
  notices, and fixed footer placement. `DialogActions`, `DialogForm`, and
  `DialogSection` own the footer action flow, native form flow, and body
  grouping used inside it. Modules compose fields and consequences rather than
  recreating dialog anatomy.
- `DefinitionPalette`, `DefinitionPaletteGroup`, `DefinitionPaletteItem`, and
  `DefinitionNodeIcon`, together with the shared definition-canvas classes,
  own reusable graph-editor palette, canvas-control, node-icon, port and empty
  overlay visuals. Workflow/Dataflow retain node types, shapes, edges,
  validation and execution semantics. `FloatingStatus` owns the common
  non-shifting activity overlay.

Raw toolbar tags, the former generic grid and property-list classes, retired
module-local shells/states/metrics/badges, raw dialog-form wrappers, and
module-local definitions of these contracts are rejected by the focused
workspace checks. Dialog widths matching the Core size scale must use `Dialog
size`; other local widths require a reviewed exception and may only decrease.
Remaining local layout is acceptable only for unequal-track domain editors,
visualizations, trees, timelines, data tables, or domain-specific multi-pane
interaction. Generic resemblance alone is not a reason to create one oversized
page template, while exact repeated structural anatomy must be promoted.

## Surface Archetypes

Choose an archetype from the task, then specialize it for the domain. A route
may contain more than one bounded archetype, but it should have one dominant
one.

| Archetype | Use when | Standard anatomy | Do not use when |
| --- | --- | --- | --- |
| Directory or explorer | Users browse hierarchical collections such as files, mailboxes, calendars, addresses, or records. | Collection/source pane, collection actions, filter in the pane it affects, main list/content pane, optional detail pane. | The content is a set of unrelated settings or workflow stages. |
| List-detail workspace | Users repeatedly find objects, inspect one, and act without losing list context. | Search/filter/list, persistent selected-object context, detail/actions, stable selection and URL. | A single guided operation is the primary task. |
| Focused task view | Only a bounded composition is needed to complete one task. | Task identity and reason, selected object, necessary module regions/actions, progress or status, obvious exit to the full system. | Hiding a surface would obscure a consequence, blocker, or required evidence. |
| Create or edit | Users change one coherent object state. | Adaptive typed form, field-level validation, advanced section, save/cancel, unsaved-change guard. | Discovery-heavy setup or a broad consequential change needs staged review. |
| Guided setup or import | The user must discover, upload, map, test, or preflight before a safe result exists. | Named steps, current progress, preserved inputs, validation/problem list, review, resumable completion where work is durable. | An ordinary edit can be understood as one coherent form. |
| Review or decision | A person must inspect evidence and deliberately approve, reject, send, publish, or otherwise commit. | Decision context, evidence/problems, consequence and reversibility, authority/provenance, explicit action, resulting record. | The interaction is passive inspection. |
| Monitoring, progress, or report | Users observe asynchronous or aggregate state and intervene when needed. | Summary, filters, durable job/item state, last update, retry/reconcile/intervention, detail and evidence. | A toast is sufficient for a short, non-durable local action. |
| Administration or configuration | Users compare and configure separate concerns. | Heading and scope, grouped subnavigation, overview/list plus selected details, adaptive editor or guided risky operation, effective policy and source. | The primary task is browsing one structured object space. |
| Dashboard | Users need a task-oriented starting point across modules. | Prioritized actionable widgets, scoped status, clear destination per widget, explicit refresh/staleness. | It merely duplicates every module navigation item or metric. |
| Public service or entry | An unauthenticated or external participant starts or resumes a service. | Service identity, eligibility/context, privacy and evidence expectations, accessible form/task, save/resume or handoff. | The actor is performing internal administration. |

## Placement Grammar

### Shell And Navigation

- The global title bar and rail belong to core. A module contributes routes,
  navigation metadata, and explicit UI capabilities; it does not reproduce the
  shell.
- Global navigation answers "which service area?" Local subnavigation answers
  "which stable facet of this object or area?" A progress indicator answers
  "where am I in this operation?" Do not use those three controls
  interchangeably.
- Keep the current tenant, actor, object, and selected version or scope stable
  across local navigation. Guard unsaved work before navigation.
- Permission and capability filtering happens before view composition. A
  missing menu item is not evidence that an actor lacks backend access, and a
  visible item is never authorization by itself.
- Route, selection, panel, and view changes must not execute consequential
  actions.

### Page And Workspace

- Structured directories use the full available content space and persistent
  panes. They do not add a decorative heading row that reduces working height.
  Give navigation and list panes bounded widths and let the main content or
  detail pane consume the remaining space.
- In a list-detail workspace, related lists may be stacked in the left pane
  while the main pane owns view, create, and edit. Keep one create action in
  the relevant list heading instead of adding a second launcher or permanent
  creation panel.
- Workflow, configuration, dashboard, and explanatory pages may use a heading.
  The heading names the task or scoped object and contains only route-level
  actions. Use the Core `PageLayout` contract for the frame and `PageHeader`
  only when a full-canvas archetype owns its own scrolling.
- 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 collection, detail, and
  editor-pane actions in `WorkspaceActionBar` with the matching scope. Put bulk actions immediately
  above or beside the current selection. Put object actions with the object
  detail, not in the global title bar.
- Full-page create and edit surfaces put their persistent action cluster in 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
  across validation, loading, and saved states; guard unsaved work when the
  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
  secondary actions beside it. Separate destructive actions and name their real
  effect.
- Dialog actions use a stable footer: cancel/back first, then the primary action
  at the end. Header and footer stay fixed while long bodies scroll.
- Use cards for independent groups, summaries, and settings blocks. Do not wrap
  every region in a card or nest cards merely to create spacing.
- When a collapsible card contains one table and no other content, the table
  uses the card's full available width and body height. The card/table region
  owns overflow; do not add an inner max-width, decorative wrapper, duplicate
  padding, or nested scroll container that reduces the working area.
- Row actions in tables are icon-only controls in a stable rightmost action
  column. Order them by intent: inspect/open, edit, copy/duplicate,
  transfer/share/download, retry/restore, then remove/delete last. Omit actions
  only when they are structurally irrelevant to the entire table. An action
  that belongs to the table but is unavailable for one row remains in its
  normal position and is disabled; when the reason is not obvious from row
  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
  results, and blockers remain attached to the affected item or operation.

### Detail And Explanation

- Keep the selected object's identity and material status visible while its
  detail changes.
- 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
  review step.
- Empty space is not an error. An empty state states what is empty, why that can
  happen, and the permitted next action. Do not show creation actions to actors
  who cannot create.

## Visual Grammar

- Core owns the appearance contract and shared CSS tokens. Modules use core
  colors, spacing, radii, shadows, focus treatment, status colors, and disabled
  treatment; module CSS may specialize layout only.
- Establish hierarchy through spacing, typography, grouping, and placement
  before adding borders or color.
- Color never carries status or required action alone. Pair it with text and,
  where useful, an icon.
- Icons support recognition but do not replace accessible names. Use the core
  icon-name mapping for navigation.
- Keep list columns, tree indentation, headers, dialog dimensions, and action
  positions stable as content changes.
- Density is a user preference, not a license to remove labels, focus targets,
  explanations, or consequences.
- Respect system/light/dark themes and reduced-motion preferences through the
  core contract. Do not build module-local theme systems.

## Wording Grammar

Use the same noun for the same domain object in navigation, headings, fields,
actions, states, API-facing explanations, and documentation. Prefer the most
specific user-facing noun: "Recipients" rather than "Data", "Delivery job"
rather than "Process", and "Mail profile" rather than "Configuration" when
that is what the user is acting on.

Actions use a verb plus the object or consequence:

- Prefer `Save campaign`, `Review messages`, `Queue delivery`, `Retry failed
  deliveries`, or `Delete calendar`.
- Avoid `Submit`, `OK`, `Continue`, or `Execute` when a more precise action is
  available.
- Use `Continue` only when it advances a reversible guided flow without
  committing the final effect.
- Do not say `Undo` when the system can only cancel future work, create a
  correction, supersede a record, or request retraction.

State text describes observed state, not optimism. Use stable shared terms where
they fit: `Draft`, `Ready for review`, `Blocked`, `Queued`, `Running`,
`Retry scheduled`, `Partially completed`, `Completed`, `Failed`, and
`Cancelled`. Domain-specific states may refine these terms but should not give a
shared term a contradictory meaning.

Blocked and failed actions use the structured language from DUE-005:

- what is unavailable or failed
- why, in plain language
- what must happen next
- who can do it
- where to go
- optional technical details behind deliberate disclosure

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
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

Every surface implements the states it can reach; it does not render a blank
region while waiting or collapse distinct outcomes into a generic error.

| State | Required treatment |
| --- | --- |
| Loading | Keep the stable shell and context visible. Name what is loading; preserve usable prior data when safe. |
| Empty | State the scope and reason, then show only permitted next actions. |
| Validation problem | Attach the problem to the field/item and provide a navigable summary when problems span regions or steps. |
| Permission denied | Name the unavailable action or object, the required actor/role where safe, and a valid exit. Do not leak protected data. |
| Capability unavailable | Distinguish not installed, disabled, not configured, unhealthy, and not permitted when the actor may know. Give the responsible actor and target. |
| Offline or unreachable | Preserve local context and unsaved input, show last-known/stale state, and offer a safe retry. Do not present network absence as an authentication failure. |
| Stale or conflicting | Show which data changed, preserve both values where feasible, and offer reload, merge, or explicit overwrite according to policy. |
| Partial result | Show completed and incomplete effects separately. Never label a partial operation successful without qualification. |
| Asynchronous work | Show durable job identity, queued/running/retry/block/final state, last update, progress if meaningful, and leave/return behavior. |
| Success | State the resulting object/effect and provide its evidence or destination. Use a transient toast only when the result is already visible and durable elsewhere. |
| Destructive or corrective action | Preview scope, downstream effects, reversibility limit, evidence, and required confirmation or approval. |

Long-running or external work must expose retry and reconciliation as observable
states. The UI must not imply that a request and its external effect were one
atomic success when an outbox, worker, or remote system sits between them.

## Consequence And Provenance

Before an action affects records, rights, policy, retention, communications,
money, external systems, or workflow state, its action surface must answer the
decision-surface questions in the interface doctrine. At minimum show:

- affected object and scope
- acting identity or system actor and relevant authority
- immediate and possible downstream effects
- whether the operation is reversible, cancellable, corrective, or final
- blockers and their resolution path
- audit/evidence that will be created
- effective policy or configuration source when it changes the decision

After execution, users must be able to reach the command/job, observed effects,
policy result, failures, retries, reconciliation outcome, actor, time, and source
data that explain the result. Provenance may be quiet by default, but it must not
be absent.

Privacy follows the same rule: lists, previews, logs, notifications, and
diagnostics show only the personal or secret data needed for the actor's task.
Redaction must be explicit enough that users do not mistake a redacted value for
missing source data.

## Focused Views

A focused view is a declarative UI composition for a task. It selects the
routes, local regions, navigation entries, and actions relevant to that task
after installed-module, capability, permission, and policy filtering. It does
not change backend authorization or domain state.

A view definition must be able to explain:

- its stable identifier, label, and task purpose
- the current object/scope and default destination
- included navigation and contributed regions/actions, with deterministic order
- the visible escape to the containing module and full system
- why the view is active and how the user may switch when switching is allowed
- what happens to unsaved work when entering, leaving, or switching views

Focused views follow these invariants:

- Do not hide a blocker, material consequence, provenance, or required review
  merely to make the screen quieter.
- Preserve the global tenant/actor context and provide an obvious exit.
- Filter unavailable contributions without leaving broken separators, empty
  groups, or dead destinations.
- A manual or automatic switch is navigation, not consent. Guard unsaved work
  and never execute a domain action as a side effect.
- Display why a non-manual default was selected, for example a role or task
  default, without exposing protected policy details.
- Treat an unknown or invalid view as a recoverable fallback to the normal
  module surface.

When more than one source proposes a focused view, use this precedence:

1. a manual view pinned for the current user session
2. a current-task suggestion, including a future workflow-step suggestion
3. the user's saved default
4. the role or tenant default
5. the normal full interface

Show the active source and an escape to the full interface. A task or workflow
suggestion is never an authorization change and never locks the user into the
composition; tenant policy may constrain which views are selectable, but it
must not hide required evidence or remove that escape. Workflow implementation
is explicitly postponed and is not a prerequisite for defining, manually
selecting, testing, or piloting focused views. A future workflow module may
request a view through a core contract; it must not own the view composition
implementation.

## Accessibility And Responsive Contract

- Every action is reachable and operable by keyboard in a logical order.
- Use semantic headings, landmarks, labels, tables/lists, and native controls
  before adding ARIA. Icon-only controls need stable accessible names.
- Focus is visible. Dialogs trap focus, announce their name, and return focus to
  the control that opened them. Validation moves or links focus to the first
  relevant problem without losing the problem summary.
- Loading, saved, failed, queued, progress, and externally updated states are
  announced without repeatedly interrupting the user.
- Disabled primary actions need a focusable explanation; a pointer-only tooltip
  is insufficient.
- Do not rely on color, hover, drag-and-drop, pointer precision, or animation as
  the only interaction. Provide keyboard and explicit-control equivalents.
- At narrow widths and high zoom, preserve task order and action access. Collapse
  secondary panes into an explicit drawer/step and never move a destructive
  action into the primary position.
- Honor reduced motion. Avoid motion that implies progress when the operation is
  merely waiting.
- Truncation has an accessible full-value path. Personal or secret values remain
  redacted according to permission and policy in that path.

## Component Ownership

Core already exports shell, navigation, access-boundary, form, dialog, loading,
status, policy/provenance, blocker, review, table, tree, message-display, and
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
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 persistent left panel contains `My scheduling requests` and `Scheduling
  requests for me` as two stacked lists. It preserves list context like mailbox
  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
  `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
  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.
- 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
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:

- route and permission tests: module enabled/disabled permutations, route guard,
  contribution filtering, fallback, and direct-link behavior
- behavior tests: primary task, validation, unsaved-change guard, confirmation,
  retry/reconcile, partial result, and leave/return behavior
- accessibility tests: semantic names/roles, keyboard order, focus entry/return,
  live-state announcements, and non-color status meaning
- state tests: loading, empty, denied, capability-missing, stale/conflict,
  offline, partial, success, and destructive/corrective outcomes as applicable
- composition tests: absent optional module, duplicate/unknown contribution,
  deterministic ordering, and focused-view fallback
- presentation checks: supported widths/zoom, light/dark/system theme, reduced
  motion, comfortable/compact density, and long translated text
- i18n checks: user-facing strings owned by the rendering package and structural
  audits passing
- visual regression: useful for geometry and hierarchy after behavior and
  accessibility assertions exist; never the only evidence

If the current harness cannot automate a required check, record the gap and the
manual evidence in the owning issue. "Not tested" is an inventory state, not a
reason to infer that a pattern is satisfied.

## Definition Of Done For A Surface

- The dominant task and archetype are recorded in the inventory.
- Placement, action hierarchy, wording, and every reachable state follow this
  pattern language or an explicit ledger exception.
- Permission, capability, privacy, and redaction behavior are verified.
- Consequence, reversibility, authority, evidence, and provenance are present
  where applicable.
- 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/GovOPlaN/govoplan-docs/issues/15)
  supplies that experience.

## First Pilot: Campaign

[Campaign #74](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/74)
is the first full-domain audit and migration. It should prove patterns before
generic extraction:

- [#59](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/59) and
  [#73](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/73): stable,
  accessible preview and attachment-detail overlays
- [#63](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/63): review
  stages, outcomes, blockers, and intervention vocabulary
- [#62](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/62): explicit
  synchronous/asynchronous send mode and durable delivery progress
- [#65](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/65): one
  coherent report filtering and count-affordance model
- [#35](https://git.add-ideas.de/GovOPlaN/govoplan-campaign/issues/35): guided
  first-campaign entry

These slices do not depend on the Workflow runtime. Campaign's current
domain-owned review/send state is enough to prove layout, wording, focused-view,
progress, intervention, and evidence patterns.

## Revision Procedure

1. Record a changed product decision in the core UI/UX decision ledger.
2. Update the relevant pattern here without copying the full owning doctrine.
3. Update the surface inventory and rollout owner/issues.
4. Change shared components only where the proven contract belongs to core.
5. Migrate and test affected module surfaces.
6. Publish configured-system pattern/reference help through the Docs module.