baseline-foundry 0.1.6 → 0.2.0

package/README.md

@@ -115,7 +115,7 @@ The verified GitHub release artifact remains available as a fallback for
 environments that cannot reach the npm registry:
 
 ```bash
-npm install https://github.com/lyubomir-popov/baseline-foundry/releases/download/v0.1.6/baseline-foundry-0.1.6.tgz
+npm install https://github.com/lyubomir-popov/baseline-foundry/releases/download/v0.2.0/baseline-foundry-0.2.0.tgz
 ```
 
 Use the attached `.tgz`, not the GitHub source archive: generated `dist/`
@@ -291,6 +291,7 @@ Independent surface contract:
 - tier choice is a top-level class on any `.bf-theme` container: `.bf-tier-editorial`, `.bf-tier-documentation`, `.bf-tier-app`, `.bf-tier-os`
 - multiple containers can coexist side by side under the same stylesheet
 - `dist/surfaces.json` stores the runtime tokens and the font-metric artifact that produced each shipped surface — see [docs/surfaces-manifest.md](docs/surfaces-manifest.md) for the full schema, stability guarantees, and consumer recipes
+- built-in spacing is sourced from the integrity-pinned Canonical DTCG artifact; the twelve `--spacing-*` properties carry final Canonical values and the temporary `--bf-*` aliases resolve directly to them during the bounded deprecation window; custom themes stay BF-namespaced as documented in [docs/spacing-token-adapter.md](docs/spacing-token-adapter.md)
 - the published manifest omits local build-machine config/baseline file paths, so the shipped JSON stays portable
 - every tier keeps metric-derived runtime alignment while nested stacks own semantic spacing
 
@@ -444,6 +445,7 @@ The font files are resolved relative to that config file, so a downstream repo c
 At minimum, define:
 
 - `baselineUnit`
+- `inlineUnitRem`
 - `fontFiles`
 - `fontStacks`
 - `elements`
@@ -451,6 +453,18 @@ At minimum, define:
 - `layout`
 - `components`
 
+> **Unreleased custom-theme migration:** 020a changes the exported
+> `ThemeConfig`/`ThemeComponentsConfig` shape and therefore also changes what
+> `readThemeConfig` accepts. Existing custom themes must add
+> `inlineUnitRem` (the built-in value is `0.25`) and replace
+> `inlineInsetFieldRem`, `inlineInsetActionRem`, and
+> `inlineInsetContinuationRem` with whole-unit `inlineInset*Units` counts. Add
+> `markGapInlineUnits`, and replace `panelPaddingInlineBaselineUnits` with
+> `panelPaddingInlineUnits`. Convert a previous rem value with
+> `rem / inlineUnitRem`; convert the previous panel baseline count with
+> `(oldCount * baselineUnit) / inlineUnitRem`. Old config files fail fast after
+> this change. No release containing this API change has been published.
+
 Example sketch for a downstream Ubuntu Sans theme:
 
 ```json
@@ -469,6 +483,7 @@ Example sketch for a downstream Ubuntu Sans theme:
 	"fontStacks": {
 		"ubuntu-sans": "\"Ubuntu Sans\", \"Ubuntu\", system-ui, sans-serif"
 	},
+	"inlineUnitRem": 0.25,
 	"elements": [
 		{
 			"identifier": "body",
@@ -497,14 +512,14 @@ Example sketch for a downstream Ubuntu Sans theme:
 	"components": {
 		"borderWidthRem": 0.0625,
 		"radiusRem": 0,
-		"controlBlockPaddingRem": 0.5,
-		"controlCompactBlockPaddingRem": 0.25,
-		"controlInlinePaddingRem": 1,
+		"inlineInsetFieldUnits": 2,
+		"inlineInsetActionUnits": 4,
+		"inlineInsetContinuationUnits": 8,
+		"markGapInlineUnits": 2,
 		"controlVisualSizeRem": 0.75,
 		"fieldGapBaselineUnits": 1,
-		"panelPaddingInlineBaselineUnits": 2,
-		"panelPaddingBlockBaselineUnits": 2,
-		"accordionIndentBaselineUnits": 3
+		"panelPaddingInlineUnits": 4,
+		"panelPaddingBlockBaselineUnits": 2
 	}
 }
 ```

package/config/canonical-spacing.resolved.json

@@ -0,0 +1,71 @@
+{
+  "format": "canonical-resolver-apply-spacing-v1",
+  "integrity": {
+    "algorithm": "sha256",
+    "canonicalProducts": "97cffe22691cebbe29d786d2fbe10d04d014d412ed35ccaca386ca41e73bd571"
+  },
+  "source": {
+    "package": "@canonical/design-tokens",
+    "repository": "https://github.com/canonical/design-tokens",
+    "commit": "18f57b95b1aa1dfe85a45746016b055c807d6628",
+    "resolver": "tokens/canonical/canonical.resolver.json"
+  },
+  "products": {
+    "site": {
+      "spacing.baseline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.field.block": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.mark.inline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.group.block": { "$type": "dimension", "$value": { "value": 1.5, "unit": "rem" } },
+      "spacing.gap.pattern.block": { "$type": "dimension", "$value": { "value": 4, "unit": "rem" } },
+      "spacing.gap.region.block": { "$type": "dimension", "$value": { "value": 8, "unit": "rem" } },
+      "spacing.inset.field.inline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.inset.action.inline": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
+      "spacing.inset.continuation.inline": { "$type": "dimension", "$value": { "value": 2, "unit": "rem" } },
+      "spacing.inset.surface.inline": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
+      "spacing.inset.surface.block": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
+      "spacing.inset.strip.block": { "$type": "dimension", "$value": { "value": 4, "unit": "rem" } }
+    },
+    "docs": {
+      "spacing.baseline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.gap.field.block": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.mark.inline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.group.block": { "$type": "dimension", "$value": { "value": 1.5, "unit": "rem" } },
+      "spacing.gap.pattern.block": { "$type": "dimension", "$value": { "value": 3, "unit": "rem" } },
+      "spacing.gap.region.block": { "$type": "dimension", "$value": { "value": 6, "unit": "rem" } },
+      "spacing.inset.field.inline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.inset.action.inline": { "$type": "dimension", "$value": { "value": 0.75, "unit": "rem" } },
+      "spacing.inset.continuation.inline": { "$type": "dimension", "$value": { "value": 1.5, "unit": "rem" } },
+      "spacing.inset.surface.inline": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
+      "spacing.inset.surface.block": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
+      "spacing.inset.strip.block": { "$type": "dimension", "$value": { "value": 3, "unit": "rem" } }
+    },
+    "app": {
+      "spacing.baseline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.gap.field.block": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.mark.inline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.gap.group.block": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.gap.pattern.block": { "$type": "dimension", "$value": { "value": 1, "unit": "rem" } },
+      "spacing.gap.region.block": { "$type": "dimension", "$value": { "value": 2, "unit": "rem" } },
+      "spacing.inset.field.inline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.inset.action.inline": { "$type": "dimension", "$value": { "value": 0.75, "unit": "rem" } },
+      "spacing.inset.continuation.inline": { "$type": "dimension", "$value": { "value": 1.5, "unit": "rem" } },
+      "spacing.inset.surface.inline": { "$type": "dimension", "$value": { "value": 0.75, "unit": "rem" } },
+      "spacing.inset.surface.block": { "$type": "dimension", "$value": { "value": 0.75, "unit": "rem" } },
+      "spacing.inset.strip.block": { "$type": "dimension", "$value": { "value": 3, "unit": "rem" } }
+    },
+    "os": {
+      "spacing.baseline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.gap.field.block": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.gap.mark.inline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.gap.group.block": { "$type": "dimension", "$value": { "value": 1.5, "unit": "rem" } },
+      "spacing.gap.pattern.block": { "$type": "dimension", "$value": { "value": 3, "unit": "rem" } },
+      "spacing.gap.region.block": { "$type": "dimension", "$value": { "value": 6, "unit": "rem" } },
+      "spacing.inset.field.inline": { "$type": "dimension", "$value": { "value": 0.25, "unit": "rem" } },
+      "spacing.inset.action.inline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.inset.continuation.inline": { "$type": "dimension", "$value": { "value": 1.25, "unit": "rem" } },
+      "spacing.inset.surface.inline": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.inset.surface.block": { "$type": "dimension", "$value": { "value": 0.5, "unit": "rem" } },
+      "spacing.inset.strip.block": { "$type": "dimension", "$value": { "value": 2, "unit": "rem" } }
+    }
+  }
+}

package/config/experiments/ibm-plex-engine-smoke.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.5,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ibm-plex-sans",
@@ -103,13 +104,13 @@
   "components": {
     "borderWidthRem": 0.0625,
     "radiusRem": 0,
-    "controlBlockPaddingRem": 0.5,
-    "controlCompactBlockPaddingRem": 0.25,
-    "controlInlinePaddingRem": 1,
+    "inlineInsetFieldUnits": 2,
+    "inlineInsetActionUnits": 4,
+    "inlineInsetContinuationUnits": 8,
+    "markGapInlineUnits": 2,
     "controlVisualSizeRem": 1,
     "fieldGapBaselineUnits": 1,
-    "panelPaddingInlineBaselineUnits": 2,
-    "panelPaddingBlockBaselineUnits": 2,
-    "accordionIndentBaselineUnits": 3
+    "panelPaddingInlineUnits": 4,
+    "panelPaddingBlockBaselineUnits": 2
   }
 }

package/config/experiments/ubuntu-engine-smoke.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.5,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ubuntu-sans",
@@ -103,13 +104,13 @@
   "components": {
     "borderWidthRem": 0.0625,
     "radiusRem": 0,
-    "controlBlockPaddingRem": 0.5,
-    "controlCompactBlockPaddingRem": 0.25,
-    "controlInlinePaddingRem": 1,
+    "inlineInsetFieldUnits": 2,
+    "inlineInsetActionUnits": 4,
+    "inlineInsetContinuationUnits": 8,
+    "markGapInlineUnits": 2,
     "controlVisualSizeRem": 1,
     "fieldGapBaselineUnits": 1,
-    "panelPaddingInlineBaselineUnits": 2,
-    "panelPaddingBlockBaselineUnits": 2,
-    "accordionIndentBaselineUnits": 3
+    "panelPaddingInlineUnits": 4,
+    "panelPaddingBlockBaselineUnits": 2
   }
 }

package/config/foundation-theme.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.5,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ubuntu-sans",
@@ -105,13 +106,13 @@
   "components": {
     "borderWidthRem": 0.0625,
     "radiusRem": 0,
-    "controlBlockPaddingRem": 0.5,
-    "controlCompactBlockPaddingRem": 0.25,
-    "controlInlinePaddingRem": 1,
+    "inlineInsetFieldUnits": 2,
+    "inlineInsetActionUnits": 4,
+    "inlineInsetContinuationUnits": 8,
+    "markGapInlineUnits": 2,
     "controlVisualSizeRem": 1,
     "fieldGapBaselineUnits": 1,
-    "panelPaddingInlineBaselineUnits": 2,
-    "panelPaddingBlockBaselineUnits": 2,
-    "accordionIndentBaselineUnits": 3
+    "panelPaddingInlineUnits": 4,
+    "panelPaddingBlockBaselineUnits": 2
   }
 }

package/config/tiers/app.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.25,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ubuntu-sans",
@@ -105,16 +106,14 @@
   },
   "components": {
     "borderWidthRem": 0.0625,
-    "radiusRem": 0.125,
-    "controlBlockPaddingRem": 0.5,
-    "controlCompactBlockPaddingRem": 0.375,
-    "controlInlinePaddingRem": 1,
-    "controlInlinePaddingActionRem": 1,
-    "controlInlinePaddingFieldRem": 0.25,
+    "radiusRem": 0,
+    "inlineInsetFieldUnits": 1,
+    "inlineInsetActionUnits": 3,
+    "inlineInsetContinuationUnits": 6,
+    "markGapInlineUnits": 1,
     "controlVisualSizeRem": 1,
     "fieldGapBaselineUnits": 2,
-    "panelPaddingInlineBaselineUnits": 3,
-    "panelPaddingBlockBaselineUnits": 3,
-    "accordionIndentBaselineUnits": 6
+    "panelPaddingInlineUnits": 3,
+    "panelPaddingBlockBaselineUnits": 3
   }
 }

package/config/tiers/documentation.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.25,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ubuntu-sans",
@@ -106,15 +107,13 @@
   "components": {
     "borderWidthRem": 0.0625,
     "radiusRem": 0,
-    "controlBlockPaddingRem": 0.5,
-    "controlCompactBlockPaddingRem": 0.375,
-    "controlInlinePaddingRem": 0.875,
-    "controlInlinePaddingActionRem": 1,
-    "controlInlinePaddingFieldRem": 0.5,
+    "inlineInsetFieldUnits": 2,
+    "inlineInsetActionUnits": 3,
+    "inlineInsetContinuationUnits": 6,
+    "markGapInlineUnits": 2,
     "controlVisualSizeRem": 0.875,
     "fieldGapBaselineUnits": 2,
-    "panelPaddingInlineBaselineUnits": 4,
-    "panelPaddingBlockBaselineUnits": 4,
-    "accordionIndentBaselineUnits": 6
+    "panelPaddingInlineUnits": 4,
+    "panelPaddingBlockBaselineUnits": 4
   }
 }

package/config/tiers/editorial.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.5,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ubuntu-sans",
@@ -106,15 +107,13 @@
   "components": {
     "borderWidthRem": 0.0625,
     "radiusRem": 0,
-    "controlBlockPaddingRem": 0.5,
-    "controlCompactBlockPaddingRem": 0.25,
-    "controlInlinePaddingRem": 1,
-    "controlInlinePaddingActionRem": 1,
-    "controlInlinePaddingFieldRem": 0.5,
+    "inlineInsetFieldUnits": 2,
+    "inlineInsetActionUnits": 4,
+    "inlineInsetContinuationUnits": 8,
+    "markGapInlineUnits": 2,
     "controlVisualSizeRem": 1,
     "fieldGapBaselineUnits": 1,
-    "panelPaddingInlineBaselineUnits": 2,
-    "panelPaddingBlockBaselineUnits": 2,
-    "accordionIndentBaselineUnits": 3
+    "panelPaddingInlineUnits": 4,
+    "panelPaddingBlockBaselineUnits": 2
   }
 }

package/config/tiers/os.json

@@ -1,5 +1,6 @@
 {
   "baselineUnit": 0.25,
+  "inlineUnitRem": 0.25,
   "fontFiles": [
     {
       "family": "ubuntu-sans",
@@ -106,15 +107,13 @@
   "components": {
     "borderWidthRem": 0.0625,
     "radiusRem": 0,
-    "controlBlockPaddingRem": 0.375,
-    "controlCompactBlockPaddingRem": 0.25,
-    "controlInlinePaddingRem": 0.75,
-    "controlInlinePaddingActionRem": 1,
-    "controlInlinePaddingFieldRem": 0.25,
+    "inlineInsetFieldUnits": 1,
+    "inlineInsetActionUnits": 2,
+    "inlineInsetContinuationUnits": 5,
+    "markGapInlineUnits": 1,
     "controlVisualSizeRem": 0.75,
     "fieldGapBaselineUnits": 1,
-    "panelPaddingInlineBaselineUnits": 2,
-    "panelPaddingBlockBaselineUnits": 2,
-    "accordionIndentBaselineUnits": 3
+    "panelPaddingInlineUnits": 2,
+    "panelPaddingBlockBaselineUnits": 2
   }
 }

package/dist/application-layout.js

@@ -7,7 +7,7 @@ const CLOSE_SELECTOR = "[data-application-layout-close]";
 const PIN_SELECTOR = "[data-application-layout-pin]";
 const COLLAPSED_CLASS = "is-collapsed";
 const PINNED_CLASS = "is-pinned";
-const LARGE_BREAKPOINT = "(min-width: 64.75rem)";
+const LARGE_BREAKPOINT = "(min-width: 48rem)";
 const lastTriggerByNavigation = new WeakMap();
 function queryAllWithinRoot(root, selector) {
     const elements = Array.from(root.querySelectorAll(selector));

package/dist/build.d.ts

@@ -12,6 +12,7 @@ export interface BuildThemeFromConfigOptions {
     surfaceLabel?: string;
     additionalSurfaces?: AdditionalThemeSurfaceBuildConfig[];
 }
+export declare function validateThemeConfig(config: ThemeConfig): void;
 export declare function readThemeConfig(configPath: string): Promise<ThemeConfig>;
 export declare function buildThemeFromConfig(configPath?: string, options?: BuildThemeFromConfigOptions): Promise<BuildThemeResult>;
 export declare function buildThemeFromTier(tier: TierName): Promise<BuildThemeResult>;

package/dist/build.js

@@ -1,7 +1,9 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { generateFoundryCss } from "./css.js";
+import { assertSpacingSetsEqual, canonicalProductForBuiltInTheme, dtcgSpacingValue, legacyThemeConfigSpacing, readCanonicalSpacingProduct } from "./dtcg-spacing.js";
 import { normalizeBuiltInThemeName, presetNames, resolveBuiltInThemePath, resolvePresetPath, resolveTierPath, tierNames } from "./presets.js";
+const DISCLOSURE_ICON_INLINE_SIZE_REM = 1;
 function parseRem(remValue) {
     return Number.parseFloat(remValue.replace("rem", ""));
 }
@@ -52,18 +54,14 @@ const REQUIRED_LAYOUT_FIELDS = [
 const REQUIRED_COMPONENT_FIELDS = [
     "borderWidthRem",
     "radiusRem",
-    "controlBlockPaddingRem",
-    "controlInlinePaddingRem",
+    "inlineInsetFieldUnits",
+    "inlineInsetActionUnits",
+    "inlineInsetContinuationUnits",
+    "markGapInlineUnits",
     "controlVisualSizeRem",
     "fieldGapBaselineUnits",
-    "panelPaddingInlineBaselineUnits",
-    "panelPaddingBlockBaselineUnits",
-    "accordionIndentBaselineUnits"
-];
-const OPTIONAL_COMPONENT_FIELDS = [
-    "controlCompactBlockPaddingRem",
-    "controlInlinePaddingActionRem",
-    "controlInlinePaddingFieldRem"
+    "panelPaddingInlineUnits",
+    "panelPaddingBlockBaselineUnits"
 ];
 function assertNoDuplicateRoleKeys(raw, configPath) {
     const rolesMatch = raw.match(/"roles"\s*:\s*\{([\s\S]*?)\}/);
@@ -79,7 +77,7 @@ function assertNoDuplicateRoleKeys(raw, configPath) {
         seen.add(roleName);
     }
 }
-function validateConfig(config) {
+export function validateThemeConfig(config) {
     if (!config.fontFiles.length) {
         throw new Error("Theme config requires at least one font file.");
     }
@@ -99,18 +97,52 @@ function validateConfig(config) {
     if (config.baselineUnit <= 0) {
         throw new Error('Theme config field "baselineUnit" must be greater than zero.');
     }
+    assertFiniteNumberConfigField(config.inlineUnitRem, "inlineUnitRem");
+    if (config.inlineUnitRem <= 0) {
+        throw new Error('Theme config field "inlineUnitRem" must be greater than zero.');
+    }
     for (const field of REQUIRED_LAYOUT_FIELDS) {
         assertFiniteNumberConfigField(config.layout[field], `layout.${field}`);
     }
     for (const field of REQUIRED_COMPONENT_FIELDS) {
         assertFiniteNumberConfigField(config.components[field], `components.${field}`);
     }
-    for (const field of OPTIONAL_COMPONENT_FIELDS) {
-        const value = config.components[field];
-        if (value !== undefined) {
-            assertFiniteNumberConfigField(value, `components.${field}`);
+    if (config.components.borderWidthRem <= 0 || config.components.controlVisualSizeRem <= 0) {
+        throw new Error("Component border width and control visual size must be greater than zero.");
+    }
+    if (config.components.radiusRem < 0 ||
+        config.components.inlineInsetFieldUnits < 0 ||
+        config.components.inlineInsetActionUnits < 0 ||
+        config.components.inlineInsetContinuationUnits < 0 ||
+        config.components.markGapInlineUnits < 0 ||
+        config.components.fieldGapBaselineUnits < 0 ||
+        config.components.panelPaddingInlineUnits < 0 ||
+        config.components.panelPaddingBlockBaselineUnits < 0) {
+        throw new Error("Component radius, inline insets, gaps, and surface padding must be non-negative.");
+    }
+    for (const field of [
+        "inlineInsetFieldUnits",
+        "inlineInsetActionUnits",
+        "inlineInsetContinuationUnits",
+        "markGapInlineUnits",
+        "panelPaddingInlineUnits"
+    ]) {
+        if (!Number.isInteger(config.components[field])) {
+            throw new Error(`Theme config field "components.${field}" must be a whole inline-unit count.`);
         }
     }
+    if (config.components.inlineInsetActionUnits * config.inlineUnitRem < config.components.borderWidthRem) {
+        throw new Error("Component action inset must contain its bordered action edge.");
+    }
+    if (config.components.inlineInsetFieldUnits > config.components.inlineInsetActionUnits ||
+        config.components.inlineInsetActionUnits > config.components.inlineInsetContinuationUnits) {
+        throw new Error("Component inline inset counts must be ordered field <= action <= continuation.");
+    }
+    const authoredContinuation = config.components.inlineInsetContinuationUnits * config.inlineUnitRem;
+    const authoredDisclosureNeed = DISCLOSURE_ICON_INLINE_SIZE_REM + (config.components.markGapInlineUnits * config.inlineUnitRem);
+    if (authoredContinuation < authoredDisclosureNeed) {
+        throw new Error(`Component continuation inset ${toRem(authoredContinuation)} cannot contain its fixed disclosure canvas and mark gap ${toRem(authoredDisclosureNeed)}.`);
+    }
     const elementIdentifiers = new Set();
     for (const [index, element] of config.elements.entries()) {
         if (elementIdentifiers.has(element.identifier)) {
@@ -140,7 +172,7 @@ export async function readThemeConfig(configPath) {
     const raw = await fs.readFile(configPath, "utf8");
     assertNoDuplicateRoleKeys(raw, configPath);
     const config = JSON.parse(raw);
-    validateConfig(config);
+    validateThemeConfig(config);
     return config;
 }
 function createBaselineConfig(config, sourceConfigPath, baselineConfigPath) {
@@ -205,28 +237,26 @@ function toTypographyToken(identifier, token, config) {
         textTransform: elementConfig?.textTransform
     };
 }
-function buildComponentTokens(config) {
-    const controlInlinePaddingActionRem = config.components.controlInlinePaddingActionRem ?? config.components.controlInlinePaddingRem;
-    const controlInlinePaddingFieldRem = config.components.controlInlinePaddingFieldRem ?? (controlInlinePaddingActionRem / 2);
+function spacingRem(spacing, id) {
+    return dtcgSpacingValue(spacing[id]);
+}
+function buildComponentTokens(config, spacing) {
     return {
         borderWidth: toRem(config.components.borderWidthRem),
         // Vanilla's shared $bar-thickness is represented as 0.1875rem so emphasis
         // bars and thin borders both scale with root text sizing.
         barThickness: toRem(3 / 16),
         radius: toRem(config.components.radiusRem),
-        controlBlockPadding: toRem(config.components.controlBlockPaddingRem),
-        controlCompactBlockPadding: toRem(config.components.controlCompactBlockPaddingRem ?? config.components.controlBlockPaddingRem),
-        controlInlinePadding: toRem(controlInlinePaddingActionRem),
-        controlInlinePaddingAction: toRem(controlInlinePaddingActionRem),
-        controlInlinePaddingField: toRem(controlInlinePaddingFieldRem),
+        inlineInsetField: spacingRem(spacing, "spacing.inset.field.inline"),
+        inlineInsetAction: spacingRem(spacing, "spacing.inset.action.inline"),
+        inlineInsetContinuation: spacingRem(spacing, "spacing.inset.continuation.inline"),
         controlVisualSize: toRem(config.components.controlVisualSizeRem),
-        fieldGap: toRem(config.components.fieldGapBaselineUnits * config.baselineUnit),
-        panelPaddingInline: toRem(config.components.panelPaddingInlineBaselineUnits * config.baselineUnit),
-        panelPaddingBlock: toRem(config.components.panelPaddingBlockBaselineUnits * config.baselineUnit),
-        accordionIndent: toRem(config.components.accordionIndentBaselineUnits * config.baselineUnit)
+        fieldGap: spacingRem(spacing, "spacing.gap.field.block"),
+        panelPaddingInline: spacingRem(spacing, "spacing.inset.surface.inline"),
+        panelPaddingBlock: spacingRem(spacing, "spacing.inset.surface.block")
     };
 }
-function buildThemeTokens(config, baselineTokens) {
+function buildThemeTokens(config, baselineTokens, spacing, canonicalSpacing) {
     const elements = Object.fromEntries(Object.entries(baselineTokens.elements).map(([identifier, token]) => [identifier, toTypographyToken(identifier, token, config)]));
     const roles = Object.fromEntries(Object.entries(config.roles).map(([roleName, identifier]) => {
         const roleToken = elements[identifier];
@@ -235,8 +265,31 @@ function buildThemeTokens(config, baselineTokens) {
         }
         return [roleName, roleToken];
     }));
+    const body = roles.body;
+    if (!body) {
+        throw new Error('Theme tokens require a generated "body" role.');
+    }
+    const nestedLineHeight = parseRem(body.lineHeight) - parseRem(baselineTokens.baselineUnit);
+    if (nestedLineHeight < parseRem(body.fontSize)) {
+        throw new Error(`Nested line ${toRem(nestedLineHeight)} cannot contain the body font ${body.fontSize}.`);
+    }
+    if (nestedLineHeight < config.components.controlVisualSizeRem) {
+        throw new Error(`Nested line ${toRem(nestedLineHeight)} cannot contain the control visual ${toRem(config.components.controlVisualSizeRem)}.`);
+    }
+    const nestedFramedPaint = nestedLineHeight + (config.components.borderWidthRem * 2);
+    if (nestedFramedPaint > parseRem(body.lineHeight)) {
+        throw new Error(`Nested framed controls require ${toRem(nestedFramedPaint)}, which exceeds the body line ${body.lineHeight}.`);
+    }
+    const leadingMarkNeed = config.components.controlVisualSizeRem +
+        spacing["spacing.gap.mark.inline"].$value.value;
+    if (spacing["spacing.inset.continuation.inline"].$value.value < leadingMarkNeed) {
+        throw new Error(`Continuation inset ${spacingRem(spacing, "spacing.inset.continuation.inline")} cannot contain the leading mark and gap ${toRem(leadingMarkNeed)}.`);
+    }
     return {
-        baselineUnit: baselineTokens.baselineUnit,
+        baselineUnit: spacingRem(spacing, "spacing.baseline"),
+        inlineUnit: toRem(config.inlineUnitRem),
+        canonicalSpacing,
+        spacing,
         fontFiles: config.fontFiles,
         fontStacks: config.fontStacks,
         roles,
@@ -245,15 +298,15 @@ function buildThemeTokens(config, baselineTokens) {
             contentMaxWidth: toRem(config.layout.contentMaxWidthRem),
             contentPaddingInline: toRem(config.layout.contentPaddingInlineRem),
             measure: toRem(config.layout.measureRem),
-            sectionSpace: toRem(config.layout.sectionSpaceBaselineUnits * config.baselineUnit),
-            sectionSpaceShallow: toRem(config.layout.sectionSpaceShallowBaselineUnits * config.baselineUnit),
-            sectionSpaceDeep: toRem(config.layout.sectionSpaceDeepBaselineUnits * config.baselineUnit),
-            stripSpace: toRem(config.layout.stripSpaceBaselineUnits * config.baselineUnit),
+            sectionSpace: spacingRem(spacing, "spacing.gap.pattern.block"),
+            sectionSpaceShallow: spacingRem(spacing, "spacing.gap.group.block"),
+            sectionSpaceDeep: spacingRem(spacing, "spacing.gap.region.block"),
+            stripSpace: spacingRem(spacing, "spacing.inset.strip.block"),
             gridGapInline: toRem(config.layout.gridGapInlineBaselineUnits * config.baselineUnit),
             gridGapBlock: toRem(config.layout.gridGapBlockBaselineUnits * config.baselineUnit),
             pageMargin: toRem(config.layout.pageMarginBaselineUnits * config.baselineUnit)
         },
-        components: buildComponentTokens(config)
+        components: buildComponentTokens(config, spacing)
     };
 }
 function inferBuiltInPresetName(resolvedConfigPath) {
@@ -305,6 +358,15 @@ function buildSurfaceManifest(defaultSurface, surfaces) {
 }
 async function buildThemeSurface(name, resolvedConfigPath, baselineDir, outputDir, options = {}) {
     const config = await readThemeConfig(resolvedConfigPath);
+    const builtInName = inferBuiltInPresetName(resolvedConfigPath);
+    const legacySpacing = legacyThemeConfigSpacing(config);
+    const canonicalSpacing = builtInName
+        ? await readCanonicalSpacingProduct(canonicalProductForBuiltInTheme(builtInName))
+        : undefined;
+    const spacing = canonicalSpacing ? structuredClone(canonicalSpacing) : legacySpacing;
+    if (builtInName) {
+        assertSpacingSetsEqual(spacing, legacySpacing, `Built-in ${builtInName} spacing authoring assertion (update the pinned Canonical artifact and matching tier counts together)`);
+    }
     const resolvedBaselineDir = path.resolve(baselineDir);
     const resolvedOutputDir = path.resolve(outputDir);
     await ensureDirectory(resolvedBaselineDir);
@@ -324,7 +386,7 @@ async function buildThemeSurface(name, resolvedConfigPath, baselineDir, outputDi
         configPath: resolvedConfigPath,
         baselineConfigPath,
         baselineTokensPath: path.join(resolvedBaselineDir, "tokens.json"),
-        tokens: buildThemeTokens(runtimeConfig, baselineTokens),
+        tokens: buildThemeTokens(runtimeConfig, baselineTokens, spacing, canonicalSpacing),
         metrics: runtimeMetricsTokens(baselineTokens, runtimeConfig.fontFiles)
     };
 }