Skip to content
omaris

Build

Making it look designed

Personality first, one hero, space over lines, two greys, and the AI look to take out.

Everything else on this site makes a screen that works. This page is about the difference between a screen that works and one a designer would sign — and it is a short list, because most of that difference is restraint. Each rule is one decision and the habit that keeps it. The same rules go into the AGENTS.md that omaris init writes, so a model building in your project reads them before its first screen.

1. Decide the personality before the first screen

A journal is not a dashboard, and both on the stock theme look like the same template. The product's character is one line in the provider, set before any page is written, and derived from what the app is rather than from what the defaults happen to be: a look for the personality and a hue for the brand.

<OmarisProvider theme={{ look: 'paper', hue: 155 }}>

Looks

The nine looks, each drawn with its own shape, surface, typeface and density. The colour is the page's: a look never carries one, so what differs here is exactly what choosing it would change.

plain

Plain

Hairlines, soft corners, the system face. The defaults.

Paid
expressive

Expressive

Material 3 Expressive: tonal blocks, big soft containers, pill controls, vivid colour.

Paid
soft

Soft

Pastel and pillowy: low chroma, tinted greys, round everything, room to breathe.

Paid
playful

Playful

Candy colour at full volume, a rounded face, big friendly shapes.

Paid
editorial

Editorial

A magazine: serif headlines, square containers, hairlines, generous margins.

Paid
paper

Paper

Warm, quiet greys and cards that cast a shadow — a desk, not a screen.

Paid
poster

Poster

Loud and flat: saturated tonal blocks, sharp corners, a grotesque face.

Paid
terminal

Terminal

Monospace, compact, square, nearly grey. The developer tool and the trading desk.

Paid
glass

Glass

Liquid glass: cards, bars and menus over a still wallpaper of the theme's hues, that give under a finger.

Paid
<script lang="ts">	import {		Button,		Card,		Chip,		Text,		THEME_LOOKS,		THEME_DEFAULTS,		THEME_PRESETS	} from 'omaris';	import { resolveTheme } from '$lib/theme/resolve.js';	import type { ThemeLookName } from '$lib/theme/looks.js';​	const NAMES = Object.keys(THEME_LOOKS) as ThemeLookName[];​	/* `surface` is the store's default; here each card says its own, since the	 * store is not scoped to a tile. `tonal` is the filled card. */	const CARD = { outlined: 'outlined', tonal: 'filled', elevated: 'elevated' } as const;​	/* The vars a look resolves to, as inline style, so the tile's own	 * `rounded-shape-*`, `gap-*` and typeface read them instead of the page's. */	function vars(name: ThemeLookName) {		const s = THEME_LOOKS[name].settings;		const v = resolveTheme({ ...THEME_DEFAULTS, ...s }, THEME_PRESETS).vars;		return [			`--roundness:${v['--roundness']}`,			v['--roundness-container'] && `--roundness-container:${v['--roundness-container']}`,			`--spacing:${v['--spacing']}`,			v['--font-family-user'] && `--font-family-user:${v['--font-family-user']}`,			`font-family:var(--font-family-user,var(--font-family-sans))`		]			.filter(Boolean)			.join(';');	}</script>​<div class="grid w-full gap-4 sm:grid-cols-2 lg:grid-cols-3">	{#each NAMES as name (name)}		{@const look = THEME_LOOKS[name]}		<div class="flex flex-col gap-2" style={vars(name)}>			<Card variant={CARD[look.settings.surface ?? 'outlined']} size="lg" class="gap-4">				<div class="flex flex-col gap-1">					<Text variant="label-md" tone="muted" class="tracking-wide uppercase">{name}</Text>					<Text as="h3" variant="title-lg">{look.label}</Text>					<Text variant="body-sm" tone="muted">{look.hint}</Text>				</div>				<div class="flex flex-wrap items-center gap-2">					<Button size="xs">Continue</Button>					<Chip size="sm" variant="tonal">Paid</Chip>					<span class="h-7 min-w-16 flex-1 rounded-shape-xs border border-input"></span>				</div>			</Card>		</div>	{/each}</div>
The app is…Provider themeFrame
Personal — a journal, notes, reading{ look: 'paper', hue: 55 } or 'editorial'No sidebar. AppShellContent width="sm", one column, a TopAppBar
A dashboard, admin, ops{ look: 'paper', preset: 'graphite', density: 'compact' }AppShell + NavigationDrawer responsive, width="xl"
Consumer, phone-first{ look: 'expressive', hue: 20 }NavigationBar in the footer, sheets not dialogs, width="md"
A developer tool{ look: 'terminal', hue: 270 }Drawer collapsed, width="full", tables and code blocks
Money, health, anything that must feel safe{ look: 'soft', hue: 160 }width="lg", fewer cards, more whitespace

A look is far from every other look on at least three axes — shape, what a card is, typeface, density, how loud — so any one of them is a visible decision, and the hue on top of it is yours. The nine are on the Theming page; the one not to pick is plain, the stock theme, which omaris audit reports a provider for having by default.

Shape comes from the look, not from radius. radius is the control radius; containers follow shape — expressive takes cards, dialogs and sheets to Material 3 Expressive's big soft corners over crisp fields and pill buttons, sharp makes them square. Setting radius: 'xl' to get round cards rounds every field with them and the screen reads as a toy.

A tint above 1 is the cheapest signature there is. The greys lean toward the accent, so even an empty surface belongs to this product and no other — which is what "our own look" means in practice. Pick once, put it on the provider, write it in DESIGN.md, and never override it per page.

2. One hero per screen

Every screen has one thing the person came for. It gets the size — headline-lg, or display-sm for a number — the top-start position, and air around it. Everything else is a step down from 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
<script lang="ts">	import { Text } from 'omaris';</script>​<div class="flex w-full flex-col gap-4">	<div class="flex flex-col gap-1">		<Text variant="label-sm" tone="muted" font="mono">display-sm</Text>		<Text variant="display-sm">The quick brown fox</Text>	</div>	<div class="flex flex-col gap-1">		<Text variant="label-sm" tone="muted" font="mono">headline-md</Text>		<Text variant="headline-md">The quick brown fox</Text>	</div>	<div class="flex flex-col gap-1">		<Text variant="label-sm" tone="muted" font="mono">title-lg</Text>		<Text variant="title-lg">The quick brown fox</Text>	</div>	<div class="flex flex-col gap-1">		<Text variant="label-sm" tone="muted" font="mono">body-md</Text>		<Text variant="body-md">The quick brown fox</Text>	</div>	<div class="flex flex-col gap-1">		<Text variant="label-sm" tone="muted" font="mono">label-md</Text>		<Text variant="label-md">The quick brown fox</Text>	</div></div>

A row of four equal stat cards has no hero. Make one number big and set the other three under it as title-md, or drop the row. The question to ask before laying anything out is "what is the one thing here?" — and if the answer is "the four cards", it is the wrong answer.

3. Space does the work

Whitespace before a line, a line before a shadow, and never a border and a shadow on the same box. Between sections gap-8 or gap-10; inside a card gap-3. Depth, where it is needed, is a surface tier — up one per level of nesting, and stop at three.

Surface tiers

The elevation ladder, as background tiers. Higher reads as closer.

surface-container-lowest
surface-container-low
surface-container
surface-container-high
surface-container-highest
surface-variant
<script lang="ts">	// Written out in full: Tailwind scans source text, so a class assembled at	// runtime (`bg-{tier}`) would never be generated.	const TIERS = [		['bg-surface-container-lowest', 'surface-container-lowest'],		['bg-surface-container-low', 'surface-container-low'],		['bg-surface-container', 'surface-container'],		['bg-surface-container-high', 'surface-container-high'],		['bg-surface-container-highest', 'surface-container-highest'],		['bg-surface-variant', 'surface-variant']	];</script>​<div class="grid w-full grid-cols-[repeat(auto-fill,minmax(11rem,1fr))] gap-3">	{#each TIERS as [cls, name] (name)}		<div class="flex min-h-16 flex-col justify-end rounded-shape-md border border-border p-3 {cls}">			<code class="text-label-md text-foreground">{name}</code>		</div>	{/each}</div>

Not everything is a card. A card is for a unit that stands alone — a stat, a product, a plan. A list of entries is rows, flex flex-col gap-1 with rounded-shape-md px-3 py-2 hover:bg-surface-container-high on each, not a card per row. A form is fields on the page, not a card around a card. And one level of nesting: a card inside a card inside a panel is three borders around one number.

Align everything to a single left edge and let the right rag. Centre only a marketing hero or an empty state.

4. Type is the design

Big and quiet. One large title, body-md for everything that is read, and above the title an eyebrow — label-md, uppercase, tracking-wide, tone="muted". That three-line stack, eyebrow → title → one muted sentence, is how nearly every good screen opens.

<div class="flex flex-col gap-1 pb-8">	<Text variant="label-md" tone="muted" class="tracking-wide uppercase">This week</Text>	<Text as="h1" variant="headline-lg">Seven entries</Text>	<Text tone="muted">Two more than last week. The longest was Tuesday.</Text></div>

Two greys of text, not five: text-foreground and tone="muted". A third tone means the hierarchy has a hole in it. Numbers are always tabular, and a big number carries its unit small beside it. Prose has a measure — max-w-prose on a paragraph, width="sm" on a page that is mostly reading.

5. Colour is a role — and tonal blocks are how it arrives

The canvas is a surface tier, not white. The filled accent goes on the primary action and the selected item and nowhere else — if bg-primary appears in more than two places, the screen is loud. Colour arrives instead as tonal blocks: a -container pair on a hero band, a chosen tile, a status chip, the one stat that matters. That is Material's whole trick, and the difference between a screen that is coloured and one that is tinted.

Variants

The five MD3 fill styles, in the spec's own order of emphasis, plus link.

<script lang="ts">	import { Button } from 'omaris';</script>​<Button variant="elevated">Elevated</Button><Button variant="filled">Filled</Button><Button variant="tonal">Tonal</Button><Button variant="outlined">Outlined</Button><Button variant="text">Text</Button><Button variant="link">Link</Button>
  • A tinted area is a -container pair — `bg-primary-container

text-primary-container-foreground — never the role at /10. tertiary-container` is the second voice.

  • How many is the look's call: under expressive, poster and playful a tonal block per section is the design; under editorial, paper and terminal one per screen is.
  • success, warning, destructive and info mean status and nothing else. A green card that is not "healthy" is a lie.
  • One filled button per screen; the rest step down the ladder. On a phone that one button can be size="lg" — Material 3 Expressive's call to action — as long as it is alone.
  • No gradient text, no glow, no backdrop-blur class. Glass is a look (glass, or translucent: true) the person can turn off; a gradient has one home, as a scrim over a photo.

6. The details that read as designed

Each of these is one line, and each is the difference between a mock-up and a product.

Icons and tones

check={false} keeps the icon when it is the meaning — a pin, a swatch; tone with tonal for a chip that reads as a state.

Pinned Paid Overdue Small Large
<script lang="ts">	import { Chip } from 'omaris';</script>​{#snippet pin()}	...{/snippet}​<Chip>	{#snippet start()}{@render pin()}{/snippet}	Pinned</Chip><Chip selectable selected check={false}>	{#snippet start()}{@render pin()}{/snippet}	Keeps its icon</Chip><Chip tone="success" variant="tonal">Paid</Chip><Chip tone="destructive" variant="tonal">Overdue</Chip><Chip size="sm">Small</Chip><Chip size="lg">Large</Chip>
  • An eyebrow above the title.
  • The date, large, where a journal or a feed starts the day.
  • A tonal Chip for a status, not a coloured Badge on every row.
  • An AvatarGroup with its +3; a Sparkline inside a stat; a Progress under a quota.
  • Hover that tints (hover:bg-surface-container-high), not hover that adds a border. An interactive Card lifts on its own.
  • Icons from one set — Lucide matches the built-in glyphs — at size-4 beside text and size-5 in an IconButton. Never an emoji as an icon.
  • Rounded avatars, square-cornered thumbnails (rounded-shape-md): one rule for pictures, kept everywhere.
  • The empty state exists on day one, because it is the first screen a new user sees.

Basic

An empty state should say what goes here and offer the way to make one.

No invoices yet

They will show up here the moment one is raised.

<script lang="ts">	import { Button, Empty } from 'omaris';</script>​<Empty	class="w-full"	bordered	title="No invoices yet"	description="They will show up here the moment one is raised.">	{#snippet icon()}		...	{/snippet}	{#snippet actions()}		<Button>New invoice</Button>	{/snippet}</Empty>
  • Transitions on every state change — duration-200 ease-standard, with motion-reduce:transition-none beside them — and nothing that moves on its own.

7. Copy

Real names and real numbers; never "Lorem ipsum", never "John Doe", never "Sample item 1". Sentence case everywhere and no exclamation marks — no "Welcome to your dashboard!" and no "Manage your things with ease". Headings are nouns (Entries, This week); buttons are verbs (Write, Save, Invite); an empty state is one sentence and one verb ("Nothing written yet." → "Write the first entry"). A title is the word a person would say — "Journal", not "Journal Entry Management".

8. The AI look

If a screen has any of these, it was assembled rather than designed. Take it out:

  • A provider with no theme: hairline cards on white, the default blue, soft corners. Every omaris app nobody themed looks exactly like this, and it is the first thing to fix.
  • Four stat cards, then a chart, then a table — on every page, whatever the app.
  • A centred hero with gradient text and three feature cards with an emoji each.
  • A Badge on every row, a border on every box, a shadow on every card.
  • Every card with a header, a description, content and a footer.
  • rounded-2xl and shadow-lg sprinkled on things — both ignore the theme.
  • A toast on every button.
  • Purple, on a product that has nothing to do with purple.
  • Five shades of grey text and three sizes of heading in one card.
  • A sidebar on an app with four pages.

Before you call it done

Open it at 390px and at 1440px, in light and in dark, and answer each of these with a yes:

  1. Can you name the one thing on the screen in three words?
  2. Is there exactly one filled button?
  3. Is there nothing with both a border and a shadow?
  4. Are there at most two greys of text?
  5. Does the empty state exist, and does it say what to do?
  6. Does every number line up, in Western digits, and every time read 12-hour with AM/PM?
  7. Does nothing move unless something happened?
  8. Would you show it as your own work?

A "no" on any of them is the next edit, not a note. Principles is why these rules hold; Building a screen is the order to build in.