# Philosophy

> The core thesis, the three public messages, the seven Lean Rules with their engineering meaning, the mantra, and what the project does not claim.

Page: https://svelte-lean.vercel.app/docs/philosophy · Markdown: https://svelte-lean.vercel.app/docs/philosophy.md · Index: https://svelte-lean.vercel.app/llms.txt

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.

## 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](https://svelte-lean.vercel.app/docs/architecture/native-first.md)).
- **Runtime.** It grows with the interaction: a dialog needs no behavior, tabs a shared one, an owned [select](https://svelte-lean.vercel.app/primitives/select.md) a lazy controller. Every primitive declares its [runtime tier](https://svelte-lean.vercel.app/docs/architecture/runtime-tiers.md).
- **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](https://svelte-lean.vercel.app/docs/distribution.md)).
- **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](https://svelte-lean.vercel.app/docs/trade-offs.md)).

## 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](https://svelte-lean.vercel.app/docs/why-not-bits-ui.md#measured), which follow the [methodology](https://svelte-lean.vercel.app/performance/methodology.md).
- Anything unverified: the claim registry records the evidence of each public statement.

See also [What we do not do](https://svelte-lean.vercel.app/docs/what-we-dont-do.md) and [Trade-offs](https://svelte-lean.vercel.app/docs/trade-offs.md).