govoplan-core/docs/UI_UX_DECISION_LEDGER.md

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

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.

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?
• 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.