Skip to contentWolf-Rayet

Decision records

ADR-0012 Spatial primitives live in the Primitives collection

Accepted2026-08-27Phase 2

#Context

ADR-0007 resolves spatial semantic tokens through the Density collection, but the raw scales those semantics alias have no declared home. Section 9 describes Primitives as "mode-less, the raw OKLCH ramps" — chromatic only. Phase 2 cannot generate a spacing or type scale until the collection list says where the output lives and how density modes reach it.

#Decision

The Primitives collection carries both sets: the chromatic ramps and the raw spatial scales. It stays mode-less, which is the property that qualifies both sets for membership — a spatial primitive is a position on a generated scale, identical under every theme and every density, exactly as a ramp step is identical under every density. Density modes alias spatial primitives the way Theme modes alias chromatic ones: comfortable and compact each select steps from the same scale, they never author values. Spatial scales are generated, not hand-picked — a modular type scale and a spacing scale defined as functions with parameters in the generator config, extending the rule that the generator is the sole author of primitives. The symmetry is the architecture: one mode-less primitive layer, two orthogonal mode axes selecting from it, semantic aliases as the only consumer surface.

#Rejected options

A separate Spatial-Primitives collection. Cleaner separation on paper. Rejected because it multiplies collections without a difference in kind: both sets are mode-less, generated, and aliased-only, so a second collection adds a boundary with no distinct resolution semantics — structure that explains nothing is structure to maintain.

Raw values inside the Density modes. The shortest path: compact simply states its sizes. Rejected because it repeals the primitive-to-semantic discipline for the spatial half of the system — hand-authored values with no generated source, no receipts, and nothing for a second density to derive from. The chromatic side already rejected hand-picked values; the spatial side does not get a lower standard.

Per-density generated scales. Two generator runs, one per mode. Rejected because it makes the modes authors instead of selectors: two scales can drift apart in ratio, and the relationship between comfortable and compact becomes an accident of two configs rather than a stated selection rule from one scale.

#Consequences

Section 9's Primitives line is superseded to name both sets. The Phase 2 generators extend generator.config.json with spatial entries and emit spatial primitives into the same DTCG output and receipt pipeline as the ramps. The density-completeness check gains its object: the spatial semantic set resolving in both modes against one primitive scale. Figma's Primitives collection carries the spatial variables when Foundations syncs. Touches the Density completeness row; adds no new check.