Build

Building a screen

Shell, rhythm, surfaces, the four states, and the phone — in the order you build them.

A screen is built from the outside in: the frame, then the rhythm of the content, then the surfaces things sit on, then the states the data can be in, then the phone. Do it in that order and each step has something to hang on.

1. The frame

Dashboard frame

The layout most omaris apps end up with. Only the content column scrolls — the sidebar stays put and the app bar finds its own scroller, which is what makes sticky work without a second scrollbar.

Overview

1<script lang="ts">2	import {3		AppShell,4		AppShellSidebar,5		AppShellMain,6		AppShellContent,7		NavigationDrawer,8		NavigationDrawerItem,9		TopAppBar10	} from 'omaris';1112	let selected = $state('Overview');13</script>1415<div class="h-96 w-full overflow-hidden rounded-shape-lg border border-border">16	<AppShell class="h-full">17		<AppShellSidebar breakpoint="sm">18			<NavigationDrawer bordered label="Sections">19				<NavigationDrawerItem20					label="Overview"21					selected={selected === 'Overview'}22					onclick={() => (selected = 'Overview')}23				/>24				<NavigationDrawerItem25					label="Orders"26					selected={selected === 'Orders'}27					onclick={() => (selected = 'Orders')}28				/>29				<NavigationDrawerItem30					label="Customers"31					selected={selected === 'Customers'}32					onclick={() => (selected = 'Customers')}33				/>34			</NavigationDrawer>35		</AppShellSidebar>3637		<AppShellMain>38			<TopAppBar title={selected} sticky />39			<AppShellContent width="lg">40				<div class="flex flex-col gap-3">41					<!-- Enough rows to have something to scroll. -->42					{#each { length: 12 }, i (i)}43						<div class="h-12 rounded-shape-md bg-surface-container"></div>44					{/each}45				</div>46			</AppShellContent>47		</AppShellMain>48	</AppShell>49</div>

AppShell gives you the layout most dashboards end up with, and the one thing that is hard to add later: only the content column scrolls. The sidebar stays put, the app bar sticks to its own scroller, and there is never a second scrollbar. AppShellContent supplies the page gutter and the vertical rhythm between its children — sections are direct children of it and own no padding of their own.

width is the reading measure. full is the default and right for a wide table; xl or lg for a page of cards and prose.

Content width

width sets the reading measure and centres it. full is right for a table, md for prose.

width="sm" — a column narrow enough to read comfortably, centred in whatever space the shell has.

1<script lang="ts">2	import { AppShell, AppShellMain, AppShellContent } from 'omaris';3</script>45<div class="h-64 w-full overflow-hidden rounded-shape-lg border border-border">6	<AppShell>7		<AppShellMain>8			<AppShellContent width="sm">9				<div class="rounded-shape-md bg-primary-container p-4">10					<p class="text-body-md text-primary-container-foreground">11						width="sm" — a column narrow enough to read comfortably, centred in whatever space the12						shell has.13					</p>14				</div>15			</AppShellContent>16		</AppShellMain>17	</AppShell>18</div>

2. The rhythm

Spacing is Tailwind's numeric scale, which the theme rescales with the density setting — so gap-4 is already right, and p-[16px] is a bug. These are the layouts a dashboard is made of. Use them rather than inventing a grid per page, and the pages agree with each other for free.

Layout	Classes
Stat row	`grid gap-4 sm:grid-cols-2 xl:grid-cols-4`
Chart row, one wide	`grid gap-4 lg:grid-cols-3` and `lg:col-span-2` on the wide card
Two up	`grid gap-4 lg:grid-cols-2`
Card list	`grid gap-4 sm:grid-cols-2 xl:grid-cols-3`
Inside a card	`flex flex-col gap-3`
Page heading with controls	`flex flex-wrap items-end justify-between gap-4`
A cluster of buttons	`flex items-center gap-2`

Type has a rhythm too, and it is the Text variant: headline-md for the page title, title-lg for a section, title-md for a card, body-md for everything you read, label-md for a column header. A metric is display-sm with tabular. The variant carries size, weight, leading and tracking together, so there is nothing to add after it.

Scale

Five roles, three sizes each. The variant carries size, line height, letter spacing and weight together — if you find yourself adding font-semibold after it, the role is wrong, not the weight.

display-sm

The quick brown fox

headline-md

The quick brown fox

title-lg

The quick brown fox

body-md

The quick brown fox

label-md The quick brown fox

1<script lang="ts">2	import { Text } from 'omaris';3</script>45<div class="flex w-full flex-col gap-4">6	<div class="flex flex-col gap-1">7		<Text variant="label-sm" tone="muted" font="mono">display-sm</Text>8		<Text variant="display-sm">The quick brown fox</Text>9	</div>10	<div class="flex flex-col gap-1">11		<Text variant="label-sm" tone="muted" font="mono">headline-md</Text>12		<Text variant="headline-md">The quick brown fox</Text>13	</div>14	<div class="flex flex-col gap-1">15		<Text variant="label-sm" tone="muted" font="mono">title-lg</Text>16		<Text variant="title-lg">The quick brown fox</Text>17	</div>18	<div class="flex flex-col gap-1">19		<Text variant="label-sm" tone="muted" font="mono">body-md</Text>20		<Text variant="body-md">The quick brown fox</Text>21	</div>22	<div class="flex flex-col gap-1">23		<Text variant="label-sm" tone="muted" font="mono">label-md</Text>24		<Text variant="label-md">The quick brown fox</Text>25	</div>26</div>

3. The surfaces

Depth is tiers, not borders. The page is bg-background; a panel is surface-container-low; a card is surface-container; something raised inside it, or a hover, is surface-container-high. Up one tier per level of nesting, and stop at three. A Card does this for you — outlined when it sits on a plain page, elevated in a grid of cards, filled for a well.

Variants

outlined is the default. elevated lifts — a grid of cards on a page wants it; filled sits in a tinted well, for a card inside another surface.

elevated

The same card, three surfaces.

filled

The same card, three surfaces.

outlined

The same card, three surfaces.

1<script lang="ts">2	import { Card, CardContent, CardHeader } from 'omaris';3</script>45<Card variant="elevated" class="w-56 max-w-full">6	<CardHeader heading="elevated" />7	<CardContent>The same card, three surfaces.</CardContent>8</Card>9<Card variant="filled" class="w-56 max-w-full">10	<CardHeader heading="filled" />11	<CardContent>The same card, three surfaces.</CardContent>12</Card>13<Card variant="outlined" class="w-56 max-w-full">14	<CardHeader heading="outlined" />15	<CardContent>The same card, three surfaces.</CardContent>16</Card>

A Divider is for when the grouping is still not clear after the surfaces and the spacing. It is not the default way to separate two things.

4. The four states

Every list, every table, every chart has four states, and the design is only finished when all four are on screen. The empty one is the one people forget, and it is the first thing a new user sees.

State	Show	Component
Loading	The shape of what is coming	Skeleton, or `loading` on the Table
Empty	Why it is empty, and the one action that changes that	Empty
Error	What went wrong and how to try again	Alert `tone="destructive"` with an action
Ready	The data	The component

States

Loading draws skeleton rows at the real row height, so nothing jumps.

Name	City	Total

Name	City	Total
No orders yet. They will show up here the moment one lands.

1<script lang="ts">2	import { Table } from 'omaris';34	const COLUMNS = [5		{ key: 'name', header: 'Name' },6		{ key: 'city', header: 'City' },7		{ key: 'total', header: 'Total', numeric: true }8	];9</script>1011<div class="flex w-full flex-col gap-6">12	<Table columns={COLUMNS} rows={[]} loading loadingRows={3} label="Loading" />13	<Table14		columns={COLUMNS}15		rows={[]}16		emptyText="No orders yet. They will show up here the moment one lands."17		label="Empty"18	/>19</div>

A skeleton is the same shape as the content it stands in for — a table's rows, a card's title and two lines — so nothing jumps when the data lands. Progress bars are for a known amount; a skeleton is for "soon".

5. The phone

The same screen, not a second one. Three things carry a dashboard onto a phone:

The drawer becomes modal. NavigationDrawer responsive is a sidebar above 900px and a modal below it, from one drawer.
The bottom gets a bar. AppShellSidebar hides below md, so give phones a Navigation Bar in AppShellFooter — three to five destinations, the ones that matter.
Sheets, not dialogs, for tasks. A Sheet is a bottom sheet on a phone with a handle to throw it away by; a Dialog is for a decision.

Basic

Three to five destinations, on a phone. More than five wants a drawer.

1<script lang="ts">2	import { NavigationBar, NavigationBarItem } from 'omaris';34	let tab = $state('home');5</script>67{#snippet house()}8	...9{/snippet}1011{#snippet bag()}12	...13{/snippet}1415{#snippet person()}16	...17{/snippet}1819<div class="w-full max-w-sm overflow-hidden rounded-shape-lg border border-border">20	<NavigationBar label="Sections">21		<NavigationBarItem label="Home" selected={tab === 'home'} onclick={() => (tab = 'home')}>22			{#snippet icon()}{@render house()}{/snippet}23		</NavigationBarItem>24		<NavigationBarItem25			label="Orders"26			badge={3}27			selected={tab === 'orders'}28			onclick={() => (tab = 'orders')}29		>30			{#snippet icon()}{@render bag()}{/snippet}31		</NavigationBarItem>32		<NavigationBarItem33			label="Profile"34			selected={tab === 'profile'}35			onclick={() => (tab = 'profile')}36		>37			{#snippet icon()}{@render person()}{/snippet}38		</NavigationBarItem>39	</NavigationBar>40</div>

Every component is built on logical properties (ms-, pe-, start-), so a right-to-left language mirrors the whole screen without anything in your code changing. Write your own layout the same way and it stays true.

Whole screens to copy

Twelve complete apps live at /patterns, each on its own URL and built only from what this library exports — a dashboard, an inbox, a till, a board, a shop, sign-in, a wizard, settings, a fleet map, a phone app, a clinic schedule and an AI assistant. Open the one closest to what you are building and take the layout. Anything in them is something you can have.

The frame, the rhythm and the states make a screen that works. Making it look designed is what makes it one you would sign.