govoplan/docs/FRONTEND_LAYOUT_PRINCIPLES.md

GovOPlaN Frontend Layout Principles

GovOPlaN modules should choose their page layout by the kind of work the user is doing, not by the repository that owns the feature.

Structured Data Directories

Use a full-available-space workspace for structured data directories: files, addresses, calendars, records, mailboxes, document stores, and similar domains where the primary task is browsing, selecting, filtering, inspecting, and acting on related objects.

Principles:

• The module route should use the full available content area.
• Do not add a separate page heading row above the main workspace.
• Prefer persistent navigation panes, such as tree panels, source panels, folder panels, calendar list panels, or mailbox folder panels.
• Keep collection navigation and collection-level actions close to the relevant pane header.
• Use bounded widths for navigation/list panes and let the main detail/content pane take the remaining space.
• Keep filtering controls inside the pane they affect.
• Use overlays, toasts, or floating alerts for transient messages so the workspace height does not change.

This pattern is appropriate when the user is working inside one coherent data domain and needs spatial continuity.

Workflow And Configuration Surfaces

Use the standard heading/menu/card visual language for workflow structures, settings, administration, dashboards, and pages that collect essentially unrelated areas.

Principles:

• A page heading and subnavigation are appropriate when the page explains a task, workflow stage, or administrative area.
• Cards are appropriate for repeated independent panels, settings groups, summaries, and dashboard widgets.
• Collapsible panels and segmented controls are appropriate when a dense configuration area needs controlled disclosure.
• Avoid forcing workflow/configuration pages into a file-explorer style unless the primary interaction is genuinely directory browsing.

This pattern is appropriate when the user is comparing or configuring separate concerns rather than navigating one structured object space.

Shared Components

Reusable layout components belong in govoplan-core WebUI. Modules may consume shared components from core, but must not import another module's private UI components directly.

When a module-specific component becomes generally useful, promote it to core with a parameterized API before reusing it elsewhere.