fix(ui): unify heading help, table sizing and navigation contracts

Verified with the coordinated workspace changes by devkit full run
2026-09-08T225814-186389-0000-3e3ed7cd (all seven phases passed).
This shared UI pass does not mark the individual module reviews complete.

docs/UI_DESIGN_PRINCIPLES.md

@@ -0,0 +1,150 @@
+# 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.