@dxos/ui-theme 0.8.4-staging.ac66bdf99f → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/ui-theme",
-  "version": "0.8.4-staging.ac66bdf99f",
+  "version": "0.9.0",
   "description": "A set of design system tokens to use with DXOS UI.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": [
     "*.css"
@@ -27,13 +27,6 @@
       "require": "./dist/plugin/node-cjs/plugins/ThemePlugin.cjs"
     }
   },
-  "typesVersions": {
-    "*": {
-      "plugin": [
-        "dist/types/src/plugins/ThemePlugin.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
@@ -44,29 +37,29 @@
     "@fontsource/poiret-one": "^5.0.20",
     "@radix-ui/react-slot": "1.1.2",
     "@tailwindcss/forms": "^0.5.9",
-    "@tailwindcss/postcss": "^4.2.0",
-    "autoprefixer": "^10.4.12",
-    "esbuild-style-plugin": "^1.6.1",
-    "glob": "^7.2.3",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "autoprefixer": "^10.5.0",
+    "esbuild-style-plugin": "^1.6.3",
     "globby": "14.1.0",
     "lodash.merge": "^4.6.2",
-    "postcss": "^8.4.41",
+    "postcss": "^8.5.12",
     "postcss-import": "^16.1.0",
     "postcss-nesting": "^13.0.1",
     "tailwind-merge": "^3.5.0",
     "tailwind-scrollbar": "^4.0.0",
-    "tailwindcss": "^4.2.0",
+    "tailwindcss": "^4.3.0",
     "tailwindcss-radix": "^4.0.2",
-    "@dxos/log": "0.8.4-staging.ac66bdf99f",
-    "@dxos/util": "0.8.4-staging.ac66bdf99f",
-    "@dxos/node-std": "0.8.4-staging.ac66bdf99f"
+    "@dxos/log": "0.9.0",
+    "@dxos/util": "0.9.0",
+    "@dxos/node-std": "0.9.0"
   },
   "devDependencies": {
     "@types/lodash.merge": "^4.6.6",
     "@types/postcss-import": "^14.0.3",
-    "esbuild": "0.25.11",
-    "vite": "^7.1.11",
-    "@dxos/ui-types": "0.8.4-staging.ac66bdf99f"
+    "esbuild": "0.28.0",
+    "vite": "^8.0.16",
+    "@dxos/ui-types": "0.9.0"
   },
   "peerDependencies": {
     "react": "~19.2.3"

package/src/Theme.stories.tsx

@@ -3,7 +3,7 @@
 //
 
 import { type Meta } from '@storybook/react-vite';
-import React from 'react';
+import React, { useLayoutEffect, useRef, useState } from 'react';
 
 import { hueShades, hues } from './defs';
 import { mx } from './util';
@@ -13,6 +13,8 @@ const neutralShades: [number, string][] = [
   [50,  'bg-neutral-50'],
   [75,  'bg-neutral-75'],
   [100, 'bg-neutral-100'],
+  [125, 'bg-neutral-125'],
+  [150, 'bg-neutral-150'],
   [200, 'bg-neutral-200'],
   [250, 'bg-neutral-250'],
   [300, 'bg-neutral-300'],
@@ -22,12 +24,15 @@ const neutralShades: [number, string][] = [
   [700, 'bg-neutral-700'],
   [750, 'bg-neutral-750'],
   [800, 'bg-neutral-800'],
+  [825, 'bg-neutral-825'],
+  [850, 'bg-neutral-850'],
+  [875, 'bg-neutral-875'],
   [900, 'bg-neutral-900'],
   [925, 'bg-neutral-925'],
   [950, 'bg-neutral-950'],
 ];
 
-const ColorSwatch = ({ hue }: { hue: string }) => {
+const StyleSwatch = ({ hue }: { hue: string }) => {
   return (
     <div
       style={{
@@ -37,17 +42,18 @@ const ColorSwatch = ({ hue }: { hue: string }) => {
     >
       <div
         style={{
-          color: `var(--color-${hue}-text)`,
           backgroundColor: `var(--color-base-surface)`,
+          color: `var(--color-${hue}-text)`,
         }}
         className='p-2 text-sm'
       >
-        {hue}
+        <div>{hue}</div>
+        <div className='text-xs'>-text</div>
       </div>
       <div
         style={{
+          backgroundColor: `var(--color-${hue}-bg)`,
           color: `var(--color-${hue}-text)`,
-          backgroundColor: `var(--color-${hue}-fill)`,
         }}
         className='px-1 text-sm flex items-center'
       >
@@ -57,12 +63,13 @@ const ColorSwatch = ({ hue }: { hue: string }) => {
       </div>
       <div
         style={{
-          color: `var(--color-${hue}-surface-text)`,
           backgroundColor: `var(--color-${hue}-surface)`,
+          color: `var(--color-${hue}-fg)`,
         }}
         className='p-2 text-sm'
       >
-        {hue}
+        <div>{hue}</div>
+        <div className='text-xs'>-fg/-surface</div>
       </div>
     </div>
   );
@@ -103,7 +110,7 @@ export const Styles = {
       <div className='p-4'>
         <div className='flex flex-wrap gap-2'>
           {['neutral', ...hues].map((hue) => (
-            <ColorSwatch key={hue} hue={hue} />
+            <StyleSwatch key={hue} hue={hue} />
           ))}
         </div>
       </div>
@@ -148,27 +155,87 @@ export const Neutral = {
   },
 };
 
+// prettier-ignore
+const surfaces: [surface: string, foreground: string, label: string][] = [
+  // Sorted lightest -> darkest at runtime (see Surfaces story); surfaces without a dedicated
+  // foreground fall back to base-fg.
+  ['bg-base-surface',    'text-base-fg',     'base'],
+  ['bg-deck-surface',    'text-base-fg',     'deck'],
+  ['bg-card-surface',    'text-base-fg',     'card'],
+  ['bg-toolbar-surface', 'text-base-fg',     'toolbar'],
+  ['bg-sidebar-surface', 'text-base-fg',     'sidebar'],
+  ['bg-group-surface',   'text-base-fg',     'group'],
+  ['bg-header-surface',  'text-base-fg',     'header'],
+  ['bg-modal-surface',   'text-base-fg',     'modal'],
+  ['bg-l1-surface',      'text-base-fg',     'l1'],
+  ['bg-r1-surface',      'text-base-fg',     'r1'],
+  ['bg-hover-surface',   'text-hover-fg',    'hover'],
+  ['bg-current-surface', 'text-current-fg',  'current'],
+  ['bg-selected-surface','text-selected-fg', 'selected'],
+  ['bg-l0-surface',      'text-base-fg',     'l0'],
+  ['bg-r0-surface',      'text-base-fg',     'r0'],
+  ['bg-input-surface',   'text-input-fg',    'input'],
+  ['bg-inverse-surface', 'text-inverse-fg',  'inverse'],
+  ['bg-scrim-surface',   'text-base-fg',     'scrim'],
+];
+
+// Resolve any CSS color (oklch, light-dark(), rgb, ...) to a 0-1 luminance via a 1x1 canvas.
+const colorLuminance = (css: string): number => {
+  const canvas = document.createElement('canvas');
+  canvas.width = canvas.height = 1;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    return 0;
+  }
+  ctx.clearRect(0, 0, 1, 1);
+  ctx.fillStyle = css;
+  ctx.fillRect(0, 0, 1, 1);
+  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+  return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255;
+};
+
 export const Surfaces = {
   render: () => {
+    const rowRefs = useRef(new Map<string, HTMLDivElement>());
+    const [order, setOrder] = useState(surfaces);
+    useLayoutEffect(() => {
+      // Sort lightest -> darkest by the resolved background; re-runs when the theme toggles.
+      const sort = () => {
+        const ranked = surfaces
+          .map((row) => {
+            const element = rowRefs.current.get(row[2]);
+            return { row, luminance: element ? colorLuminance(getComputedStyle(element).backgroundColor) : 0 };
+          })
+          .sort((a, b) => b.luminance - a.luminance)
+          .map(({ row }) => row);
+        setOrder(ranked);
+      };
+      sort();
+      const observer = new MutationObserver(sort);
+      observer.observe(document.body, {
+        attributes: true,
+        subtree: true,
+        attributeFilter: ['class', 'style', 'data-theme'],
+      });
+      return () => observer.disconnect();
+    }, []);
     return (
-      <div className='absolute inset-0 h-full p-4 bg-white dark:bg-black'>
-        <div className='flex flex-wrap gap-2'>
-          {[
-            { className: 'bg-scrim-surface', label: 'scrim' },
-            { className: 'bg-base-surface', label: 'base' },
-            { className: 'bg-deck-surface', label: 'deck' },
-            { className: 'bg-group-surface', label: 'group' },
-            { className: 'bg-sidebar-surface', label: 'sidebar' },
-            { className: 'bg-header-surface', label: 'header' },
-            { className: 'bg-card-surface', label: 'card' },
-            { className: 'bg-modal-surface', label: 'modal' },
-            { className: 'bg-input-surface', label: 'input' },
-            { className: 'bg-active-surface', label: 'active' },
-            { className: 'bg-hover-surface', label: 'hover' },
-            { className: 'bg-inverse-surface text-inverse-surface-text', label: 'inverse' },
-          ].map(({ className, label }) => (
-            <div key={className} className={mx('shrink-0 p-2 aspect-square w-48 rounded-md', className)}>
-              {label}
+      <div className='absolute inset-0 overflow-auto bg-white dark:bg-black'>
+        <div className='flex flex-col'>
+          {order.map(([surface, foreground, label]) => (
+            <div
+              key={label}
+              ref={(element) => {
+                if (element) {
+                  rowRefs.current.set(label, element);
+                }
+              }}
+              className={mx('flex items-baseline justify-between px-4 py-3', surface, foreground)}
+            >
+              <span className='text-sm'>{label}</span>
+              <span className='text-xs opacity-60'>
+                {surface} · {foreground}
+              </span>
             </div>
           ))}
         </div>
@@ -206,7 +273,7 @@ export const Animation = {
   render: () => {
     return (
       <div className='absolute inset-0 grid place-items-center'>
-        <div className='dx-density-coarse border border-separator rounded-md'>
+        <div className='dx-density-lg border border-separator rounded-md'>
           <div
             className={mx(
               'flex items-center font-mono text-2xl text-test-experimental',

package/src/css/DESIGN_SYSTEM.md

@@ -0,0 +1,187 @@
+# Design System: Color Tokens
+
+This document describes how color tokens are organized in `ui-theme`, the naming rules they follow, and the rationalization of overlapping state tokens (`current` / `active` / `highlight` / `selected` / `hover`) and text-on-surface tokens (`surface-text` → `foreground`).
+
+## Token tiers
+
+Three layers, each consuming the one below:
+
+| Tier        | File                                         | Purpose                                                                                                                                                                 | Example                                                                 |
+| ----------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| 1. Scale    | [`theme/palette.css`](./theme/palette.css)   | Raw color values. Extends Tailwind's neutral/blue scales with intermediate stops and aliases the `primary-*` ramp to `blue-*`.                                          | `--color-neutral-150`, `--color-primary-500`                            |
+| 2. Hue role | [`theme/styles.css`](./theme/styles.css)     | Per-hue role tokens for every Tailwind hue plus `neutral`. Six roles each: `bg`, `bg-hover`, `surface`, `fg`, `text`, `border`. Light/dark resolved via `light-dark()`. | `--color-red-surface`, `--color-neutral-border`                         |
+| 3. Semantic | [`theme/semantic.css`](./theme/semantic.css) | Named UI surfaces and states. May reference hue-role tokens (e.g. `error-surface` → `rose-surface`) or compose directly from the scale.                                 | `--color-card-surface`, `--color-current-surface`, `--color-error-text` |
+
+A consumer should reach for the highest tier that fits. Use `bg-card-surface`, not `bg-neutral-825`. Use `text-error-text`, not `text-rose-700`.
+
+## Naming convention
+
+Token names follow `--color-{name}-{part}[-{state}]`:
+
+- **`name`** identifies the role or surface (`card`, `current`, `accent`, `error`, `red`).
+- **`part`** is one of a fixed vocabulary:
+  - `surface` — the background fill of a thing.
+  - `fg` — the text/icon color that sits on the surface (paired with `surface`).
+  - `bg` — solid attention-grabbing fill (buttons, badges, indicators); more saturated than `surface`.
+  - `bg-hover` — hover state for `bg`.
+  - `border` — border color on the surface.
+  - `text` — text color used standalone, on the base canvas (no enclosing surface).
+- **`state`** is optional, appended last: `hover`, `active` (pressed). State always follows the part it modifies.
+
+### Pattern rules
+
+- Suffix order is fixed: `{name}-{part}-{state}`. The part comes first, then the state.
+- Pair rule: every `{name}-surface` that hosts text has a matching `{name}-fg`. Don't invent new ink-suffix names — keep the vocabulary closed.
+- A state token implies a base — `current-surface-hover` only makes sense if `current-surface` exists.
+- The `-text` part (standalone) is reserved for text on the base canvas, with no enclosing surface (e.g. `accent-text` for a hyperlink in body copy). Text on any named surface uses `{name}-fg`.
+
+## Surfaces
+
+Surfaces are governed by a strict elevation ladder: **lighter = higher = closer to the viewer** in dark
+mode; inverted toward white in light mode. Every named surface token is an alias of exactly one
+`--dx-elevation-N` level. Never set a surface to a raw scale value — pick the level that matches the
+role and point the token there.
+
+| Level | Name     | Dark    | Light   | Named surfaces                                                                |
+| ----- | -------- | ------- | ------- | ----------------------------------------------------------------------------- |
+| 0     | `void`   | `n-950` | `n-200` | scrim base, window gaps                                                       |
+| 1     | `rail`   | `n-900` | `n-175` | `l0-surface` (icon rail)                                                      |
+| 2     | `chrome` | `n-875` | `n-150` | `sidebar-surface`, `header-surface`, `l1-surface`, `r0-surface`, `r1-surface` |
+| 3     | `canvas` | `n-850` | `n-125` | `base-surface`, `deck-surface`                                                |
+| 4     | `raised` | `n-825` | `n-100` | `card-surface`, `group-surface`, `input-surface`                              |
+| 5     | `bar`    | `n-800` | `n-75`  | `toolbar-surface` (sticky, drop-shadowed)                                     |
+| 6     | `modal`  | `n-775` | `n-50`  | `modal-surface` (dialogs)                                                     |
+| 7     | `float`  | `n-750` | `white` | `popover-surface` (menus, popovers, toasts, tooltips)                         |
+
+The primitive `--dx-elevation-0…7` is defined in `semantic.css` using `light-dark()`. Raw scale values
+(`n-*`) are in `palette.css` — the table above is for human reference only.
+
+### Visual hierarchy (dark)
+
+```text
+popover/float   n-750  ↑ highest / closest to viewer
+modal/dialog    n-775
+toolbar         n-800  (sticky bar; content passes beneath)
+card/raised     n-825
+canvas/deck     n-850
+chrome/sidebar  n-875
+rail/L0         n-900
+void            n-950  ↓ lowest
+```
+
+Each surface that hosts text declares a matching `*-fg` (defaulting to `n-950 / n-50`).
+
+## Elevation primitive
+
+The `--dx-elevation-0…7` custom properties in `semantic.css` are the single source of truth for the
+surface ladder. They are private (`--dx-*` prefix) — never use them directly in component CSS; use the
+named surface tokens (`bg-card-surface`, `dx-modal-surface`, etc.) instead.
+
+When adding a new surface:
+
+1. Decide which elevation level the new surface belongs to (see the table above).
+2. Add `--color-<name>-surface: var(--dx-elevation-N);` in the Surfaces block of `semantic.css`.
+3. Add a matching `--color-<name>-fg` if text/icons sit on it.
+4. If the surface needs a utility class (like `dx-modal-surface`), add it to `surface.css`.
+
+## State tokens (rationalized)
+
+The system has three orthogonal states. Pick by what the ARIA / markup is saying.
+
+| State                      | Token                    | When                                                             | Value             |
+| -------------------------- | ------------------------ | ---------------------------------------------------------------- | ----------------- |
+| Active item, one-of-N      | `current-surface`        | `aria-current=true` (nav cursor, current row, current path)      | `n-100` / `n-900` |
+| Hovering on current item   | `current-surface-hover`  | pointer-over on a `current` element                              | `n-200` / `n-800` |
+| Text on a current surface  | `current-fg`             | text/icon color paired with `current-surface`                    | `n-950` / `n-50`  |
+| Selected / checked         | `selected-surface`       | `aria-selected=true` (multi-select, listbox option, checked row) | `n-150` / `n-850` |
+| Hovering on selected       | `selected-surface-hover` | pointer-over on a `selected` element                             | `n-250` / `n-750` |
+| Text on a selected surface | `selected-fg`            | text/icon color paired with `selected-surface`                   | `n-950` / `n-50`  |
+| Transient pointer-over     | `hover-surface`          | `:hover`, Radix `data-highlighted` (keyboard cursor in menus)    | `n-250` / `n-750` |
+| Text on a transient hover  | `hover-fg`               | text/icon color paired with `hover-surface`                      | `n-950` / `n-50`  |
+
+**Why these three.** `current` describes one-of-N navigation/selection state ("you are here"); `selected` describes a checked item in a set (multi-select-able); `hover` is transient pointer feedback. Driving the distinction off ARIA keeps markup and tokens in sync.
+
+### Visual hierarchy (state, dark)
+
+```text
+card-surface          n-825    resting
+current-surface       n-100 / n-900    "I am the active one"
+current-surface-hover n-200 / n-800    hovering the active one
+hover-surface         n-250 / n-750    transient pointer-over anywhere else
+```
+
+## Consolidation: tokens that go away
+
+These are merged into the rationalized state vocabulary:
+
+| Removed                   | Replaced by             | Notes                                                                                                                                                                             |
+| ------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `active-surface`          | `current-surface`       | Same concept ("the active one"). Same value already.                                                                                                                              |
+| `active-text`             | `current-fg`            | Renamed and reclassified — it was always foreground (text on the surface), not `text`.                                                                                            |
+| `highlight-surface`       | `current-surface`       | `selected.css` used it for `aria-current=true`.                                                                                                                                   |
+| `highlight-surface-hover` | `current-surface-hover` |                                                                                                                                                                                   |
+| `highlight-surface-text`  | `current-fg`            | Rename to the new `-fg` suffix.                                                                                                                                                   |
+| `*-surface-text` (all)    | `*-fg`                  | Repository-wide rename for every hue, semantic, and named-surface token (e.g. `base-surface-text` → `base-fg`, `red-surface-text` → `red-fg`, `error-surface-text` → `error-fg`). |
+
+### Out-of-scope drift to fix separately
+
+Two sites use `bg-hover-surface` as a _resting_ fill (not a hover state):
+
+- [packages/plugins/plugin-navtree/src/experimental/Tree.tsx:196](../../../../plugins/plugin-navtree/src/experimental/Tree.tsx)
+- [packages/plugins/plugin-script/src/components/TestPanel/TestPanel.tsx:171](../../../../plugins/plugin-script/src/components/TestPanel/TestPanel.tsx)
+
+These should probably move to `card-surface` or `current-surface` depending on intent. Tracked as a follow-up.
+
+## Accent (primary)
+
+`accent-*` is the project's primary brand color (blue). The token name is `accent`, not `primary`, to avoid colliding with the raw scale `--color-primary-*` (which is aliased to `blue-*` for Tailwind utility convenience).
+
+| Token               | Purpose                                             |
+| ------------------- | --------------------------------------------------- |
+| `accent-bg`         | Fill for primary buttons / call-to-action surfaces. |
+| `accent-bg-hover`   | Hover state.                                        |
+| `accent-fg`         | Text/icon color on accent surfaces.                 |
+| `accent-text`       | Standalone accent-colored text (links, emphasis).   |
+| `accent-text-hover` | Hover state for accent text.                        |
+
+This is the canonical illustration of the `fg` vs `text` distinction: `accent-fg` is the ink on an accent button; `accent-text` is the accent-colored body link.
+
+Note: `accent-focus-indicator` is removed — focus rings are now global tokens (see [Focus rings](#focus-rings)).
+
+## Focus rings
+
+Focus indicators are a global UI affordance, not a per-surface property. Every focusable element should pick from the same small set of ring colors so focus stays visually consistent and accessible.
+
+| Token               | Value             | Used by                                                  |
+| ------------------- | ----------------- | -------------------------------------------------------- |
+| `focus-ring`        | `blue-600`        | Default focus ring (buttons, inputs, grid cells, links). |
+| `focus-ring-subtle` | `n-400` / `n-600` | Subdued ring for low-emphasis focusable elements.        |
+
+Tokens removed in this rationalization:
+
+| Removed                   | Replaced by         | Notes                                                          |
+| ------------------------- | ------------------- | -------------------------------------------------------------- |
+| `accent-focus-indicator`  | `focus-ring`        | Was `blue-600`. Same value.                                    |
+| `grid-focus-indicator`    | `focus-ring`        | Was `primary-600` (= `blue-600`). Identical to accent variant. |
+| `neutral-focus-indicator` | `focus-ring-subtle` | Was `n-400` / `n-600`. Same value.                             |
+
+## Semantic aliases
+
+Status colors point at hue-role tokens:
+
+| Token       | Aliases     |
+| ----------- | ----------- |
+| `info-*`    | `cyan-*`    |
+| `success-*` | `emerald-*` |
+| `warning-*` | `amber-*`   |
+| `error-*`   | `rose-*`    |
+
+Each provides `bg`, `bg-hover`, `surface`, `fg`, `text`, `border`.
+
+## Adding a new token
+
+1. Does an existing semantic token already cover it? For a new named surface, check the elevation ladder first — the new surface probably fits an existing level and should alias `--dx-elevation-N` rather than a raw scale value.
+2. Does it represent a new named surface, state, or status? Add it to `semantic.css` referencing scale or hue-role tokens — never raw hex.
+3. Follow the suffix order: `{name}-{part}[-{state}]`.
+4. If the new token will be used through a Tailwind utility that the source-scan can't see (e.g. CSS file, dynamic class), add it to `@source inline(...)` in [`main.css`](./main.css).
+5. If it ships state variants (`-hover`, `-active`), declare them adjacent to the base in the same block.

package/src/css/base/base.css

@@ -35,9 +35,9 @@
   html .dark,
   .sb-show-main {
     background-color: var(--color-base-surface);
-    color: var(--color-base-surface-text);
+    color: var(--color-base-fg);
     --surface-bg: var(--color-base-surface);
-    --surface-text: var(--color-base-surface-text);
+    --foreground: var(--color-base-fg);
     --description-text: var(--color-description);
   }
 }

package/src/css/components/button.css

@@ -10,8 +10,14 @@
 
   /* Base styles */
   .dx-button {
-    @apply shrink-0 inline-flex select-none items-center justify-center overflow-hidden min-h-[2.5rem] px-3;
-    @apply font-medium transition-colors duration-100 ease-linear bg-input-surface;
+    @apply shrink-0 inline-flex select-none items-center justify-center overflow-hidden min-h-[2rem] px-3;
+    @apply font-medium transition-colors duration-100 ease-linear bg-input-bg;
+    /* The default variant inherits ambient valence colors when rendered inside a valence surface
+     * (e.g. Message.Root, which sets --dx-valence-*); otherwise it falls back to the base input styling. */
+    &[data-variant='default'] {
+      color: var(--dx-valence-text, inherit);
+      background: var(--dx-valence-bg, var(--color-input-bg));
+    }
     &[aria-pressed='true'],
     &[aria-checked='true'] {
       @apply text-accent-text bg-attention-surface;
@@ -26,10 +32,17 @@
     &[data-variant='ghost'] {
       @apply bg-transparent;
       &:hover {
-        @apply bg-hover-surface text-inherit;
+        /* 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;
       }
       &[data-state='open'] {
-        @apply bg-input-surface;
+        @apply bg-input-bg;
       }
       &[aria-pressed='true'],
       &[aria-checked='true'] {
@@ -46,30 +59,55 @@
     /* Enabled styles */
     &:not([disabled]),
     &[disabled='false'] {
-      /* Hover */
       &:hover {
         @apply bg-hover-surface;
       }
 
-      /* Variants */
+      &[data-variant='default']:hover {
+        color: var(--dx-valence-text);
+        background-color: var(--dx-valence-bg-hover, var(--color-hover-surface));
+      }
+
+      /* 
+       * Inside a valence surface the (otherwise transparent) ghost hover adopts the valence background;
+       * elsewhere it falls back to the standard hover surface. 
+       */
+      &[data-variant='ghost']:hover {
+        color: var(--dx-valence-text);
+        background-color: var(--dx-valence-bg, var(--color-hover-surface));
+      }
+
       &[data-variant='primary'] {
-        @apply text-accent-surface-text bg-accent-surface;
+        @apply text-accent-fg bg-accent-bg;
         &:hover,
         &[aria-pressed='true'],
-        &[aria-checked='true'] &[data-state='open'] {
-          @apply bg-accent-surface-hover;
+        &[aria-checked='true'],
+        &[data-state='open'] {
+          @apply bg-accent-bg-hover;
         }
       }
       &[data-variant='destructive'] {
-        @apply text-accent-surface-text bg-rose-fill;
+        @apply text-accent-fg bg-error-bg;
+        &:hover,
+        &[aria-pressed='true'],
+        &[aria-checked='true'],
+        &[data-state='open'] {
+          @apply bg-error-bg-hover;
+        }
+      }
+      &[data-variant='valence'] {
+        @apply text-inverse-fg;
+        background: var(--dx-valence-bg, var(--color-neutral-bg));
         &:hover,
         &[aria-pressed='true'],
-        &[aria-checked='true'] &[data-state='open'] {
-          @apply bg-rose-fill;
+        &[aria-checked='true'],
+        &[data-state='open'] {
+          background-color: var(--dx-valence-bg-hover, var(--color-neutral-bg-hover));
         }
       }
     }
   }
+
   /* Props */
   .dx-button:not([data-props~='grouped']) {
     @apply rounded-xs;
@@ -77,8 +115,20 @@
   .dx-button:not([data-props~='wrap']) {
     @apply truncate;
   }
+  .dx-button[data-density='lg'] {
+    @apply min-h-[2.5rem] px-3;
+  }
+  .dx-button[data-density='sm'] {
+    @apply min-h-[1.75rem] px-2;
+  }
+  .dx-button[data-density='xs'] {
+    @apply min-h-[1.5rem] px-1 text-xs;
+  }
+  .dx-button[data-density='xs'].aspect-square {
+    @apply size-6 px-0;
+  }
   @media (pointer: fine) {
-    .dx-button[data-density='fine'] {
+    .dx-button[data-density='md'] {
       @apply min-h-[2rem] px-2.5;
     }
   }

package/src/css/components/card.css

@@ -0,0 +1,14 @@
+@layer dx-components {
+  /**
+   * Card.Section is `col-span-full grid grid-cols-subgrid` so it owns a full row and
+   * exposes the Card.Root's 3 column tracks (gutter / content / gutter) to its children.
+   *
+   * Direct children that do not carry their own column placement default to the center
+   * (content) track via `--dx-col`, so raw content (editors, text, lists) lands in the
+   * content column instead of CSS Grid auto-placing it into a gutter. Children with
+   * an explicit `col-span-*` utility (Card.Action, Card.Row, Card.Section title) opt out.
+   */
+  .dx-card__section > *:not([class*='col-span']) {
+    grid-column: var(--dx-col, auto);
+  }
+}

package/src/css/components/checkbox.css

@@ -10,7 +10,7 @@
     &[aria-checked='true'],
     &[aria-checked='mixed'],
     &:checked {
-      @apply bg-accent-surface accent-accent-surface border-accent-surface;
+      @apply bg-accent-bg accent-accent-bg border-accent-bg;
     }
 
     &:not([disabled]),
@@ -20,14 +20,14 @@
         &[aria-checked='true'],
         &[aria-checked='mixed'],
         &:checked {
-          @apply bg-accent-surface-hover accent-accent-surface-hover border-accent-surface-hover;
+          @apply bg-accent-bg-hover accent-accent-bg-hover border-accent-bg-hover;
         }
       }
     }
   }
 
   .dx-checkbox {
-    @apply w-4 h-4 overflow-hidden shadow-inner transition-colors bg-un-accent accent-un-accent text-accent-surface-text shrink-0 inline-grid place-items-center rounded-xs;
+    @apply w-4 h-4 overflow-hidden shadow-inner transition-colors bg-un-accent accent-un-accent text-accent-fg shrink-0 inline-grid place-items-center rounded-xs;
   }
 
   /* TODO(ZaymonFC): Focus is handled by .dx-focus-ring, but should ideally be applied as part of this component.*/