Duolith docs

0016. Grow the utility vocabulary from data, with fixed scales beside theme tokens

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: Mik
  • Planning item: WP7 part 1 (styling and themes)

Context

The walking skeleton had seventeen utilities. Real screens need sizing, positioning, self-alignment, borders, shadows, weights, truncation and more. Some of these values are design choices a project should own (space, radius, colours, shadows, text styles); others are plain arithmetic that no project should redefine (w-1/2 is half, opacity-50 is half opaque, z-10 is above z-0).

Decision

  • The vocabulary lives in spec/styling/utilities.yaml, one entry per pattern, each with a section, a description and its declarations. Names follow Tailwind's where the meaning is the same. The full list is generated into docs/guide/styling.md.
  • A {group} in a pattern matches either a theme token (space, radius, color, shadow, text) or a step of a fixed scale declared in the same file (fraction, opacity, z, border-width, weight, line-clamp). Scale steps become literal values; tokens stay token references so each target expresses them its own way.
  • A fixed name always wins over a pattern (text-center is alignment even if a theme defines a colour called center); among patterns, file order decides.
  • The theme gains shadow tokens (light and dark, stronger in dark), radius xs, xl, 2xl, larger space steps up to 96 (384px), and a success colour.
  • border is now three properties (border-width, border-style, border-color) so border-primary and border-2 combine with it in any order.
  • Within one style table entry, rules with fewer conditions come first, so a conditional utility is never undone by an unconditional one written after it.
  • duolith_style::closest_utility returns the nearest utility to an unknown class (Damerau edit distance, one edit plus one per four characters), keeping or correcting prefixes, for the analyzer to add "did you mean" to E0103.

Alternatives considered

OptionWhy not
Arbitrary values such as w-[37px]Bypasses tokens, cannot be checked, and makes native mapping open-ended
Make fractions and opacity theme tokensA project changing what 1/2 means helps no one and makes utilities unpredictable
Hand-written Rust per utilityThe vocabulary is data; docs, completion and suggestions all need to read it

Consequences

Adding a utility is a YAML edit plus a regenerated reference (node tools/generate-styling-reference.ts; pnpm check:repo fails if it is stale). Native emitters must map the CSS property names used here; line-clamp-* and truncate use web forms today and map to the native text engine's line limit later.