Docs Start
Philosophy
Native when possible, tiny behavior when necessary: the browser owns what it already understands, and Svelte Lean adds the smallest runtime only where the platform is incomplete.
Markdown version of this page, for assistants (Markdown for AI)
On this page
The thesis
- Architecture. Ask what the browser already does before writing JavaScript:
<dialog>, popover, invoker commands,<details>, form controls, anchor positioning (ADR 0001, Native-first). - Runtime. It grows with the interaction: a dialog needs no behavior, tabs a shared one, an owned select a lazy controller. Every primitive declares its runtime tier.
- Distribution. Installing is not shipping. Native-only markup ships 0 B of behavior JavaScript; a page with tabs ships 1839 B brotli including the kernel (Distribution).
- Not zero JavaScript. A select with search needs real behavior code; the goal is the minimum necessary runtime.
The Lean Rules
Seven rules, in order of precedence, from the architecture contract.
| Rule | In practice |
|---|---|
| Native before custom | A modal is a <dialog> opened by command="show-modal",
not a controller with a focus trap and a portal. |
| Static before reactive | Options are static attributes on the root; nothing runs for a root until its first interaction. |
| DOM before duplicated state | open, checked, aria-selected, tabindex, hidden are the state; no mirror object. |
| Shared before per-instance | One listener per event type for every root: a thousand tabs roots keep one click and one keydown, asserted by a release-gate test. |
| Lazy before eager | Roots are found on their first event; a Tier 2 controller is created then and released
through an AbortController. |
| Compile before runtime | The build reads the markup and adds only the registration modules it uses. |
| Measure before optimize | Every number comes from a script in the repository; a missing one reads "not measured". |
The playbook adds: correctness before cleverness, accessibility before byte shaving, measure before claiming. In one line: if the browser owns the behavior, Svelte Lean owns nothing.
What it is not
- Not a Tailwind component collection: no package depends on a CSS framework.
- Not a Radix port or a Headless UI clone: behavior is not a component instance with its own listeners and state.
- Not a Web Components library: the markup is plain HTML that Svelte renders and hydrates.
- Not a claim that Svelte is slow: the gain is the absence of abstractions the platform makes unnecessary.
- Not anti-JavaScript, and not a claim that the browser solves every widget.
Who it is for
- Teams that write markup and want pages to work before hydration and without JavaScript.
- Svelte 5 and SvelteKit applications that render on the server: ids are authored, nothing is generated at hydration.
- Projects that want to own their CSS and depend only on a maintained behavior engine.
- A poorer fit for teams that want a component API for every interaction, or a widget the platform does not cover in their browser target (Trade-offs).
What is not claimed
- That small bundles are the goal: bytes are one cost among listeners, allocations, layout reads and hydration, and accessibility is never traded for them.
- Anything about another library beyond the measured cases on Compared with Bits UI, which follow the methodology.
- Anything unverified: the claim registry records the evidence of each public statement.
See also What we do not do and Trade-offs.