# Norns docs

> Documentation for the Norns platform: SvelteKit with Pug + Civet, the norns runtime, norns-ui and norns-tron.

Every page below is served as Markdown at the listed URL; the HTML version is the same path without the `/md` prefix. The full corpus is at `/llms-full.txt`.

## norns (@human-synthesis/norns)

SvelteKit preconfigured for Pug + Civet, plus the runtime: feature folders, DI container, page/route wrappers with valibot validation, migrations and the norns CLI.

- [norns](https://norns-docs.humansynthesis.ai/md/norns.md): SvelteKit preconfigured for Pug + Civet, plus a small opinionated runtime — feature folders, a DI container, page and route wrappers with valibot validation, migrations, and the norns CLI.
- [Getting started](https://norns-docs.humansynthesis.ai/md/norns/getting-started.md): Install norns, learn the project layout, and build your first feature folder.
- [Install](https://norns-docs.humansynthesis.ai/md/norns/getting-started/install.md): Create a Norns app from the starter template, or add norns to an existing SvelteKit project.
- [Project structure](https://norns-docs.humansynthesis.ai/md/norns/getting-started/project-structure.md): The layout of a Norns app and which SvelteKit files can be written in Civet.
- [Feature folders](https://norns-docs.humansynthesis.ai/md/norns/getting-started/feature-folders.md): The unit of modularity in a Norns app — a bounded domain with a module, a repo, a service, a facade and a shared schema.
- [Configuration](https://norns-docs.humansynthesis.ai/md/norns/config.md): The two config files, the Vite plugins, and the file extensions norns registers.
- [svelte.config.js](https://norns-docs.humansynthesis.ai/md/norns/config/svelte-config.md): nornsConfig() builds a SvelteKit config with the Norns defaults; spread your own overrides on top.
- [Vite plugin](https://norns-docs.humansynthesis.ai/md/norns/config/vite-plugin.md): nornsCivetPlugin() compiles Civet modules and teaches Vite the Norns extensions; pugTailwindExtract() closes Tailwind's blind spot on Pug class chains.
- [File extensions](https://norns-docs.humansynthesis.ai/md/norns/config/file-extensions.md): What .n, .c and .civet mean, and why the framework did not invent a new component extension.
- [Auto-imports](https://norns-docs.humansynthesis.ai/md/norns/auto-imports.md): Framework helpers, components, UI presets and project exports resolve by name in .n and .c files.
- [How it works](https://norns-docs.humansynthesis.ai/md/norns/auto-imports/how-it-works.md): nornsAutoImport() is a Svelte preprocessor and a Vite plugin in one object, with four resolvers that run in priority order.
- [Options](https://norns-docs.humansynthesis.ai/md/norns/auto-imports/options.md): Every nornsAutoImport() option with its default.
- [UI presets](https://norns-docs.humansynthesis.ai/md/norns/auto-imports/ui-presets.md): A preset is a function returning a components map; compose it with your own options and shadow any component by file name.
- [Runtime](https://norns-docs.humansynthesis.ai/md/norns/runtime.md): The server layer exported from @human-synthesis/norns/server — boot, the container, the page and route wrappers, validation, serializers and request scope.
- [Boot](https://norns-docs.humansynthesis.ai/md/norns/runtime/boot.md): boot() builds the root container, runs every feature module, and returns the SvelteKit hooks.
- [Container](https://norns-docs.humansynthesis.ai/md/norns/runtime/container.md): A small DI container with string tokens, singleton and transient bindings, overrides for tests, and child scopes per request.
- [Page wrappers](https://norns-docs.humansynthesis.ai/md/norns/runtime/page-wrappers.md): page.load and page.actions wrap +page.server.c exports with container resolution, form parsing and valibot validation.
- [route()](https://norns-docs.humansynthesis.ai/md/norns/runtime/route.md): Wrap a +server.c handler with body parsing, validation, container resolution and JSON (or TRON) serialization.
- [Validation](https://norns-docs.humansynthesis.ai/md/norns/runtime/validation.md): valibot at the edge — how page.actions and route() validate input, and what the error shapes look like.
- [Serializers](https://norns-docs.humansynthesis.ai/md/norns/runtime/serializers.md): An app-wide or per-route hook that turns route() results into a Response and reads non-JSON request bodies.
- [Request scope](https://norns-docs.humansynthesis.ai/md/norns/runtime/request-scope.md): Every request gets a child container on event.locals.container, also reachable through AsyncLocalStorage.
- [Data](https://norns-docs.humansynthesis.ai/md/norns/data.md): Migrations, database driver factories, and the Cloudflare D1 pattern.
- [Migrations](https://norns-docs.humansynthesis.ai/md/norns/data/migrations.md): Forward-only SQL files per feature, applied and tracked by the norns CLI.
- [Drivers](https://norns-docs.humansynthesis.ai/md/norns/data/drivers.md): Driver factories that assemble a Drizzle instance for SQLite, D1, libSQL or Postgres, with a portable transaction helper.
- [Cloudflare D1](https://norns-docs.humansynthesis.ai/md/norns/data/cloudflare-d1.md): Bind a per-request D1 handle from event.platform.env and apply migrations with wrangler.
- [CLI](https://norns-docs.humansynthesis.ai/md/norns/cli.md): The norns binary — dev, build, preview, migrate, lint, check and diag.
- [Commands](https://norns-docs.humansynthesis.ai/md/norns/cli/commands.md): norns dev, build, preview, migrate, lint, check, diag, and the help screen.
- [Lint rules](https://norns-docs.humansynthesis.ai/md/norns/cli/lint-rules.md): The static checks behind norns lint, each tied to a documented Civet or Pug pitfall.
- [check and diag](https://norns-docs.humansynthesis.ai/md/norns/cli/check-and-diag.md): norns check compiles every file the way the build does and maps errors to the line you wrote; norns diag shows the compiled output.
- [Deploy](https://norns-docs.humansynthesis.ai/md/norns/deploy.md): A Norns app deploys like any SvelteKit app. Cloudflare Workers is the reference target; Node and the other adapters work too.
- [Cloudflare Workers](https://norns-docs.humansynthesis.ai/md/norns/deploy/cloudflare.md): adapter-cloudflare, the two compatibility flags the runtime needs, static assets, custom domains and a deploy workflow.
- [Node and other adapters](https://norns-docs.humansynthesis.ai/md/norns/deploy/node-and-others.md): The runtime needs AsyncLocalStorage and a SQLite driver; beyond that any SvelteKit adapter works.
- [Pitfalls](https://norns-docs.humansynthesis.ai/md/norns/pitfalls.md): The handful of Civet and Pug constructs that compile to the wrong thing, and the verification order that catches them.
- [Civet pitfalls](https://norns-docs.humansynthesis.ai/md/norns/pitfalls/civet.md): Constructs that Civet parses into something other than what you meant.
- [Pug pitfalls](https://norns-docs.humansynthesis.ai/md/norns/pitfalls/pug.md): Template lines that Pug parses differently from what a Svelte author expects.
- [Verification workflow](https://norns-docs.humansynthesis.ai/md/norns/pitfalls/verification.md): The order to run checks before calling a change done, and the runtime gotchas that type checks do not catch.

## norns-core (@human-synthesis/norns-core)

The Svelte preprocessor behind `.n` files: Civet scripts, Pug templates, `+if` / `+snippet` chains, class-shorthand rewriting and source-mapped errors.

- [norns-core](https://norns-docs.humansynthesis.ai/md/norns-core.md): The Svelte preprocessor behind .n files — Civet scripts, Pug templates, +if and +snippet chains, class-shorthand rewriting and source-mapped errors.
- [Guide](https://norns-docs.humansynthesis.ai/md/norns-core/guide.md): How a .n file is put together and what each preprocessing step does.
- [The .n file](https://norns-docs.humansynthesis.ai/md/norns-core/guide/the-n-file.md): A .n file is Pug on top, a Civet script block below, and an optional style block — no wrappers, no lang attributes.
- [Civet script](https://norns-docs.humansynthesis.ai/md/norns-core/guide/civet-script.md): The subset of Civet that Norns code is written in, and the JavaScript it becomes.
- [Pug template](https://norns-docs.humansynthesis.ai/md/norns-core/guide/pug-template.md): Pug syntax as used in .n files, including the Svelte-specific attribute and text forms.
- [Control flow](https://norns-docs.humansynthesis.ai/md/norns-core/guide/control-flow.md): +if / +elseif / +else chains, +each, and +snippet blocks with {@render}.
- [Class shorthand](https://norns-docs.humansynthesis.ai/md/norns-core/guide/class-shorthand.md): The rewriter that lets Tailwind variants, slashes and fractions live in Pug's .class chains, and the extractor that tells Tailwind about them.
- [Error mapping](https://norns-docs.humansynthesis.ai/md/norns-core/guide/error-mapping.md): Pug and Civet errors are mapped back to the file, line and column you wrote, with a code frame.
- [Reference](https://norns-docs.humansynthesis.ai/md/norns-core/reference.md): The exported API and the vetted subset the tests pin.
- [API](https://norns-docs.humansynthesis.ai/md/norns-core/reference/api.md): nornsPreprocess(options) and the four helper functions exported from @human-synthesis/norns-core/preprocess.
- [Vetted subset](https://norns-docs.humansynthesis.ai/md/norns-core/reference/vetted-subset.md): The Civet and Pug constructs the norns-core test suite pins, and the documented traps it keeps trapped.

## norns-ui (@human-synthesis/norns-ui)

Component library written in Pug + Civet on Tailwind v4: forms, overlays, display and composite components, headless behaviors, theming tokens and motion.

- [norns-ui](https://norns-docs.humansynthesis.ai/md/norns-ui.md): Component library for the Norns ecosystem — Pug + Civet components on Tailwind v4, headless behaviors on @floating-ui/dom, Iconify icons, theming tokens and motion.
- [Getting started](https://norns-docs.humansynthesis.ai/md/norns-ui/getting-started.md): Install, wire the preset, add the styles, and set up dark mode and icons.
- [Install](https://norns-docs.humansynthesis.ai/md/norns-ui/getting-started/install.md): Add norns-ui to a Norns app.
- [Setup](https://norns-docs.humansynthesis.ai/md/norns-ui/getting-started/setup.md): Register presetUI() with the auto-importer in both config files and import the stylesheet.
- [Dark mode](https://norns-docs.humansynthesis.ai/md/norns-ui/getting-started/dark-mode.md): Every component swaps on <html data-theme="dark">; persist the choice with an inline script and the ThemeToggler component.
- [Icons](https://norns-docs.humansynthesis.ai/md/norns-ui/getting-started/icons.md): Iconify through @iconify/svelte, with the Lucide collection bundled; register it once, then use <Icon> anywhere.
- [Guide](https://norns-docs.humansynthesis.ai/md/norns-ui/guide.md): The tiers of the library and how they fit together.
- [Forms](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/forms.md): Form derives an error map from the page's form prop; each Field finds its own error by name; inputs inherit the field's id and name.
- [Overlays](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/overlays.md): Dialog, Sheet, Popover, Dropdown, Tooltip, ContextMenu, Tabs, Accordion and Collapsible, all positioned by @floating-ui/dom and driven by the in-tree behaviors.
- [Toast](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/toast.md): Mount ToastProvider once and call toast(), notify() or dismiss() from anywhere.
- [Behaviors](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/behaviors.md): Headless Svelte 5 actions and a floating-ui factory, exported at @human-synthesis/norns-ui/behaviors.
- [Theming](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/theming.md): The Tailwind v4 @theme tokens the library exposes and how to override them.
- [Motion](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/motion.md): Five animated components that are opt-in imports, not part of the auto-import preset.
- [Overriding components](https://norns-docs.humansynthesis.ai/md/norns-ui/guide/overriding.md): Shadow any library component by file name, or extend one with class merging.
- [Reference](https://norns-docs.humansynthesis.ai/md/norns-ui/reference.md): The generated component reference and migration notes.
- [Component reference](https://norns-docs.humansynthesis.ai/md/norns-ui/reference/components.md): Every component with its import path and prop types, generated from the norns-ui type shims.
- [Migrating 0.0.5 → 0.0.6](https://norns-docs.humansynthesis.ai/md/norns-ui/reference/migration-0-0-6.md): Bits UI was removed in 0.0.6; overlays moved to @floating-ui/dom plus the in-tree behaviors.

## norns-tron (@human-synthesis/norns-tron)

TRON wire format for route() responses and LLM-facing output: fewer tokens than JSON, content-negotiated, with schema mode derived from valibot.

- [norns-tron](https://norns-docs.humansynthesis.ai/md/norns-tron.md): TRON serialization for the Norns ecosystem — a token-efficient, faster-than-JSON wire format for APIs and LLM-facing output, with zero runtime dependencies.
- [Guide](https://norns-docs.humansynthesis.ai/md/norns-tron/guide.md): Enabling TRON, calling it, schema mode, limits and performance.
- [Turn it on app-wide](https://norns-docs.humansynthesis.ai/md/norns-tron/guide/enable.md): Pass tronSerializer() to boot(); every route() response becomes content-negotiated and nothing breaks for JSON clients.
- [Call it from the client](https://norns-docs.humansynthesis.ai/md/norns-tron/guide/client.md): The api wrapper sends the Accept header and decodes TRON or JSON transparently; inside load functions create one with SvelteKit's fetch.
- [Schema mode](https://norns-docs.humansynthesis.ai/md/norns-tron/guide/schema-mode.md): When both ends know the shape, derive the wire schema from the valibot schema you already have and skip shape detection entirely.
- [Semantics and limits](https://norns-docs.humansynthesis.ai/md/norns-tron/guide/limits.md): What TRON preserves, what it does not, and where it should not be used.
- [Performance guide](https://norns-docs.humansynthesis.ai/md/norns-tron/guide/performance.md): Pick the right mode, compile schemas once, declare enums, do not encode small payloads, and reach for the columnar tape when data is numeric.
- [Reference](https://norns-docs.humansynthesis.ai/md/norns-tron/reference.md): The four entry points and their exported types.
- [Core](https://norns-docs.humansynthesis.ai/md/norns-tron/reference/core.md): encode, decode, defineSchema, createRegistry, the columnar pair and the WASM controls.
- [Server](https://norns-docs.humansynthesis.ai/md/norns-tron/reference/server.md): tronSerializer() and the helpers behind it.
- [Client](https://norns-docs.humansynthesis.ai/md/norns-tron/reference/client.md): The api wrapper, createApi, parseResponse and ApiError.
- [valibot](https://norns-docs.humansynthesis.ai/md/norns-tron/reference/valibot.md): Derive a TRON schema spec, or a compiled schema, from a valibot object schema.

## norns-app

The starter template: one page, one feature folder, everything wired. `bun create human-synthesis/norns-app`.

- [norns-app](https://norns-docs.humansynthesis.ai/md/norns-app.md): The starter template — a single page that exercises the whole runtime in about sixty lines you can read in one sitting and rewrite in two.
- [Walkthrough](https://norns-docs.humansynthesis.ai/md/norns-app/walkthrough.md): Every file in the starter, the messages feature, and how to go further.

## norns-demo

Reference app: notes on Cloudflare D1, tic-tac-toe with stores, the norns-ui showcase, each example also written in vanilla SvelteKit for comparison.

- [norns-demo](https://norns-docs.humansynthesis.ai/md/norns-demo.md): The reference app — notes on Cloudflare D1, tic-tac-toe with stores, the norns-ui showcase, each example also written in vanilla SvelteKit for comparison.
- [Notes](https://norns-docs.humansynthesis.ai/md/norns-demo/notes.md): A CRUD feature on Cloudflare D1 with form actions, a dynamic route, an error page and a schema-mode TRON endpoint.
- [Tic-tac-toe](https://norns-docs.humansynthesis.ai/md/norns-demo/tic-tac-toe.md): Component composition, Svelte stores in a Civet module, $effect, a toggle group and a small AI.
- [UI showcase](https://norns-docs.humansynthesis.ai/md/norns-demo/ui-showcase.md): One page that renders every norns-ui component with its variants, in light and dark mode.
- [Deploy](https://norns-docs.humansynthesis.ai/md/norns-demo/deploy.md): The Workers + D1 configuration and the GitHub Actions workflow that applies migrations and deploys on push.

## Reference

Cross-cutting pages: version matrix, glossary, the fork and release policy, and how this site is built.

- [Reference](https://norns-docs.humansynthesis.ai/md/reference.md): Cross-cutting pages — the package matrix, a glossary, the fork and release policy, and how this site is built.
- [Packages](https://norns-docs.humansynthesis.ai/md/reference/packages.md): Every repository in the Norns platform, what it publishes, and how it is consumed.
- [Glossary](https://norns-docs.humansynthesis.ai/md/reference/glossary.md): Terms used across the Norns docs.
- [Fork and release policy](https://norns-docs.humansynthesis.ai/md/reference/upstream-policy.md): Two forks that never modify upstream, four npm packages published by hand, and the apps consumed from GitHub.
- [About this site](https://norns-docs.humansynthesis.ai/md/reference/this-site.md): The docs are a Norns app — markdown under content/, a docs feature folder, prerendered on Cloudflare Workers.