0028. Kit parts are .duo components built into the compiler and imported from @duolith/kit
- Status: Proposed
- Date: 2026-11-14
- Decided by: integrator (internal only), pending Mik's approval
- Planning item: WP7 (kit), D20 (explicit imports)
Context
The kit's parts (Button, ListRow, TextField and the rest) must work on the web now and on iOS and Android through Lynx later, with no extra work per target, and look right under any theme. A page must be able to use them with one import, from a project in any folder, without an install step. Pages already place components from components/ (decision 0015), and the language already has every element, utility and token a part needs, or gains them in decision 0029.
Decision
- A part is an ordinary component file,
packages/kit/parts/<Part>.duo, written only with the language's own elements, utilities, scoped style blocks and theme tokens (var(--color-primary)and so on, never a literal colour). So a part is compiled by the same analyzer and emitters as a project's components, and reaches native when they do. Its specification isspec/kit/<part>.yaml, checked againstspec/schemas/kit.schema.jsonand against the part itself bypnpm check. - Pages import parts by name:
import { Button, Card as Panel } from "@duolith/kit". The analyzer gives each name the component path@duolith/kit/<Part>.duo, a path no project folder can have, so a part never collides with a project component of the same name. A name that is not a part is diagnostic E0123, with a suggestion. Inside the kit, parts import each other relatively (import Spinner from "./Spinner.duo"). - The compiler carries the parts.
crates/cli/src/kit.rsembeds every part withinclude_str!, ascrates/emit-webalready does for the runtime, soduolith buildworks from any folder, offline, and the kit always matches the compiler that compiles it. A test keeps the list in step with the folder. - Only what a project uses is built. The build follows the imports of the project's pages and components, then the parts' own imports, and compiles only those parts. On the web each part is one module at
_duolith/kit/<Part>.js; its styles join the shared component stylesheet, scoped like any component's, so the kit's styles cannot leak (E0122 still applies inside the kit). - Variants are props (
variant="primary",size="sm"), turned into classes withclass:name={condition}(decision 0029).
Alternatives considered
| Option | Why not |
|---|---|
| Read the parts from the repository at build time | Breaks duolith build outside the repository and after install; the kit could drift from the compiler |
| Ship the kit as an npm package of web components | Web only; native would need a second implementation of every part |
| Hand-written parts in each emitter | Two (later three) implementations per part, and themes would need special cases |
import Button from "@duolith/kit/Button" | One line per part; named imports read like any TypeScript library |
| Compile every part into every build | Ships 19 modules a project may never use |
Consequences
- Changing a part needs a rebuild of the
duolithbinary (cargo build);duolith devpicks it up on restart. - A project cannot yet override a part's pieces or look except through theme tokens; overrides are a later decision.
- Kit diagnostics carry paths such as
@duolith/kit/Button.duo; any diagnostic there is a framework bug, and a test compiles every part with none.