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

New Issue

zemion · 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 added the

module/core

area/webui

codex/ready

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

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.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: add-ideas/govoplan-core#225