Guided layered UI/UX overhaul for admin and configuration surfaces #225

New Issue

2026-07-09T12:57:01+02:00

zemion commented

2026-07-09 12:57:01 +02:00

The product vision now treats guided, layered UI as a quality gate. This issue tracks the cross-system UI/UX pass needed to make GovOPlaN usable for non-technical operators while retaining full power for expert users.

Vision reference: govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md, section User Experience Direction.

Goals:

Replace option dumps with guided flows and progressive disclosure.
Avoid raw JSON as the primary configuration UI; every setting needs fields, validation, and help.
Use wizards for connector setup, package import, module lifecycle changes, policy changes, and destructive operations.
Use discovery where possible, for example Nextcloud base URL -> discovered WebDAV endpoint.
Explain blocked or unavailable actions in plain language, including who can fix the problem and where.
Reuse shared visual patterns, placement, modal behavior, problem lists, and empty/error states.

First implementation plan:

Inventory all admin/settings/configuration screens and classify them as overview, repeated administration, setup wizard, policy editor, or destructive operation.
Define shared WebUI primitives for layered configuration: wizard shell, collapsible advanced section, explanatory help affordance, actionable blocker callout, review step, and problem list.
Apply the pattern first to file connectors and mail servers because they already share server/credential/policy concepts.
Refactor module/package install flows to a step-based operator workflow with preflight, review, daemon handoff, and rollback explanation.
Refactor policy and retention editors around effective value, source/provenance, local override, and reason for disabled edits.
Add a recurring UX review checklist for new admin/configuration surfaces.

Acceptance criteria:

New shared components exist in core WebUI and are documented through local usage patterns.
File connector and mail server setup use the same layered server/credential/policy workflow.
Disabled actions expose actionable explanations rather than silent disabled states.
No primary admin/configuration flow requires JSON editing.
At least one connector setup flow performs guided discovery and fills technical fields for review.
Future issues can be split by module/surface from this umbrella issue.

The product vision now treats guided, layered UI as a quality gate. This issue tracks the cross-system UI/UX pass needed to make GovOPlaN usable for non-technical operators while retaining full power for expert users. Vision reference: `govoplan-core/docs/GOVOPLAN_MASTER_ROADMAP.md`, section `User Experience Direction`. Goals: - Replace option dumps with guided flows and progressive disclosure. - Avoid raw JSON as the primary configuration UI; every setting needs fields, validation, and help. - Use wizards for connector setup, package import, module lifecycle changes, policy changes, and destructive operations. - Use discovery where possible, for example Nextcloud base URL -> discovered WebDAV endpoint. - Explain blocked or unavailable actions in plain language, including who can fix the problem and where. - Reuse shared visual patterns, placement, modal behavior, problem lists, and empty/error states. First implementation plan: 1. Inventory all admin/settings/configuration screens and classify them as overview, repeated administration, setup wizard, policy editor, or destructive operation. 2. Define shared WebUI primitives for layered configuration: wizard shell, collapsible advanced section, explanatory help affordance, actionable blocker callout, review step, and problem list. 3. Apply the pattern first to file connectors and mail servers because they already share server/credential/policy concepts. 4. Refactor module/package install flows to a step-based operator workflow with preflight, review, daemon handoff, and rollback explanation. 5. Refactor policy and retention editors around effective value, source/provenance, local override, and reason for disabled edits. 6. Add a recurring UX review checklist for new admin/configuration surfaces. Acceptance criteria: - New shared components exist in core WebUI and are documented through local usage patterns. - File connector and mail server setup use the same layered server/credential/policy workflow. - Disabled actions expose actionable explanations rather than silent disabled states. - No primary admin/configuration flow requires JSON editing. - At least one connector setup flow performs guided discovery and fills technical fields for review. - Future issues can be split by module/surface from this umbrella issue.

zemion commented

2026-07-09 13:03:16 +02:00

Decision ledger added and synced to the wiki:

Repository: govoplan-core/docs/UI_UX_DECISION_LEDGER.md
Wiki page: Repo-docs-UI-UX-DECISION-LEDGER

The ledger records binding UX decisions UX-001 through UX-009, the impact index, and the review checklist. The immediate product decisions to confirm before implementation are DUE-001 through DUE-006:

Standard two-zone admin/configuration shell.
Standard wizard step model.
Explanation placement rules.
Advanced-options contract.
Structured blocker language contract.
First migration surface: file connectors, then mail servers.

Implementation should not create new one-off admin/configuration patterns unless this ledger is revised first.

Decision ledger added and synced to the wiki: - Repository: `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` - Wiki page: `Repo-docs-UI-UX-DECISION-LEDGER` The ledger records binding UX decisions `UX-001` through `UX-009`, the impact index, and the review checklist. The immediate product decisions to confirm before implementation are `DUE-001` through `DUE-006`: 1. Standard two-zone admin/configuration shell. 2. Standard wizard step model. 3. Explanation placement rules. 4. Advanced-options contract. 5. Structured blocker language contract. 6. First migration surface: file connectors, then mail servers. Implementation should not create new one-off admin/configuration patterns unless this ledger is revised first.

zemion commented

2026-07-09 13:05:34 +02:00

Product decision recorded: DUE-001 through DUE-006 are green-lit and now marked accepted in govoplan-core/docs/UI_UX_DECISION_LEDGER.md.

Implementation may proceed with:

UX inventory of admin/settings/configuration surfaces.
Core WebUI primitives for the shared guided configuration pattern.
File connector guided setup as the first converted surface.
Mail server setup using the same pattern.

Future admin/configuration work should treat the accepted DUE decisions plus UX-001 through UX-009 as binding unless the ledger is explicitly revised first.

Product decision recorded: DUE-001 through DUE-006 are green-lit and now marked accepted in `govoplan-core/docs/UI_UX_DECISION_LEDGER.md`. Implementation may proceed with: 1. UX inventory of admin/settings/configuration surfaces. 2. Core WebUI primitives for the shared guided configuration pattern. 3. File connector guided setup as the first converted surface. 4. Mail server setup using the same pattern. Future admin/configuration work should treat the accepted DUE decisions plus UX-001 through UX-009 as binding unless the ledger is explicitly revised first.

zemion commented

2026-07-09 13:17:03 +02:00

Implementation update, 2026-07-09:

Phase-0 inventory baseline added to govoplan-core/docs/UI_UX_DECISION_LEDGER.md and synced to wiki page Repo-docs-UI-UX-DECISION-LEDGER.
Core WebUI now has reusable guided-configuration primitives: GuidedConfigDialog, AdvancedOptionsPanel, ActionBlockerHint, and GuidedReviewList.
First file-connector UI slice is implemented in govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx: connection and credential create/edit flows now use wizard steps, review summaries, structured blocker hints, and collapsed advanced metadata/protocol/env fields.
Existing file connector API behavior is unchanged; this is a UX layering slice around the current profile/credential save paths.

Verification:

npm run build in govoplan-core/webui passed.
npm run audit:i18n-structural in govoplan-core/webui passed.
git diff --check passed for touched tracked core files; files module check has no tracked diff because the panel file is currently untracked in that repo state.

Remaining work on this issue:

Add real provider discovery/test inside the connector wizard, especially Nextcloud base URL to WebDAV endpoint.
Layer the central connector policy card using the same effective-policy/edit-modal pattern.
Migrate mail server settings to the same guided server/credential/policy structure.
Continue inventory conversion for module/package operations, retention/privacy, API keys, and user settings.

Implementation update, 2026-07-09: - Phase-0 inventory baseline added to `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` and synced to wiki page `Repo-docs-UI-UX-DECISION-LEDGER`. - Core WebUI now has reusable guided-configuration primitives: `GuidedConfigDialog`, `AdvancedOptionsPanel`, `ActionBlockerHint`, and `GuidedReviewList`. - First file-connector UI slice is implemented in `govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx`: connection and credential create/edit flows now use wizard steps, review summaries, structured blocker hints, and collapsed advanced metadata/protocol/env fields. - Existing file connector API behavior is unchanged; this is a UX layering slice around the current profile/credential save paths. Verification: - `npm run build` in `govoplan-core/webui` passed. - `npm run audit:i18n-structural` in `govoplan-core/webui` passed. - `git diff --check` passed for touched tracked core files; files module check has no tracked diff because the panel file is currently untracked in that repo state. Remaining work on this issue: - Add real provider discovery/test inside the connector wizard, especially Nextcloud base URL to WebDAV endpoint. - Layer the central connector policy card using the same effective-policy/edit-modal pattern. - Migrate mail server settings to the same guided server/credential/policy structure. - Continue inventory conversion for module/package operations, retention/privacy, API keys, and user settings.

zemion commented

2026-07-09 13:31:52 +02:00

Design correction, 2026-07-09:

The default file connector create/edit interaction has been changed from a stepper wizard to an adaptive full-state dialog.

Rationale recorded in govoplan-core/docs/UI_UX_DECISION_LEDGER.md as DUE-007:

Ordinary create/edit should show the full editable state in one consistent form.
The form adapts immediately when provider, credential mode, or policy mode changes, showing only relevant fields.
Editing an existing object must look like the state created earlier, not force the user through a linear setup path.
Wizard shells remain available for assisted setup, first-run guidance, import/discovery-heavy workflows, and operational preflight.

Implementation update:

govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx now uses adaptive dialogs for file connections and credentials.
GuidedConfigDialog remains exported in core for later assisted setup flows.
Core modal CSS was adjusted so the wizard shell fills its modal body and scrolls only inside the content pane.

Verification:

npm run build in govoplan-core/webui passed.
npm run audit:i18n-structural in govoplan-core/webui passed.
Targeted whitespace/diff checks passed.

Design correction, 2026-07-09: The default file connector create/edit interaction has been changed from a stepper wizard to an adaptive full-state dialog. Rationale recorded in `govoplan-core/docs/UI_UX_DECISION_LEDGER.md` as DUE-007: - Ordinary create/edit should show the full editable state in one consistent form. - The form adapts immediately when provider, credential mode, or policy mode changes, showing only relevant fields. - Editing an existing object must look like the state created earlier, not force the user through a linear setup path. - Wizard shells remain available for assisted setup, first-run guidance, import/discovery-heavy workflows, and operational preflight. Implementation update: - `govoplan-files/webui/src/features/files/FileConnectorSettingsPanel.tsx` now uses adaptive dialogs for file connections and credentials. - `GuidedConfigDialog` remains exported in core for later assisted setup flows. - Core modal CSS was adjusted so the wizard shell fills its modal body and scrolls only inside the content pane. Verification: - `npm run build` in `govoplan-core/webui` passed. - `npm run audit:i18n-structural` in `govoplan-core/webui` passed. - Targeted whitespace/diff checks passed.

zemion commented

2026-07-09 15:18:08 +02:00

Implemented the next connector UI/workflow slice: shared connection tree now fills card bodies through LoadingFrame and keeps columns aligned with child indentation; file credential creation is only available from a parent connection row and uses UserRoundKey after bumping lucide-react to 1.23.0; required-field blockers now use field highlighting plus disabled-save hover feedback; WebDAV/Nextcloud endpoint discovery route and inline connection-dialog feedback were added; app rail navigation now goes through the unsaved-change guard. Updated the UI/UX decision ledger and synced the wiki with the discovery-feedback and compact blocker rules.

zemion commented

2026-07-09 15:40:57 +02:00

Follow-up connector UI fixes: stabilized ConnectionTree action column so rows/header align; kept credential indentation inside the first column only; made the add-credential UserRoundKey action primary-colored; added a credential login test button in the secret section using a strict discovery probe; changed the local Nextcloud placeholder from /files/govoplan/ to /files/admin/ after confirming the Docker service returns 404 for govoplan and 207 for admin/webdav. Build and i18n audit pass; connector smoke passes for WebDAV and Nextcloud, SMB skipped unless smbprotocol is installed.

zemion commented

2026-07-20 14:43:15 +02:00

This is now the admin/configuration child of the product-wide interface pattern-language program add-ideas/govoplan#11. Its primitives and migrations should follow that shared taxonomy; Campaign #74 is the first full-domain pilot.

zemion added the area/governance area/webui codex/ready module/core

labels 2026-07-29 14:15:12 +02:00

zemion commented

2026-07-30 17:46:46 +02:00

Admin navigation slice pushed in Core f0898fc, Access e8ea347, and the contributing module commits.

Administration now uses a reusable tree navigation with scope branches and nested module-specific settings. Module contributions declare their owning module and whether a surface is management or settings, so Files, Mail, Policy, Audit, Postbox, Views and other optional modules appear in the right branch only when installed/authorized. This is a bounded slice of the broader UI overhaul; the issue remains open.

Admin navigation slice pushed in Core `f0898fc`, Access `e8ea347`, and the contributing module commits. Administration now uses a reusable tree navigation with scope branches and nested module-specific settings. Module contributions declare their owning module and whether a surface is management or settings, so Files, Mail, Policy, Audit, Postbox, Views and other optional modules appear in the right branch only when installed/authorized. This is a bounded slice of the broader UI overhaul; the issue remains open.

zemion commented

2026-07-31 22:54:26 +02:00

Evaluation: this remains a valid cross-platform umbrella and is not complete.

The platform now has several of the required primitives and examples (shared Dialog/Button/DataGrid/alerts/help, wizard directory, connector discovery, policy provenance, module installer queue, Campaign workflow visuals, Views, and version-aware Docs). The acceptance criteria still require a systematic file-connector/mail-server convergence, actionable explanations on every disabled admin action, elimination of primary JSON editors, and the recurring cross-module UX review. Keep this issue open and split implementation by concrete surface rather than attempting one monolithic redesign.

Evaluation: this remains a valid cross-platform umbrella and is not complete. The platform now has several of the required primitives and examples (shared Dialog/Button/DataGrid/alerts/help, wizard directory, connector discovery, policy provenance, module installer queue, Campaign workflow visuals, Views, and version-aware Docs). The acceptance criteria still require a systematic file-connector/mail-server convergence, actionable explanations on every disabled admin action, elimination of primary JSON editors, and the recurring cross-module UX review. Keep this issue open and split implementation by concrete surface rather than attempting one monolithic redesign.

zemion referenced this issue from GovOPlaN/govoplan-access

2026-08-03 08:08:40 +02:00

[Debt] Migrate Access WebUI to the interface pattern language #19

zemion referenced this issue from GovOPlaN/govoplan-admin

2026-08-03 08:08:41 +02:00

[Debt] Migrate Admin WebUI to the interface pattern language #8

zemion referenced this issue from GovOPlaN/govoplan-audit

2026-08-03 08:08:41 +02:00

[Debt] Migrate Audit WebUI to the interface pattern language #8

zemion referenced this issue from GovOPlaN/govoplan-policy

2026-08-03 08:08:43 +02:00

[Debt] Migrate Policy WebUI to the interface pattern language #11

zemion referenced this issue from GovOPlaN/govoplan-tenancy

2026-08-03 08:08:45 +02:00

[Debt] Migrate Tenancy WebUI to the interface pattern language #6

zemion referenced this issue from GovOPlaN/govoplan-views

2026-08-03 08:08:45 +02:00

[Debt] Migrate Views WebUI to the interface pattern language #2

zemion commented

2026-08-03 08:45:28 +02:00

Codex State: progress

Summary

Advanced the guided admin/configuration program through Admin commit 6dbccd5.
Module installation now has a tested five-stage operator projection, stale-evidence guard, contextual help, and canonical queue blocker explanation.
The 2026-08-03 generated interface inventory now links bounded migration issues for all 35 WebUI contributors in meta commit 935c1fe.

Verification

Admin installer workflow model: 4 passed.
Core WebUI TypeScript and structural i18n audits passed.
Workspace manifest registry: 65/65 passed.

Next / Blocked

Umbrella remains open for file/mail server convergence, the remaining admin panels, and the systematic disabled-action/JSON-primary-editor audit.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Advanced the guided admin/configuration program through Admin commit 6dbccd5. - Module installation now has a tested five-stage operator projection, stale-evidence guard, contextual help, and canonical queue blocker explanation. - The 2026-08-03 generated interface inventory now links bounded migration issues for all 35 WebUI contributors in meta commit 935c1fe. ### Verification - `Admin installer workflow model: 4 passed.` - `Core WebUI TypeScript and structural i18n audits passed.` - `Workspace manifest registry: 65/65 passed.` ### Next / Blocked - Umbrella remains open for file/mail server convergence, the remaining admin panels, and the systematic disabled-action/JSON-primary-editor audit. Suggested status label: `status/in-progress`

zemion commented

2026-08-03 10:17:55 +02:00

Codex State: done

Summary

Closed the guided Core configuration umbrella after completing the platform-owned host contract and the first two cross-module migrations. Core settings, reusable credentials, and retention now use typed controls, contextual documentation, unsaved-state handling, actionable scope/permission/lock blockers, and keyboard-reachable disabled-action explanations. Files and Mail independently document and verify the same layered server/credential/policy workflow, including connector discovery. Remaining surface work is already bounded in module-owned migration issues under GovOPlaN #11.

Changed Files

Core fa32cca; Files d8ae506; Mail 7844d9c; Admin lifecycle 6dbccd5; meta rollout evidence 7b6ceeb.

Verification

Core action-blocker, documentation-help, module-capability/privacy-policy/help-context suites; Core interface-pattern structural gate; structural i18n and theme contracts; 121 module-system tests; full-product TypeScript/Vite build and bundle budgets. Files and Mail focused backend/WebUI suites were recorded on their closed migration issues.

Next / Blocked

Continue Policy #11, Audit #8, Access #19, Admin #8, Tenancy #6 and Views #2 as module-owned migrations. New configuration surfaces remain subject to the Core checklist and GovOPlaN #11 definition of done.

## Codex State: done ### Summary - Closed the guided Core configuration umbrella after completing the platform-owned host contract and the first two cross-module migrations. Core settings, reusable credentials, and retention now use typed controls, contextual documentation, unsaved-state handling, actionable scope/permission/lock blockers, and keyboard-reachable disabled-action explanations. Files and Mail independently document and verify the same layered server/credential/policy workflow, including connector discovery. Remaining surface work is already bounded in module-owned migration issues under GovOPlaN #11. ### Changed Files - `Core fa32cca; Files d8ae506; Mail 7844d9c; Admin lifecycle 6dbccd5; meta rollout evidence 7b6ceeb.` ### Verification - `Core action-blocker, documentation-help, module-capability/privacy-policy/help-context suites; Core interface-pattern structural gate; structural i18n and theme contracts; 121 module-system tests; full-product TypeScript/Vite build and bundle budgets. Files and Mail focused backend/WebUI suites were recorded on their closed migration issues.` ### Next / Blocked - Continue Policy #11, Audit #8, Access #19, Admin #8, Tenancy #6 and Views #2 as module-owned migrations. New configuration surfaces remain subject to the Core checklist and GovOPlaN #11 definition of done.

zemion closed this issue

2026-08-03 10:17:55 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan-core#225