# GovOPlaN UI/UX Decision Ledger

This ledger records product UI/UX decisions that affect admin, settings,
configuration, connector, policy, and module-management surfaces. It is a
binding design reference: future implementation should follow these decisions
unless the decision is explicitly revised here and affected screens are updated
to match.

Active tracking issue: `add-ideas/govoplan-core#225`.

## Operating Rule

GovOPlaN must expose advanced platform capability without presenting the user
with every option at once. Non-technical users should be able to complete common
workflows through guided, plain-language flows. Expert and diagnostic detail may
exist, but it must be deliberately layered.

The ethical design doctrine in `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` is the
normative baseline for this ledger. A screen can be visually quiet and still be
ethically complete only when it preserves context, consequence,
contestability, responsibility, and traceability at the point of action.

## Binding Decisions

| ID | Decision | Status | Applies To |
| --- | --- | --- | --- |
| UX-001 | Use progressive disclosure by default. Common decisions stay visible; advanced or hazardous options live in collapsed panels, later wizard steps, or explicit advanced sections. | Accepted | Admin, settings, connector setup, policy editors, module operations |
| UX-002 | Raw JSON is not a primary configuration editor. Every normal configuration path needs typed controls, validation, and help text. JSON may be shown for import/export, diagnostics, or expert inspection only. | Accepted | All admin/configuration UIs |
| UX-003 | Prefer guided workflows over option dumps for setup and risky changes. Use wizards for connector setup, configuration package import, module install/uninstall, destructive actions, and policy changes with broad impact. | Accepted | Connectors, package import, module lifecycle, governance/policy |
| UX-004 | Discover technical values when possible. Ask for the smallest user-known input, then discover and prefill technical fields for review. | Accepted | File connectors, mail/groupware, public URLs, future external providers |
| UX-005 | Disabled actions and failed steps must explain why they are unavailable, who can fix them, and where to go next. Silent disabled states are not acceptable for primary actions. | Accepted | All primary actions |
| UX-006 | Explanations must be available but quiet. Use short inline text and expose richer explanations through help affordances, side panels, expandable sections, or review steps. | Accepted | All complex forms and flows |
| UX-007 | Creation/editing should prefer modals or focused step flows when it reduces page clutter. Overview and comparison screens remain full-page. | Accepted | Settings/admin surfaces |
| UX-008 | Similar concepts must use shared placement and components: server/credential/policy rows, problem lists, review steps, advanced panels, confirmation modals, and empty/error states. | Accepted | Core WebUI and module WebUIs |
| UX-009 | Preflight and diagnostics are product UX. Validation, policy, permission, dependency, and capability failures must be written for operators before exposing internal details. | Accepted | Installer, connectors, policy, package import |
| UX-010 | Context, decision, and consequence must be visible together for actions that affect rights, duties, records, money, communication, retention, external systems, or workflow state. | Accepted | Workflow, admin, portal, policy, connector, records, payments |
| UX-011 | Navigation is not consent. Route changes, panel switches, and passive selection must not execute consequential actions without an explicit action surface. | Accepted | All WebUI surfaces |
| UX-012 | Automated actions must remain inspectable. The UI must show the system actor, trigger, policy result, observed effects, and failure/manual-intervention state when automation changes administrative state. | Accepted | Workflow, automation, connectors, tasks, audit |
| UX-013 | Contestable decisions must expose provenance. Denials, locks, generated outputs, calculated defaults, policy decisions, access decisions, and retention decisions need a reachable source path. | Accepted | Policy, access, templates, workflow, retention, records |
| UX-014 | Retraction, expiry, undo, rollback, and delete controls must state the real limit of the operation. Corrective or future-only actions must not be described as if they undo already observed effects. | Accepted | Postbox, files, records, installer, workflow, payments |
| UX-015 | Core owns the platform appearance contract. Modules must use shared CSS tokens and shared controls for theme-aware UI; they must not define independent light/dark palette systems. | Accepted | Core shell and all module WebUIs |
| UX-016 | Full-page create/edit surfaces keep `Discard` and the named `Save …` action in the upper-right page action cluster, with Save at the far right. Their position remains stable through validation and loading states. | Accepted | All full-page create/edit surfaces |
| UX-017 | Table row actions use icon-only controls in a stable rightmost column and intent order: inspect/open, edit, copy, transfer/share/download, retry/restore, destructive action last. Every icon requires a translated accessible name and tooltip. | Accepted | All structured tables |
| UX-018 | A collapsible card containing only one table gives the table the card's full available body, without decorative inner wrappers, duplicate padding, max-widths, or nested scrolling. | Accepted | List, detail, workflow, and configuration surfaces |
| UX-019 | Focused-view precedence is manual session pin, current-task suggestion, user default, role/tenant default, then the full interface. The active source and a full-interface escape remain visible; a suggested view never changes authorization or implies consent. | Accepted | Shell, modules, future workflow composition |
| UX-020 | Centrally exported Core components are mandatory wherever their contract covers the interaction. A custom reusable control, presentation primitive, or module-local substitute requires explicit product-owner authorization, a narrowly specific purpose, and documented rationale and scope; it must not duplicate a central component. | Accepted | Core WebUI and all module WebUIs |
| UX-021 | A collection-wide create action belongs in that collection's page heading and is not duplicated in a persistent side panel. When a side panel is the creation surface, it is present for the creation view only. | Accepted | List-detail, directory, and create surfaces |
| UX-022 | Use central `Card` components for logical sections, `DataGrid` for tabular row collections and their ordered actions, and `ToggleSwitch` for boolean settings. Repeatable people/contact editors use one structured row per person with name, email address, and actions; free-form address parsing is reserved for an explicitly designed bulk-import flow. | Accepted | All WebUI forms and collection editors |
| UX-023 | `FieldLabel` is the standard label/help surface for every field that is not self-explanatory. Any field rendered without it must be recorded in the omission register below, including its accessible-name source and rationale. Users may hide inline help markers through their persisted interface preference; the field label itself remains visible. | Accepted | All Core and module forms |
| UX-024 | Explicit `Discard` actions and dirty in-application navigation use the shared `UnsavedChangesProvider` dialog. A page registers save/discard behavior with `useUnsavedDraftGuard`; its Discard button calls `requestDiscard`, and route changes use `useGuardedNavigate` or `requestNavigation`. | Accepted | All create/edit surfaces |
| UX-025 | `window.alert` and the global `alert` function are prohibited. A narrowly necessary exception requires product-owner authorization and an entry in the alert exception register before implementation. | Accepted | All WebUI code |
| UX-026 | A table defines one stable ordered action set. A row-level unavailable action remains in its normal position and is disabled, preferably with `disabledReason`; structurally irrelevant actions are omitted for the entire table. Empty rows reserve the same slots so their Add action stays in the normal left-most action position. | Accepted | All structured tables |

## Confirmed Implementation Decisions

These decisions were accepted on 2026-07-09 for the first implementation slice.
They shape reusable components and screen structure. Future changes must revise
this section and update affected screens.

### DUE-001: Primary Admin Configuration Shell

Decision: admin/configuration surfaces should standardize on a two-zone layout.

- Left or top area: searchable overview/list, status, and primary actions.
- Main area: selected item summary and common settings.
- Modal/wizard: create, connect, edit, test, review, and confirm actions.
- Collapsed advanced panels: rarely used technical fields.

Use this for file connectors and mail servers first, then migrate policy,
retention, API keys, and module operations.

### DUE-002: Wizard Step Model

Decision: standard wizard steps and names use this baseline:

1. Choose type or scope.
2. Enter essentials.
3. Discover or test.
4. Configure ownership and policy.
5. Review changes and blockers.
6. Save or submit for operator action.

Not every wizard needs every step, but flows should use these names and order
where applicable.

This applies to explicit assisted setup, onboarding, import, preflight, and
risky multi-step operations. It is not the default shape for ordinary create or
edit dialogs.

### DUE-003: Explanation Placement

Decision: richer explanations should use this placement model:

- Short helper text below labels only when it prevents common mistakes.
- Tooltips for icon-only controls and compact terms.
- Expandable "Why?" or "Details" blocks for contextual explanations.
- Right-side detail panel or review step for preflight/provenance/diagnostics.

Avoid permanently visible paragraphs inside dense admin cards.

### DUE-004: Advanced Options Contract

Decision: advanced options are fields that are needed for control, compatibility,
or diagnostics but are not part of the common setup path.

- protocol-specific endpoints, ports, path overrides, TLS/signing toggles,
  timeout/retry tuning, raw headers, migration/destructive flags, and fallback
  compatibility settings are advanced.
- names, descriptions, provider type, base URL, ownership, policy mode, and
  basic credentials are not advanced.

Advanced fields must still be editable through typed controls.

### DUE-005: Blocker Language Contract

Decision: all disabled or blocked primary actions should use a shared structured
reason object.

Shape:

- `summary`: short plain-language reason.
- `details`: optional explanation.
- `required_action`: what needs to happen.
- `actor`: who can do it, for example system administrator or tenant admin.
- `target`: where to go or which setting/capability is missing.
- `technical_details`: optional expandable developer/operator data.

For simple missing required fields, highlight the fields and put the structured
reason in a compact hover/focus bubble on the disabled primary action instead of
adding a large persistent warning block.

### DUE-006: First Migration Surface

Decision: convert file connectors first, then mail servers. They share the same
server/credential/policy model, are high-value, and will prove the reusable
patterns quickly.

### DUE-007: Adaptive Create/Edit Forms

Decision: ordinary create/edit dialogs should show the full editable state in an
adaptive form, not force a linear wizard.

- The user chooses a type, provider, credential mode, or policy mode.
- The dialog immediately adjusts to show only the fields relevant to that state.
- Editing an existing object uses the same field grouping and layout as creating
  it, so users can recognize the state they configured.
- Discovery and test actions must give visible feedback in the same dialog:
  directly usable, discovered alternative, credentials needed/rejected, or not
  found with the next action the user can take.
- Wizard shells remain available for assisted setup, first-run guidance,
  imports, discovery-heavy flows, and operational preflight workflows.

### DUE-008: Platform Theme Contract

Decision: the WebUI shell exposes a small, stable appearance contract based on
shared CSS tokens and persisted user preference selection.

- Core applies `system`, `light`, and `dark` preferences at the document root.
- Core owns shared tokens such as `--bg`, `--bar`, `--panel`, `--surface`,
  `--line`, `--line-dark`, `--text`, `--text-strong`, `--muted`, semantic
  status colors, radii, shadows, and disabled-control colors.
- Modules must style new UI with these tokens and shared controls. Module-local
  CSS may tune layout and spacing, but it must not introduce a separate
  appearance system.
- Appearance controls live in user settings first. Tenant defaults and policy
  enforcement can be added later without changing the token contract.
- Visual preview in settings is illustrative; it must reflect token families,
  not become a second theme implementation.

### DUE-009: Central Component And Exception Contract

Decision: module interfaces are compositions of the components exported by
`@govoplan/core-webui`. When Core already owns the matching interaction, using
the central component is required rather than preferred.

A route or domain-specific page composed from central components is ordinary
module composition. A new reusable UI control, presentation primitive, or
module-local substitute is a custom component. Before one is implemented, the
product owner must explicitly authorize it and the owning decision or issue must
record:

- its single, narrowly defined purpose and intended consumers
- why central components or their composition cannot meet that purpose
- the permitted scope and the boundary it must not grow beyond
- accessibility, reachable states, theme behavior, and test expectations
- whether the component remains domain-owned or is a candidate for Core

Custom components must not duplicate, fork, or cosmetically replace a central
component. An existing local implementation does not grant an exception. If a
central contract later covers the need, migrate to it unless the product owner
explicitly retains the exception.

### DUE-010: Scheduling Request Reference Composition

Decision: Scheduling requests provide a concrete reference application of the
universal placement and component rules.

- The persistent left panel stacks `My scheduling requests` and `Scheduling
  requests for me`; it is list context, not a second creation affordance.
- The left panel's `Scheduling requests` header owns one `Add` action. It opens
  the shared view/create/edit surface in the right main panel.
- Basic information, Calendar integration, candidate slots, and participants
  use the central `Card` component as four logical sections.
- Candidate slots and participants use the central `DataGrid`, including its
  standard row-action placement and order.
- Calendar integration uses the central `ToggleSwitch`, with its dependent
  controls shown when enabled.
- Each participant is edited as one structured row with name, email address,
  and actions. The normal editor does not parse a free-form list of addresses;
  that interaction requires a separate, explicitly designed bulk-import flow.

Equivalent list/create/edit surfaces use the same underlying rules. These are
not Scheduling-local component variants.

### DUE-011: Field Help, Discard, And Table Action Contracts

Decision: the central components own these interactions; modules compose them
instead of reproducing their behavior.

- `FormField` and `ToggleSwitch` already render `FieldLabel`. Direct field
  compositions use `FieldLabel` explicitly when the meaning or limitation is
  not self-explanatory.
- `help` content is contextual guidance, not the accessible name. The persisted
  `show_inline_help_hints` user preference hides only the `InlineHelp` marker by
  applying `ui-hide-help-hints` at the document root.
- A dirty editor registers once with `useUnsavedDraftGuard`. An explicit
  Discard button calls `useUnsavedChanges().requestDiscard(afterResolve)`; SPA
  navigation uses `useGuardedNavigate` or `requestNavigation`. Both paths show
  the same shared unsaved-changes dialog. A browser tab/window unload remains a
  browser-controlled confirmation because browsers do not permit a custom
  modal at that boundary.
- `TableActionGroup` receives the table's stable action set. Use `disabled` and
  `disabledReason` for row state; omit an action only when that action does not
  belong to the table. `minimumSlots` reserves trailing positions for an empty
  row. `DataGridEmptyAction` does this for the standard add/move/remove layout.
- A paginated `DataGrid` has exactly one query owner. Client mode receives the
  complete logical row set and applies filtering and sorting before slicing a
  page. Server mode receives only the loaded page, requires `onQueryChange`,
  and the backend applies every emitted filter/sort before pagination while
  returning `totalRows` for the filtered result. Server list filters declare
  their complete option domain instead of deriving it from the loaded page.
- Feedback and confirmation use `Dialog`, `ConfirmDialog`, or
  `DismissibleAlert`. They never fall back to `window.alert`.

#### FieldLabel Omission Register

Every Core field surface that intentionally does not render `FieldLabel` is
listed here. Module repositories keep an equivalent register in their durable
UI documentation until a central cross-repository audit is available.

| Core scope | Why `FieldLabel` is omitted | Accessible/context label source |
| --- | --- | --- |
| `PasswordField`, `ColorPickerField`, `DateField`, `TimeField`, and `DateTimeField` input internals | These are label-neutral composite primitives and are placed inside `FormField`/`FieldLabel` by the consuming form. Rendering another label inside the primitive would duplicate it. | Enclosing label; a direct consumer must pass an accessible name and record that direct composition here. |
| `ToggleSwitch` native checkbox | The shared component already renders its visible text through `FieldLabel`; the native input must not render a second label. | The enclosing native label and derived `aria-label`. |
| `FileDropZone` hidden file input | The input is an implementation detail of the labelled keyboard-operable drop target. | Drop target text and `inputLabel`/`aria-label`. |
| `AdminSelectionList` and `DataGrid` list-filter checkboxes | Each option is self-explanatory and already enclosed by its visible option label. | Enclosing native option label. |
| `EmailAddressInput` compact Name and Email fields | These two conventional fields are self-explanatory in the compact address popover; richer address guidance belongs to the enclosing field. | Visible native labels; the free-form editor also has a descriptive `aria-label`. |
| `DataGrid` page-size, filter, and inline cell editors | The surrounding column header/filter heading supplies field context; repeating a labelled help marker in every cell would add noise. | Column header, filter heading/native label, or generated cell `aria-label`. |
| Retention-policy value controls | `PolicyRow` owns the field label, help, effective value, and provenance for its control. | The containing `PolicyRow` label/help contract. |

#### Alert Exception Register

No `window.alert` or global `alert` exception is authorized.

## Implementation Sequence

| Phase | Scope | Output |
| --- | --- | --- |
| 0 | UX inventory | List every admin/settings/configuration surface, classify it, and record whether it violates a binding decision. |
| 1 | Core primitives | Shared wizard shell, advanced panel, help affordance, blocker callout, problem list, review step, and discovery/test result components. |
| 2 | File connectors | Adaptive create/edit for provider/server, credential, discovery/test, ownership/policy, plus optional assisted wizard later. |
| 3 | Mail servers | Same adaptive pattern as files, adapted to server/credential/policy and test-send/test-login behavior. |
| 4 | Policy/retention editors | Effective value first, provenance visible, override/edit in modal, blocked edits explained. |
| 5 | Module/package operations | Step-based install/uninstall flow with preflight, maintenance, daemon handoff, migration, and rollback explanation. |
| 6 | Remaining settings/admin screens | Apply inventory findings by priority and remove one-off layouts. |

## Current Surface Inventory

This is the phase-0 inventory baseline. It should be extended as each screen is
converted or reviewed.

| Surface | Repository | UX State | Next Action |
| --- | --- | --- | --- |
| File connector settings | `govoplan-files` | First adaptive modal slice started: connections and credentials now use full-state create/edit forms with conditional fields, advanced panels, and blocker primitives. Wizard shell is retained for later assisted setup. Central policy card still needs a layered editor. | Finish provider discovery/test-in-flow, then convert policy editing. |
| Mail server settings | `govoplan-mail` / `govoplan-core` | Uses the shared server/credential model visually, but create/edit still needs the same adaptive pattern as files. | Migrate to adaptive server/credential/policy dialogs, with optional assisted wizard later. |
| Connector policy/effective rows | `govoplan-core`, module UIs | Effective-policy direction exists, but many editors still expose broad option sets. | Put effective value first, move overrides into modal, and explain blocked edits. |
| Admin module management | `govoplan-admin` | Has preflight concepts, but operational choices are still technical and dense. | Convert install/uninstall/package changes to operator wizards. |
| Configuration packages | `govoplan-admin` | Catalog/import work exists, but package editing can still drift toward technical fields. | Add guided import/review/problem-list flow. |
| Retention and privacy | `govoplan-core` | Functional editor exists; consequence language and provenance can be stronger. | Layer advanced retention options and add review for broad changes. |
| API keys | `govoplan-access` / admin UI | Security-sensitive creation needs least-privilege guidance. | Add scoped creation wizard with expiry/owner review. |
| User settings | `govoplan-core` | Preferences persistence exists; interface navigation issue was fixed earlier, but the surface still needs UX review. | Keep simple sections, remove double-click traps, and add quiet explanations. |

## Impact Index

| Surface | Current Risk | Expected Pattern |
| --- | --- | --- |
| File connectors | Too many technical fields and unclear setup order. | Adaptive create/edit form with optional assisted wizard, discovery/test, credential binding, policy review, and advanced protocol panel. |
| Mail servers | Similar server/credential/policy concepts risk diverging from files. | Same tree/list and adaptive server/credential/policy model as file connectors. |
| Connector credentials | Security-sensitive details can overwhelm users. | Separate credential flow with secret-reference language and test result explanation. |
| Policy and effective settings | Users need to know why a value is inherited or locked. | Effective row first, source/provenance, local override action, actionable blocked reason. |
| Module install/uninstall | Operationally risky, currently inherently technical. | Operator wizard with preflight, maintenance, daemon handoff, review, and rollback explanation. |
| Configuration packages | Could become package JSON editing. | Package catalog/import wizard using provider data requirements and problem lists. |
| Retention/privacy | High-risk settings need explanation and provenance. | Layered editor with plain-language consequences and review. |
| Automation/workflow commands | Hidden side effects would undermine accountability. | Action/effect preview, system-actor display, command record, retry/quarantine/manual states, and audit links. |
| Postbox and encrypted communication | Retraction and access can be misunderstood. | Honest key-fetch/decryption state, expiry limits, recipient/device access provenance, and delivery evidence. |
| API keys | Security-sensitive creation and scope selection. | Scoped creation wizard, least-privilege suggestions, clear expiry/owner explanation. |
| User settings | Needs clarity and persistence across profile/interface/preferences. | Simple settings sections with immediate feedback and no double-click navigation traps. |

## Review Checklist

Every new or changed admin/configuration surface should answer:

- What is the common path, and is it visible without noise?
- Which fields are advanced, and are they collapsed by default?
- Is every configuration value editable through typed controls?
- Does the flow avoid JSON as the primary editor?
- Does the screen explain disabled actions and failed validation in plain
  language?
- Does it say who can fix a blocker and where?
- Does it reuse existing core patterns for wizard steps, problem lists, modals,
  help, and review?
- Is there a review or preflight step before broad, destructive, or risky
  changes?
- Does the action surface show consequence, reversibility, and audit evidence
  when rights, duties, records, money, communication, external systems, or
  workflow state are affected?
- Does the surface use every applicable central Core component? If it contains
  a custom component, is the product-owner authorization, narrow purpose,
  rationale, scope, and non-duplication evidence recorded?
- Is a collection-wide create action in the collection heading rather than
  duplicated in a persistent side panel?
- Are logical sections, tabular collections, boolean settings, and repeatable
  people/contact rows composed with `Card`, `DataGrid`, `ToggleSwitch`, and one
  structured row per person respectively?
- Does every non-self-explanatory field use `FieldLabel`, and is every omission
  recorded with its rationale and accessible-name source?
- Do explicit Discard and dirty navigation use the shared unsaved-changes
  registration/dialog rather than a page-local confirmation?
- Does every row retain the table's action set in the same order, disabling
  unavailable actions and reserving the same empty-row slots?
- Is feedback rendered with a central dialog/alert component, with no
  unauthorized `window.alert` or global `alert` call?
- If automation is involved, can the user see the trigger, system actor,
  observed effects, and failure/manual-intervention state?
- Are technical details available without being the first thing the user sees?

## Revision Rule

When a UX decision changes:

1. Update this ledger.
2. Update the affected shared components.
3. Update existing screens listed in the impact index.
4. Add or update Gitea issues for any remaining surfaces that still follow the
   old decision.
5. Sync the wiki.