Screens

Which component to use for a whole page, a shell, or the structure a page sits in. Find the job, take the component, and read the “not when” before you commit: it names the thing people reach for by mistake, and what to use instead.

Screen types

Start a screen from a template, not from a blank file.

Screen	Start from	Uses	When
An application page — a list, a dashboard, a record	app-shell	`Nav`, `Sidebar`, `Breadcrumbs`, `PageHead`, `Stat`, `Table`, `Timeline`, `State`	Every client application starts here: header, rail, page head with figures, a data panel.
A multi-step form or wizard	intake	`Flow`, `Stepper`, `Field`, `Input`, `Choice`, `ErrorSummary`, `State`	Back on the left, forward on the right, one step at a time, and all six states.
A checkout or anything with a price	purchase	`Flow`, `Quantity`, `RadioCards`, `Summary`, `Panel`	Quantities, a delivery choice with a figure on each option, and one emphasised total.
A create form — describe, label, attach	work-item-create	`Flow`, `Field`, `Input`, `Segmented`, `TokenInput`, `Combobox`, `FileUpload`	A new record with a type, labels, an owner and evidence.
Closing or approving a record, with an irreversible confirm	work-item-close	`Checklist`, `RadioCards`, `FileUpload`, `Comment`, `Dialog`, `Panel`	Criteria that stay visible once checked, an outcome, evidence, the thread, and a confirm that lists what it writes.
A marketing or landing page	landing	`Nav`, `Layout`, `SectionBand`, `Card`, `Type`	The one saturated band, feature cards and a close.
A presentation deck	deck	`Slide`, `Table`, `Meter`, `Tag`	Slides sized in container units, so a deck reads the same in a grid or projected.

At a glance

Job	Use	Not when	Instead	Because
Hold one self-contained thing on a hairline surface	`Card`	The surface hosts a region — a table, a form, a list — with a header	`Panel`	A panel is a frame for a region with a header and one action; a card is the thing itself.
		The content is a document someone reads	`Paper`	Paper is a sheet on a ground, made for reading down; a card is for scanning across.
		There is a list of records, each read on its own	`Item`	A list of cards is a wall of boxes; an item list keeps rows quiet and aligned.
		The card is a choice someone picks in a form	`RadioCards`	A radio card is a real radio with the whole card as its label.
Build the page between somebody and the product — sign in, accept an invitation	`Entry`	The screen says there is nothing here, or that the person may not see it	`State`	An empty or denied state reports absence; a sign-in form drawn with it reads as a dead end.
		Getting in takes several steps of questions	`Flow`	A multi-step journey needs the step rail and the back/forward footer.
		The page is the product itself — a header, a rail and content	`Nav`	The product starts from the app shell — header, rail, content; an entry page holds no navigation.
Lay out a multi-step journey with a step rail, one step of content and a fixed footer	`Flow`	You only need to show where someone is in a sequence, inside a page that is not a step flow	`Stepper`	The stepper is the position marker on its own; the flow is the whole shell around it.
		The process does not fit a rail, a content region and a back/forward footer	`Stepper`	Compose your own from the parts — Stepper, Progress, State — rather than bending the shell.
		The screen is a sign-in or other single gate into the product	`Entry`	A gate has one thing to do and no steps; it says what the product is and offers the way in.
Say what a page is, above what it holds, with a rule that ends the header	`PageHead`	You are naming a section inside the page, not the page itself	`SectionHead`	A section heading is set at section size with a quiet lede; a page head is the page's one band.
		You want a small mono marker or classification	`Type`	`.label` is the mono voice, and it never sits above a heading as an eyebrow.
		The header belongs to one region — a table, a form — rather than the page	`Panel`	A panel header names the region it hosts and carries at most one action.
Frame a region of a page — a table, a form, a list — under a header	`Panel`	The thing is self-contained and sits in a grid of its kind	`Card`	A card is one thing; a panel is the frame around a region of many.
		You only need a heading over a section, no frame	`SectionHead`	A border is not needed to name a section; space does that.
		The region is a document to read	`Paper`	Paper gives a document a sheet and a ground; a panel is for scanned data.
Name a section inside a page, louder than the sentence under it	`SectionHead`	It is the heading of the whole page	`PageHead`	The page head is the band at the top with a rule under it; a section head sits inside the page.
		You want a mono marker, a figure label or a classification	`Type`	`.label` is small mono grey and must never stand in for a section name.
		The section is a bordered region holding a table or a form	`Panel`	A panel brings its own header and border around the region.
Put a side pane beside the main area that the reader can resize and collapse	`Split`	The side panel opens over the page for a moment and takes focus	`Drawer`	A drawer is modal and dismissed; a split pane stays part of the layout.
		The side column is the app's navigation	`Sidebar`	The rail of places is navigation with `aria-current`; it is not reader-sized.
		The side column is a document's contents next to the document	`Paper`	`PaperAside` sits on the ground beside the sheet and scrolls with the window.
Set page width, section rhythm and the spacing between things	`Layout`	The region needs a border and a title	`Panel`	A panel frames a region; layout classes only space it.
		A pane beside the main area should be resizable	`Split`	A split carries the separator, its keyboard and its collapse.
		The page is the one place that needs a saturated full-bleed field	`SectionBand`	The band is the one deep-ink section a page may have.
Give one section of a page presence with a full-bleed field, or atmosphere on empty ground	`SectionBand`	You want a second band, a gradient, or a coloured box to make something stand out	`Callout`	The band is once a page and never a gradient; an aside in prose is a callout.
	`SectionBand`	The section is an ordinary part of the page	`Layout`	`.section` gives the rhythm; presence comes from space, not fills.
Build a 16:9 presentation slide whose type scales with the slide	`Slide`	The page is a marketing page someone scrolls	`SectionBand`	A landing page uses sections and its one band; slides are fixed frames.
	`Slide`	The content is a document someone reads at length	`Paper`	A document belongs on a sheet at reading measure, not split across frames.

`Card`

Hold one self-contained thing on a hairline surface.

Use when

A thing that stands on its own in a grid or a row — a feature, a product, a summary — with a kicker, a title, a body and meta.
The whole card is one link target: use CardLink, which keeps a real anchor.
An image that bleeds to the edges: CardMedia.

Not when

The surface hosts a region — a table, a form, a list — with a header → Panel. A panel is a frame for a region with a header and one action; a card is the thing itself.
The content is a document someone reads → Paper. Paper is a sheet on a ground, made for reading down; a card is for scanning across.
There is a list of records, each read on its own → Item. A list of cards is a wall of boxes; an item list keeps rows quiet and aligned.
The card is a choice someone picks in a form → RadioCards. A radio card is a real radio with the whole card as its label.

Confused with Panel, Paper, Item, RadioCardsReact Card CardLink CardKicker CardTitle CardBody CardMeta CardMediaClasses .card

See it on the demo page

`Entry`

Build the page between somebody and the product — sign in, accept an invitation.

Use when

The first page anybody sees: it names the product, says what the person is about to do, and holds the way in.
One recommended way in (children) and other ways below a rule (alternatives), so a second button does not read as a variant of the first.
Something a person must know before they try — an invitation rule, a support address — goes in note.

Not when

The screen says there is nothing here, or that the person may not see it → State. An empty or denied state reports absence; a sign-in form drawn with it reads as a dead end.
Getting in takes several steps of questions → Flow. A multi-step journey needs the step rail and the back/forward footer.
The page is the product itself — a header, a rail and content → Nav. The product starts from the app shell — header, rail, content; an entry page holds no navigation.

Confused with State, Flow, CardReact EntryClasses .entry .entry-ground

No demo page yet.

`Flow`

Lay out a multi-step journey with a step rail, one step of content and a fixed footer.

Use when

A form or process that takes several steps — intake, purchase, create or close a work item.
Back must stay on the left and forward on the right on every step; the footer holds both.
A long step needs its fields held to a readable measure (FlowFields) and a save state between the buttons (FlowFooterStatus).

Not when

You only need to show where someone is in a sequence, inside a page that is not a step flow → Stepper. The stepper is the position marker on its own; the flow is the whole shell around it.
The process does not fit a rail, a content region and a back/forward footer → Stepper. Compose your own from the parts — Stepper, Progress, State — rather than bending the shell.
The screen is a sign-in or other single gate into the product → Entry. A gate has one thing to do and no steps; it says what the product is and offers the way in.

Confused with Stepper, ErrorSummary, State, EntryReact Flow FlowRail FlowRailTitle FlowMain FlowHeader FlowStepOf FlowTitle FlowLede FlowContent FlowFields FlowFooter FlowFooterStatusClasses .flow

See it on the template

`PageHead`

Say what a page is, above what it holds, with a rule that ends the header.

Use when

The top band of an app page: the title, a standfirst under it, and at the end figures, a control or one button (PageActions).
The header needs an edge so the reader can see where it stops and the page begins.

Not when

You are naming a section inside the page, not the page itself → SectionHead. A section heading is set at section size with a quiet lede; a page head is the page's one band.
You want a small mono marker or classification → Type. .label is the mono voice, and it never sits above a heading as an eyebrow.
The header belongs to one region — a table, a form — rather than the page → Panel. A panel header names the region it hosts and carries at most one action.

Confused with SectionHead, Type, Panel, BreadcrumbsReact PageHead PageActionsClasses .shell-head .shell-actions

See it on the template

`Panel`

Frame a region of a page — a table, a form, a list — under a header.

Use when

A region of an app page needs a border and a title: a data table, a settings form, an activity list.
The region has at most one action, which sits in the header.

Not when

The thing is self-contained and sits in a grid of its kind → Card. A card is one thing; a panel is the frame around a region of many.
You only need a heading over a section, no frame → SectionHead. A border is not needed to name a section; space does that.
The region is a document to read → Paper. Paper gives a document a sheet and a ground; a panel is for scanned data.

Confused with Card, SectionHead, PaperReact Panel PanelHeader PanelTitle PanelBodyClasses .panel

See it on the demo page

`SectionHead`

Name a section inside a page, louder than the sentence under it.

Use when

A section of a dense page needs a title and a line about it; the title is the loud part.
The section has one control of its own — an Add, a Refresh — at the end of the title line (action).
The outline level differs from the look: as sets h2–h6, the size stays the same.

Not when

It is the heading of the whole page → PageHead. The page head is the band at the top with a rule under it; a section head sits inside the page.
You want a mono marker, a figure label or a classification → Type. .label is small mono grey and must never stand in for a section name.
The section is a bordered region holding a table or a form → Panel. A panel brings its own header and border around the region.

Confused with PageHead, Type, PanelReact SectionHeadClasses .section-head .section-title .section-lede

See it on the demo page

`Split`

Put a side pane beside the main area that the reader can resize and collapse.

Use when

A list or tree beside the thing it opens — documents beside the preview, sources beside the reader.
The reader should choose the width: drag the handle or use arrows; a click on the handle collapses it.
The chosen width should persist — onChange reports it, and 0 on collapse.

Not when

The side panel opens over the page for a moment and takes focus → Drawer. A drawer is modal and dismissed; a split pane stays part of the layout.
The side column is the app's navigation → Sidebar. The rail of places is navigation with aria-current; it is not reader-sized.
The side column is a document's contents next to the document → Paper. PaperAside sits on the ground beside the sheet and scrolls with the window.

Confused with Drawer, Sidebar, Paper, DocPreviewReact SplitClasses .split

See it on the demo page

`Layout`

Set page width, section rhythm and the spacing between things.

Use when

A page needs a centred width (.container) and the section rhythm (.section, with -tight and -loose).
Children stack with a gap (.stack) or sit in a wrapping row (.row).
A divider is truly needed (.hr) — reach for a bigger space step first.

Not when

The region needs a border and a title → Panel. A panel frames a region; layout classes only space it.
A pane beside the main area should be resizable → Split. A split carries the separator, its keyboard and its collapse.
The page is the one place that needs a saturated full-bleed field → SectionBand. The band is the one deep-ink section a page may have.

Confused with Panel, Split, SectionBandClasses .container .section .stack .row .hr

See it on the demo page

`SectionBand`

Give one section of a page presence with a full-bleed field, or atmosphere on empty ground.

Use when

A landing page's one moment of weight — a figure, a statement — in a flat deep-ink band, at most once a page.
Empty ground behind a hero or a slide: .bg-dot-grid or .bg-noise.

Not when

You want a second band, a gradient, or a coloured box to make something stand out → Callout. The band is once a page and never a gradient; an aside in prose is a callout.
The section is an ordinary part of the page → Layout. .section gives the rhythm; presence comes from space, not fills.

Confused with Layout, SlideClasses .section-band .bg-dot-grid .bg-noise

See it on the demo page

`Slide`

Build a 16:9 presentation slide whose type scales with the slide.

Use when

A deck: title, list and divider slides sized in container units, so it reads the same in a grid or projected.
Start from templates/deck/ and keep its slide types.

Not when

The page is a marketing page someone scrolls → SectionBand. A landing page uses sections and its one band; slides are fixed frames.
The content is a document someone reads at length → Paper. A document belongs on a sheet at reading measure, not split across frames.

Confused with SectionBand, PaperClasses .slide

See it on the template

Other guides: Overlays · Status and feedback · Navigation · Data · Input · Reading · Agents and live work

Generated from the when.ts beside each component — the same data the Claude Code plugin reads.