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/admin/pages/PlainResourcePages.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/PlainResourcePages.tsx)
- [frontend/src/admin/pages/DataList.tsx](/home/ray/dev/linkong/planet/frontend/src/admin/pages/DataList.tsx)
- [frontend/src/index.css](/home/ray/dev/linkong/planet/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:

```tsx
<AdminLayout>
  <div className="page-shell">
    <div className="page-shell__header">...</div>
    <div className="page-shell__body">...</div>
  </div>
</AdminLayout>
```

Total page height should be bounded within the `AdminLayout` 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:

```tsx
<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