Duolith docs

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 is spec/kit/<part>.yaml, checked against spec/schemas/kit.schema.json and against the part itself by pnpm 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.rs embeds every part with include_str!, as crates/emit-web already does for the runtime, so duolith build works 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 with class:name={condition} (decision 0029).

Alternatives considered

OptionWhy not
Read the parts from the repository at build timeBreaks duolith build outside the repository and after install; the kit could drift from the compiler
Ship the kit as an npm package of web componentsWeb only; native would need a second implementation of every part
Hand-written parts in each emitterTwo (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 buildShips 19 modules a project may never use

Consequences

  • Changing a part needs a rebuild of the duolith binary (cargo build); duolith dev picks 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.