@dxos/ui-theme 0.9.0 → 0.9.1-staging.ee54ba693a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/ui-theme",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "A set of design system tokens to use with DXOS UI.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -48,21 +48,22 @@
     "postcss-nesting": "^13.0.1",
     "tailwind-merge": "^3.5.0",
     "tailwind-scrollbar": "^4.0.0",
+    "tailwind-variants": "^3.2.2",
     "tailwindcss": "^4.3.0",
     "tailwindcss-radix": "^4.0.2",
-    "@dxos/log": "0.9.0",
-    "@dxos/util": "0.9.0",
-    "@dxos/node-std": "0.9.0"
+    "@dxos/log": "0.9.1-staging.ee54ba693a",
+    "@dxos/node-std": "0.9.1-staging.ee54ba693a",
+    "@dxos/util": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
     "@types/lodash.merge": "^4.6.6",
     "@types/postcss-import": "^14.0.3",
-    "esbuild": "0.28.0",
+    "esbuild": "0.28.1",
     "vite": "^8.0.16",
-    "@dxos/ui-types": "0.9.0"
+    "@dxos/ui-types": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
-    "react": "~19.2.3"
+    "react": "~19.2.7"
   },
   "publishConfig": {
     "access": "public"

package/src/Theme.stories.tsx

@@ -5,7 +5,7 @@
 import { type Meta } from '@storybook/react-vite';
 import React, { useLayoutEffect, useRef, useState } from 'react';
 
-import { hueShades, hues } from './defs';
+import { hues, hueShades } from './defs';
 import { mx } from './util';
 
 // prettier-ignore

package/src/css/components/button.css

@@ -18,9 +18,15 @@
       color: var(--dx-valence-text, inherit);
       background: var(--dx-valence-bg, var(--color-input-bg));
     }
+    /* Toggle / tab group: the selected item reads as standard text on a surface-relative fill (selected-surface
+     * tracks the enclosing --surface-bg, so it stays visible on any surface); unselected items recede to subdued. */
     &[aria-pressed='true'],
     &[aria-checked='true'] {
-      @apply text-accent-text bg-attention-surface;
+      @apply text-base-fg bg-selected-surface;
+    }
+    &[aria-pressed='false'],
+    &[aria-checked='false'] {
+      @apply text-description;
     }
 
     /* Disabled styles */
@@ -32,14 +38,9 @@
     &[data-variant='ghost'] {
       @apply bg-transparent;
       &:hover {
-        /* Tint relative to the host surface (--surface-bg, set by the enclosing dx-*-surface zone)
-         * so the hover reads correctly on any background: darker in light mode, lighter in dark.
-         * Falls back to base-surface when no surface zone is in scope. */
-        background: light-dark(
-          oklch(from var(--surface-bg, var(--color-base-surface)) calc(l - 0.05) c h),
-          oklch(from var(--surface-bg, var(--color-base-surface)) calc(l + 0.05) c h)
-        );
-        @apply text-inherit;
+        /* Shares the surface-derived control hover (--color-hover-surface tracks the enclosing
+         * --surface-bg) so every variant tints consistently on any background. */
+        @apply bg-hover-surface text-inherit;
       }
       &[data-state='open'] {
         @apply bg-input-bg;

package/src/css/components/state.css

@@ -19,12 +19,12 @@
    */
   .dx-hover {
     @apply cursor-pointer
-      hover:bg-hover-surface! hover:text-hover-fg!
+      hover:bg-hover-surface-subtle! hover:text-hover-fg!
       hover:aria-selected:bg-selected-surface-hover hover:aria-selected:text-selected-fg
       hover:aria-[current=true]:bg-current-surface-hover hover:aria-[current=true]:text-current-fg;
   }
   .dx-hover-row {
-    @apply group-hover/row:bg-hover-surface! group-hover/row:text-hover-fg!
+    @apply group-hover/row:bg-hover-surface-subtle! group-hover/row:text-hover-fg!
       group-hover/row:group-aria-selected/row:bg-selected-surface-hover!
       group-hover/row:group-aria-selected/row:text-selected-fg!
       group-hover/row:group-aria-[current=true]/row:bg-current-surface-hover!
@@ -74,26 +74,3 @@
       hover:data-[highlighted]:bg-current-surface-hover;
   }
 }
-
-@layer dx-tokens {
-  /*
-   * Sidebars sit on a different surface than the main content, so nudge the state highlights to
-   * keep contrast: offset each token off its `*-base` (see semantic.css) — darker in light mode,
-   * lighter in dark. Tune the magnitude via --dx-sidebar-l-shift.
-   */
-  .dx-main-sidebar {
-    --dx-sidebar-l-shift: 0.04;
-    --color-hover-surface: light-dark(
-      oklch(from var(--dx-hover-surface-base) calc(l - var(--dx-sidebar-l-shift)) c h),
-      oklch(from var(--dx-hover-surface-base) calc(l + var(--dx-sidebar-l-shift)) c h)
-    );
-    --color-current-surface: light-dark(
-      oklch(from var(--dx-current-surface-base) calc(l - var(--dx-sidebar-l-shift)) c h),
-      oklch(from var(--dx-current-surface-base) calc(l + var(--dx-sidebar-l-shift)) c h)
-    );
-    --color-current-surface-hover: light-dark(
-      oklch(from var(--dx-current-surface-hover-base) calc(l - var(--dx-sidebar-l-shift)) c h),
-      oklch(from var(--dx-current-surface-hover-base) calc(l + var(--dx-sidebar-l-shift)) c h)
-    );
-  }
-}

package/src/css/components/surface.css

@@ -1,5 +1,13 @@
 /**
  * Surfaces
+ *
+ * A surface zone paints a background AND publishes its colour as `--surface-bg`, so descendant
+ * controls can derive a visible hover/current highlight from the actual surface (see the
+ * derivation block below) and surface-matching elements (avatars, gradients) can read it directly.
+ *
+ * Always enter a surface via one of these `dx-*-surface` classes. A bare `bg-*-surface` utility
+ * paints the colour but does NOT publish `--surface-bg`, so control hover collapses onto the
+ * base-surface fallback and can become invisible when the surface shares that elevation.
  */
 
 @layer dx-components {
@@ -8,42 +16,87 @@
     --surface-bg: var(--color-base-surface);
   }
 
+  .dx-deck-surface {
+    @apply bg-deck-surface text-base-fg;
+    --surface-bg: var(--color-deck-surface);
+  }
+
   .dx-sidebar-surface {
     @apply bg-sidebar-surface text-base-fg;
     --surface-bg: var(--color-sidebar-surface);
   }
 
+  .dx-header-surface {
+    @apply bg-header-surface text-base-fg;
+    --surface-bg: var(--color-header-surface);
+  }
+
+  .dx-card-surface {
+    @apply bg-card-surface text-base-fg;
+    --surface-bg: var(--color-card-surface);
+  }
+
+  .dx-group-surface {
+    @apply bg-group-surface text-base-fg;
+    --surface-bg: var(--color-group-surface);
+  }
+
+  .dx-input-surface {
+    @apply bg-input-surface text-base-fg;
+    --surface-bg: var(--color-input-surface);
+  }
+
+  .dx-toolbar-surface {
+    @apply bg-toolbar-surface text-base-fg;
+    --surface-bg: var(--color-toolbar-surface);
+  }
+
   .dx-modal-surface {
     @apply bg-modal-surface text-base-fg backdrop-blur-md;
     --surface-bg: var(--color-modal-surface);
   }
 
-  .dx-attention-surface {
-    @apply bg-attention-surface text-base-fg;
-    --surface-bg: var(--color-attention-surface);
-  }
-
   .dx-popover-surface {
     @apply bg-popover-surface text-base-fg backdrop-blur-md;
     --surface-bg: var(--color-popover-surface);
   }
+
+  .dx-attention-surface {
+    @apply bg-attention-surface text-base-fg;
+    --surface-bg: var(--color-attention-surface);
+  }
 }
 
 @layer dx-tokens {
   /*
-   * Elevated surfaces (modal, popover) sit higher than the hover/current base tokens, so the
-   * un-offset state colours collide with the surface itself (e.g. in dark mode the popover surface
-   * and hover surface are both neutral-750 → the highlight is invisible). Re-derive the state
-   * colours off the actual surface (--surface-bg) via relative oklch — darker in light mode,
-   * lighter in dark — so highlights stay visible regardless of how the surface tokens are tuned.
-   * Mirrors the .dx-main-sidebar offset in state.css.
+   * Re-derive the state colours (hover, current, selected) off the host surface for every context
+   * that publishes its own --surface-bg. Custom-property substitution runs once per scope, so the
+   * formula must be repeated here (it cannot simply inherit from semantic.css, which resolved it
+   * against the root surface). Listing all surface zones in one block keeps the offsets identical
+   * across surfaces — there is no per-surface divergence to tune.
+   *
+   * Magnitudes mirror semantic.css; selected-* track current-* via the aliases declared there.
    */
+  .dx-base-surface,
+  .dx-deck-surface,
+  .dx-sidebar-surface,
+  .dx-header-surface,
+  .dx-card-surface,
+  .dx-group-surface,
+  .dx-input-surface,
+  .dx-toolbar-surface,
   .dx-modal-surface,
-  .dx-popover-surface {
+  .dx-popover-surface,
+  .dx-attention-surface,
+  .dx-main-sidebar {
     --color-hover-surface: light-dark(
       oklch(from var(--surface-bg) calc(l - 0.08) c h),
       oklch(from var(--surface-bg) calc(l + 0.08) c h)
     );
+    --color-hover-surface-subtle: light-dark(
+      oklch(from var(--surface-bg) calc(l - 0.02) c h),
+      oklch(from var(--surface-bg) calc(l + 0.02) c h)
+    );
     --color-current-surface: light-dark(
       oklch(from var(--surface-bg) calc(l - 0.1) c h),
       oklch(from var(--surface-bg) calc(l + 0.1) c h)

package/src/css/components/tag.css

@@ -11,9 +11,9 @@
 
   .dx-tag--anchor {
     /* NOTE: Margin offsets padding so that border is flush with text. This should only apply to anchor tags inside of Codemirror. */
-    @apply inline cursor-pointer px-[4px] py-0.5;
+    @apply inline-block cursor-pointer px-[4px] py-0.5;
     /** TODO(burdon): Configure secondary color. */
-    @apply bg-input-surface ring ring-neutral-border rounded-sm;
+    @apply bg-input-surface ring-inset ring ring-neutral-border rounded-sm;
     &:hover {
       @apply bg-hover-surface;
     }

package/src/css/layout/size.css

@@ -64,7 +64,7 @@
   }
 
   .dx-card-popover {
-    @apply inline-card-max-width bg-card-surface;
+    @apply inline-card-max-width bg-popover-surface;
     max-width: min(var(--radix-popper-available-width), var(--spacing-card-max-width));
     max-height: min(var(--radix-popper-available-height), var(--spacing-card-max-height));
   }

package/src/css/theme/semantic.css

@@ -13,95 +13,180 @@
    * Elevation ladder — strictly monotonic, z-order low → high.
    * Dark: darker = lower. Light: lighter = higher (inverted toward white).
    *
-   * Level  Name    Roles
-   *   0    void    window gaps, scrim base
-   *   1    rail    L0 icon rail
-   *   2    chrome  L1/R sidebars, header
-   *   3    canvas  base, deck
-   *   4    raised  card, group, input
-   *   5    bar     toolbar (sticky, drop-shadowed)
-   *   6    modal   dialog, modal, popover
-   *   7    float   menu, toast, tooltip
+   * Level  Name     Roles
+   *   0    void     deck, scrim base
+   *   1    base     base content, L0 icon rail
+   *   2    chrome   L1/R sidebars, header
+   *   3    card     card
+   *   4    raised   group, input, focus/attention
+   *   5    bar      dialog/modal, toolbar (sticky, drop-shadowed)
+   *   6    modal    popover, menu, toast, tooltip
+   *   7    float    
    *
    * These are private (--dx-*) knobs — use named surface tokens in components, not these directly.
    */
   --dx-elevation-0: light-dark(var(--color-neutral-300), var(--color-neutral-950));
-  --dx-elevation-1: light-dark(var(--color-neutral-200), var(--color-neutral-900));
-  --dx-elevation-2: light-dark(var(--color-neutral-125), var(--color-neutral-875));
-  --dx-elevation-3: light-dark(var(--color-neutral-125), var(--color-neutral-850));
-  --dx-elevation-4: light-dark(var(--color-neutral-100), var(--color-neutral-825));
-  --dx-elevation-5: light-dark(var(--color-neutral-75), var(--color-neutral-800));
-  --dx-elevation-6: light-dark(var(--color-neutral-50), var(--color-neutral-775));
-  --dx-elevation-7: light-dark(white, var(--color-neutral-750));
-
-  /* Surfaces — each maps to exactly one elevation level */
-  --color-sidebar-surface: var(--dx-elevation-2);
-  --color-header-surface: var(--dx-elevation-2);
-  --color-deck-surface: var(--dx-elevation-3);
-  --color-base-surface: var(--dx-elevation-3);
-  --color-card-surface: var(--dx-elevation-3);
-  --color-group-surface: var(--dx-elevation-4);
-  /* Subtle alternate of group-surface for zebra striping (e.g. calendar months) — offset off
-   * elevation-4 via relative oklch so it tracks the ramp: darker in light mode, lighter in dark. */
-  --color-group-alt-surface: light-dark(
-    oklch(from var(--dx-elevation-4) calc(l - 0.03) c h),
-    oklch(from var(--dx-elevation-4) calc(l + 0.03) c h)
-  );
-  --color-input-surface: var(--dx-elevation-4);
-  --color-toolbar-surface: var(--dx-elevation-5);
-  --color-modal-surface: var(--dx-elevation-6);
-  --color-popover-surface: var(--dx-elevation-6);
+  --dx-elevation-1: light-dark(var(--color-neutral-300), var(--color-neutral-925));
+  --dx-elevation-2: light-dark(var(--color-neutral-200), var(--color-neutral-900));
+  --dx-elevation-3: light-dark(var(--color-neutral-125), var(--color-neutral-875));
+  --dx-elevation-4: light-dark(var(--color-neutral-125), var(--color-neutral-850));
+  --dx-elevation-5: light-dark(var(--color-neutral-100), var(--color-neutral-825));
+  --dx-elevation-6: light-dark(var(--color-neutral-75), var(--color-neutral-800));
+  --dx-elevation-7: light-dark(var(--color-neutral-50), var(--color-neutral-775));
+  --dx-elevation-8: light-dark(white, var(--color-neutral-750));
+
+  /** 
+   * Elevation 0
+   */
 
-  /* Sidebar / panel layout levels */
-  --color-l0-surface: var(--dx-elevation-1);
-  --color-l1-surface: var(--dx-elevation-2);
-  --color-r0-surface: var(--dx-elevation-2);
-  --color-r1-surface: var(--dx-elevation-2);
+  --color-deck-surface: var(--dx-elevation-0);
 
+  /* Translucent dimming layer; tracks the lowest elevation (void) rather than a raw neutral. */
   --color-scrim-surface: light-dark(
-    oklch(from var(--color-neutral-50) l c h / 0.5),
-    oklch(from var(--color-neutral-950) l c h / 0.25)
+    oklch(from var(--dx-elevation-0) l c h / 0.5),
+    oklch(from var(--dx-elevation-0) l c h / 0.25)
   );
 
-  --color-inverse-surface: light-dark(var(--color-neutral-800), var(--color-neutral-200));
-  --color-inverse-fg: light-dark(var(--color-neutral-50), var(--color-neutral-950));
+  /** 
+   * Elevation 1
+   */
 
+  --color-card-surface: var(--dx-elevation-1);
+
+  /** 
+   * Elevation 2
+   */
+
+  --color-base-surface: var(--dx-elevation-2);
   --color-base-fg: light-dark(var(--color-neutral-950), var(--color-neutral-150));
 
+  /* Map attention to focus-surface logic so that elements acting as active attention zones highlight correctly on focus. */
+  --color-attention-surface: var(--dx-elevation-2);
+  --color-attention-contains: oklch(from var(--color-accent-bg) l c h / 0.3);
+
+  /**
+   * Elevation 3
+   */
+
+  --color-header-surface: var(--dx-elevation-3);
+
+  --color-sidebar-surface: var(--dx-elevation-3);
   /* Sidebar body text. Default sits one ramp stop below the current/selected emphasis. */
   --color-sidebar-fg: light-dark(var(--color-neutral-700), var(--color-neutral-250));
   --color-sidebar-current-fg: light-dark(var(--color-neutral-950), var(--color-neutral-75));
 
-  /* Focus */
-  --color-focus-surface: light-dark(var(--color-neutral-50), var(--color-neutral-850));
+  /* Sidebar / panel layout levels */
+  --color-l0-surface: var(--dx-elevation-2);
+  --color-l1-surface: var(--dx-elevation-3);
+  --color-r0-surface: var(--dx-elevation-3);
+  --color-r1-surface: var(--dx-elevation-3);
+
+  /** 
+   * Elevation 4
+   */
+
+  --color-toolbar-surface: var(--dx-elevation-4);
+
+  /** 
+   * Elevation 5
+   */
+
+  /* Focus — a raised content surface (one level above card) so an attended pane reads as lifted. */
+  --color-focus-surface: var(--dx-elevation-5);
   --color-focus-ring: light-dark(var(--color-blue-400), var(--color-blue-600));
   --color-focus-ring-subtle: light-dark(var(--color-neutral-300), var(--color-neutral-600));
 
-  /* Map attention to focus-surface logic so that elements acting as active attention zones highlight correctly on focus. */
-  --color-attention-surface: var(--color-focus-surface);
-  --color-attention-contains: oklch(from var(--color-accent-bg) l c h / 0.3);
+  --color-group-surface: var(--dx-elevation-5);
+  /* Subtle alternate of group-surface for zebra striping (e.g. calendar months) — offset off
+   * elevation-4 via relative oklch so it tracks the ramp: darker in light mode, lighter in dark. */
+  --color-group-alt-surface: light-dark(
+    oklch(from var(--dx-elevation-5) calc(l - 0.03) c h),
+    oklch(from var(--dx-elevation-5) calc(l + 0.03) c h)
+  );
 
-  /* input */
+  --color-input-surface: var(--dx-elevation-5);
+
+  /**
+   * Elevation 6
+   */
+
+  --color-modal-surface: var(--dx-elevation-6);
+
+  /**
+   * Elevation 7
+   */
+
+  --color-popover-surface: var(--dx-elevation-7);
+
+  /**
+   * Elevation 8
+   */
+
+  /**
+   * Misc
+   */
+
+  --color-inverse-surface: light-dark(var(--color-neutral-800), var(--color-neutral-200));
+  --color-inverse-fg: light-dark(var(--color-neutral-50), var(--color-neutral-950));
+
+  /*
+   * Text emphasis — foregrounds at decreasing emphasis, anchored on --color-base-fg (strongest):
+   *   base-fg → description → subdued → placeholder (weakest).
+   * Tuned for legibility against the surfaces rather than mapped to the elevation ladder (which
+   * governs backgrounds, not text contrast), so these stay explicit neutrals.
+   */
+  --color-description: light-dark(var(--color-neutral-600), var(--color-neutral-400));
+  --color-subdued: light-dark(var(--color-neutral-500), var(--color-neutral-600));
+  --color-placeholder: light-dark(var(--color-neutral-400), var(--color-neutral-600));
+
+  /*
+   * Controls — the input/control fill is a deliberate off-ladder token (cf. the grid "paper"
+   * surfaces). It backs text inputs and the default/ghost button (bg-input-bg) and must contrast
+   * whatever surface it sits on: a subtle inset well in light mode, a raised fill in dark mode that
+   * reads lighter than the topmost surface. Do not map it to an elevation level.
+   */
   --color-input-bg: light-dark(var(--color-neutral-250), var(--color-neutral-700));
-  --color-input-fg: light-dark(var(--color-neutral-950), var(--color-neutral-150));
+  --color-input-fg: var(--color-base-fg);
 
-  /* 
-   * hover (:hover, data-highlighted)
-   * `*-base` primitives are the un-offset values; 
-   * surface contexts (e.g. .dx-main-sidebar in state.css) re-derive the public token off the base via relative oklch. 
+  /*
+   * State surfaces (hover, current, selected) are derived from the host surface (--surface-bg) via
+   * relative oklch — darker in light mode, lighter in dark — so a highlight stays visible at any
+   * elevation. The values here resolve against the root --surface-bg (= base-surface, set in
+   * base.css), giving the correct default for content outside any surface zone. Surface zones
+   * publish their own --surface-bg and re-derive these tokens in surface.css, which is where the
+   * substitution re-runs for that subtree.
+   *
+   * Offset magnitudes (lightness): hover ∓0.08, subtle ∓0.02, current ∓0.10, current-hover ∓0.12.
+   * Keep these in sync with the per-zone re-derivation in components/surface.css.
    */
-  --dx-hover-surface-base: light-dark(var(--color-neutral-200), var(--color-neutral-850));
-  --color-hover-surface: var(--dx-hover-surface-base);
+  --color-hover-surface: light-dark(
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l - 0.08) c h),
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l + 0.08) c h)
+  );
   --color-hover-fg: light-dark(var(--color-neutral-950), var(--color-neutral-150));
 
+  /*
+   * Subtle region hover for large highlight targets (list rows, tiles) where the full
+   * control-strength hover reads as too heavy. Consumed by `.dx-hover` / `.dx-hover-row`;
+   * controls (buttons) keep --color-hover-surface.
+   */
+  --color-hover-surface-subtle: light-dark(
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l - 0.02) c h),
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l + 0.02) c h)
+  );
+
   /* current (aria-current) */
-  --dx-current-surface-base: light-dark(var(--color-neutral-150), var(--color-neutral-800));
-  --dx-current-surface-hover-base: light-dark(var(--color-neutral-150), var(--color-neutral-600));
-  --color-current-surface: var(--dx-current-surface-base);
-  --color-current-surface-hover: var(--dx-current-surface-hover-base);
+  --color-current-surface: light-dark(
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l - 0.1) c h),
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l + 0.1) c h)
+  );
+  --color-current-surface-hover: light-dark(
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l - 0.12) c h),
+    oklch(from var(--surface-bg, var(--color-base-surface)) calc(l + 0.12) c h)
+  );
   --color-current-fg: light-dark(var(--color-neutral-950), var(--color-neutral-50));
 
-  /* selected (aria-selected) */
+  /* selected (aria-selected) tracks current */
   --color-selected-surface: var(--color-current-surface);
   --color-selected-surface-hover: var(--color-current-surface-hover);
   --color-selected-fg: var(--color-current-fg);
@@ -113,13 +198,15 @@
   --color-accent-text: light-dark(var(--color-blue-600), var(--color-blue-400));
   --color-accent-text-hover: light-dark(var(--color-blue-500), var(--color-blue-500));
 
+  /* Unaccented */
   --color-un-accent: var(--color-neutral-400);
   --color-un-accent-hover: var(--color-neutral-500);
 
   /* Separator */
-  --color-primary-separator: light-dark(var(--color-neutral-300), var(--color-neutral-700));
+  --color-primary-separator: light-dark(var(--color-neutral-200), var(--color-neutral-800));
   --color-separator: light-dark(var(--color-neutral-200), var(--color-neutral-700));
-  --color-subdued-separator: light-dark(var(--color-neutral-250), var(--color-neutral-750));
+  --color-input-separator: light-dark(var(--color-neutral-250), var(--color-neutral-750));
+  --color-subdued-separator: light-dark(var(--color-neutral-250), var(--color-neutral-775));
   --color-active-separator: light-dark(var(--color-blue-500), var(--color-blue-500));
 
   /* Scrollbar */
@@ -128,16 +215,21 @@
   --color-scrollbar-thumb-active: light-dark(var(--color-neutral-200), var(--color-neutral-600));
   --color-scrollbar-thumb-hover: light-dark(var(--color-neutral-200), var(--color-neutral-600));
 
-  /* Sheet */
-  --color-axis-selected-surface: light-dark(var(--color-neutral-100), var(--color-neutral-900));
-  --color-axis-selected-text: light-dark(var(--color-neutral-100), var(--color-neutral-900));
-  --color-axis-surface: light-dark(var(--color-neutral-50), var(--color-neutral-800));
-  --color-axis-text: light-dark(var(--color-neutral-800), var(--color-neutral-200));
-
   /*
-   * Grid
+   * Sheet / Grid — intentionally OFF the elevation ladder.
    * NOTE: Update main.css when changing grid tokens (and restart dev server).
+   *
+   * These are "paper" surfaces for the data grid: maximum-contrast canvases (near-white in light,
+   * near-black in dark) plus saturated selection/comment accents. The elevation ladder is
+   * monotonic (light: lighter = higher), so it cannot express a surface that is simultaneously the
+   * lightest in light mode and the darkest in dark mode. Keep these as explicit neutrals/accents;
+   * do not fold them into --dx-elevation-*.
    */
+  --color-axis-surface: light-dark(var(--color-neutral-100), var(--color-neutral-900));
+  --color-axis-text: light-dark(var(--color-neutral-700), var(--color-neutral-300));
+  --color-axis-selected-surface: light-dark(var(--color-neutral-100), var(--color-neutral-900));
+  --color-axis-selected-text: light-dark(var(--color-neutral-100), var(--color-neutral-900));
+
   --color-grid-surface: light-dark(var(--color-neutral-50), var(--color-neutral-950));
   --color-grid-fg: light-dark(var(--color-neutral-950), var(--color-neutral-50));
   --color-grid-line: light-dark(var(--color-neutral-200), var(--color-neutral-800));
@@ -149,9 +241,4 @@
     oklch(from var(--color-green-400) l c h / 0.5),
     oklch(from var(--color-green-600) l c h / 0.5)
   );
-
-  /* Text */
-  --color-placeholder: light-dark(var(--color-neutral-400), var(--color-neutral-600));
-  --color-subdued: light-dark(var(--color-neutral-500), var(--color-neutral-600));
-  --color-description: light-dark(var(--color-neutral-600), var(--color-neutral-400));
 }

package/src/css/theme/spacing.css

@@ -31,7 +31,7 @@
   /** Minimal trim to allow for ring/outline. */
   --spacing-form-chrome: var(--spacing-trim-xs);
   --spacing-form-gap: var(--spacing-trim-sm);
-  --spacing-form-section-gap: var(--spacing-trim-lg);
+  --spacing-form-section-gap: var(--spacing-trim-md);
 
   /**
    * Density: md (default).
@@ -84,10 +84,12 @@
     --dx-lacuna-4: 0.5rem;
     --dx-lacuna-6: 0.75rem;
 
-    --dx-gutter-xs: 0.25rem; /* Input rings */
-    --dx-gutter-sm: 1rem; /* 16px (sm density card) */
-    --dx-gutter-md: 2rem; /* 32px (md density card — default) */
-    --dx-gutter-lg: 2.5rem; /* 40px (dialog, lg density card) */
+    /* Form:   8px */
+    --dx-gutter-sm: 0.5rem;
+    /* Dialog: 16px */
+    --dx-gutter-md: 1rem;
+    /* Card:   32px */
+    --dx-gutter-lg: 2rem;
   }
 
   :root {

package/src/util/index.ts

@@ -6,4 +6,6 @@ export * from './elevation';
 export * from './hash-styles';
 export * from './mx';
 export * from './size';
+export * from './tv';
+export * from './tw-merge-config';
 export * from './valence';

package/src/util/mx.ts

@@ -4,45 +4,15 @@
 
 import { extendTailwindMerge, validators } from 'tailwind-merge';
 
-type AdditionalClassGroups = 'density' | 'dx-focus-ring';
+import { type AdditionalClassGroups, twMergeConfig } from './tw-merge-config';
 
 export const mx = extendTailwindMerge<AdditionalClassGroups>({
   extend: {
+    ...twMergeConfig.extend,
     classGroups: {
-      'font-family': ['font-body', 'font-mono'],
-      'font-weight': [
-        // App weights
-        'font-thin',
-        'font-extralight',
-        'font-light',
-        'font-normal',
-        'font-medium',
-        'font-semibold',
-        'font-bold',
-        'font-extrabold',
-        'font-black',
-        // Arbitrary numbers
-        validators.isArbitraryNumber,
-      ],
-
-      density: ['dx-density-sm', 'dx-density-md', 'dx-density-lg'],
-
-      'dx-focus-ring': [
-        'dx-focus-ring',
-        'dx-focus-ring-inset',
-        'dx-focus-ring-always',
-        'dx-focus-ring-inset-always',
-        'dx-focus-ring-group',
-        'dx-focus-ring-group-x',
-        'dx-focus-ring-group-y',
-        'dx-focus-ring-group-always',
-        'dx-focus-ring-group-x-always',
-        'dx-focus-ring-group-y-always',
-        'dx-focus-ring-inset-over-all',
-        'dx-focus-ring-inset-over-all-always',
-        'dx-focus-ring-main',
-        'dx-focus-ring-main-always',
-      ],
+      ...twMergeConfig.extend.classGroups,
+      // Arbitrary numeric font-weights require a validator (not expressible as a plain string token).
+      'font-weight': [...twMergeConfig.extend.classGroups['font-weight'], validators.isArbitraryNumber],
     },
   },
 });