Guidelines

Screen patterns

How to build the usual app screens (settings, profile, list pages) from Alea components, and the rules for density, borders, shadows, type, empty states, cards and forms that keep them consistent.

Examples

Settings page

PageHeader, TabNav for the pages of the section, then SettingsSection groups of SettingRow. One title size per role, rows instead of stacked cards.

Profile page

SplitLayout with the person on the narrow side and the details on the wide one. Read-only facts in a PropertyList, edits in a Form with a fixed gap.

List page

PageHeader with the one primary action, a Card with padding none around the list, and an EmptyState sized for a card when there is nothing.

Settings pages

Start with PageHeader. When the settings have more than one page of options, give each topic its own address and put a TabNav in the header (tabs). Inside a page, use one SettingsSection per topic and one SettingRow per option. The control goes on the right; a Switch, a Select and a Button are the usual ones.

A short settings page needs no tabs: PageHeader, then two or three sections. Settings that need a Save button are a Form, placed under the section it belongs to, with FormActions.

Profile pages

Use SplitLayout. The narrow column holds the person (Avatar, name, role) and the wide column holds the details. Read-only facts go in Descriptions; edits go in a Form inside a Card. SplitLayout stacks by its own width, so the page holds up in a narrow window.

List pages

PageHeader with one primary action, then a Card with padding="none" around the list (ListView, Table or a tree), so rows run edge to edge. Filters go in a Toolbar above the card. When the list is empty, the EmptyState replaces the list inside the same card.

Density and space

All space is on the 4 px scale (Space and sizes). Pick the gap by relationship, not by taste.

Between	Use	How
Sections of a page	gap 5 (20 px)	Stack gap={5}
Cards or rows of cards	gap 4 (16 px)	Grid or Stack gap={4}
Fields in a form	16 px	Form gap={16}
A title and its help	2 px	Built into CardHeader and SettingsSection
Page edge	Set by the shell	Never add padding around a page inside AppShell

Borders and shadows

A surface that rests on the page gets a border or the card shadow, never both. Panels that frame a page (the shell panel, a SettingsSection) use a 1 px border. Cards use the soft ring. Only floating things (menus, popovers, dialogs) use the pop shadow. Do not nest a bordered panel in a bordered panel: use appearance="plain" or a deep Card for the inner one.

Type hierarchy

One h1 per page, from PageHeader. Cards and sections start at level 2 (headingLevel={2}).
Titles of cards and sections are the compact semibold ones: CardHeader and SettingsSection. Use the large display title only for a lead card or a hero.
Help text is Text size="sm" tone="muted". Do not invent a fourth text size on a page.
Modals: titleSize="sm" for forms and settings, the default for dialogs that present something.

Empty states

Inside a card use EmptyState size="sm"; for a whole page use the default size. Say what is missing, then give the one action that fixes it. Do not blame the person.

Cards

One topic per card. Do not nest cards.
Cards of a list share a width: use Grid with columns="auto" and a minItemWidth.
A card that holds a list or table uses padding="none".
Do not override a card's CSS: pick the surface, radius and padding props.

Forms

Labels above fields, one column, Form gap={16} and a maxWidth of about 520 px so lines stay short.
Validate on submit, show server errors on the fields, and never disable the submit button to say the form is incomplete.
Group related fields in a Fieldset. Put the submit button at the start of the row, after the last field.