govoplan-core/docs/UI_DESIGN_PRINCIPLES.md

# Product UI design principles

These rules govern every GovOPlaN module, including administration, tenant and
user settings, public forms, widgets, dialogs and shared shell surfaces. Core
owns the reusable components; modules own their meaning and authorized behavior.
They complement the [page composition contract](PAGE_LAYOUT_USAGE_GUIDELINES.md).

Initial rule revision: **UI-2026-09-08**. Record this identifier in review evidence;
subsequent rule changes need a dated change reference and a UI-09 propagation check.

## UI-01 — Help belongs to visible text

Place a small documentation book immediately after the heading or label whose
meaning it explains. For example, the Dashboard book belongs to **Dashboard**,
not the Reload, Edit or Save group. The same applies to page, pane, card and
dialog titles, field labels, widget summaries and contextual explanations.
Do not put an isolated documentation icon in an action bar or in an otherwise
empty row. A navigation icon is not a contextual documentation link.

Use `titleHelp={<DocumentationHelpLink reference={...} />}` on `PageLayout`,
`PageHeader`, `PageTitle`, `AdminPageLayout`, `Card` or `Dialog`. Full-canvas
workspaces use the visible `title` and `titleHelp` of `WorkspaceActionBar` (or
`PageActionBar`), separate from its action groups. Use `TextWithHelp` around
existing text for smaller contexts; fields use `FormField`/`FieldLabel` and
their documentation reference. Do not duplicate the heading to add help.

Dashboard widgets provide their owning `documentation` reference in
`DashboardWidgetContribution`; Dashboard renders it beside the existing widget
card title. Do not add a second widget heading or a footer-only documentation icon.

Keep the icon outside the heading's accessible name and outside other buttons
or links. It needs an accessible purpose, keyboard focus and a usable hit area.
Long German headings must wrap without colliding with actions. Collapsing a
card or configuring a dashboard must not change which title the book explains.
The existing optional Docs-module/hosted-documentation fallback remains intact;
placement does not change permissions or require the Docs module.

## UI-02 — Display first; edit deliberately

Ordinary overview and detail pages show compact, readable data. Group related
facts with shared description, summary and card components. Offer a clear Edit
action that opens a scoped dialog for a coherent group of settings. Avoid
presenting every possible input, select and save control simultaneously.

The Campaign dashboard is a priority application: show the effective settings
and their state compactly, then edit related settings in focused dialogs. This
is review work to implement, not a claim that all current screens already comply.

An explicit editing mode is a justified exception for genuinely broad editing,
large tables, graphical designers or other tasks poorly served by a modal.
Record why the exception helps the user. Keep reading and editing distinguishable;
enter editing deliberately and preserve shared Save/Cancel, validation, conflict,
permission and unsaved-draft behavior. Filters, search and selection do not need
an edit dialog: they change the view rather than the underlying data.

Cancel/Close must work even without changes. Never save a draft merely because
a dialog opens, selection changes or navigation happens. Commit only the intended
fields; do not let unrelated incomplete settings block an independent edit.

## UI-03 — Predictable actions and consequences

Follow the shared semantic page/pane action contract: context on the left;
Reload on refreshable surfaces followed by Create on the right. Editable drafts
have the standard state, Cancel/Discard and Save controls. Keep positions stable
across selection and loading changes, and explain unavailable applicable actions.
Separate destructive actions visually and semantically. Reload is a read, not
an implicit synchronization, import, send or other mutation.

## UI-04 — Shared geometry and readable collections

Use central page, card, table, form-grid and dialog primitives. Table cards use
`bodyLayout="table"`, spanning the card body without negative margins or expanded
`calc()` widths. Keep row actions reachable and deliberate column resizing
predictable. Avoid redundant taglines, arbitrary gaps, fixed dialog widths and
horizontal scrolling where content can wrap. Use actual pagination and shared
list filters; every result and every validation detail must remain reachable.

## UI-05 — Stable feedback and loading

Preserve useful loaded content on refresh failure; distinguish initial loading,
empty, unavailable, stale, blocked, failed and successful states. Use the shared
scoped loading overlay. Long operations show truthful processed/total and outcome
counts when known, not simulated progress or whole-page background reloads.
Prevent duplicate submissions without trapping the user in a clean editing mode.

## UI-06 — Predictable navigation and selection

Use shared breadcrumbs, side rail and tree contracts. Tree disclosure controls
expand/collapse; labels select. Track the clicked occurrence when one topic or
record appears in several branches. Preserve context, filters and selection
where appropriate, without carrying data across authorization or tenant scopes.

## UI-07 — Accessibility and German parity

Check keyboard order, visible focus, accessible names, dialog focus restoration,
contrast, zoom and narrow layouts. Status must not rely on color alone. Use
plain, task-oriented wording and complete German UI and module-owned help for
the changed workflow. Long labels must not hide actions or force needless scroll.

## UI-08 — Integrity and permissions are not visual shortcuts

Preserve authorization, versioning, audit evidence, immutable historical data and
safe retries. Do not remove a guard to make an action look available. Keep drafts
recoverable after failures and conflicts. Loading, cancellation and dialog
transitions must not silently write, discard or overwrite data. Never verify UI
changes by sending real mail or changing production records without authorization.

## UI-09 — Review incrementally and propagate lessons

The [Meta UI-review epic](https://git.add-ideas.de/GovOPlaN/govoplan/issues/56)
links one review ledger per module. Each starts pending, including modules
touched by a focused shared-component pass. An implemented help-placement rule
does not constitute a full module review.

Inventory the module's surfaces, inspect them with realistic data and permissions,
record findings and decisions, implement bounded fixes, then attach automated
and manual evidence. Distinguish **to do**, **implemented**, **verified**, and
**accepted exception**. Record the applicable principle IDs and actual screen
coverage; do not mark a module complete from a code search alone.

When a review reveals a reusable lesson, update this document and the central
component/check first where possible. Record the rule change in Meta and create
a follow-up or reopen affected already-reviewed modules. The review ledger must
show which rule revision each module has actually verified. Prefer finishing
the active review slice before expanding functionality, while recording unrelated
bugs and decision-dependent work without losing them.

## Kurzfassung auf Deutsch

- **UI-01:** Das Dokumentationsbuch steht direkt rechts neben der zugehörigen
  Überschrift oder Beschriftung, nicht zwischen Aktionsschaltflächen.
- **UI-02:** Daten zunächst kompakt anzeigen; zusammengehörige Einstellungen
  gezielt in einem Dialog bearbeiten. Ein ausdrücklich aktivierter
  Bearbeitungsmodus, etwa für große Tabellen, ist eine begründete Ausnahme.
  Abbrechen funktioniert auch ohne Änderungen; Änderungen werden bewusst gespeichert.
- **UI-03–UI-08:** Einheitliche Aktionen und Abstände, erreichbare Tabelleninhalte,
  verständlicher Fortschritt, vorhersehbare Navigation, Barrierefreiheit und
  deutsche Texte dürfen Berechtigungen oder Datenintegrität nicht schwächen.
- **UI-09:** Alle Module werden einzeln geprüft. Neue Gestaltungsregeln werden
  auch in bereits geprüften Modulen nachgezogen und mit Nachweisen dokumentiert.

## Automated coverage and its limits

`tools/checks/check-heading-help.mjs` in Meta checks JSX documentation-link
placement throughout the workspace, including aliases and simple local variables.
Core component and browser tests check heading association, accessible names,
focus, collapse/loading transitions and narrow/wide layouts. Existing layout,
action, dialog and DataGrid checks continue to apply. These tests protect shared
contracts; they do not certify every module's usability or replace the individual
screen reviews and their documented exceptions.