docs / composition

gru · 0.7.0

Composition

How to structure pages: pick a shell, put lists in Panel/Card, reuse demo patterns for controls.

Rules

  1. Go-first · compose widgets in Go. Optional .gru is just structure.
  2. One job per layer · shell → (optional viewport) → Panel / Card → children.
  3. Surfaces host lists · dense ListTile stacks live in a Panel or Card.
  4. No new wrapper widgets when Panel, Card, Container, and ListTile already cover it.
  5. Borrow controls from demos · copy a pattern, not a whole private app shell.
  6. Name the height mode · intrinsic, fill (FlexGrow), or fixed.

Shell matrix

Shell IDUse whenDemo
CP-SHELL-PAGEScrollable demo / document pagesForm Demo
CP-SHELL-APPSHELLAppBar + scroll / fill bodyApp Shell (Go)
CP-SHELL-DESKTOPMenuBar + nav rail + mainDesktop Shell (Go)
CP-SHELL-EDGEFull-bleed utility chromeList Pane · Settings Desktop
CP-SHELL-GRIDFixed 12-col gridsResponsive Grid

Default for new apps / samples: flex column root + Card / Panel (samples/hello), or CP-SHELL-PAGE when using demo helpers.

Surfaces

WidgetRole
PanelFramed region, optional title / scroll
CardSection surface inside a page
ListTileRow in a list (title, subtitle, trailing)
ContainerLayout grouping (not a styled panel substitute)

Prefer theme styles (card, panel, list-tile, form-label) over one-off colors.

Borrow matrix (public)

You wantBorrow from
Page + cardsCard Nest (Go)
Desktop railDesktop Shell (Go)
AppBar + FABApp Shell (Go)
Desktop settings rowsSettings · Desktop (Go)
List + detailList Pane (Go)
FormsForm Demo + field batches
OverlaysBatch 1 · Modal; Batch 7 · Toast
WebView embedWebView Module / Focus Handoff
Signals starterCounter Demo

Modals & overlays

Full cookbook in the repo: COMPOSITION.md. Layout contracts: architecture/layout.md.

Next: Widgets · Demos · Architecture