add root spacing tokens

CHANGELOG.md

@@ -17,6 +17,27 @@ Prefix the change with one of these keywords:
 
 ## [Unreleased]
 
+### Added
+
+- Root spacing tokens. `baseStyles.spacing` now produces a `Root Spacing` group on `:root` in `<prefix>-tokens.css` (and `tokens.wp.css` when themeable), mirrored in `<prefix>-tokens.js` as `root`, so components can use the page gutter anywhere — including WordPress block themes, which don't load `layout.css`:
+
+  ```css
+  --mylib--root-padding-x: var(--mylib--spacing-large);
+  --mylib--root-padding-y: 0;
+  --mylib--root-padding-top: var(--mylib--root-padding-y);
+  --mylib--root-padding-right: var(--mylib--root-padding-x);
+  --mylib--root-padding-bottom: var(--mylib--root-padding-y);
+  --mylib--root-padding-left: var(--mylib--root-padding-x);
+  --mylib--root-block-gap: var(--mylib--spacing-medium);
+  ```
+
+- `baseStyles.spacing.padding` accepts `x` (right and left) and `y` (top and bottom) alongside the four sides, and a side set on its own wins over its axis. Without an explicit `x`/`y`, an axis takes the value both of its sides share, so existing four-side configs get the axis tokens with no change. theme.json still receives the four sides.
+
+### Changed
+
+- `layout.css` no longer declares the root padding and block-gap custom properties in a `body { }` block. They keep their names and now live on `:root` in `tokens.css`, which `layout.css` already depended on for spacing values. The `.has-global-padding` rules are emitted only when horizontal root padding is configured.
+- Unknown keys under `baseStyles.spacing.padding` now throw at config load instead of passing through into theme.json.
+
 ## [0.7.2] - 2026-09-07
 
 ### Fixed

CLAUDE.md

@@ -109,6 +109,8 @@ Individual headings (h1-h6) get `fontStyle: 'normal'` default via `ensureFontSty
 
 Link's `hoverColor` generates `:hover` pseudo-class in both theme.json (nested `":hover"` key) and SCSS (`:where(a:hover)` rule).
 
+**Root spacing tokens**: `baseStyles.spacing` also produces `--{prefix}--root-padding-x`/`-y`, `--{prefix}--root-padding-{top,right,bottom,left}` and `--{prefix}--root-block-gap`. `src/generators/root-tokens.ts` builds them; `tokens.css`/`tokens.wp.css` declare them on `:root` and `tokens.js` mirrors them as `root`. `padding` accepts `x`, `y` and the four sides; `resolveRootPadding()` in `config.ts` is the single source of truth — an axis is its explicit value or the value both its sides share, and a side is its explicit value or its axis (emitted as a `var()` alias of the axis token). `layout.css` holds only rules: its `.has-global-padding` rules read the side tokens so per-side overrides still match theme.json, where `x`/`y` expand to the four sides.
+
 ### Locked vs Themeable Mode
 
 - **`themeable: false`** (default): Hardcoded token values, `custom`/`customDuotone`/`customGradient` set to `false` in theme.json. integrate.php enforces layout lock and editor restrictions at theme layer.
@@ -143,6 +145,7 @@ src/
   generators/
     tokens-css.ts     CSS custom properties (:root { --prefix--* })
     tokens-wp-css.ts  WordPress preset-mapped CSS variables
+    root-tokens.ts    Root spacing tokens from baseStyles.spacing (shared by tokens css/wp.css/js)
     theme-json.ts     WordPress theme.json (settings + styles)
     fonts-css.ts      @font-face declarations
     copy-fonts.ts     Font file copying from fontsDir to dist

c2b.config.example.json

@@ -127,10 +127,8 @@
             "blockGap": "medium",
             "entryContent": "large",
             "padding": {
-                "top": "0",
-                "right": "large",
-                "bottom": "0",
-                "left": "large"
+                "x": "large",
+                "y": "0"
             }
         }
     }

dist/config.d.ts

@@ -1,4 +1,4 @@
-import type { C2bConfig, C2bConfigInput, TokenCategory, BaseStyleElementDef, BaseStylesConfig } from './types.js';
+import type { C2bConfig, C2bConfigInput, TokenCategory, BaseStyleElementDef, BaseStylesConfig, BaseStylesSpacingPadding } from './types.js';
 export declare function loadConfig(configPath?: string): C2bConfig;
 export declare function validateConfig(input: C2bConfigInput): C2bConfig;
 export interface ResolvedTokenRef {
@@ -35,6 +35,17 @@ export declare function resolveForThemeJson(value: string, tokens: C2bConfig['to
  * If the config doesn't specify fontStyle, default to "normal".
  */
 export declare function ensureFontStyle(def: BaseStyleElementDef): BaseStyleElementDef;
+/**
+ * Resolve `baseStyles.spacing.padding` into its two axes and four sides — the
+ * single source of truth for root padding in the token outputs, layout.css and
+ * theme.json. Values stay as written in config (token keys or raw CSS).
+ *
+ * - An axis is its explicit `x`/`y`, else the shared value when both of its
+ *   sides are set and identical. A lone or asymmetric pair has no single axis
+ *   value, so the axis stays undefined.
+ * - A side is its explicit value, else its axis.
+ */
+export declare function resolveRootPadding(padding: BaseStylesSpacingPadding | undefined): BaseStylesSpacingPadding;
 /** Classification result for a baseStyles value. */
 export type BaseStyleValueClass = {
     kind: 'token';

dist/generators/layout-css.d.ts

@@ -1,11 +1,13 @@
 import type { C2bConfig } from '../types.js';
 /**
- * Emit layout.css — root padding/block-gap CSS variables on `body` plus the
- * layout-utility rules (block-gap on constrained/flex/grid, layout constraint
- * for content/wide widths, has-global-padding helpers, alignfull bleed).
+ * Emit layout.css — the layout-utility rules: block-gap on constrained/flex/grid,
+ * layout constraint for content/wide widths, has-global-padding helpers,
+ * alignfull bleed.
  *
- * Per-element typography lives in base-styles.css; flow-spacing rules live in
- * typography.css. This file is the layout-only output.
+ * The root padding and block-gap custom properties these rules read are tokens,
+ * declared on :root in tokens.css (see root-tokens.ts) so they also exist where
+ * this file isn't loaded. Per-element typography lives in base-styles.css;
+ * flow-spacing rules live in typography.css.
  *
  * Returns null when no layout-relevant config is present.
  */