Docs Philosophy
What we do not do
Each omission below is a rule of the repository's architecture contract, with its reason and where it is enforced.
Markdown version of this page, for assistants (Markdown for AI)
On this page
Omissions
| We do not | Because | Enforced by |
|---|---|---|
| Build a JavaScript dialog | <dialog> provides the top layer, inertness, Escape, focus return and the
backdrop. | Dialog contract; native-only fixture, Svelte Lean chunk 0 B |
| Add a listener per instance | One listener per event type routes along composedPath() for every root. | Forbidden changes, tabs.test.ts, listeners.spec.ts (1 and 1000 roots, counted two ways) |
Discover roots with a MutationObserver | The router finds a root on its first event; an observer adds work on every update. | ADR 0004; the audit's grep -rn MutationObserver packages/*/src returns
nothing |
| Mirror native state into Svelte state | open, checked, disabled and focus are in the DOM; a
copy can drift. | Tabs unit test asserts no WeakMap in the behavior |
| Require a Provider | Theme is CSS tokens; the runtime attaches to the document. | grep -rni provider packages/*/src returns nothing |
| Ship a positioning engine | CSS anchor positioning places popovers; without it the platform default placement is the documented fallback. | grep -rni floating-ui packages/*/src returns nothing |
| Force virtualization or a component per cell | <DataTable /> renders a native <table>; grouping,
pivot, clipboard, export, server data and persistence load only when imported. | table-basic fixture |
The table's state object is application state by design, not a mirror. Virtual rows are not shipped.
Also not
- Random ids for ARIA relationships.
documentorwindowaccess at module evaluation.eval,new Functionor string-to-code attributes (strict CSP safe).- A Tailwind or CSS-in-JS dependency.
- A production dependency without a written reason.
- A root entry that registers every behavior.
- A rename of a protocol attribute, event, token or export without a deprecation window.
Full list: "Forbidden changes" in AGENTS.md. Costs: Trade-offs.