@almadar/ui 4.57.4 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/ui",
-  "version": "4.57.4",
+  "version": "5.0.0",
   "description": "React UI components, hooks, and providers for Almadar",
   "type": "module",
   "sideEffects": [
@@ -129,7 +129,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@almadar/core": "^7.16.0",
+    "@almadar/core": "^9.0.0",
     "@almadar/evaluator": ">=2.9.2",
     "@almadar/logger": "^1.3.0",
     "@almadar/patterns": "^2.26.0",

package/tailwind-preset.cjs

@@ -256,8 +256,13 @@ module.exports = {
 ],
   theme: {
     fontFamily: {
+      // `sans` continues to read --font-family for backward compat.
       sans: ['var(--font-family)', 'ui-sans-serif', 'system-ui', 'sans-serif'],
       mono: ['var(--font-family-mono, ui-monospace)', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'monospace'],
+      // Layer 1 Type axis: display + body family slots fall back to --font-family
+      // so existing themes that don't define them keep their current look.
+      display: ['var(--font-family-display, var(--font-family))', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+      body: ['var(--font-family-body, var(--font-family))', 'ui-sans-serif', 'system-ui', 'sans-serif'],
     },
     extend: {
       colors: {
@@ -313,12 +318,34 @@ module.exports = {
         lg: 'var(--radius-lg)',
         xl: 'var(--radius-xl)',
         full: 'var(--radius-full)',
+        // Geometry-axis intent overlay. Codemod targets these for `rounded-*` by component intent:
+        //   Card / containers   → rounded-container
+        //   Button / interactive → rounded-interactive
+        //   Avatar / Badge      → rounded-pill
+        container: 'var(--radius-container, var(--radius-md))',
+        interactive: 'var(--radius-interactive, var(--radius-md))',
+        pill: 'var(--radius-pill, var(--radius-full))',
+      },
+      borderWidth: {
+        // Geometry-axis border rhythm with intent. Existing literal `border` / `border-2` keep working.
+        hairline: 'var(--border-hairline, 1px)',
+        standard: 'var(--border-standard, var(--border-width, 1px))',
+        heavy: 'var(--border-heavy, var(--border-width-thick, 2px))',
       },
       boxShadow: {
         sm: 'var(--shadow-sm)',
         DEFAULT: 'var(--shadow-main)',
         lg: 'var(--shadow-lg)',
         inner: 'var(--shadow-inner)',
+        // Elevation-axis per-layer intent. Codemod targets:
+        //   Card                → shadow-elevation-card
+        //   Popover / Tooltip   → shadow-elevation-popover
+        //   Dialog              → shadow-elevation-dialog
+        //   Toast               → shadow-elevation-toast
+        'elevation-card': 'var(--elevation-card, var(--shadow-sm))',
+        'elevation-popover': 'var(--elevation-popover, var(--shadow-main))',
+        'elevation-dialog': 'var(--elevation-dialog, var(--shadow-lg))',
+        'elevation-toast': 'var(--elevation-toast, var(--shadow-main))',
       },
       fontWeight: {
         normal: 'var(--font-weight-normal, 400)',
@@ -326,10 +353,98 @@ module.exports = {
         bold: 'var(--font-weight-bold, 600)',
       },
       transitionDuration: {
-        fast: 'var(--transition-fast, 150ms)',
-        normal: 'var(--transition-normal, 250ms)',
-        slow: 'var(--transition-slow, 400ms)',
+        // Existing aliases retained; resolve through the Motion-axis tokens
+        // with the previous `--transition-*` values as fallback so themes that
+        // don't define `--duration-*` keep their pre-Layer-1 motion.
+        fast: 'var(--duration-fast, var(--transition-fast, 150ms))',
+        normal: 'var(--duration-normal, var(--transition-normal, 250ms))',
+        slow: 'var(--duration-slow, var(--transition-slow, 400ms))',
+        instant: 'var(--duration-instant, 0ms)',
+        dramatic: 'var(--duration-dramatic, 600ms)',
+      },
+      transitionTimingFunction: {
+        // Motion-axis easing palette. `standard` falls back to the existing
+        // `--transition-timing` so backward compat is preserved.
+        linear: 'var(--easing-linear, linear)',
+        standard: 'var(--easing-standard, var(--transition-timing, cubic-bezier(0.4, 0, 0.2, 1)))',
+        emphasized: 'var(--easing-emphasized, cubic-bezier(0.2, 0, 0, 1))',
+        spring: 'var(--easing-spring, cubic-bezier(0.34, 1.56, 0.64, 1))',
+      },
+      // Density-axis spacing scale. Tailwind's default `p-3` / `gap-4` resolve
+      // here so existing classes keep working — but now read from tokens.
+      // Defaults match Tailwind's default (12px / 16px / 24px for 3 / 4 / 6),
+      // so post-migration visual output is identical until a theme overrides.
+      spacing: {
+        0: 'var(--space-0, 0px)',
+        1: 'var(--space-1, 4px)',
+        2: 'var(--space-2, 8px)',
+        3: 'var(--space-3, 12px)',
+        4: 'var(--space-4, 16px)',
+        5: 'var(--space-5, 20px)',
+        6: 'var(--space-6, 24px)',
+        7: 'var(--space-7, 28px)',
+        8: 'var(--space-8, 32px)',
+        9: 'var(--space-9, 36px)',
+        10: 'var(--space-10, 40px)',
+        11: 'var(--space-11, 44px)',
+        12: 'var(--space-12, 48px)',
+        // Component-intent spacing (codemod targets for padding-by-intent)
+        'card-sm': 'var(--card-padding-sm, 12px)',
+        'card-md': 'var(--card-padding-md, 16px)',
+        'card-lg': 'var(--card-padding-lg, 24px)',
+        'dialog': 'var(--dialog-padding, 24px)',
+        'section': 'var(--section-gap, 32px)',
+      },
+      // Type-axis size scale. Each step pairs a size with a line-height,
+      // both read from tokens with Tailwind-default fallbacks so existing
+      // `text-sm` resolves to the same 14px/20px until a theme overrides.
+      fontSize: {
+        xs: ['var(--text-xs, 12px)', { lineHeight: 'var(--leading-xs, 16px)' }],
+        sm: ['var(--text-sm, 14px)', { lineHeight: 'var(--leading-sm, 20px)' }],
+        base: ['var(--text-base, 16px)', { lineHeight: 'var(--leading-base, 24px)' }],
+        lg: ['var(--text-lg, 18px)', { lineHeight: 'var(--leading-lg, 28px)' }],
+        xl: ['var(--text-xl, 20px)', { lineHeight: 'var(--leading-xl, 28px)' }],
+        '2xl': ['var(--text-2xl, 24px)', { lineHeight: 'var(--leading-2xl, 32px)' }],
+        '3xl': ['var(--text-3xl, 30px)', { lineHeight: 'var(--leading-3xl, 36px)' }],
+        '4xl': ['var(--text-4xl, 36px)', { lineHeight: 'var(--leading-4xl, 40px)' }],
+        'display-1': ['var(--text-display-1, 48px)', { lineHeight: 'var(--leading-display-1, 52px)' }],
+        'display-2': ['var(--text-display-2, 60px)', { lineHeight: 'var(--leading-display-2, 64px)' }],
+      },
+      // Density-axis per-element heights (codemod targets for `h-{px}` on
+      // buttons / inputs / rows / icons).
+      height: {
+        'button-sm': 'var(--button-height-sm, 28px)',
+        'button-md': 'var(--button-height-md, 36px)',
+        'button-lg': 'var(--button-height-lg, 44px)',
+        'input-sm': 'var(--input-height-sm, 28px)',
+        'input-md': 'var(--input-height-md, 36px)',
+        'input-lg': 'var(--input-height-lg, 44px)',
+        'row-compact': 'var(--row-height-compact, 32px)',
+        'row-normal': 'var(--row-height-normal, 40px)',
+        'row-spacious': 'var(--row-height-spacious, 48px)',
+        'icon-default': 'var(--icon-default-size, 16px)',
+      },
+      minHeight: {
+        'button-sm': 'var(--button-height-sm, 28px)',
+        'button-md': 'var(--button-height-md, 36px)',
+        'button-lg': 'var(--button-height-lg, 44px)',
+        'input-sm': 'var(--input-height-sm, 28px)',
+        'input-md': 'var(--input-height-md, 36px)',
+        'input-lg': 'var(--input-height-lg, 44px)',
+        'row-compact': 'var(--row-height-compact, 32px)',
+        'row-normal': 'var(--row-height-normal, 40px)',
+        'row-spacious': 'var(--row-height-spacious, 48px)',
+      },
+      width: {
+        'icon-default': 'var(--icon-default-size, 16px)',
       },
+      // Geometry-axis radius rhythm (codemod targets for `rounded-*` by intent).
+      // The existing sm/md/lg/xl/full keys above continue to work as-is.
+      // Codemod converts `rounded-md` on Card → `rounded-container`, on Button → `rounded-interactive`, on Avatar/Badge → `rounded-pill`.
+      // borderRadius is extended below alongside the existing radius tokens.
+      // Elevation-axis per-layer shadow mapping.
+      // Codemod converts `shadow-sm` on Card → `shadow-elevation-card`, etc.
+      // boxShadow is extended below.
       // Container-query breakpoints aligned 1:1 with Tailwind's default
       // viewport breakpoints (sm 640 / md 768 / lg 1024 / xl 1280 /
       // 2xl 1536). Lets components use `@lg/foo:hidden` as a drop-in

package/themes/_contract.md

@@ -0,0 +1,198 @@
+# Theme CSS Variable Contract
+
+> Reference: `docs/Almadar_Std_Variations.md` §2 (Skin layer).
+> Type counterpart: `@almadar/core` exports `ThemeTokens` with typed sub-interfaces — `DensityTokens`, `TypeScaleTokens`, `MotionTokens`, `IconographyTokens`, `ElevationTokens`, `GeometryTokens`.
+> This file is **not loaded at runtime**. It is the authoritative reference both for theme authors and for the `_defaults.css` fallback layer in `themes/index.css`.
+
+CSS custom properties are the runtime source of truth — every `@almadar/ui` component reads from these variables via Tailwind utility classes (mapped in `tailwind-preset.cjs`). A theme that omits a variable inherits a deterministic fallback from the `:root` block declared in `themes/index.css`; the fallbacks are calibrated to preserve the visual baseline of the 18 pre-Layer-1 themes.
+
+A "truly unique" theme overrides variables across **all** axes below — not just `--color-*`. Two themes that diverge only on color will feel like the same product in two paint jobs.
+
+## Existing variables (preserved unchanged)
+
+These were defined by every pre-Layer-1 theme and continue to be the canonical paint surface. Backfill agents MUST NOT change existing values; they only append the new axis variables below.
+
+### Color
+`--color-primary`, `--color-primary-hover`, `--color-primary-foreground`,
+`--color-secondary`, `--color-secondary-hover`, `--color-secondary-foreground`,
+`--color-accent`, `--color-accent-foreground`,
+`--color-muted`, `--color-muted-foreground`,
+`--color-background`, `--color-foreground`,
+`--color-card`, `--color-card-foreground`,
+`--color-surface`, `--color-border`, `--color-input`, `--color-ring`,
+`--color-error`, `--color-error-foreground`,
+`--color-success`, `--color-success-foreground`,
+`--color-warning`, `--color-warning-foreground`,
+`--color-info`, `--color-info-foreground`.
+
+Optional table-specific (defined by some themes, fall back to neutrals when absent): `--color-table-header`, `--color-table-border`, `--color-table-row-hover`, `--color-surface-hover`, `--color-border-hover`, `--color-placeholder`.
+
+### Radius (existing — Geometry axis below adds intent overlay)
+`--radius-none`, `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`, `--radius-full`.
+
+### Border width (existing — Geometry axis adds intent overlay)
+`--border-width`, `--border-width-thin`, `--border-width-thick`.
+
+### Shadow (existing — Elevation axis adds intent overlay)
+`--shadow-none`, `--shadow-sm`, `--shadow-main`, `--shadow-lg`, `--shadow-inner`, `--shadow-hover`, `--shadow-active`.
+
+### Typography (existing — TypeScale axis adds family triplet + scale)
+`--font-family`, `--font-weight-normal`, `--font-weight-medium`, `--font-weight-bold`, `--line-height`, `--letter-spacing`.
+
+### Icon (existing — Iconography axis adds family selector)
+`--icon-stroke-width`, `--icon-color`.
+
+### Transitions (existing — Motion axis adds named palette)
+`--transition-fast`, `--transition-normal`, `--transition-slow`, `--transition-timing`.
+
+### Interaction (existing)
+`--hover-scale`, `--hover-translate-y`, `--hover-translate-x`,
+`--active-scale`, `--active-translate-y`,
+`--focus-ring-width`, `--focus-ring-offset`, `--focus-ring-color`.
+
+---
+
+## New variables (added in Layer 1)
+
+Every theme — backfilled or new — defines the variables below. The defaults column shows what the `_defaults.css` `:root` block declares; backfill agents copy these into each existing theme block so post-migration visual output stays identical. New-theme authors override per their personality brief.
+
+### Density axis — `--space-*` scale + per-element heights/paddings
+
+Spacing scale (12 steps; current Tailwind defaults shown to preserve `p-3 / p-4 / p-6` parity):
+
+| Variable | Default | Tailwind equivalent |
+|---|---|---|
+| `--space-0` | `0px` | `0` |
+| `--space-1` | `4px` | `1` |
+| `--space-2` | `8px` | `2` |
+| `--space-3` | `12px` | `3` |
+| `--space-4` | `16px` | `4` |
+| `--space-5` | `20px` | `5` |
+| `--space-6` | `24px` | `6` |
+| `--space-7` | `28px` | `7` |
+| `--space-8` | `32px` | `8` |
+| `--space-9` | `36px` | `9` |
+| `--space-10` | `40px` | `10` |
+| `--space-11` | `44px` | `11` |
+| `--space-12` | `48px` | `12` |
+
+Per-element heights:
+
+| Variable | Default | Used by |
+|---|---|---|
+| `--button-height-sm` | `28px` | Button size="sm" |
+| `--button-height-md` | `36px` | Button size="md" |
+| `--button-height-lg` | `44px` | Button size="lg" |
+| `--input-height-sm` | `28px` | Input size="sm" |
+| `--input-height-md` | `36px` | Input size="md" |
+| `--input-height-lg` | `44px` | Input size="lg" |
+| `--row-height-compact` | `32px` | Table dense rows |
+| `--row-height-normal` | `40px` | Table default rows |
+| `--row-height-spacious` | `48px` | Table comfortable rows |
+
+Per-element padding:
+
+| Variable | Default | Used by |
+|---|---|---|
+| `--card-padding-sm` | `12px` | Card padding="sm" (matches `p-3`) |
+| `--card-padding-md` | `16px` | Card padding="md" (matches `p-4`) |
+| `--card-padding-lg` | `24px` | Card padding="lg" (matches `p-6`) |
+| `--dialog-padding` | `24px` | Dialog body |
+| `--section-gap` | `32px` | Section-to-section vertical rhythm |
+
+### Type axis — family triplet + scale + intent mapping
+
+Family slots (the existing `--font-family` aliases to `--font-family-body` for backward compat):
+
+| Variable | Default |
+|---|---|
+| `--font-family-display` | `var(--font-family)` |
+| `--font-family-body` | `var(--font-family)` |
+| `--font-family-mono` | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace` |
+
+Size scale + paired line-heights (defaults match Tailwind's default `text-*` scale so existing `text-sm` resolves to identical px):
+
+| Size key | `--text-*` default | `--leading-*` default |
+|---|---|---|
+| `xs` | `12px` | `16px` |
+| `sm` | `14px` | `20px` |
+| `base` | `16px` | `24px` |
+| `lg` | `18px` | `28px` |
+| `xl` | `20px` | `28px` |
+| `2xl` | `24px` | `32px` |
+| `3xl` | `30px` | `36px` |
+| `4xl` | `36px` | `40px` |
+| `display-1` | `48px` | `52px` |
+| `display-2` | `60px` | `64px` |
+
+Intent mapping — three vars per intent (`size`, `weight`, `leading`). Defaults are calibrated against current component usage (Card title `text-lg` → `heading-major`; subtitle `text-sm` muted → `caption`):
+
+| Intent | `--intent-*-size` | `--intent-*-weight` | `--intent-*-leading` |
+|---|---|---|---|
+| `heading-major` | `var(--text-2xl)` | `var(--font-weight-bold)` | `var(--leading-2xl)` |
+| `heading-minor` | `var(--text-lg)` | `var(--font-weight-bold)` | `var(--leading-lg)` |
+| `body-emphasis` | `var(--text-base)` | `var(--font-weight-medium)` | `var(--leading-base)` |
+| `body-default` | `var(--text-sm)` | `var(--font-weight-normal)` | `var(--leading-sm)` |
+| `body-quiet` | `var(--text-sm)` | `var(--font-weight-normal)` | `var(--leading-sm)` |
+| `caption` | `var(--text-xs)` | `var(--font-weight-normal)` | `var(--leading-xs)` |
+| `numeric` | `var(--text-sm)` | `var(--font-weight-medium)` | `var(--leading-sm)` |
+
+### Motion axis — duration palette + easing palette
+
+Duration palette (existing `--transition-fast/normal/slow` alias to `--duration-fast/normal/slow`):
+
+| Variable | Default |
+|---|---|
+| `--duration-instant` | `0ms` |
+| `--duration-fast` | `var(--transition-fast)` |
+| `--duration-normal` | `var(--transition-normal)` |
+| `--duration-slow` | `var(--transition-slow)` |
+| `--duration-dramatic` | `600ms` |
+
+Easing palette (existing `--transition-timing` aliases to `--easing-standard`):
+
+| Variable | Default |
+|---|---|
+| `--easing-linear` | `linear` |
+| `--easing-standard` | `var(--transition-timing)` |
+| `--easing-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` |
+| `--easing-spring` | `cubic-bezier(0.34, 1.56, 0.64, 1)` |
+
+### Iconography axis
+
+| Variable | Default | Notes |
+|---|---|---|
+| `--icon-family` | `lucide` | String identifier consumed by the icon resolver. Values: `lucide` \| `phosphor-outline` \| `phosphor-fill` \| `phosphor-duotone` \| `tabler` \| `fa-solid`. |
+| `--icon-default-size` | `16px` | Default icon px size when component doesn't override. |
+
+`--icon-stroke-width` and `--icon-color` continue from the existing surface.
+
+### Elevation axis — per-layer mapping
+
+| Variable | Default |
+|---|---|
+| `--elevation-card` | `var(--shadow-sm)` |
+| `--elevation-popover` | `var(--shadow-main)` |
+| `--elevation-dialog` | `var(--shadow-lg)` |
+| `--elevation-toast` | `var(--shadow-main)` |
+
+### Geometry axis — radius rhythm + border-width rhythm with intent
+
+| Variable | Default |
+|---|---|
+| `--radius-container` | `var(--radius-md)` |
+| `--radius-interactive` | `var(--radius-md)` |
+| `--radius-pill` | `var(--radius-full)` |
+| `--border-hairline` | `1px` |
+| `--border-standard` | `var(--border-width)` |
+| `--border-heavy` | `var(--border-width-thick)` |
+
+---
+
+## Authoring rules
+
+1. **Backfill agents** (B1, B2, B3): copy the defaults above verbatim into each existing theme's light and dark blocks. Do not change any pre-existing variable. The migration must produce pixel-identical output to today for every pre-Layer-1 theme.
+2. **New-theme agents** (B4–B8): define every variable above. Pick values that express the personality brief — compact density, editorial type, sharp geometry, dramatic motion, filled iconography, etc. Defaults are NOT a fallback for new themes; new themes are the proof that the axis surface works.
+3. **No raw pixel literals in components**. All dimensional values flow through these tokens or through Tailwind utilities backed by them in `tailwind-preset.cjs`. Components that hardcode `text-[10px]` or `min-w-[44px]` are migration targets.
+4. **Icon family swap is runtime-resolved**. `--icon-family` is read by the icon resolver in `@almadar/ui`; setting the variable in a theme does not require component edits.
+5. **Wireframe and trait-wars exceptions**. Wireframe's `--easing-standard` is `linear` not the default cubic-bezier; trait-wars's iconography may remain `lucide` even if its visual personality diverges. Document any per-theme override at the top of the theme file.

package/themes/almadar-website.css

@@ -97,6 +97,112 @@
     --focus-ring-width: 2px;
     --focus-ring-offset: 2px;
     --focus-ring-color: #14b8a6;
+
+    /* Layer 1 — backfill (preserves current visual output, see themes/_contract.md) */
+    /* Density axis — spacing scale */
+    --space-0: 0px;
+    --space-1: 4px;
+    --space-2: 8px;
+    --space-3: 12px;
+    --space-4: 16px;
+    --space-5: 20px;
+    --space-6: 24px;
+    --space-7: 28px;
+    --space-8: 32px;
+    --space-9: 36px;
+    --space-10: 40px;
+    --space-11: 44px;
+    --space-12: 48px;
+    /* Density axis — per-element heights */
+    --button-height-sm: 28px;
+    --button-height-md: 36px;
+    --button-height-lg: 44px;
+    --input-height-sm: 28px;
+    --input-height-md: 36px;
+    --input-height-lg: 44px;
+    --row-height-compact: 32px;
+    --row-height-normal: 40px;
+    --row-height-spacious: 48px;
+    /* Density axis — per-element padding */
+    --card-padding-sm: 12px;
+    --card-padding-md: 16px;
+    --card-padding-lg: 24px;
+    --dialog-padding: 24px;
+    --section-gap: 32px;
+    /* Type axis — family triplet (aliases existing --font-family for backward compat) */
+    --font-family-display: var(--font-family);
+    --font-family-body: var(--font-family);
+    --font-family-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    /* Type axis — size scale */
+    --text-xs: 12px;
+    --leading-xs: 16px;
+    --text-sm: 14px;
+    --leading-sm: 20px;
+    --text-base: 16px;
+    --leading-base: 24px;
+    --text-lg: 18px;
+    --leading-lg: 28px;
+    --text-xl: 20px;
+    --leading-xl: 28px;
+    --text-2xl: 24px;
+    --leading-2xl: 32px;
+    --text-3xl: 30px;
+    --leading-3xl: 36px;
+    --text-4xl: 36px;
+    --leading-4xl: 40px;
+    --text-display-1: 48px;
+    --leading-display-1: 52px;
+    --text-display-2: 60px;
+    --leading-display-2: 64px;
+    /* Type axis — intent mapping (calibrated to existing component usage) */
+    --intent-heading-major-size: var(--text-2xl);
+    --intent-heading-major-weight: var(--font-weight-bold);
+    --intent-heading-major-leading: var(--leading-2xl);
+    --intent-heading-minor-size: var(--text-lg);
+    --intent-heading-minor-weight: var(--font-weight-bold);
+    --intent-heading-minor-leading: var(--leading-lg);
+    --intent-body-emphasis-size: var(--text-base);
+    --intent-body-emphasis-weight: var(--font-weight-medium);
+    --intent-body-emphasis-leading: var(--leading-base);
+    --intent-body-default-size: var(--text-sm);
+    --intent-body-default-weight: var(--font-weight-normal);
+    --intent-body-default-leading: var(--leading-sm);
+    --intent-body-quiet-size: var(--text-sm);
+    --intent-body-quiet-weight: var(--font-weight-normal);
+    --intent-body-quiet-leading: var(--leading-sm);
+    --intent-caption-size: var(--text-xs);
+    --intent-caption-weight: var(--font-weight-normal);
+    --intent-caption-leading: var(--leading-xs);
+    --intent-numeric-size: var(--text-sm);
+    --intent-numeric-weight: var(--font-weight-medium);
+    --intent-numeric-leading: var(--leading-sm);
+    /* Motion axis — duration palette (aliases existing --transition-* for backward compat) */
+    --duration-instant: 0ms;
+    --duration-fast: var(--transition-fast);
+    --duration-normal: var(--transition-normal);
+    --duration-slow: var(--transition-slow);
+    --duration-dramatic: 600ms;
+    /* Motion axis — easing palette (aliases existing --transition-timing for backward compat) */
+    --easing-linear: linear;
+    --easing-standard: var(--transition-timing);
+    --easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
+    --easing-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+    /* Iconography axis */
+    --icon-family: lucide;
+    --icon-default-size: 16px;
+    /* Elevation axis — per-layer mapping */
+    --elevation-card: var(--shadow-sm);
+    --elevation-popover: var(--shadow-main);
+    --elevation-dialog: var(--shadow-lg);
+    --elevation-toast: var(--shadow-main);
+    /* Geometry axis — radius rhythm with intent */
+    --radius-container: var(--radius-md);
+    --radius-interactive: var(--radius-md);
+    --radius-pill: var(--radius-full);
+    /* Geometry axis — border-width rhythm */
+    --border-hairline: 1px;
+    --border-standard: var(--border-width);
+    --border-heavy: var(--border-width-thick);
 }
 
 /* ==========================================================================
@@ -194,4 +300,110 @@
     --focus-ring-width: 2px;
     --focus-ring-offset: 2px;
     --focus-ring-color: #14b8a6;
+
+    /* Layer 1 — backfill (preserves current visual output, see themes/_contract.md) */
+    /* Density axis — spacing scale */
+    --space-0: 0px;
+    --space-1: 4px;
+    --space-2: 8px;
+    --space-3: 12px;
+    --space-4: 16px;
+    --space-5: 20px;
+    --space-6: 24px;
+    --space-7: 28px;
+    --space-8: 32px;
+    --space-9: 36px;
+    --space-10: 40px;
+    --space-11: 44px;
+    --space-12: 48px;
+    /* Density axis — per-element heights */
+    --button-height-sm: 28px;
+    --button-height-md: 36px;
+    --button-height-lg: 44px;
+    --input-height-sm: 28px;
+    --input-height-md: 36px;
+    --input-height-lg: 44px;
+    --row-height-compact: 32px;
+    --row-height-normal: 40px;
+    --row-height-spacious: 48px;
+    /* Density axis — per-element padding */
+    --card-padding-sm: 12px;
+    --card-padding-md: 16px;
+    --card-padding-lg: 24px;
+    --dialog-padding: 24px;
+    --section-gap: 32px;
+    /* Type axis — family triplet (aliases existing --font-family for backward compat) */
+    --font-family-display: var(--font-family);
+    --font-family-body: var(--font-family);
+    --font-family-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+    /* Type axis — size scale */
+    --text-xs: 12px;
+    --leading-xs: 16px;
+    --text-sm: 14px;
+    --leading-sm: 20px;
+    --text-base: 16px;
+    --leading-base: 24px;
+    --text-lg: 18px;
+    --leading-lg: 28px;
+    --text-xl: 20px;
+    --leading-xl: 28px;
+    --text-2xl: 24px;
+    --leading-2xl: 32px;
+    --text-3xl: 30px;
+    --leading-3xl: 36px;
+    --text-4xl: 36px;
+    --leading-4xl: 40px;
+    --text-display-1: 48px;
+    --leading-display-1: 52px;
+    --text-display-2: 60px;
+    --leading-display-2: 64px;
+    /* Type axis — intent mapping (calibrated to existing component usage) */
+    --intent-heading-major-size: var(--text-2xl);
+    --intent-heading-major-weight: var(--font-weight-bold);
+    --intent-heading-major-leading: var(--leading-2xl);
+    --intent-heading-minor-size: var(--text-lg);
+    --intent-heading-minor-weight: var(--font-weight-bold);
+    --intent-heading-minor-leading: var(--leading-lg);
+    --intent-body-emphasis-size: var(--text-base);
+    --intent-body-emphasis-weight: var(--font-weight-medium);
+    --intent-body-emphasis-leading: var(--leading-base);
+    --intent-body-default-size: var(--text-sm);
+    --intent-body-default-weight: var(--font-weight-normal);
+    --intent-body-default-leading: var(--leading-sm);
+    --intent-body-quiet-size: var(--text-sm);
+    --intent-body-quiet-weight: var(--font-weight-normal);
+    --intent-body-quiet-leading: var(--leading-sm);
+    --intent-caption-size: var(--text-xs);
+    --intent-caption-weight: var(--font-weight-normal);
+    --intent-caption-leading: var(--leading-xs);
+    --intent-numeric-size: var(--text-sm);
+    --intent-numeric-weight: var(--font-weight-medium);
+    --intent-numeric-leading: var(--leading-sm);
+    /* Motion axis — duration palette (aliases existing --transition-* for backward compat) */
+    --duration-instant: 0ms;
+    --duration-fast: var(--transition-fast);
+    --duration-normal: var(--transition-normal);
+    --duration-slow: var(--transition-slow);
+    --duration-dramatic: 600ms;
+    /* Motion axis — easing palette (aliases existing --transition-timing for backward compat) */
+    --easing-linear: linear;
+    --easing-standard: var(--transition-timing);
+    --easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
+    --easing-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+    /* Iconography axis */
+    --icon-family: lucide;
+    --icon-default-size: 16px;
+    /* Elevation axis — per-layer mapping */
+    --elevation-card: var(--shadow-sm);
+    --elevation-popover: var(--shadow-main);
+    --elevation-dialog: var(--shadow-lg);
+    --elevation-toast: var(--shadow-main);
+    /* Geometry axis — radius rhythm with intent */
+    --radius-container: var(--radius-md);
+    --radius-interactive: var(--radius-md);
+    --radius-pill: var(--radius-full);
+    /* Geometry axis — border-width rhythm */
+    --border-hairline: 1px;
+    --border-standard: var(--border-width);
+    --border-heavy: var(--border-width-thick);
 }