@dxos/ui-theme 0.0.0 → 0.8.4-main.05e74ebcff

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@dxos/ui-theme",
-  "version": "0.0.0",
+  "version": "0.8.4-main.05e74ebcff",
   "description": "A set of design system tokens to use with DXOS UI.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
   "sideEffects": [
     "*.css"
@@ -16,24 +20,11 @@
       "types": "./dist/types/src/index.d.ts",
       "default": "./dist/lib/browser/index.mjs"
     },
-    "./esbuild-plugin": {
-      "source": "./src/plugins/esbuild-plugin.ts",
-      "types": "./dist/types/src/plugins/esbuild-plugin.d.ts",
-      "import": "./dist/plugin/node-esm/plugins/esbuild-plugin.mjs",
-      "require": "./dist/plugin/node-cjs/plugins/esbuild-plugin.cjs"
-    },
     "./plugin": {
-      "source": "./src/plugins/plugin.ts",
-      "types": "./dist/types/src/plugins/plugin.d.ts",
-      "import": "./dist/plugin/node-esm/plugins/plugin.mjs",
-      "require": "./dist/plugin/node-cjs/plugins/plugin.cjs"
-    }
-  },
-  "typesVersions": {
-    "*": {
-      "plugin": [
-        "dist/types/src/plugins/plugin.d.ts"
-      ]
+      "source": "./src/plugins/ThemePlugin.ts",
+      "types": "./dist/types/src/plugins/ThemePlugin.d.ts",
+      "import": "./dist/plugin/node-esm/plugins/ThemePlugin.mjs",
+      "require": "./dist/plugin/node-cjs/plugins/ThemePlugin.cjs"
     }
   },
   "files": [
@@ -41,40 +32,42 @@
     "src"
   ],
   "dependencies": {
-    "@ch-ui/tailwind-tokens": "2.8.1",
-    "@ch-ui/tokens": "3.0.1",
-    "@fontsource-variable/inter": "5.0.16",
+    "@fontsource-variable/inter": "5.2.8",
     "@fontsource-variable/jetbrains-mono": "5.0.21",
     "@fontsource/poiret-one": "^5.0.20",
-    "@tailwindcss/container-queries": "^0.1.1",
-    "@tailwindcss/forms": "^0.5.3",
-    "autoprefixer": "^10.4.12",
-    "esbuild-style-plugin": "^1.6.1",
-    "glob": "^7.2.3",
+    "@radix-ui/react-slot": "1.1.2",
+    "@tailwindcss/forms": "^0.5.9",
+    "@tailwindcss/postcss": "^4.2.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",
-    "tailwind-merge": "^2.2.1",
-    "tailwind-scrollbar": "^3.1.0",
-    "tailwindcss": "~3.4.1",
-    "tailwindcss-logical": "^3.0.0",
-    "tailwindcss-radix": "^2.8.0",
-    "@dxos/node-std": "0.8.3",
-    "@dxos/util": "0.8.3"
+    "postcss-nesting": "^13.0.1",
+    "tailwind-merge": "^3.5.0",
+    "tailwind-scrollbar": "^4.0.0",
+    "tailwindcss": "^4.2.0",
+    "tailwindcss-radix": "^4.0.2",
+    "@dxos/log": "0.8.4-main.05e74ebcff",
+    "@dxos/node-std": "0.8.4-main.05e74ebcff",
+    "@dxos/util": "0.8.4-main.05e74ebcff"
   },
   "devDependencies": {
-    "@ch-ui/colors": "1.2.1",
     "@types/lodash.merge": "^4.6.6",
     "@types/postcss-import": "^14.0.3",
-    "esbuild": "0.25.10",
-    "vite": "7.1.9",
-    "@dxos/ui-types": "0.0.0"
+    "esbuild": "0.28.0",
+    "vite": "^8.0.13",
+    "@dxos/ui-types": "0.8.4-main.05e74ebcff"
+  },
+  "peerDependencies": {
+    "react": "~19.2.3"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "audit-classes": "npx tsx bin/audit-classes.mts",
     "tailwind-check": "tailwindcss -i ./dist/plugin/node-esm/theme.css --config ./src/tailwind.ts --content \"./src/**/*.{js,ts,jsx,tsx,vue}\" --check"
   }
 }

package/src/Theme.stories.tsx

@@ -0,0 +1,224 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta } from '@storybook/react-vite';
+import React from 'react';
+
+import { hueShades, hues } from './defs';
+import { mx } from './util';
+
+// prettier-ignore
+const neutralShades: [number, string][] = [
+  [50,  'bg-neutral-50'],
+  [75,  'bg-neutral-75'],
+  [100, 'bg-neutral-100'],
+  [200, 'bg-neutral-200'],
+  [250, 'bg-neutral-250'],
+  [300, 'bg-neutral-300'],
+  [400, 'bg-neutral-400'],
+  [500, 'bg-neutral-500'],
+  [600, 'bg-neutral-600'],
+  [700, 'bg-neutral-700'],
+  [750, 'bg-neutral-750'],
+  [800, 'bg-neutral-800'],
+  [900, 'bg-neutral-900'],
+  [925, 'bg-neutral-925'],
+  [950, 'bg-neutral-950'],
+];
+
+const ColorSwatch = ({ hue }: { hue: string }) => {
+  return (
+    <div
+      style={{
+        borderColor: `var(--color-${hue}-border)`,
+      }}
+      className={mx('shrink-0 aspect-square w-36 grid grid-rows-3 border-2 overflow-hidden rounded-md')}
+    >
+      <div
+        style={{
+          backgroundColor: `var(--color-base-surface)`,
+          color: `var(--color-${hue}-text)`,
+        }}
+        className='p-2 text-sm'
+      >
+        {hue}
+      </div>
+      <div
+        style={{
+          backgroundColor: `var(--color-${hue}-fill)`,
+          color: `var(--color-${hue}-text)`,
+        }}
+        className='px-1 text-sm flex items-center'
+      >
+        <svg className='h-6 w-6'>
+          <use href='/icons.svg#ph--aperture--regular' />
+        </svg>
+      </div>
+      <div
+        style={{
+          backgroundColor: `var(--color-${hue}-surface)`,
+          color: `var(--color-${hue}-foreground)`,
+        }}
+        className='p-2 text-sm'
+      >
+        {hue}
+      </div>
+    </div>
+  );
+};
+
+const HueSwatch = ({ hue, shades }: { hue: string; shades: readonly number[] }) => (
+  <div className='flex gap-1'>
+    {shades.map((shade) => (
+      <div
+        key={shade}
+        className='shrink-0 aspect-square w-24 flex flex-col rounded-sm'
+        style={{ backgroundColor: `var(--color-${hue}-${shade})` }}
+      >
+        <span
+          className='flex flex-col h-full justify-between text-sm p-2'
+          style={{ color: shade <= 500 ? 'black' : 'white' }}
+        >
+          <span className='text-xs'>{shade}</span>
+          {shade === 500 && <span className='text-xs'>{hue}</span>}
+        </span>
+      </div>
+    ))}
+  </div>
+);
+
+const meta = {
+  title: 'ui/ui-theme/Theme',
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta;
+
+export default meta;
+
+export const Styles = {
+  render: () => {
+    return (
+      <div className='p-4'>
+        <div className='flex flex-wrap gap-2'>
+          {['neutral', ...hues].map((hue) => (
+            <ColorSwatch key={hue} hue={hue} />
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Colors = {
+  render: () => {
+    return (
+      <div className='p-4'>
+        <div className='flex flex-col gap-1'>
+          {['neutral', ...hues].map((hue) => (
+            <HueSwatch key={hue} hue={hue} shades={hueShades} />
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Neutral = {
+  render: () => {
+    return (
+      <div className='p-4'>
+        <div className='flex flex-col items-center'>
+          {neutralShades.map(([value, className]) => (
+            <div
+              key={value}
+              className={mx(
+                'h-12 w-48 p-2 text-right text-sm',
+                className,
+                value <= 500 ? 'text-neutral-950' : 'text-neutral-50',
+              )}
+            >
+              {value}
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Surfaces = {
+  render: () => {
+    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-current-surface', label: 'current' },
+            { className: 'bg-hover-surface', label: 'hover' },
+            { 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}
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Tags = {
+  render: () => {
+    return (
+      <div className='p-4'>
+        <div className='flex flex-col gap-1'>
+          {['neutral', ...hues].map((hue) => (
+            <div key={hue} className='grid grid-cols-[8rem_8rem]'>
+              <div>
+                <span className='dx-tag' data-hue={hue}>
+                  {hue}
+                </span>
+              </div>
+              <div>
+                <span className='dx-text text-sm' data-hue={hue}>
+                  {hue}
+                </span>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    );
+  },
+};
+
+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={mx(
+              'flex items-center font-mono text-2xl text-test-experimental',
+              'p-form-padding w-card-min-width grid grid-cols-[min-content_1fr_min-content]',
+            )}
+          >
+            <span className='animate-blink text-error-text'>*</span>
+            <span className='text-center'>experimental</span>
+            <span className='animate-blink text-error-text'>*</span>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};

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

@@ -0,0 +1,43 @@
+/**
+ * Base utilities.
+ */
+
+@layer dx-base {
+  :root {
+    color-scheme: light;
+    touch-action: pan-x pan-y;
+    font-synthesis: none;
+    font-variation-settings:
+      'wght' 400,
+      'slnt' 0;
+    scroll-padding-block-start: var(--spacing-14);
+    scroll-padding-block-end: var(--spacing-2);
+    @apply font-body;
+  }
+
+  .dark {
+    color-scheme: dark;
+  }
+
+  button {
+    @apply cursor-pointer;
+    -webkit-tap-highlight-color: transparent;
+  }
+}
+
+@layer dx-tokens {
+  :root {
+    --dx-tag-padding-block: var(--spacing-tag-padding-block);
+  }
+
+  html,
+  html.dark,
+  html .dark,
+  .sb-show-main {
+    background-color: var(--color-base-surface);
+    color: var(--color-base-foreground);
+    --surface-bg: var(--color-base-surface);
+    --foreground: var(--color-base-foreground);
+    --description-text: var(--color-description);
+  }
+}