From 9b227f1f3115c14e0fc8bf74fe53ef05f0b9041b Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Thu, 9 Jul 2026 13:02:47 +0200 Subject: [PATCH] Sync wiki after UX decision ledger --- Codex-Project-Index.md | 1 + Repo-docs-DOCUMENTATION-MAP.md | 3 +- Repo-docs-UI-UX-DECISION-LEDGER.md | 174 +++++++++++++++++++++++++++++ 3 files changed, 177 insertions(+), 1 deletion(-) create mode 100644 Repo-docs-UI-UX-DECISION-LEDGER.md diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 633b1b3..369fbad 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -20,3 +20,4 @@ This page is generated from repository and product-directory project files. - [Repo-docs-PUBLIC-SECTOR-INTEGRATION-STRATEGY](Repo-docs-PUBLIC-SECTOR-INTEGRATION-STRATEGY) - `/mnt/DATA/git/govoplan-core/docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` - [Repo-docs-RELEASE-DEPENDENCIES](Repo-docs-RELEASE-DEPENDENCIES) - `/mnt/DATA/git/govoplan-core/docs/RELEASE_DEPENDENCIES.md` - [Repo-docs-REMOTE-WEBUI-BUNDLES](Repo-docs-REMOTE-WEBUI-BUNDLES) - `/mnt/DATA/git/govoplan-core/docs/REMOTE_WEBUI_BUNDLES.md` +- [Repo-docs-UI-UX-DECISION-LEDGER](Repo-docs-UI-UX-DECISION-LEDGER) - `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md` diff --git a/Repo-docs-DOCUMENTATION-MAP.md b/Repo-docs-DOCUMENTATION-MAP.md index d8e6551..e6abe98 100644 --- a/Repo-docs-DOCUMENTATION-MAP.md +++ b/Repo-docs-DOCUMENTATION-MAP.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-core/docs/DOCUMENTATION_MAP.md`. > Origin: `repository`. @@ -34,6 +34,7 @@ operator, and roadmap pages. | Topic | Canonical document | Notes | | --- | --- | --- | | Product roadmap and module routing | `GOVOPLAN_MASTER_ROADMAP.md` | Product-level sequencing, implementation gates, issue routing, and missing-module decisions. | +| UI/UX decisions | `UI_UX_DECISION_LEDGER.md` | Binding guided-UI decisions, open decisions, impact index, and review checklist. | | Public-sector integration posture | `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` | Strategy index; executable target inventory lives in `govoplan-connectors`. | | Configuration packages | `CONFIGURATION_PACKAGES.md` | Package model, provider contract, import/export flow, and tracking slices. | diff --git a/Repo-docs-UI-UX-DECISION-LEDGER.md b/Repo-docs-UI-UX-DECISION-LEDGER.md new file mode 100644 index 0000000..a573456 --- /dev/null +++ b/Repo-docs-UI-UX-DECISION-LEDGER.md @@ -0,0 +1,174 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/UI_UX_DECISION_LEDGER.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# 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. + +## 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 | + +## Decisions Due Now + +These decisions should be made before the first implementation slice because +they shape reusable components and screen structure. + +### DUE-001: Primary Admin Configuration Shell + +Decision needed: should admin/configuration surfaces 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. + +Recommended default: yes. Use this for file connectors and mail servers first, +then migrate policy, retention, API keys, and module operations. + +### DUE-002: Wizard Step Model + +Decision needed: standard wizard steps and names. + +Recommended 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. + +### DUE-003: Explanation Placement + +Decision needed: where do richer explanations live? + +Recommended baseline: + +- 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 needed: what qualifies as advanced? + +Recommended baseline: + +- 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 needed: should all disabled/blocked actions use a shared structured +reason object? + +Recommended default: yes. 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. + +### DUE-006: First Migration Surface + +Decision needed: first screen family to convert. + +Recommended default: file connectors, then mail servers. They share the same +server/credential/policy model, are high-value, and will prove the reusable +patterns quickly. + +## 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 | Guided setup for provider/server, credential, discovery/test, ownership/policy, and review. | +| 3 | Mail servers | Same 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. | + +## Impact Index + +| Surface | Current Risk | Expected Pattern | +| --- | --- | --- | +| File connectors | Too many technical fields and unclear setup order. | Provider wizard with discovery/test, credential binding, policy review, advanced protocol panel. | +| Mail servers | Similar server/credential/policy concepts risk diverging from files. | Same tree/list and wizard 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. | +| 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? +- 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.