add-ideas/govoplan-core
1
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

Sync wiki after UX decision ledger

Albrecht Degering
2026-07-09 13:02:47 +02:00
parent 920694fdc9
commit 9b227f1f31
3 changed files with 177 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
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`

3
Repo-docs-DOCUMENTATION-MAP.md

@@ -1,4 +1,4 @@
<!-- codex-wiki-sync:7be9ad6a43754dcb72861497 -->
<!-- codex-wiki-sync:6c0873d5054a4797a0bbf7d4 -->
> 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. |

174
Repo-docs-UI-UX-DECISION-LEDGER.md Normal file

@@ -0,0 +1,174 @@
<!-- codex-wiki-sync:cf53d20eede728869b7f3de3 -->
> 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.