Domain map
The framework is organised by domain-driven design: bounded contexts with their own words and owner paths, talking only through contracts. This page is the reference for that structure; the reasons are in decision records 0002 to 0004.
The allowed dependency directions are data in [tools/boundaries.yaml](../../tools/boundaries.yaml) and the ownership of paths is in [OWNERS.yaml](../../OWNERS.yaml). Both are checked in CI.
1. Domain-driven design: the bounded contexts
The framework is split into contexts. Each one has a single responsibility, its own words, one owner path in the repository and a public surface that other contexts use. Contexts talk only through the contracts in parallel-work.md.
| Context | Kind | Responsible for | Lives in |
|---|---|---|---|
| Language | Core | What a page file means: elements, attributes, directives, expressions, editions | spec/language, spec/glossary.yaml |
| Syntax | Core | Turning source text into a syntax tree, and back (formatting) | crates/syntax, crates/fmt, editors/grammars |
| Analysis | Core | Resolving names, checking rules, producing diagnostics and the Screen IR | crates/analyzer, crates/lint, spec/diagnostics |
| Styling | Core | Tokens, themes, utilities, prefixes and the style table | crates/style |
| Emission | Core | Turning Screen IR into output for a target | crates/emit-web, crates/emit-native, crates/script (shared script rewrites) |
| Runtime | Core | State, state that loads, actions, streams, bindings, boundaries, skeletons, motion, scheduling on the device | packages/client, crates/runtime |
| Navigation | Supporting | Routes, layouts, guards, transitions, morph, deep links | packages/client/navigation, crates/analyzer/routes |
| Kit | Supporting | Built-in parts, their pieces, variants, looks and overrides | packages/kit, spec/kit |
| Platform | Supporting | Platform effects, permissions, app shells, lifecycle | native/ios, native/android, packages/effects, spec/effects |
| Modules | Supporting | Module manifests, binding generation, the compatibility verdict | packages/modules, spec/schemas/module.schema.json |
| Tooling | Supporting | The command-line tool, dev server, build report, doctor, explain | crates/cli |
| Editor intelligence | Supporting | Language server, TypeScript plugin, compiler service | packages/language-server, packages/ts-plugin, crates/wasm |
| Editor shells | Generic | Packaging the server for each editor | editors/vscode, editors/jetbrains, editors/others |
| Agent surface | Supporting | Skills, llms.txt, the tool server | skills/, packages/mcp-server |
| Delivery | Generic | Environments, signing, store uploads, release pipeline | tools/release, crates/cli/ship |
Core contexts are the product and get the most care and the strictest review. Supporting contexts are ours but conventional. Generic contexts follow each platform's standard way of doing things and should look boring.
The context map
┌──────────────┐
│ Language │ published language: every context conforms
└──────┬───────┘
│ language definition, glossary
┌──────────────────┼────────────────────┐
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌─────────┐
│ Syntax │──tree─►│ Analysis │──IR───► │Emission │
└────────┘ └────┬─────┘ └────┬────┘
│ diagnostics │ generated code calls
▼ ▼
┌────────────────────┐ ┌───────────┐ anti-corruption ┌──────┐
│Editor intelligence │ │ Runtime │◄─── layer ───────►│ Lynx │
└────────────────────┘ └─────┬─────┘ (engine adapter) └──────┘
│ ports
┌──────────────┬───────────┼──────────────┐
▼ ▼ ▼ ▼
Kit Navigation Platform TanStack Query core
(effects) (behind an adapter)
Three relationships are deliberate:
- Language is a published language. Every other context reads the definition and the glossary; none of them invents its own terms for the same thing.
- Lynx sits behind an anti-corruption layer. Only the engine adapter imports it. Lynx's words (element PAPI, main thread, background thread) never appear outside that adapter. This is what makes Tab 1's promise of swapping engines real.
- Third-party cores sit behind ports. TanStack Query, UniFFI and each crash or analytics provider are reached through an interface we own, so replacing one changes one folder.
2. The ubiquitous language
One word per concept, used identically in the spec, code, docs, error messages, skills and conversation. The glossary is data in spec/glossary.yaml; the docs page and editor hover text are generated from it.
The glossary itself is data in [spec/glossary.yaml](../../spec/glossary.yaml). A summary of the core terms:
| Term | Means | Not to be called |
|---|---|---|
| page | A file in pages/ that becomes a route; markup, script block and style | screen file, view, template |
| screen | The running instance of a page on a device | page (at runtime) |
| component | A reusable file with markup, used by name inside a page | widget |
| element | A built-in tag such as view, text, list | node, tag (in public APIs) |
| part | A built-in kit component such as sheet or tabs | widget, control |
| piece | A named, overridable section of a part, such as a sheet's handle | slot (slot is a page concept) |
| look | The starting visual style of the kit: default or platform | skin, mode |
| variant | A declared alternative of a component or part, such as primary | flavour, kind |
| token | A named design value in the theme | variable (except in the CSS output) |
| theme | A complete set of token values | palette |
| utility | A short class that applies tokens, such as p-4 | helper class |
| prefix | A condition on a utility, such as pressed: or wide: | modifier, variant |
| state | A reactive value, which may hold or load data | store, signal, resource (in public APIs) |
| action | An asynchronous write with pending, error, retry and refresh | mutation, command |
| stream | State fed continuously by a live source | subscription, feed |
| binding | A link from state to a view property | |
| boundary | A part of a screen that shows a skeleton until its state is ready | suspense |
| skeleton | The placeholder drawn at a boundary while it loads | shimmer, placeholder |
| island | A unit of a screen that loads, updates and fails on its own | |
| motion | Automatic or preset movement of an element | animation (in public APIs) |
| morph | An element carried from one screen to another | shared element |
| transition | Movement between screens | |
| interaction | A module bundling a gesture, its state, motion and haptic | gesture handler |
| module | Anything installed with add: script, capability or component | extension, plugin, package |
| effect | An operating-system feature implemented per platform, such as haptics | native module, capability |
| target | An output: web, ios, android | platform (platform is the OS) |
| rung | A level of the execution ladder, 0 to 3 | tier, level |
| diagnostic | An error, warning or hint with a stable code | error (generically) |
| Screen IR | The analysed, target-neutral description of a screen | AST (it is not syntax) |
| edition | A version of the language that a project opts into |
Three rules keep it honest:
- A public name must be a glossary term or be made of glossary terms. A lint checks exported names in Rust and TypeScript against the glossary and flags the rest.
- Words from other systems stay inside their adapter.
signal,query client,PAPIandmutationmay appear only in the adapter that wraps them. - The glossary changes like the language does, through a decision record. Who approves which changes is D37.
This draft also fixes contradictions in the source docs: "store", "resource" and "signal" become state; "extension" and "module" become module; "capability extension" becomes a module using effects.
3. Dependency rules
The arrows in the context map are the only allowed directions. CI enforces them; a pull request that adds a forbidden import fails.
| Rule | Enforced by |
|---|---|
spec/ depends on nothing | It contains only data and schemas |
Rust crates depend downward only: syntax ← analyzer ← emit-web, emit-native; style is used by analyzer and the emitters; cli and wasm sit on top | cargo workspace layout plus tools/check-boundaries |
No crate or package depends on cli | Boundary check |
Runtime packages (client, kit, effects) never import the compiler | Boundary check |
kit depends only on client's public API and tokens | Boundary check |
Only packages/engine imports Lynx; only packages/client/data-core imports TanStack Query | Boundary check |
| Editor shells depend only on the language server's protocol, never on compiler crates | Boundary check |
| No cycles, anywhere | cargo and a TypeScript cycle check |
Generated code is produced only from spec/ and is never imported by spec/ | Generated-file check |
| Third-party dependencies need a one-line reason in the pull request and must have a compatible licence | cargo-deny and a licence check |
Each folder's README states, in one line, what it must not depend on. The check itself reads tools/boundaries.yaml, which is the authority when the two differ.