trackgo-fe/.agents/skills/detail-layout/SKILL.md

name, description

name

description

detail-layout

Use whenever building or editing a read-only detail / show page in the ERP project (entity detail screens, master-data detail, transaction detail, device/asset detail, contract-style detail with tabs). Governs LAYOUT ONLY — page vertical stack, identity/hero placement, section card stacking, key-value grids vs label/value rows, status metric blocks, summary multi-column blocks, workflow steppers, horizontal tabs for many data categories, embedded tables/lists, and action placement. Does not govern colors, fonts, border-radius, shadows, or other visual styling. Trigger this any time a detail page, detail section, FieldValue grid, detail tab, or related-list table on a detail page is added or restructured — including when the user says "build a detail page", "show entity data", or explicitly asks for tabs.

Detail Layout

Layout rules for read-only detail / show pages, derived from this project's detail references:

• references/web-device-detail.png — desktop stacked section cards + key-value grid
• references/mobile-device-detail.png — narrow stacked cards + label/value rows
• references/web-contract-detail-tabs.png — top summary + stepper + horizontal tabs for many categories

These rules are about structure and position, not visual style (color, weight, radius, shadows belong to the design system / @repo/ui, not this skill).

Every detail page decision should be made by walking the steps below, in order.

Project chrome (do not rebuild)

Detail routes already render inside EnterpriseDetailPageProvider → ModulePageHeader / CorePageContainer. That chrome owns:

• Breadcrumbs
• Page title (+ optional highlight key, e.g. code/id)
• Status badge next to the title
• Global page actions (Edit, Duplicate, Delete, lifecycle actions, Create)

Do not re-implement those in the detail body. This skill governs the children of EnterpriseDetailPageProvider — the detail content below the module header.

Optional identity / hero (§3) is an extra content block when the entity benefits from an avatar/image + display name stack; it is not a second page header.

1. Pick the page body mode

Look at how many distinct data categories the entity has — that decides stacked vs tabbed body:

Detail type	Body mode
Few categories (≤3–4 section cards; e.g. Branch, User, simple master data)	Stacked sections — vertical stack of section cards under the header
Many categories (>3–4 distinct groups) or the user explicitly asks for tabs	Tabbed body — keep a slim always-visible top (identity / summary / stepper), then a horizontal tab bar; each tab owns one category's content
Narrow / mobile viewport	Same mode as desktop; only the internal key-value and status layouts collapse (§13)

Once a page picks stacked vs tabbed, stay consistent — don't mix an ad-hoc tab region with an ad-hoc long scroll of the same categories.

Force tabs when:

1. The user prompt says to use tab(s), or
2. Showing every section at once would produce a long scroll of ≥4–5 independent category cards (e.g. Basic / Attachments / Milestone / Payment / Approvals / History).

2. Vertical structure of the detail page

Top → bottom, never reorder:

1. Module chrome — already provided by EnterpriseDetailPageProvider (breadcrumbs, title, status, global actions).
2. Identity / hero (optional, §3) — only when an image/avatar + primary display name is part of the entity story.
3. Summary block (optional, §7) — high-level at-a-glance metadata / parties / key facts in a multi-column grid. Prefer this on tabbed pages so critical facts stay visible while tabs switch.
4. Workflow stepper (optional, §8) — only for entities with a linear lifecycle.
5. Body — either:
   • Stacked: section cards (§4) in category order, or
   • Tabbed: tab bar (§9) then the active tab panel (§10).

Gap between these major bands uses the largest rhythm gap (§12).

3. Identity / hero (optional content block)

Use when the entity has a meaningful visual (device photo, avatar, logo). Skip for plain master-data rows where the module header title is enough.

Desktop / wide

Single horizontal row inside one section surface:

Left	Middle (flex grow)	Right
Leading media (fixed square/circle)	Title stack: primary name (+ id if not already in chrome), then one short subtitle/category line	Primary content action if it belongs to this block (usually omit — Edit lives in module chrome)

• Media left-aligned; title stack left-aligned next to media; any block-level action right-aligned on the same row.
• Do not center the hero on wide layouts.

Narrow / mobile

Vertical centered stack: media → title → subtitle → optional full-width outline action.

• Center alignment is correct on narrow widths only.
• Primary action, if shown here, is full width under the subtitle — not beside the title.

4. Section cards (category containers)

Every logical data group is its own section container (e.g. "Device Details", "Security & OS Details", "Documents"):

• Sections stack vertically with consistent gap (§12) — never side-by-side category cards for independent groups.
• Inside each section, top row is a section header band:
  • Left: section title (bold text only — no input).
  • Right (optional): section-scoped action (e.g. "Upload a document") — text/link or secondary control, right-aligned on the same baseline as the title.
• Body of the section is one of: key-value grid (§5), key-value list (§5), status metric row/stack (§6), embedded table (§11), or a short summary + table combo (§10).
• One section = one job. Don't dump unrelated fields into the same card.

5. Key-value fields

Use FieldValue (or equivalent) for static metadata. Choose orientation by viewport / density:

A. Label-above grid (default on desktop / wide)

Matches the web device-detail reference and current SimpleGrid + FieldValue usage:

• Multi-column grid, typically 3–5 columns on wide (md+), 2 on sm, 1 on base.
• Each cell is a vertical stack: label on top, value underneath (this is what FieldValue already does).
• Fill left → right, top → bottom in reading order.
• Prefer equal column tracks; a short leftover row leaves trailing cells empty — do not stretch the last field full width just to fill space.
• Long free-text (address, notes) may span 2 columns or the full section width when the value would wrap awkwardly in a single track.

B. Label-left / value-right rows (default on narrow / mobile)

Matches the mobile device-detail reference:

• One field per row: label left-aligned, value right-aligned.
• Rows stack vertically inside the section; no multi-column grid on the narrow breakpoint.
• Status-colored values and link values stay in the value slot (right side) — they do not move to a new row.

Do not mix A and B inside the same section at the same breakpoint. Responsive collapse (§13) switches A → B on narrow widths.

6. Status / metric blocks

Use when each item is a named capability or check with its own status (e.g. Antivirus / MDM / Encryption / OS), not a flat field list.

Desktop / wide

Horizontal row of equal sub-blocks inside the section:

Each sub-block, top → bottom:

1. Icon + small category label (same row)
2. Primary value (software name / version)
3. Status badge / tag under the value

Narrow / mobile

Same sub-blocks, stacked vertically. Inside each sub-block:

1. Icon + small category label (top row)
2. Primary value on the next row, with status badge on the same row to the right of the value

Don't use this pattern for ordinary scalar fields — those stay in §5.

7. Summary multi-column block (optional, top of body)

Use on complex / tabbed details when several at-a-glance groups must stay visible above tabs (e.g. dates/value metadata | Party A | Party B):

• Full-width band under identity (or under module chrome if no identity).
• 2–3 equal columns on wide; each column is a titled group of compact key-value rows (label then value on one line, or icon + label + value).
• Columns are peer groups, not a key-value grid of unrelated fields — if fields aren't grouped into 2–3 stories, use a normal §5 section instead.
• Collapses to a vertical stack of the same groups on narrow widths (§13).

8. Workflow stepper (optional)

Only for entities with a linear lifecycle (Draft → Review → … → Active):

• Full-width band under summary (or under identity / chrome).
• Horizontal sequence left → right; completed → current → upcoming order must match domain order.
• Label the band with a short section title above the stepper (e.g. "Status update").
• On narrow widths, keep sequence order; may scroll horizontally or show a compact current-step focus — never reorder stages.

9. Horizontal tabs (many-data body)

When §1 selects tabbed body:

• Tab bar sits below identity / summary / stepper and above the active panel — never above the module chrome, never below the first content card of a stacked page.
• Tabs are a single horizontal list of category labels (Basic details, Attachments, Milestone, Payment, …).
• One active tab at a time; switching tabs replaces the panel content — do not keep all tab panels mounted as a long scroll underneath.
• Prefer ≤8–9 tabs; if more categories exist, merge related ones or keep rare ones behind a secondary entry inside a tab.
• Tab labels are short nouns/phrases; order tabs by user-task frequency (overview / basics first, history last).
• Use project Tabs from @repo/ui/components (see showcase forms demo for list/panel structure) — layout concern only: Tabs.List then Tabs.Panels.

What stays outside tabs

Always-visible above the tab bar (when present): identity (§3), summary (§7), stepper (§8). Do not put the only copy of critical status / party / date facts exclusively inside a tab if the user needs them while browsing other tabs.

10. Tab panel content

Each panel is laid out as if it were a small stacked detail of its own:

1. Optional panel sub-header — section title left; optional summary metrics split left/right on the same row (e.g. "Total invoice value" left, "Total estimated project value" right).
2. Optional visual summary (progress bar / distribution) full width under the sub-header — position only; styling is design-system.
3. One or more section cards (§4) and/or an embedded table (§11).

Do not nest a second tab bar inside a panel.

11. Embedded tables / related lists

For collections (documents, payment proofs, line history):

• Table lives inside a section card (§4).
• Section header band: title left, section action(s) right — filters and "Add …" sit on the right of the header, same row as the title (or immediately under the title row if filters + primary action don't fit).
• Column headers above rows; text/id columns left-aligned; numeric columns right-aligned; status as an inline indicator in its cell; row actions in a fixed trailing column (ellipsis / menu) — same width every row.
• Empty state stays inside the table/section body — don't relocate the section action.

12. Vertical rhythm

Define three consistent gap sizes and use them the same way on every detail page:

1. Label → value (smallest): binds a field's label to its value (FieldValue gap).
2. Field → next field / sub-block → next sub-block (medium): separates peers inside a section.
3. Section → section, and major band → next band (largest): separates cards, summary, stepper, and tab bar from each other.

Horizontal gaps inside grids match the medium rhythm. Don't invent a fourth gap tier per page.

13. Responsive collapse

Wide layout	Narrow collapse
Identity hero row (media | title | action)	Centered vertical stack (media → title → subtitle → full-width action)
Key-value label-above grid (§5A)	Label-left / value-right rows (§5B)
Status metric horizontal row (§6)	Stacked metric sub-blocks; badge beside value
Summary 2–3 columns (§7)	Stacked column groups, same order
Tab list	Horizontally scrollable tab list; panels still one-at-a-time
Table	Horizontal scroll inside the section or stacked label/value per row — pick one strategy per table type and keep it project-wide

Never re-pair fields into different logical groups on collapse — only column count / orientation changes.

14. Action placement (position only)

Action scope	Position
Global entity actions (Edit, Delete, Activate, …)	Module header actions via EnterpriseDetailPageProvider — top-right of chrome
Section-scoped action (Upload, Add record)	Right side of that section's header band (§4 / §11)
Section filters	Right side of the table/section header, before or beside the section primary action
Row action	Trailing column of that row only

Do not duplicate Edit in the body if the provider already exposes it, unless a mobile identity block needs a full-width local affordance (§3 narrow).

15. Checklist before finalizing any detail page

• Did you choose stacked vs tabbed from category count / user request, per §1?
• Is module chrome left to EnterpriseDetailPageProvider (no second breadcrumb/title/action bar)?
• If tabbed: do identity / summary / stepper stay above the tab bar, per §9?
• Is every category its own section card with title-left / action-right, per §4?
• Are scalar fields using label-above grid on wide and label/value rows on narrow, per §5 / §13?
• Are status/capability items using metric sub-blocks (§6), not mixed into a flat field grid?
• Do related lists use header actions + table alignment rules, per §11?
• Are global vs section vs row actions in the correct slots, per §14?
• Does collapse preserve grouping and only change orientation/columns, per §13?

Quick mapping to this codebase

// Stacked (few categories) — children of EnterpriseDetailPageProvider
<>
  {/* optional identity */}
  <Paper>{/* section: SimpleGrid + FieldValue */}</Paper>
  <Paper>{/* section: status metrics or table */}</Paper>
</>

// Tabbed (many categories / user asked for tabs)
<>
  {/* optional identity + summary + stepper */}
  <Tabs defaultValue="basic">
    <Tabs.List>{/* category tabs */}</Tabs.List>
    <Tabs.Panel value="basic">{/* section cards */}</Tabs.Panel>
    <Tabs.Panel value="payments">{/* summary row + table */}</Tabs.Panel>
  </Tabs>
</>

Prefer existing primitives: Paper / section surfaces, SimpleGrid, FieldValue, Tabs, StatusBadge, table components from @repo/ui — this skill decides where they sit, not how they are themed.