@dxos/ui-theme 0.8.4-main.abd8ff62ef → 0.8.4-main.bc2380dfbc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/ui-theme",
-  "version": "0.8.4-main.abd8ff62ef",
+  "version": "0.8.4-main.bc2380dfbc",
   "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"
@@ -39,8 +39,7 @@
     "@tailwindcss/forms": "^0.5.9",
     "@tailwindcss/postcss": "^4.2.0",
     "autoprefixer": "^10.5.0",
-    "esbuild-style-plugin": "^1.6.1",
-    "glob": "^7.2.3",
+    "esbuild-style-plugin": "^1.6.3",
     "globby": "14.1.0",
     "lodash.merge": "^4.6.2",
     "postcss": "^8.5.12",
@@ -50,16 +49,16 @@
     "tailwind-scrollbar": "^4.0.0",
     "tailwindcss": "^4.2.0",
     "tailwindcss-radix": "^4.0.2",
-    "@dxos/log": "0.8.4-main.abd8ff62ef",
-    "@dxos/node-std": "0.8.4-main.abd8ff62ef",
-    "@dxos/util": "0.8.4-main.abd8ff62ef"
+    "@dxos/log": "0.8.4-main.bc2380dfbc",
+    "@dxos/node-std": "0.8.4-main.bc2380dfbc",
+    "@dxos/util": "0.8.4-main.bc2380dfbc"
   },
   "devDependencies": {
     "@types/lodash.merge": "^4.6.6",
     "@types/postcss-import": "^14.0.3",
     "esbuild": "0.28.0",
-    "vite": "^8.0.10",
-    "@dxos/ui-types": "0.8.4-main.abd8ff62ef"
+    "vite": "^8.0.13",
+    "@dxos/ui-types": "0.8.4-main.bc2380dfbc"
   },
   "peerDependencies": {
     "react": "~19.2.3"

package/src/Theme.stories.tsx

@@ -37,8 +37,8 @@ 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'
       >
@@ -46,8 +46,8 @@ const ColorSwatch = ({ hue }: { hue: string }) => {
       </div>
       <div
         style={{
-          color: `var(--color-${hue}-text)`,
           backgroundColor: `var(--color-${hue}-fill)`,
+          color: `var(--color-${hue}-text)`,
         }}
         className='px-1 text-sm flex items-center'
       >
@@ -57,8 +57,8 @@ const ColorSwatch = ({ hue }: { hue: string }) => {
       </div>
       <div
         style={{
-          color: `var(--color-${hue}-surface-text)`,
           backgroundColor: `var(--color-${hue}-surface)`,
+          color: `var(--color-${hue}-foreground)`,
         }}
         className='p-2 text-sm'
       >
@@ -163,9 +163,9 @@ export const Surfaces = {
             { 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-current-surface', label: 'current' },
             { className: 'bg-hover-surface', label: 'hover' },
-            { className: 'bg-inverse-surface text-inverse-surface-text', label: 'inverse' },
+            { className: 'bg-inverse-surface text-inverse-foreground', label: 'inverse' },
           ].map(({ className, label }) => (
             <div key={className} className={mx('shrink-0 p-2 aspect-square w-48 rounded-md', className)}>
               {label}

package/src/css/DESIGN_SYSTEM.md

@@ -0,0 +1,159 @@
+# 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 generated mechanically for every Tailwind hue plus `neutral`. Five roles each: `fill`, `surface`, `foreground`, `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-75`. 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.
+  - `foreground` — the text/icon color that sits on the surface (paired with `surface`).
+  - `border` — border color on the surface.
+  - `fill` — solid attention-grabbing fill (badges, dots, indicators); more saturated than `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}-foreground`. 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}-foreground`.
+
+## Surfaces
+
+Layered fills, ordered from recessive to prominent:
+
+```
+base-surface          n-50  / n-950   the page canvas
+deck-surface          n-50  / n-950   deck panes
+toolbar-surface       n-75  / n-925   toolbars
+card-surface          n-75  / n-925   cards
+group-surface         n-100 / n-900   grouped containers
+modal-surface         n-100 / n-900   modals / dialogs
+sidebar-surface       n-100 / n-900   sidebars
+header-surface        n-100 / n-900   headers
+input-surface         n-200 / n-800   form controls
+```
+
+Each surface that hosts text declares a matching `*-foreground` (defaulting to `n-950 / n-50`).
+
+## 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-foreground`     | 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-foreground`    | 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-foreground`       | 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
+
+```
+card-surface          n-75  / n-925    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-foreground`    | 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-foreground`    | Rename to the new `-foreground` suffix.                                                                                                                                                                   |
+| `*-surface-text` (all)    | `*-foreground`          | Repository-wide rename for every hue, semantic, and named-surface token (e.g. `base-surface-text` → `base-foreground`, `red-surface-text` → `red-foreground`, `error-surface-text` → `error-foreground`). |
+
+### Visual change to expect
+
+The 9 `bg-active-surface` call sites become one shade subtler (from `n-200/800` to `n-100/900`). This aligns them with the existing `selected.css` treatment of `aria-current=true` and produces the coherent layering shown above.
+
+### 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; not part of this rationalization.
+
+## 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-surface`       | Fill for primary buttons / call-to-action surfaces. |
+| `accent-surface-hover` | Hover state.                                        |
+| `accent-foreground`    | 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 `foreground` vs `text` distinction: `accent-foreground` 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 `fill`, `surface`, `foreground`, `text`, `border`.
+
+## Adding a new token
+
+1. Does an existing semantic token already cover it? If yes, use it.
+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-foreground);
     --surface-bg: var(--color-base-surface);
-    --surface-text: var(--color-base-surface-text);
+    --foreground: var(--color-base-foreground);
     --description-text: var(--color-description);
   }
 }

package/src/css/components/button.css

@@ -10,7 +10,7 @@
 
   /* Base styles */
   .dx-button {
-    @apply shrink-0 inline-flex select-none items-center justify-center overflow-hidden min-h-[2.5rem] px-3;
+    @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-surface;
     &[aria-pressed='true'],
     &[aria-checked='true'] {
@@ -53,7 +53,7 @@
 
       /* Variants */
       &[data-variant='primary'] {
-        @apply text-accent-surface-text bg-accent-surface;
+        @apply text-accent-foreground bg-accent-surface;
         &:hover,
         &[aria-pressed='true'],
         &[aria-checked='true'] &[data-state='open'] {
@@ -61,7 +61,7 @@
         }
       }
       &[data-variant='destructive'] {
-        @apply text-accent-surface-text bg-rose-fill;
+        @apply text-accent-foreground bg-rose-fill;
         &:hover,
         &[aria-pressed='true'],
         &[aria-checked='true'] &[data-state='open'] {

package/src/css/components/checkbox.css

@@ -27,7 +27,7 @@
   }
 
   .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-foreground 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.*/

package/src/css/components/focus.css

@@ -12,10 +12,10 @@
       }
 
       &:focus-visible {
-        @apply ring-focus-line ring-offset-focus-offset z-[1] ring-[var(--color-neutral-focus-indicator)];
+        @apply ring-focus-line ring-offset-focus-offset z-[1] ring-[var(--color-focus-ring-subtle)];
 
         &[data-variant='primary'] {
-          @apply ring-[var(--color-accent-focus-indicator)];
+          @apply ring-[var(--color-focus-ring)];
         }
 
         &:hover {
@@ -45,10 +45,10 @@
       }
 
       &:focus {
-        @apply ring-focus-line ring-offset-focus-offset z-[1] ring-[var(--color-neutral-focus-indicator)];
+        @apply ring-focus-line ring-offset-focus-offset z-[1] ring-[var(--color-focus-ring-subtle)];
 
         &[data-variant='primary'] {
-          @apply ring-[var(--color-accent-focus-indicator)];
+          @apply ring-[var(--color-focus-ring)];
         }
 
         &:hover {
@@ -79,10 +79,10 @@
   .dx-focus-ring-group:focus-visible .dx-focus-ring-group-indicator,
   .dx-focus-ring-group-x:focus-visible .dx-focus-ring-group-x-indicator,
   .dx-focus-ring-group-y:focus-visible .dx-focus-ring-group-y-indicator {
-    @apply ring-focus-line ring-offset-focus-offset ring-[var(--color-neutral-focus-indicator)];
+    @apply ring-focus-line ring-offset-focus-offset ring-[var(--color-focus-ring-subtle)];
 
     &[data-variant='primary'] {
-      @apply ring-[var(--color-accent-focus-indicator)];
+      @apply ring-[var(--color-focus-ring)];
     }
 
     &:hover {
@@ -97,10 +97,10 @@
   .dx-focus-ring-group-always:focus .dx-focus-ring-group-indicator,
   .dx-focus-ring-group-x-always:focus .dx-focus-ring-group-x-indicator,
   .dx-focus-ring-group-y-always:focus .dx-focus-ring-group-y-indicator {
-    @apply ring-focus-line ring-offset-focus-offset ring-[var(--color-neutral-focus-indicator)];
+    @apply ring-focus-line ring-offset-focus-offset ring-[var(--color-focus-ring-subtle)];
 
     &[data-variant='primary'] {
-      @apply ring-[var(--color-accent-focus-indicator)];
+      @apply ring-[var(--color-focus-ring)];
     }
 
     &:hover {
@@ -145,11 +145,11 @@
 
       &:focus-visible {
         &::after {
-          @apply ring-focus-line ring-offset-focus-offset ring-inset z-[1] ring-[var(--color-neutral-focus-indicator)];
+          @apply ring-focus-line ring-offset-focus-offset ring-inset z-[1] ring-[var(--color-focus-ring-subtle)];
         }
 
         &[data-variant='primary']::after {
-          @apply ring-[var(--color-accent-focus-indicator)];
+          @apply ring-[var(--color-focus-ring)];
         }
 
         &:hover {
@@ -178,11 +178,11 @@
 
       &:focus {
         &::after {
-          @apply ring-focus-line ring-offset-focus-offset ring-inset z-[1] ring-[var(--color-neutral-focus-indicator)];
+          @apply ring-focus-line ring-offset-focus-offset ring-inset z-[1] ring-[var(--color-focus-ring-subtle)];
         }
 
         &[data-variant='primary']::after {
-          @apply ring-[var(--color-accent-focus-indicator)];
+          @apply ring-[var(--color-focus-ring)];
         }
 
         &:hover {

package/src/css/components/panel.css

@@ -1,5 +1,5 @@
 /**
- * Panel — applies bg-{hue}-surface / text-{hue}-surface-text / border-{hue}-border tokens via data-hue attribute or BEM modifier.
+ * Panel — applies bg-{hue}-surface / text-{hue}-foreground / border-{hue}-border tokens via data-hue attribute or BEM modifier.
  * Example: <div className='dx-panel' data-hue='blue'>...</div>
  * Example: <div className='dx-panel dx-panel--blue'>...</div>
  */
@@ -7,111 +7,111 @@
 @layer dx-components {
   [data-hue='neutral'] .dx-panel,
   .dx-panel--neutral {
-    @apply bg-neutral-surface text-neutral-surface-text border-neutral-border;
+    @apply bg-neutral-surface text-neutral-foreground border-neutral-border;
   }
 
   [data-hue='red'] .dx-panel,
   .dx-panel--red {
-    @apply bg-red-surface text-red-surface-text border-red-border;
+    @apply bg-red-surface text-red-foreground border-red-border;
   }
 
   [data-hue='orange'] .dx-panel,
   .dx-panel--orange {
-    @apply bg-orange-surface text-orange-surface-text border-orange-border;
+    @apply bg-orange-surface text-orange-foreground border-orange-border;
   }
 
   [data-hue='amber'] .dx-panel,
   .dx-panel--amber {
-    @apply bg-amber-surface text-amber-surface-text border-amber-border;
+    @apply bg-amber-surface text-amber-foreground border-amber-border;
   }
 
   [data-hue='yellow'] .dx-panel,
   .dx-panel--yellow {
-    @apply bg-yellow-surface text-yellow-surface-text border-yellow-border;
+    @apply bg-yellow-surface text-yellow-foreground border-yellow-border;
   }
 
   [data-hue='lime'] .dx-panel,
   .dx-panel--lime {
-    @apply bg-lime-surface text-lime-surface-text border-lime-border;
+    @apply bg-lime-surface text-lime-foreground border-lime-border;
   }
 
   [data-hue='green'] .dx-panel,
   .dx-panel--green {
-    @apply bg-green-surface text-green-surface-text border-green-border;
+    @apply bg-green-surface text-green-foreground border-green-border;
   }
 
   [data-hue='emerald'] .dx-panel,
   .dx-panel--emerald {
-    @apply bg-emerald-surface text-emerald-surface-text border-emerald-border;
+    @apply bg-emerald-surface text-emerald-foreground border-emerald-border;
   }
 
   [data-hue='teal'] .dx-panel,
   .dx-panel--teal {
-    @apply bg-teal-surface text-teal-surface-text border-teal-border;
+    @apply bg-teal-surface text-teal-foreground border-teal-border;
   }
 
   [data-hue='cyan'] .dx-panel,
   .dx-panel--cyan {
-    @apply bg-cyan-surface text-cyan-surface-text border-cyan-border;
+    @apply bg-cyan-surface text-cyan-foreground border-cyan-border;
   }
 
   [data-hue='sky'] .dx-panel,
   .dx-panel--sky {
-    @apply bg-sky-surface text-sky-surface-text border-sky-border;
+    @apply bg-sky-surface text-sky-foreground border-sky-border;
   }
 
   [data-hue='blue'] .dx-panel,
   .dx-panel--blue {
-    @apply bg-blue-surface text-blue-surface-text border-blue-border;
+    @apply bg-blue-surface text-blue-foreground border-blue-border;
   }
 
   [data-hue='indigo'] .dx-panel,
   .dx-panel--indigo {
-    @apply bg-indigo-surface text-indigo-surface-text border-indigo-border;
+    @apply bg-indigo-surface text-indigo-foreground border-indigo-border;
   }
 
   [data-hue='violet'] .dx-panel,
   .dx-panel--violet {
-    @apply bg-violet-surface text-violet-surface-text border-violet-border;
+    @apply bg-violet-surface text-violet-foreground border-violet-border;
   }
 
   [data-hue='purple'] .dx-panel,
   .dx-panel--purple {
-    @apply bg-purple-surface text-purple-surface-text border-purple-border;
+    @apply bg-purple-surface text-purple-foreground border-purple-border;
   }
 
   [data-hue='fuchsia'] .dx-panel,
   .dx-panel--fuchsia {
-    @apply bg-fuchsia-surface text-fuchsia-surface-text border-fuchsia-border;
+    @apply bg-fuchsia-surface text-fuchsia-foreground border-fuchsia-border;
   }
 
   [data-hue='pink'] .dx-panel,
   .dx-panel--pink {
-    @apply bg-pink-surface text-pink-surface-text border-pink-border;
+    @apply bg-pink-surface text-pink-foreground border-pink-border;
   }
 
   [data-hue='rose'] .dx-panel,
   .dx-panel--rose {
-    @apply bg-rose-surface text-rose-surface-text border-rose-border;
+    @apply bg-rose-surface text-rose-foreground border-rose-border;
   }
 
   [data-hue='info'] .dx-panel,
   .dx-panel--info {
-    @apply bg-info-surface text-info-surface-text border-info-border;
+    @apply bg-info-surface text-info-foreground border-info-border;
   }
 
   [data-hue='success'] .dx-panel,
   .dx-panel--success {
-    @apply bg-success-surface text-success-surface-text border-success-border;
+    @apply bg-success-surface text-success-foreground border-success-border;
   }
 
   [data-hue='warning'] .dx-panel,
   .dx-panel--warning {
-    @apply bg-warning-surface text-warning-surface-text border-warning-border;
+    @apply bg-warning-surface text-warning-foreground border-warning-border;
   }
 
   [data-hue='error'] .dx-panel,
   .dx-panel--error {
-    @apply bg-error-surface text-error-surface-text border-error-border;
+    @apply bg-error-surface text-error-foreground border-error-border;
   }
 }

package/src/css/components/selected.css

@@ -1,35 +1,76 @@
 /**
- * Selected / Highlighted state utilities.
+ * Selected / Current / Highlighted state utilities.
  *
  * See `./selected.md` for the ARIA pairing grammar — every class below
  * fires off a specific attribute and silently does nothing without it.
  */
 
 @layer dx-components {
-  /* Pure visual affordance, no ARIA pair. Combine with dx-selected or dx-current. */
+  /*
+   * Pure visual affordance, no ARIA pair. Combine with dx-selected or dx-current.
+   *
+   * Picks the hover variant matching the element's underlying state:
+   *   - neither aria-selected nor aria-current → hover-surface
+   *   - aria-selected="true"                   → selected-surface-hover
+   *   - aria-current="true"                    → current-surface-hover (wins if both)
+   *
+   * Higher-specificity rules (attribute selectors) override the plain :hover rule,
+   * and `aria-current` is listed last so it beats `aria-selected` at equal specificity.
+   */
   .dx-hover {
-    @apply cursor-pointer hover:bg-highlight-surface! hover:text-highlight-surface-text!;
+    @apply cursor-pointer
+      hover:bg-hover-surface! hover:text-hover-foreground!
+      hover:aria-selected:bg-selected-surface-hover! hover:aria-selected:text-selected-foreground!
+      hover:aria-[current=true]:bg-current-surface-hover! hover:aria-[current=true]:text-current-foreground!;
+  }
+  .dx-hover-row {
+    @apply group-hover/row:bg-hover-surface! group-hover/row:text-hover-foreground!
+      group-hover/row:group-aria-selected/row:bg-selected-surface-hover!
+      group-hover/row:group-aria-selected/row:text-selected-foreground!
+      group-hover/row:group-aria-[current=true]/row:bg-current-surface-hover!
+      group-hover/row:group-aria-[current=true]/row:text-current-foreground!;
   }
 
-  /* Pairs with Radix-managed `data-highlighted`. Don't set the attribute manually. */
-  .dx-highlighted {
-    @apply data-[highlighted]:bg-highlight-surface
-      data-[highlighted]:text-highlight-surface-text
-      hover:data-[highlighted]:bg-highlight-surface-hover;
+  /*
+   * Pairs with `aria-selected`. Use for listbox/option selection (master/detail).
+   * `!` is required: these utilities live in the `dx-components` layer, but
+   * background utilities like `bg-card-surface` live in Tailwind's
+   * `utilities` layer (declared later in the cascade), so without
+   * `!important` the card background would override the state colour.
+   *
+   * NOTE: Declared before `.dx-current` so that when an element has both
+   * `aria-selected="true"` and `aria-current="true"`, `dx-current` wins at
+   * equal specificity (consistent with how `dx-hover` resolves the same
+   * conflict).
+   */
+  .dx-selected {
+    @apply aria-selected:bg-selected-surface! aria-selected:text-selected-foreground!
+      aria-selected:font-semibold aria-selected:tracking-normal
+      transition-[color,font-variation-settings,letter-spacing];
   }
 
-  /* Pairs with `aria-current="true|page|…"`. Use for "you are here" navigation. */
+  /*
+   * Pairs with `aria-current="true|page|…"`. Use for "you are here" navigation.
+   *
+   * The ring uses the subdued focus indicator (neutral) rather than the
+   * accent blue — `dx-current` marks position, not focus, so a saturated
+   * ring would compete with the actual keyboard focus ring.
+   */
   .dx-current {
     @apply dx-ring-pseudo
-      aria-[current=true]:bg-highlight-surface aria-[current=true]:text-highlight-surface-text
-      aria-[current=true]:after:ring-active-separator!;
+      aria-[current=true]:bg-current-surface! aria-[current=true]:text-current-foreground!
+      aria-[current=true]:after:ring-focus-ring-subtle!;
+  }
+  .dx-current-row {
+    @apply group-aria-[current=true]/row:bg-current-surface! group-aria-[current=true]/row:text-current-foreground!;
   }
 
-  /* Pairs with `aria-selected`. Use for listbox/option selection (master/detail). */
-  .dx-selected {
-    @apply aria-selected:bg-selected-surface
-      aria-selected:text-selected-surface-text hover:aria-selected:text-selected-surface-text
-      aria-selected:font-semibold aria-selected:tracking-normal
-      transition-[color,font-variation-settings,letter-spacing];
+  /*
+   * Pairs with Radix-managed `data-highlighted`. Don't set the attribute manually.
+   */
+  .dx-highlighted {
+    @apply data-[highlighted]:bg-current-surface
+      data-[highlighted]:text-current-foreground
+      hover:data-[highlighted]:bg-current-surface-hover;
   }
 }

package/src/css/components/surface.css

@@ -4,22 +4,22 @@
 
 @layer dx-components {
   .dx-base-surface {
-    @apply bg-base-surface text-base-surface-text;
+    @apply bg-base-surface text-base-foreground;
     --surface-bg: var(--color-base-surface);
   }
 
   .dx-sidebar-surface {
-    @apply bg-sidebar-surface text-base-surface-text;
+    @apply bg-sidebar-surface text-base-foreground;
     --surface-bg: var(--color-sidebar-surface);
   }
 
   .dx-modal-surface {
-    @apply bg-modal-surface text-base-surface-text backdrop-blur-md;
+    @apply bg-modal-surface text-base-foreground backdrop-blur-md;
     --surface-bg: var(--color-modal-surface);
   }
 
   .dx-attention-surface {
-    @apply bg-attention-surface text-base-surface-text;
+    @apply bg-attention-surface text-base-foreground;
     --surface-bg: var(--color-attention-surface);
   }
 }