@dxos/ui-theme 0.8.4-main.c85a9c8dae → 0.8.4-main.e00bdcdb52

package/src/css/utilities.css

@@ -1,7 +1,118 @@
 /**
- * Misc
+ * Tailwind utility classes.
  */
 
-@utility dx-icon-inline {
-  @apply inline-block align-[-0.125em];
+/**
+ * Layout rules for flex-based scroll containment:
+ * `flex flex-col`
+ *   On a container: makes it a flex column so children stack and can use `flex-1`.
+ * `flex-1`
+ *   On a child: grows to fill the flex parent. Requires the parent to be `flex`.
+ * `min-h-0` (alongside `flex-1`):
+ *   Overrides default flex children: `min-height:auto` (sized to content), which prevents shrinking.
+ *   Allows element to shrink and trigger overflow/scrolling.
+ *   Always pair with `flex-1` when scroll is needed.
+ * `h-full`:
+ *   Fills 100% of the parent's *computed* height.
+ *   Use when the parent has a definite height but is not a flex container (e.g. `overflow:hidden` wrapper).
+ *   Unlike `flex-1`, does not require the parent to be flex.
+ *
+ * Pattern for a scrollable region inside a flex ancestor:
+ *   ancestor         → `flex flex-col`             (or `flex flex-row`)
+ *   scroll root      → `flex-1 min-h-0`            (fills ancestor, can shrink)
+ *   scroll viewport  → `h-full overflow-y-scroll`  (fills root, scrolls)
+ */
+
+/**
+ * Fills the available space.
+ */
+@utility dx-expander {
+  @apply flex-1 min-h-0 min-w-0 h-full w-full;
+}
+
+/**
+ * Container that fills the available space (extends dx-expander with overflow clipping).
+ */
+@utility dx-container {
+  @apply dx-expander overflow-hidden;
+}
+
+/**
+ * Column that fills the available space (extends dx-expander with overflow clipping).
+ */
+@utility dx-column {
+  @apply flex-1 min-w-0 w-full;
+}
+
+/**
+ * Fullscreen
+ */
+@utility dx-fullscreen {
+  @apply absolute inset-0;
+}
+
+/**
+ * Visual warning to indicate incorrect usage of `slottable`.
+ */
+@utility dx-slot-warning {
+  @apply border border-rose-500 border-dashed;
+}
+
+/**
+ * Pseudo-element overlay for ring indicators (focus, current, etc.).
+ *
+ * A standard CSS `box-shadow` ring is painted behind child content, so children with
+ * opaque backgrounds (e.g., cards, avatars) obscure it. By painting the ring on an
+ * absolutely-positioned `::after` pseudo-element that sits above the element's children
+ * in stacking order, the ring is always visible regardless of child backgrounds.
+ *
+ * The pseudo-element inherits `border-radius` from its parent and is `pointer-events-none`
+ * so it doesn't interfere with interactions. The ring starts transparent; consumers
+ * activate it conditionally (e.g., `focus:after:ring-*`, `aria-[current=true]:after:ring-*`).
+ */
+@utility dx-ring-pseudo {
+  @apply relative after:content-[""] after:absolute after:inset-0 after:rounded-[inherit]
+    after:pointer-events-none after:ring after:ring-inset after:ring-transparent;
+}
+
+/**
+ * Shimmer text — animates opacity left → right across the contained text.
+ * See @keyframes shimmer-text in theme/animation.css for the keyframe definition.
+ * Geometry: mask-size 200% 100% with mask-repeat: repeat-x means each tile is
+ * 2× the element width; the keyframe slides mask-position-x by 200% (one full
+ * tile period), giving a seamless loop. The 5-stop gradient (0.4 → 1.0 → 0.4)
+ * produces a single bright pulse per cycle that traverses left → right during
+ * the first half, with a brief calm interval during the second half.
+ */
+@utility shimmer-text {
+  mask-image: linear-gradient(
+    90deg,
+    rgba(0, 0, 0, 0.4) 0%,
+    rgba(0, 0, 0, 0.4) 30%,
+    rgba(0, 0, 0, 1) 50%,
+    rgba(0, 0, 0, 0.4) 70%,
+    rgba(0, 0, 0, 0.4) 100%
+  );
+  -webkit-mask-image: linear-gradient(
+    90deg,
+    rgba(0, 0, 0, 0.4) 0%,
+    rgba(0, 0, 0, 0.4) 30%,
+    rgba(0, 0, 0, 1) 50%,
+    rgba(0, 0, 0, 0.4) 70%,
+    rgba(0, 0, 0, 0.4) 100%
+  );
+  mask-size: 200% 100%;
+  -webkit-mask-size: 200% 100%;
+  mask-repeat: repeat-x;
+  -webkit-mask-repeat: repeat-x;
+  animation: shimmer-text 2s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .shimmer-text {
+    animation: none;
+    mask-image: none;
+    -webkit-mask-image: none;
+    opacity: 0.6;
+  }
 }

package/src/defs.ts

@@ -7,7 +7,7 @@ import { type ChromaticPalette } from '@dxos/ui-types';
 /**
  * Translation namespace for OS-level translations.
  */
-export const osTranslations = 'dxos.org/i18n/os';
+export const osTranslations = 'org.dxos.i18n.os';
 
 /**
  * Available color hues for UI components.

package/src/fragments/AUDIT.md

@@ -0,0 +1,57 @@
+# Fragment Definitions Audit
+
+External packages importing fragment definitions from `ui-theme/src/fragments`.
+
+## Current Fragment Exports
+
+| File          | Definition                            | External | Internal |
+| ------------- | ------------------------------------- | -------- | -------- |
+| `density.ts`  | `densityBlockSize`                    | -        | 1        |
+| `density.ts`  | `coarseBlockSize`                     | -        | 1        |
+| `density.ts`  | `coarseDimensions`                    | -        | 1        |
+| `density.ts`  | `fineBlockSize`                       | -        | 1        |
+| `density.ts`  | `fineDimensions`                      | -        | 1        |
+| `disabled.ts` | `staticDisabled`                      | -        | 1        |
+| `disabled.ts` | `dataDisabled`                        | -        | 1        |
+| `focus.ts`    | `focusRing`                           | 2        | 5        |
+| `focus.ts`    | `subduedFocus`                        | -        | 2        |
+| `focus.ts`    | `staticFocusRing`                     | -        | 1        |
+| `hover.ts`    | `subtleHover`                         | 4        | -        |
+| `hover.ts`    | `ghostHover`                          | 8        | 2        |
+| `hover.ts`    | `ghostFocusWithin`                    | 1        | -        |
+| `hover.ts`    | `hoverableControls`                   | 9        | -        |
+| `hover.ts`    | `groupHoverControlItemWithTransition` | 2        | -        |
+| `hover.ts`    | `hoverableFocusedKeyboardControls`    | 1        | -        |
+| `hover.ts`    | `hoverableFocusedWithinControls`      | 9        | -        |
+| `hover.ts`    | `hoverableOpenControlItem`            | 3        | -        |
+| `hover.ts`    | `hoverableControlItem`                | 7        | -        |
+| `text.ts`     | `descriptionTextPrimary`              | 1        | -        |
+| `text.ts`     | `descriptionMessage`                  | 5        | -        |
+
+## Summary
+
+**Total fragments:** 21
+**Total imports (external + internal):** 96
+
+- **External:** 63
+- **Internal:** 33
+
+**Most imported overall:**
+
+- `hoverableControls` (9 external)
+- `hoverableFocusedWithinControls` (9 external)
+- `ghostHover` (8 external + 2 internal = 10 total)
+- `hoverableControlItem` (7 external)
+- `focusRing` (2 external + 5 internal = 7 total)
+
+**Internal imports by file:**
+
+- `input.ts`: 8 definitions (coarseBlockSize, coarseDimensions, fineBlockSize, fineDimensions, focusRing, staticDisabled, staticFocusRing, subduedFocus)
+- `list.ts`: 3 definitions (densityBlockSize, focusRing, ghostHover)
+- `menu.ts`: 2 definitions (dataDisabled, subduedFocus)
+- `button.ts`, `link.ts`, `popover.ts`, `toast.ts`: 1 definition each (ghostHover, focusRing, focusRing, focusRing)
+
+**Completely unused:** 7 fragments
+
+- `subtleHover` from `hover.ts`
+- `hoverableOpenControlItem`, `groupHoverControlItemWithTransition` from `hover.ts` (only 2-3 uses)

package/src/fragments/density.ts

@@ -4,10 +4,13 @@
 
 import { type Density } from '@dxos/ui-types';
 
-export const coarseBlockSize = 'min-h-[2.5rem]';
-export const coarseDimensions = `${coarseBlockSize} px-3`;
+const fineBlockSize = 'min-h-[2.5rem] pointer-fine:min-h-[2rem]';
+const coarseBlockSize = 'min-h-[2.5rem]';
 
-export const fineBlockSize = 'min-h-[2.5rem] pointer-fine:min-h-[2rem]';
-export const fineDimensions = `${fineBlockSize} px-2`;
+const fineDimensions = `${fineBlockSize} px-2`;
+const coarseDimensions = `${coarseBlockSize} px-3`;
 
-export const densityBlockSize = (density: Density = 'coarse') => (density === 'fine' ? fineBlockSize : coarseBlockSize);
+export const densityDimensions = (density: Density = 'fine') =>
+  density === 'fine' ? fineDimensions : coarseDimensions;
+
+export const densityBlockSize = (density: Density = 'fine') => (density === 'fine' ? fineBlockSize : coarseBlockSize);

package/src/fragments/index.ts

@@ -2,14 +2,9 @@
 // Copyright 2022 DXOS.org
 //
 
-// TODO(burdon): Replace fragments with utility and component classes.
+// TODO(burdon): Remove export of fragments.
 
 export * from './density';
 export * from './disabled';
-export * from './elevation';
-export * from './focus';
 export * from './hover';
-export * from './selected';
-export * from './size';
 export * from './text';
-export * from './valence';

package/src/fragments/text.ts

@@ -2,10 +2,5 @@
 // Copyright 2022 DXOS.org
 //
 
-/**
- * Content areas that contain the text editor.
- */
-export const textBlockWidth = 'w-full max-w-text-content mx-auto';
-
-export const descriptionTextPrimary = 'text-sm font-normal text-base-surface-text';
+// TODO(burdon): Replace with Message component.
 export const descriptionMessage = 'text-description border border-dashed border-separator rounded-sm p-4';

package/src/index.ts

@@ -4,5 +4,5 @@
 
 export * from './defs';
 export * from './fragments';
-export * from './theme/index';
+export * from './theme';
 export * from './util';

package/src/{theme.css → main.css}

@@ -30,10 +30,12 @@
 @import './css/components/button.css';
 @import './css/components/checkbox.css';
 @import './css/components/dialog.css';
-@import './css/components/focus-ring.css';
+@import './css/components/focus.css';
+@import './css/components/icon.css';
 @import './css/components/panel.css';
 @import './css/components/link.css';
 @import './css/components/scrollbar.css';
+@import './css/components/selected.css';
 @import './css/components/surface.css';
 @import './css/components/tag.css';
 @import './css/components/text.css';
@@ -75,9 +77,11 @@
  */
 @variant dark (&:where(.dark, .dark *));
 
-/**
- * Custom variants.
- */
-@custom-variant is-current (&[aria-current]:not([aria-current="false"]));
-@custom-variant hover-hover (@media (hover: hover));
+/** Mobile */
+@custom-variant pointer-coarse (@media (pointer: coarse));
+/** Web */
 @custom-variant pointer-fine (@media (pointer: fine));
+/** Supports mouse/trackpad (Web) */
+@custom-variant hover-hover (@media (hover: hover));
+/** Active navigation */
+@custom-variant is-current (&[aria-current]:not([aria-current="false"]));

package/src/plugins/ThemePlugin.ts

@@ -4,11 +4,10 @@
 
 /* eslint-disable no-console */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-
 import tailwindcss from '@tailwindcss/postcss';
 import autoprefixer from 'autoprefixer';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import postcssImport from 'postcss-import';
 import postcssNesting from 'postcss-nesting';
 import { type HtmlTagDescriptor, type Plugin, type UserConfig } from 'vite';
@@ -44,16 +43,15 @@ export type ThemePluginOptions = {
  */
 export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
   // Prefer source CSS if available (monorepo dev), fall back to dist for installed package.
-  const srcThemePath = resolve(import.meta.dirname, ROOT, 'src/theme.css');
-  const distThemePath = resolve(import.meta.dirname, '../theme.css');
+  const srcThemePath = resolve(import.meta.dirname, ROOT, 'src/main.css');
+  const distThemePath = resolve(import.meta.dirname, '../main.css');
   const isMonorepo = existsSync(srcThemePath);
 
-  // dark-mode.ts is always read from src (ships via "files": ["src"] in package.json).
-  // In monorepo: import.meta.dirname = src/plugins/, so the file is right here.
-  // In installed package: import.meta.dirname = dist/plugin/{format}/plugins/, so go up 4 levels.
-  const srcDarkModePath = resolve(import.meta.dirname, ROOT, 'src/plugins/dark-mode.ts');
-  const distDarkModePath = resolve(import.meta.dirname, ROOT, 'src/plugins/dark-mode.ts');
-  const darkModeScriptPath = existsSync(srcDarkModePath) ? srcDarkModePath : distDarkModePath;
+  // Static assets shipped via "files": ["src"] in package.json.
+  // Both monorepo and installed package resolve to the same src/plugins/ directory.
+  const pluginsDir = resolve(import.meta.dirname, ROOT, 'src/plugins');
+  const darkModeScriptPath = resolve(pluginsDir, 'dark-mode.ts');
+  const mainCssPath = resolve(pluginsDir, 'main.css');
 
   const config: ThemePluginOptions = {
     srcCssPath: isMonorepo ? srcThemePath : distThemePath,
@@ -112,23 +110,13 @@ export const ThemePlugin = (options: ThemePluginOptions): Plugin => {
         injectTo: 'head-prepend',
       };
 
-      // Critical pre-CSS fallbacks so text is readable before (and during) Vite HMR.
-      // In dev mode Vite injects CSS via JS; when an HMR update fires the old style tag is
-      // removed before the new one is inserted, briefly leaving all --color-* vars undefined.
-      // These static approximations of neutral-50/950 survive that gap.
-      // Values are intentionally kept in sync with @theme tokens in semantic.css.
+      // Critical styles: font sizing, overscroll, color fallbacks.
+      // Loaded from critical.css to keep styles maintainable and out of index.html.
       const criticalTag: HtmlTagDescriptor = {
         tag: 'style',
         attrs: { 'data-dxos-critical': '' },
         injectTo: 'head-prepend',
-        children: [
-          ':root { color-scheme: light; }',
-          'html { color: oklch(0.145 0 0); background-color: oklch(0.985 0 0); }', // ≈ neutral-950 / neutral-50
-          'html.dark { color-scheme: dark; color: oklch(0.985 0 0); background-color: oklch(0.145 0 0); }',
-          '@media (prefers-color-scheme: dark) {',
-          '  html:not(.dark) { color: oklch(0.985 0 0); background-color: oklch(0.145 0 0); }',
-          '}',
-        ].join('\n'),
+        children: readFileSync(mainCssPath, 'utf-8'),
       };
 
       return [darkModeTag, layersTag, criticalTag];

package/src/plugins/main.css

@@ -0,0 +1,45 @@
+/*
+ * Critical styles injected into <head> by the Vite ThemePlugin before any stylesheets load.
+ * Ensures text is readable and layout is stable on the very first paint.
+ */
+
+/* Base font size: larger default for touch devices, smaller for precision pointers. */
+html {
+  font-size: 20px;
+}
+@media (pointer: fine) {
+  html {
+    font-size: 16px;
+  }
+}
+
+/* Prevent overscroll bounce and ensure full viewport height. */
+html,
+body {
+  overscroll-behavior: none;
+  -webkit-overflow-scrolling: touch;
+}
+body {
+  height: 100vh;
+}
+
+/* Pre-CSS color fallbacks so text is readable before and during Vite HMR. */
+/* Values are intentionally kept in sync with @theme tokens in semantic.css. */
+:root {
+  color-scheme: light;
+}
+html {
+  color: oklch(0.145 0 0);
+  background-color: oklch(0.985 0 0);
+}
+html.dark {
+  color-scheme: dark;
+  color: oklch(0.985 0 0);
+  background-color: oklch(0.145 0 0);
+}
+@media (prefers-color-scheme: dark) {
+  html:not(.dark) {
+    color: oklch(0.985 0 0);
+    background-color: oklch(0.145 0 0);
+  }
+}

package/src/theme/components/avatar.ts

@@ -4,8 +4,7 @@
 
 import { type ComponentFunction, type Size, type Theme } from '@dxos/ui-types';
 
-import { getSize, getSizeHeight } from '../../fragments';
-import { mx } from '../../util';
+import { mx, getSize, getHeight } from '../../util';
 
 export type AvatarStyleProps = Partial<{
   size: Size;
@@ -30,7 +29,7 @@ export const avatarDescription: ComponentFunction<AvatarStyleProps> = ({ srOnly
   mx('text-description', srOnly && 'sr-only', ...etc);
 
 export const avatarFrame: ComponentFunction<AvatarStyleProps> = ({ variant }, ...etc) =>
-  mx('w-full h-full bg-(--surface-bg)', variant === 'circle' ? 'rounded-full' : 'rounded-sm', ...etc);
+  mx('h-full w-full bg-(--surface-bg)', variant === 'circle' ? 'rounded-full' : 'rounded-sm', ...etc);
 
 export const avatarStatusIcon: ComponentFunction<AvatarStyleProps> = ({ status, size = 3 }, ...etc) =>
   mx(
@@ -75,7 +74,7 @@ export const avatarGroupLabel: ComponentFunction<AvatarStyleProps> = ({ size, sr
     srOnly
       ? 'sr-only'
       : 'rounded-full truncate text-sm leading-none py-1 px-2 relative z-[1] flex items-center justify-center',
-    size && getSizeHeight(size),
+    size && getHeight(size),
     ...etc,
   );
 

package/src/theme/components/button.ts

@@ -32,7 +32,7 @@ export type ButtonStyleProps = Partial<{
 }>;
 
 const buttonRoot: ComponentFunction<ButtonStyleProps> = (_props, ...etc) => {
-  return mx('dx-button dx-focus-ring group max-w-full [&_span]:truncate', ...etc);
+  return mx('dx-button dx-focus-ring group [&_span]:truncate', ...etc);
 };
 
 const buttonGroup: ComponentFunction<{ elevation?: Elevation }> = (_props, ...etc) => {

package/src/theme/components/card.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type ComponentFunction, type Theme } from '@dxos/ui-types';
+import { type ComponentFunction, type Density, type Theme } from '@dxos/ui-types';
 
 import { mx } from '../../util';
 
@@ -11,30 +11,30 @@ export type CardStyleProps = {
   fullWidth?: boolean;
   srOnly?: boolean;
   variant?: 'default' | 'subtitle' | 'description';
-  coarse?: boolean;
+  density?: Density;
   truncate?: boolean;
+  padding?: boolean;
 };
 
 const cardRoot: ComponentFunction<CardStyleProps> = ({ border, fullWidth }, ...etc) =>
   mx(
-    'dx-card group/card relative flex flex-col w-full min-h-(--dx-rail-item) dx-card-min-width overflow-hidden',
+    'dx-card dx-card-min-width dx-card-max-width min-h-(--dx-rail-item) group/card relative overflow-hidden',
     border &&
       'bg-card-surface border border-separator dark:border-subdued-separator rounded-xs dx-focus-ring-group-y-indicator',
     fullWidth && 'max-w-none!',
     ...etc,
   );
 
-const cardToolbar: ComponentFunction<CardStyleProps> = ({ coarse }, ...etc) =>
+const cardToolbar: ComponentFunction<CardStyleProps> = (_, ...etc) =>
   mx(
-    'dx-card__toolbar dx-density-fine bg-transparent col-span-3 !grid grid-cols-subgrid [contain:none]',
-    coarse && 'grid-cols-[var(--dx-l0-avatar-size)_minmax(0,1fr)_var(--dx-rail-item)]',
+    'dx-card__toolbar dx-density-fine bg-transparent p-0! gap-0! col-span-3 grid! grid-cols-subgrid! [contain:none]',
     ...etc,
   );
 
 const cardTitle: ComponentFunction<CardStyleProps> = (_props, ...etc) => mx('dx-card__title grow truncate', ...etc);
 
 const cardContent: ComponentFunction<CardStyleProps> = (_props, ...etc) =>
-  mx('dx-card__content contents [&>:last-child]:pb-1', ...etc);
+  mx('dx-card__content contents pb-1 last:pb-0', ...etc);
 
 const cardHeading: ComponentFunction<CardStyleProps> = ({ variant = 'default' }, ...etc) =>
   mx(
@@ -46,9 +46,9 @@ const cardHeading: ComponentFunction<CardStyleProps> = ({ variant = 'default' },
 
 const cardText: ComponentFunction<CardStyleProps> = ({ variant = 'default', truncate: _truncate }, ...etc) =>
   mx(
-    'dx-card__text flex overflow-hidden',
+    'dx-card__text items-center overflow-hidden',
     variant === 'default' && 'py-1',
-    variant === 'description' && 'py-1.5',
+    variant === 'description' && 'py-1.5 text-description',
     ...etc,
   );
 
@@ -73,14 +73,22 @@ const cardLink: ComponentFunction<CardStyleProps> = (_props, ...etc) =>
 const cardLinkLabel: ComponentFunction<CardStyleProps> = (_props, ...etc) =>
   mx('dx-card__link-label min-w-0 flex-1 truncate', ...etc);
 
-const cardIconBlock: ComponentFunction<CardStyleProps> = (_props, ...etc) =>
-  mx('dx-card__icon-block grid h-[var(--dx-rail-item)] w-[var(--dx-rail-item)] place-items-center', ...etc);
+const cardRow: ComponentFunction<CardStyleProps> = (_, ...etc) =>
+  mx('dx-card__row col-span-3 grid grid-cols-subgrid', ...etc);
+
+const cardIconBlock: ComponentFunction<CardStyleProps> = ({ padding }, ...etc) =>
+  mx(
+    'dx-card__icon-block grid h-[var(--dx-rail-item)] w-[var(--dx-rail-item)] place-items-center',
+    padding && '[&>*]:p-1',
+    ...etc,
+  );
 
 export const cardTheme: Theme<CardStyleProps> = {
   root: cardRoot,
   toolbar: cardToolbar,
   title: cardTitle,
   content: cardContent,
+  row: cardRow,
   heading: cardHeading,
   text: cardText,
   'text-span': cardTextSpan,

package/src/theme/components/dialog.ts

@@ -5,6 +5,7 @@
 import { type ComponentFunction, type Elevation, type Theme } from '@dxos/ui-types';
 
 import { mx } from '../../util';
+import { withColumn } from '../primitives/column';
 
 export type DialogSize = 'sm' | 'md' | 'lg' | 'xl';
 
@@ -35,13 +36,13 @@ export const dialogContent: ComponentFunction<DialogStyleProps> = ({ inOverlayLa
 };
 
 export const dialogHeader: ComponentFunction<DialogStyleProps> = (_props, ...etc) =>
-  mx('dx-dialog__header flex pb-4 items-center justify-between', ...etc);
+  mx('dx-dialog__header flex pb-4 items-center justify-between', withColumn.center(), ...etc);
 
 export const dialogBody: ComponentFunction<DialogStyleProps> = (_props, ...etc) =>
-  mx('dx-dialog__body flex flex-col h-full py-2 gap-2', ...etc);
+  mx('dx-dialog__body dx-expander', withColumn.propagate(), ...etc);
 
 export const dialogActionBar: ComponentFunction<DialogStyleProps> = (_props, ...etc) =>
-  mx('dx-dialog__actionbar flex items-center pt-4 gap-2 dx-density-coarse', ...etc);
+  mx('dx-dialog__actionbar flex items-center pt-4 gap-2 dx-density-coarse', withColumn.center(), ...etc);
 
 export const dialogTitle: ComponentFunction<DialogStyleProps> = ({ srOnly }, ...etc) =>
   mx('dx-dialog__title', srOnly && 'sr-only', ...etc);

package/src/theme/components/focus.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type ComponentFunction, type Theme } from '@dxos/ui-types';
+
+import { mx } from '../../util';
+
+export type FocusStyleProps = {
+  border?: boolean;
+};
+
+/**
+ * Focus ring styles shared by Focus.Group and Focus.Item.
+ * Uses a `::after` pseudo-element overlay so the ring paints above child content
+ * (inset box-shadow alone is obscured by children with backgrounds).
+ * The pseudo-element is `pointer-events-none` and absolutely positioned over the element.
+ * When `border` is true, a subdued CSS border is always visible (e.g., for grid cell edges).
+ */
+const focusRing: ComponentFunction<FocusStyleProps> = ({ border }, ...etc) =>
+  mx(
+    'dx-ring-pseudo outline-hidden',
+    'focus:after:ring-neutral-focus-indicator',
+    'data-[focus-state=active]:after:ring-neutral-focus-indicator',
+    'data-[focus-state=error]:after:ring-rose-500',
+    border && 'border border-separator',
+    ...etc,
+  );
+
+export const focusTheme: Theme<FocusStyleProps> = {
+  group: focusRing,
+  item: focusRing,
+};

package/src/theme/components/icon-button.ts

@@ -5,14 +5,15 @@
 import type { ComponentFunction, Theme } from '@dxos/ui-types';
 
 import { mx } from '../../util';
-
 import { type ButtonStyleProps } from './button';
 
-export type IconButtonStyleProps = ButtonStyleProps & { iconOnly?: boolean };
+export type IconButtonStyleProps = ButtonStyleProps & {
+  iconOnly?: boolean;
+  square?: boolean;
+};
 
-// TODO(burdon): Gap/font size should depend on density.
-export const iconButtonRoot: ComponentFunction<IconButtonStyleProps> = ({ iconOnly }, ...etc) => {
-  return mx('gap-2', iconOnly && 'p-icon-button-padding min-h-0', ...etc);
+export const iconButtonRoot: ComponentFunction<IconButtonStyleProps> = ({ iconOnly, square }, ...etc) => {
+  return mx('px-1.5', !iconOnly && 'gap-2', square && 'aspect-square', ...etc);
 };
 
 export const iconButtonTheme: Theme<IconButtonStyleProps> = {

package/src/theme/components/icon.ts

@@ -4,15 +4,24 @@
 
 import { type ComponentFunction, type Size, type Theme } from '@dxos/ui-types';
 
-import { getSize } from '../../fragments';
-import { mx } from '../../util';
+import { getSize, mx } from '../../util';
 
 export type IconStyleProps = {
   size?: Size;
 };
 
-export const iconRoot: ComponentFunction<IconStyleProps> = ({ size }, etc) =>
-  mx('shrink-0 h-[1em] w-[1em] text-[var(--icons-color,currentColor)]', size && getSize(size), etc);
+/**
+ * Size can be specified directly, or inherited from a container (e.g., toolbar).
+ */
+export const iconRoot: ComponentFunction<IconStyleProps> = ({ size }, etc) => {
+  return mx(
+    'shrink-0 text-[var(--icons-color,currentColor)]',
+    size
+      ? getSize(size)
+      : '[width:var(--icon-size,var(--dx-default-icons-size))] [height:var(--icon-size,var(--dx-default-icons-size))]',
+    etc,
+  );
+};
 
 export const iconTheme: Theme<IconStyleProps> = {
   root: iconRoot,

package/src/theme/components/index.ts

@@ -7,6 +7,7 @@ export * from './breadcrumb';
 export * from './card';
 export * from './button';
 export * from './dialog';
+export * from './focus';
 export * from './icon';
 export * from './icon-button';
 export * from './input';