Docs Architecture
Runtime tiers
Every primitive declares one of four tiers, each with a testable runtime budget (ADR 0003).
Markdown version of this page, for assistants (Markdown for AI)
On this page
The four tiers
| Tier | Name | Budget (ADR 0003) | Meaning |
|---|---|---|---|
| 0 | Native | No runtime JavaScript, no instance listeners, no instance state objects | The browser owns the behavior. |
| 1 | Delegated micro-behavior | One shared listener per required event type; no per-root listener; state in the DOM | Registered once per page; no controller per instance. |
| 2 | Lazy scoped controller | WeakMap state created on first interaction; AbortController-scoped listeners; cleanup | Per-instance state only once the instance is used. |
| 3 | Application-controlled | Svelte state owned by the application; never required by a default primitive | The application owns the state, e.g. a sort in the URL. |
Two questions, in order, decide the tier; two "no" answers mean a scoped controller.
Tier 3 is not a primitive tier: it is how Svelte Lean Table works, one plain state object the application can bind, serialize and restore.
<script lang="ts">
import { DataTable, type TableState } from '@svelte-lean/table';
// Tier 3: the application owns the state and stores it wherever it wants.
let state = $state<Partial<TableState>>({ sorting: [{ id: 'revenue', desc: true }] });
</script>
<DataTable {data} {columns} getRowId={(row) => row.id} bind:state />Declaring a tier
The tier is a field of each primitive's contract constant; contract.md states and justifies
it in its first line.
// packages/primitives/src/tabs/contract.ts: the static description of the protocol
export const tabsContract = {
name: 'tabs',
tier: 1,
base: 'ARIA tabs markup (role=tablist, tab, tabpanel)',
parts: ['list', 'trigger', 'panel', 'native'],
options: {
value: {},
activation: { values: ['automatic', 'manual'], default: 'automatic' },
orientation: { values: ['horizontal', 'vertical'], default: 'horizontal' },
loop: { values: ['true', 'false'], default: 'true' },
render: { values: ['app'] }
},
events: ['click', 'keydown'],
emits: ['slean:change']
} as const satisfies BehaviorContract;The root entry exposes the metadata and registers nothing; every tier on this site is read from it.
import { BEHAVIORS } from '@svelte-lean/primitives';
BEHAVIORS.dialog.tier; // 0
BEHAVIORS.dialog.module; // null: nothing to register
BEHAVIORS.tabs.tier; // 1
BEHAVIORS.tabs.events; // ['click', 'keydown']
BEHAVIORS.tabs.module; // '@svelte-lean/primitives/tabs/register'Classification
| Primitive | Tier | Native base | Shared listeners | Registration module | Behavior JS (brotli) |
|---|---|---|---|---|---|
| accordion | 0 | <details> + <summary>, exclusive groups through name | none | none | 0 B |
| alert | 0 | <div> + live region roles (status, alert) | none | none | 0 B |
| avatar | 0 | <img> with initials behind it | none | none | 0 B |
| badge | 0 | <span> with an optional remove <button> | none | none | 0 B |
| breadcrumb | 0 | <nav> + <ol> + aria-current="page" | none | none | 0 B |
| button | 0 | <button type="button"> | none | none | 0 B |
| button-group | 0 | buttons in role="group" | none | none | 0 B |
| card | 0 | <article> | none | none | 0 B |
| carousel | 0 | scroll-snap, ::scroll-button(), ::scroll-marker | none | none | 0 B |
| checkbox | 0 | <input type="checkbox">, role="switch" | none | none | 0 B |
| descriptions | 0 | <dl> with <div> groups of <dt> and <dd> | none | none | 0 B |
| dialog | 0 | <dialog> + command/commandfor | none | none | 0 B |
| empty | 0 | a heading, a paragraph and an optional action | none | none | 0 B |
| field | 0 | <label for>, a control, aria-describedby; constraint validation | none | none | 0 B |
| kbd | 0 | <kbd> | none | none | 0 B |
| meter | 0 | <meter min max low high optimum value> | none | none | 0 B |
| nav | 0 | <nav> + <ul> of links + <details name> groups + aria-current="page" | none | none | 0 B |
| pagination | 0 | <nav> + links + aria-current="page" | none | none | 0 B |
| popover | 0 | [popover] + popovertarget or command/commandfor | none | none | 0 B |
| progress | 0 | <progress value max> | none | none | 0 B |
| radio-group | 0 | <fieldset> + <input type="radio" name="…"> | none | none | 0 B |
| rating | 0 | <fieldset> of <input type="radio"> sharing a name | none | none | 0 B |
| scroll-area | 0 | overflow: auto + tabindex="0" in role="region" | none | none | 0 B |
| separator | 0 | <hr>, role="separator" | none | none | 0 B |
| skeleton | 0 | aria-hidden placeholders in an aria-busy region | none | none | 0 B |
| steps | 0 | <ol> + aria-current="step" | none | none | 0 B |
| timeline | 0 | <ol> of <li> events with <time datetime> | none | none | 0 B |
| calendar | 1 | role=grid of day buttons in a <table> | click, keydown, change, reset, pointerover, pointerout | @svelte-lean/primitives/calendar/register | 4594 B |
| checkbox-group | 1 | <fieldset> + <input type="checkbox">, indeterminate | change, focusin, reset | @svelte-lean/primitives/checkbox-group/register | 1456 B |
| copy | 1 | navigator.clipboard.writeText + <button> | click | @svelte-lean/primitives/copy/register | 1291 B |
| file-drop | 1 | <input type="file"> stretched over a drop area; DataTransfer for the file list | dragenter, dragleave, drop, paste, input, change, click, reset | @svelte-lean/primitives/file-drop/register | 2983 B |
| findable | 1 | hidden="until-found" + beforematch | beforematch | @svelte-lean/primitives/findable/register | 1887 B |
| hint | 1 | role="tooltip" + popover="manual" + aria-describedby | pointerover, pointerout, pointerdown, focusin, focusout, keydown | @svelte-lean/primitives/hint/register | 2687 B |
| hover-card | 1 | popover="hint" named by interestfor | pointerover, pointerout, focusin, focusout, keydown | @svelte-lean/primitives/hover-card/register | 1985 B |
| input | 1 | <input> of any type, <textarea>; stepUp()/stepDown(), type="password"↔"text" | click, pointerdown, pointerover, focusin | @svelte-lean/primitives/input/register | 1808 B |
| listbox | 1 | ARIA listbox markup (role=listbox, option) | click, keydown, change, reset | @svelte-lean/primitives/listbox/register | 2357 B |
| menu | 1 | [popover] + ARIA menu (role=menu, menuitem) | click, keydown, beforetoggle, toggle | @svelte-lean/primitives/menu/register | 2771 B |
| menubar | 1 | role="menubar" of popovertarget menu buttons | keydown, focusin, pointerover | @svelte-lean/primitives/menubar/register | 2063 B |
| slider | 1 | <input type="range">, one or two in a group | input, reset | @svelte-lean/primitives/slider/register | 1549 B |
| tabs | 1 | ARIA tabs markup (role=tablist, tab, tabpanel) | click, keydown | @svelte-lean/primitives/tabs/register | 1839 B |
| toggle | 1 | <button type="button" aria-pressed> | click | @svelte-lean/primitives/toggle-group/register | not measured |
| toggle-group | 1 | <button aria-pressed> items in role="group" | click, keydown | @svelte-lean/primitives/toggle-group/register | 1932 B |
| toolbar | 1 | role="toolbar" | keydown, focusin | @svelte-lean/primitives/toolbar/register | 1706 B |
| tree | 1 | role="tree", treeitem, group, aria-expanded | click, keydown | @svelte-lean/primitives/tree/register | 2140 B |
| autocomplete | 2 | <input list> + <datalist>; owned: role=combobox input + [popover] + ARIA listbox | click, keydown, input, pointerdown, pointerover, focusin, focusout, toggle | @svelte-lean/primitives/autocomplete/register | 3960 B |
| date-picker | 2 | <input type="date"> + role=combobox text input + [popover] + calendar | click, keydown, input, change, pointerdown, pointerover, focusin, focusout, toggle, reset | @svelte-lean/primitives/date-picker/register | 9476 B |
| select | 2 | <select> + role=combobox trigger + [popover] + ARIA listbox (role=listbox, option) | click, keydown, input, pointerdown, pointerover, focusout, change, toggle, reset, animationstart | @svelte-lean/primitives/select/register | 5020 B |
| sortable | 2 | <ul>/<ol> + <button> handles; document order is the value | pointerdown, keydown, click | @svelte-lean/primitives/sortable/register | 3833 B |
| splitter | 2 | role="separator" (WAI-ARIA window splitter) + CSS grid | keydown, pointerdown | @svelte-lean/primitives/splitter/register | 1908 B |
| toast | 2 | popover="manual" region + aria-live list | click, pointerover, pointerout, focusin, focusout | @svelte-lean/primitives/toast/register | 1616 B |
| Svelte Lean Table | 3 | <table> | none | none (a Svelte component) | measured per entry point |
- Tier 0: the Svelte Lean chunk of the native-only production fixture.
- Tier 1 and 2: the register module built with Vite in production mode, shared kernel included (method).
- Each tier was decided, with the reason, in docs/catalog.md before the contract.
Targets and measurements
ADR 0003 initial targets next to the CI budget and the measured value; the status is computed.
| Subject | Target (ADR 0003) | Enforced budget | Measured | Status |
|---|---|---|---|---|
| Tabs registration including the shared kernel | Tabs < 1 kB brotli | 1900 B brotli | 1839 B brotli | above target |
| Basic menu registration including the shared kernel | basic Menu ~1–2 kB | 2800 B brotli | 2771 B brotli | above target |
| Every behavior that exists today, on one page, with one kernel | entire common behavior set < 5 kB | — | 4600 B brotli | within target |
- The enforced number is the budget in the size file, ten to fifteen percent above the measured value, so a regression fails CI. The ADR figure is an intent, not a claim.
- Values come from
packages/primitives/artifacts/size.jsonandfixtures/results.json.
Where state lives
First match wins:
- Browser-owned (
checked,disabled,open, focus, validity, popover open): the browser state. - DOM or ARIA representation (
aria-selected,tabindex,hidden): the DOM (Tier 1). - Ephemeral (typeahead buffer, pointer origin, open session): a lazy
WeakMapentry. Menu and listbox share one typeahead buffer per page; the select and the autocomplete keep one entry per used root and delete it when focus leaves. - Application state: Svelte and the application (Tier 3).
Example
Tier 1: these tabs and the frame's source tabs share one click and one keydown listener on the document.
Code
<script lang="ts">
// With @svelte-lean/vite the register import is injected for the static
// data-slean="tabs" marker. Without the plugin, write it yourself once:
// import '@svelte-lean/primitives/tabs/register';
import '@svelte-lean/styles/tabs.css';
import { tabsParts } from '@svelte-lean/primitives/tabs';
// Roles, ids, aria-controls, aria-labelledby, selection and the tab stop.
const t = tabsParts('settings');
</script>
<div id="settings" data-slean="tabs" data-slean-value="account">
<div {...t.list} aria-label="Settings">
<button {...t.tab('account', 'account')}>Account</button>
<button {...t.tab('security', 'account')}>Security</button>
</div>
<div {...t.panel('account', 'account')} tabindex="0">Account settings.</div>
<div {...t.panel('security', 'account')} tabindex="0">Security settings.</div>
</div>Tier 2: the autocomplete gets a WeakMap entry on first use and a scoped pointerdown listener while open; both go when it closes and focus leaves.
Code
<script lang="ts">
// With @svelte-lean/vite the register import is injected for the static
// data-slean="autocomplete" marker.
import '@svelte-lean/styles/control.css';
import '@svelte-lean/styles/autocomplete.css';
import { autocompleteParts } from '@svelte-lean/primitives/autocomplete';
const p = autocompleteParts('city');
</script>
<label {...p.label}>City</label>
<div id="city" data-slean="autocomplete">
<input {...p.input} name="city" placeholder="Select a city" />
<datalist {...p.datalist}>
<option value="Ankara"></option>
<option value="Berlin"></option>
<option value="Cairo" disabled></option>
<option value="Lisbon"></option>
<option value="Oslo"></option>
</datalist>
</div>The live reading of this page; the proof page repeats it with 1, 100 and 1000 roots.
- Runtime
- Read from the page after it loads; requires JavaScript.
Source
- ADR 0003, Runtime tiers
- ADR 0004, Shared event router
- tabs.test.ts: 1000 roots keep one listener per event type and no per-root state
- listeners.spec.ts: the same count in a real browser, two independent accounts
- autocomplete.test.ts and lazy.spec.ts: no controller for untouched roots, one per root that is used, released on close and focus loss (shipping invariant D)
- size.mjs: the script that writes the measured values and enforces the budgets