planet/docs/technical/en/frontend-layout-guidelines.md

Frontend Layout Guidelines

Admin pages in this project default to a "single-screen workspace" layout standard. The goal is not to prevent all overflow, but to ensure that under common desktop viewports:

• The main page structure is visible within one screen
• The user can simultaneously see the page header, summary area, and main workspace
• Overflow content scrolls within its module, rather than stretching the entire page vertically

Current recommended reference implementations:

• frontend/src/pages/BGP/BGP.tsx
• frontend/src/index.css

Core Principles

1. Pages Should Prioritize a Single-Screen Workspace

Admin pages default to:

• Header: title, description, main actions
• Main workspace: stats cards, tables, charts, lists, tabs

Recommended structure:

<AppLayout>
  <div className="page-shell">
    <div className="page-shell__header">...</div>
    <div className="page-shell__body">...</div>
  </div>
</AppLayout>

Total page height should be bounded within the AppLayout content area, not allowed to grow naturally downward without limit.

2. Scrolling Should Happen Inside Modules

If tables, logs, long lists, or chart details overflow their space:

• Let the card scroll internally
• Let the table scroll internally
• Let the tab content area scroll internally

Do not rely on full-page scrolling to "solve" the space problem.

3. The Main Workspace Must Get the Most Space

The most important module on a page must be the visual and spatial lead. Typically ensure:

• Header always visible
• Summary area height controlled
• Main table / chart / analysis area occupies more than 50% of visible height

If a page has multiple large modules, priority order is:

1. First compress the description and summary areas
2. Then move secondary modules into tabs or switch views
3. Only then consider adding more full-page scrolling

4. Small Screens and High Zoom Must Enter Compact Mode

When window height is low, width is narrow, or system zoom is high, actively switch to a compact layout:

• Reduce card padding
• Reduce header and cell spacing
• Convert summary area to a more compact single-row or horizontal-scroll layout
• Move secondary modules into tabs, drawers, or collapsed areas

Compact mode goal: maintain usability, not just shrink all text and controls.

5. Overflow Responsibility Must Be Explicit

Large content blocks on the page must explicitly define:

• Who is responsible for filling remaining height
• Who is responsible for clipping
• Who is responsible for scrolling

Common requirements:

• Parent container chain needs min-height: 0
• Workspace containers typically need display: flex
• The real scroll node must explicitly use overflow: auto

6. Cards Must Not Be Compressed to Unreadable

Historical problems have not been "missing scrollbars," but:

• Cards compressed by flex to only a tiny visible area
• Text can render but cannot be read completely
• Content exists but is cut off by overflow: hidden

Future constraints:

• First ensure cards have a readable minimum height
• If further compression affects readability, switch to internal scrolling
• Do not compress body text, tables, or description areas into unreadable strips just to "maintain one screen"

7. Tabs Are Not Inherently Safe Layout Containers

Historical regressions with Tabs include:

• Hidden tab panes reappearing due to custom display: flex
• All tabs having the same height/overflow rules forced on them
• Table tabs work, but markdown / help / diagnostics tabs get crushed

Constraints:

• Each type of content inside Tabs must define its own layout strategy
• Table tab: "fixed height + internal scrolling"
• Docs/Markdown tab: better as "tab pane self-scrolls + content normal document flow"
• If overriding component library styles, verify the hidden state still holds

8. Summary Areas Should Enter Compact Mode First, Not Compress Body

Historical experience shows the top summary cards are most often mishandled:

• They frequently get forcibly narrowed to "fit everything"
• Then the body, tables, and AI result areas all lose their main space

Unified constraint:

• On small screens or high zoom, summary cards should first:
  • Reduce padding
  • Switch to horizontal scrolling
  • Switch to a more compact grid
• Do not sacrifice the main workspace's visible area first

9. Long-Document Content Should Prioritize Reading Experience

Content like the following cannot directly apply "table workspace" logic:

• AI briefs
• Runtime logs
• Raw JSON
• Help text
• Multi-paragraph descriptive text

These areas should prioritize:

• Stable title and meta information visibility
• Body has a clear minimum readable height
• Body scroll strategy defined separately
• Support for Markdown tables, dividers, quotes, code blocks

10. Height Critical Paths Should Use Fewer Wrapper Layers

Many scroll problems historically were not in the component itself, but came from an extra wrapper layer:

• Height chain broken
• min-height: 0 not passed down
• overflow responsibility absorbed

Therefore:

• For height-critical areas, prefer the most direct DOM structure
• When using Space, extra wrapper div, or third-party layout containers, verify they don't change scroll and height semantics
• If an area shows "content is there but only a sliver is visible," first suspect an intermediate wrapper layer

Historical Pitfalls

From Earth, Playground, BGP, DataSources page bugfixes, several high-frequency pitfall types:

1. Using overflow: hidden to Mask Layout Problems

Superficially the page looks "clean," but actually causes:

• Content getting clipped
• Tab content reduced to a sliver
• Panel renders successfully but users can't see it

Correct approach:

• Let the real content node scroll
• Don't let upper containers unconditionally clip all child content

2. Treating All Tabs as the Same Content Type

Tables, Markdown, help cards, and log streams have completely different space requirements.

Correct approach:

• Table: fixed workspace + internal scrolling
• Document: normal flow content + pane-level scrolling
• Side description: content-driven height, not forced to fill

3. Only Doing Visual Shrinking, Not Space Reallocation

This causes:

• Card text truncated
• Table shows only 1-2 rows
• Buttons and filters crammed together

Correct approach:

• Compact mode prioritizes re-layout
• Summary area horizontal scrolling
• Collapse / hide secondary modules

4. Incomplete Parent Container Height Chain

This is the most common cause of internal scrolling failing.

Inspection order:

1. Does the outer layer actually have a determined height?
2. Does the flex parent have min-height: 0?
3. Does the real scroll node explicitly use overflow: auto?
4. Have intermediate wrapper layers silently changed layout semantics?

5. UI State and Display State Out of Sync

Repeated in Earth-related changes:

• Layer hidden, but hover/lock still active
• Tooltip still showing stale object
• Legend not switching with the state

These constraints also apply to admin pages:

• Hidden, unmounted, or switched-out content should not retain active interaction state

Recommended Implementation Patterns

Page Shell

Reuse existing common structures in the project:

• .dashboard-content-inner
• .page-shell
• .page-shell__header
• .page-shell__body
• .table-scroll-region

Do not invent a completely different height and scroll semantics for each page.

Table Workspace

Recommended pattern:

<Card>
  <div className="table-scroll-region" ref={tableRegionRef}>
    <Table
      pagination={false}
      scroll={{ x: 1200, y: tableHeight }}
    />
  </div>
</Card>

Requirements:

• Tables should scroll inside their card
• scroll.y should come from actual available height calculation, not a completely static magic number
• Parent container chain must ensure header, body, content overflow all close inside the table

Multi-Module Pages

If a page has:

• Summary cards
• Table
• Anomaly details
• Recent events

Do not simply stack all modules vertically. Prefer:

• Top summary + single main workspace at bottom
• Tab-switch multiple secondary data views
• Left-right split with each column scrolling independently

Discouraged Patterns

The following patterns are considered non-compliant with this project's page standard:

• Relying on full-page vertical scrolling to display the main workspace
• Stacking 3-4 large cards vertically on one page, each wanting to display fully
• Table without internal scrolling, causing only 1-2 rows visible after zoom
• Parent container missing min-height: 0, causing internal scrolling to fail
• Only doing visual shrinking without addressing real space allocation

Page Acceptance Checklist

Before submitting, check at minimum:

• Can page header, summary area, and main workspace appear simultaneously?
• Does the main workspace get the most height on the page?
• When table or detail overflows, does the scrollbar appear inside the module?
• Is the card compressed to the point where text doesn't display completely? If so, has it switched to internal scrolling?
• Is it still usable at browser zoom 125% / 150%?
• In a low-height window, is there still a reasonable number of visible content rows?
• Are Tabs, Card, Table still operable when overflowing?
• Do non-table tabs (Markdown, help text, logs) have their own independent and reasonable scroll strategy?

Implementation Order

When adding or refactoring admin pages, design in this order:

1. Define the main workspace first
2. Determine which modules must always be visible
3. Then handle styling and visual hierarchy

Simply put:

• First ensure correct space allocation
• Then handle scroll boundaries
• Finally handle aesthetics