Principles

The components agree with each other because they all follow the same five rules. Follow them in the code between the components — the layouts, the one-off elements, the overrides — and the whole screen agrees too. None of this is a style guide to memorise; each rule is one sentence and one habit.

1. Emphasis is hierarchy

One thing on a screen is the thing. It gets the filled treatment; everything else steps down — tonal, then outlined, then text. The same ladder runs through buttons, chips, cards, badges and alerts, which is why a screen with one filled button reads as calm and a screen with five reads as shouting.

1<script lang="ts">2	import { Button } from 'omaris';3</script>4​5<Button variant="elevated">Elevated</Button>6<Button variant="filled">Filled</Button>7<Button variant="tonal">Tonal</Button>8<Button variant="outlined">Outlined</Button>9<Button variant="text">Text</Button>10<Button variant="link">Link</Button>

The habit: before adding a filled anything, find the one that is already there. If there is one, yours is tonal.

2. Depth comes from surfaces, not lines

A card is not a box with a border. It is a tier of surface — lowest to highest — that reads as closer to the reader without a shadow. Nest tiers to group things; reach for a border or a divider only when the grouping is still unclear.

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

The habit: page bg-background → a panel bg-surface-container-low → a raised card bg-surface-container → a well inside it bg-surface-container-high. Up one tier per level of nesting, and stop at three.

3. Tokens, never values

bg-primary, not a hex. rounded-shape-lg, not rounded-[16px]. shadow-2, not shadow-md. A token follows the theme — the hue, the roundness, dark mode, high contrast, the density slider — and a raw value follows nothing, so it is the one thing on the screen that will look wrong the moment someone changes a setting.

1<script lang="ts">2	const ROLES = [3		['bg-background text-foreground', 'background'],4		['bg-card text-card-foreground', 'card'],5		['bg-primary text-primary-foreground', 'primary'],6		['bg-primary-container text-primary-container-foreground', 'primary-container'],7		['bg-secondary-container text-secondary-container-foreground', 'secondary-container'],8		['bg-tertiary text-tertiary-foreground', 'tertiary'],9		['bg-tertiary-container text-tertiary-container-foreground', 'tertiary-container'],10		['bg-muted text-muted-foreground', 'muted'],11		['bg-destructive text-destructive-foreground', 'destructive'],12		['bg-success text-success-foreground', 'success'],13		['bg-warning text-warning-foreground', 'warning'],14		['bg-info text-info-foreground', 'info']15	];16</script>17​18<div class="grid w-full grid-cols-[repeat(auto-fill,minmax(11rem,1fr))] gap-3">19	{#each ROLES as [cls, name] (name)}20		<div class="flex min-h-16 flex-col justify-end rounded-shape-md border border-border p-3 {cls}">21			<code class="text-label-md">{name}</code>22		</div>23	{/each}24</div>

The habit: every colour is a role and comes as a pair. bg-primary with text-primary-foreground; bg-primary-container with text-primary-container-foreground. Use the pair and the contrast is handled in both themes. The roles are on the Design tokens page.

4. Motion is feedback

Things move because something happened: a button pressed, a panel opened, a card grew to fit new content. Motion that runs on its own is decoration, and decoration is opt-in — the library ships no idle animation, and everything that moves says what motion-reduce does to it.

The habit: transition the property that changed, on an MD3 curve — ease-emphasized for things arriving, ease-standard for state — with motion-reduce:transition-none beside it. If you cannot say what user action the animation answers, delete it.

5. Every part is reachable, so never fork

class styles a component's root and always wins. classes={{ part: '…' }} reaches every inner element by name. Between the two there is no element you cannot restyle, which means there is never a reason to copy a component into your project to change one thing about it.

1<script lang="ts">2	import { Input } from 'omaris';3​4	let value = $state('42.0000');5</script>6​7<Input8	class="w-72 max-w-full"9	label="Reading"10	supportingText="Monospace digits, italic help"11	bind:value12	classes={{ control: 'font-mono tabular-nums', support: 'italic' }}13/>

The habit: when an override does not take, it is not the component ignoring you; it is the merge rule — aspect-video does not cancel a height, because they are different groups. Look for the prop the component gives you instead.

What this adds up to

A screen where the primary action is obvious, the grouping is felt rather than drawn, everything follows the theme, nothing moves without a reason, and nothing was forked. That is the whole design system. The component pages say which part to use where; Building a screen says how to put them together.