intermediate commit

docs/FRONTEND_LAYOUT_PRINCIPLES.md

@@ -0,0 +1,57 @@
+# 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.