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 intodocs/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-centeris alignment even if a theme defines a colour calledcenter); among patterns, file order decides. - The theme gains
shadowtokens (light and dark, stronger in dark), radiusxs,xl,2xl, larger space steps up to96(384px), and asuccesscolour. borderis now three properties (border-width,border-style,border-color) soborder-primaryandborder-2combine 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_utilityreturns 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
| Option | Why not |
|---|---|
Arbitrary values such as w-[37px] | Bypasses tokens, cannot be checked, and makes native mapping open-ended |
| Make fractions and opacity theme tokens | A project changing what 1/2 means helps no one and makes utilities unpredictable |
| Hand-written Rust per utility | The 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.