@dxos/ui-theme 0.10.0 → 0.11.0

package/src/css/components/surface.css

@@ -2,108 +2,215 @@
  * Surfaces
  *
  * A surface zone paints a background AND publishes its colour as `--surface-bg`, so descendant
- * controls can derive a visible hover/current highlight from the actual surface (see the
- * derivation block below) and surface-matching elements (avatars, gradients) can read it directly.
+ * aspects (bar, well, hover, current, selected) derive from the actual surface and stay visible at
+ * any elevation, and surface-matching elements (avatars, gradients) can read it directly.
  *
- * Always enter a surface via one of these `dx-*-surface` classes. A bare `bg-*-surface` utility
- * paints the colour but does NOT publish `--surface-bg`, so control hover collapses onto the
- * base-surface fallback and can become invisible when the surface shares that elevation.
+ * Enter a zone with `data-surface="<level>"` — the levels are the ladder in `theme/surfaces.css`.
+ * The `dx-*-surface` classes are role-named aliases of the same thing, kept because they read well
+ * at call sites (`dx-card-surface` says more than `data-surface="raised"`).
+ *
+ * A bare `bg-*-surface` utility paints the colour but does NOT publish `--surface-bg`, so every
+ * aspect inside it collapses onto the base-surface fallback — never use one to enter a zone.
  */
 
 @layer dx-components {
-  .dx-base-surface {
-    @apply bg-base-surface text-base-fg;
-    --surface-bg: var(--color-base-surface);
+  /* The outer rails sit at the same depth as the deck gaps: they frame the panels rather than
+     belonging to them, so L0/R0 read one step behind the L1/R1 sidebars they flank. */
+  [data-surface='sunken'],
+  .dx-deck-surface {
+    --surface-bg: var(--dx-surface-sunken);
   }
 
-  .dx-deck-surface {
-    @apply bg-deck-surface text-base-fg;
-    --surface-bg: var(--color-deck-surface);
+  [data-surface='chrome'],
+  .dx-sidebar-surface,
+  .dx-header-surface {
+    --surface-bg: var(--dx-surface-chrome);
   }
 
-  .dx-sidebar-surface {
-    @apply bg-sidebar-surface text-base-fg;
-    --surface-bg: var(--color-sidebar-surface);
+  /* The rails are not levels: they carry their own tone per theme (see surfaces.css). */
+  .dx-l0-surface,
+  .dx-r0-surface {
+    --surface-bg: var(--color-l0-surface);
   }
 
-  .dx-header-surface {
-    @apply bg-header-surface text-base-fg;
-    --surface-bg: var(--color-header-surface);
+  .dx-l1-surface,
+  .dx-r1-surface {
+    --surface-bg: var(--color-l1-surface);
+  }
+
+  [data-surface='base'],
+  .dx-base-surface,
+  .dx-attention-surface {
+    --surface-bg: var(--dx-surface-base);
   }
 
+  [data-surface='raised'],
   .dx-card-surface {
-    @apply bg-card-surface text-base-fg;
-    --surface-bg: var(--color-card-surface);
+    --surface-bg: var(--dx-surface-raised);
   }
 
-  .dx-group-surface {
-    @apply bg-group-surface text-base-fg;
-    --surface-bg: var(--color-group-surface);
+  [data-surface='overlay'],
+  .dx-modal-surface {
+    --surface-bg: var(--dx-surface-overlay);
   }
 
-  .dx-input-surface {
-    @apply bg-input-surface text-base-fg;
-    --surface-bg: var(--color-input-surface);
+  [data-surface='popup'],
+  .dx-popover-surface {
+    --surface-bg: var(--dx-surface-popup);
   }
 
+  /*
+   * Aspect zones. These do not pick a level — they take a step off whatever hosts them and then
+   * republish that as `--surface-bg`, so a control inside a toolbar or a well derives its own
+   * states from the aspect rather than from the level underneath it.
+   */
+  [data-surface='bar'],
   .dx-toolbar-surface {
-    @apply bg-toolbar-surface text-base-fg;
     --surface-bg: var(--color-toolbar-surface);
   }
 
-  .dx-modal-surface {
-    @apply bg-modal-surface text-base-fg backdrop-blur-md;
-    --surface-bg: var(--color-modal-surface);
+  [data-surface='well'],
+  .dx-group-surface,
+  .dx-input-surface {
+    --surface-bg: var(--color-group-surface);
   }
 
-  .dx-popover-surface {
-    @apply bg-popover-surface text-base-fg backdrop-blur-md;
-    --surface-bg: var(--color-popover-surface);
+  /* Every zone paints its published surface and takes the default ink. */
+  [data-surface],
+  .dx-deck-surface,
+  .dx-sidebar-surface,
+  .dx-header-surface,
+  .dx-l0-surface,
+  .dx-l1-surface,
+  .dx-r0-surface,
+  .dx-r1-surface,
+  .dx-base-surface,
+  .dx-attention-surface,
+  .dx-card-surface,
+  .dx-modal-surface,
+  .dx-popover-surface,
+  .dx-toolbar-surface,
+  .dx-group-surface,
+  .dx-input-surface {
+    background-color: var(--surface-bg);
+    @apply text-base-fg;
   }
 
-  .dx-attention-surface {
-    @apply bg-attention-surface text-base-fg;
-    --surface-bg: var(--color-attention-surface);
+  /* Floating levels frost whatever passes beneath them. */
+  [data-surface='overlay'],
+  [data-surface='popup'],
+  .dx-modal-surface,
+  .dx-popover-surface {
+    @apply backdrop-blur-md;
   }
 }
 
 @layer dx-tokens {
   /*
-   * Re-derive the state colours (hover, current, selected) off the host surface for every context
-   * that publishes its own --surface-bg. Custom-property substitution runs once per scope, so the
-   * formula must be repeated here (it cannot simply inherit from semantic.css, which resolved it
-   * against the root surface). Listing all surface zones in one block keeps the offsets identical
-   * across surfaces — there is no per-surface divergence to tune.
+   * Aspect derivation. Custom-property substitution runs once per scope, so the formulas must be
+   * re-evaluated wherever `--surface-bg` changes — these two blocks are that one place
+   * (surfaces.css declares the same formulas against the root fallback, for content outside any
+   * zone). Keep the offsets in sync with the Aspects block there.
    *
-   * Magnitudes mirror semantic.css; selected-* track current-* via the aliases declared there.
+   * States re-derive in EVERY zone, including the aspect zones: a row inside a toolbar should
+   * highlight against the toolbar, not against the level beneath it.
    */
-  .dx-base-surface,
+  [data-surface],
   .dx-deck-surface,
   .dx-sidebar-surface,
   .dx-header-surface,
+  .dx-l0-surface,
+  .dx-l1-surface,
+  .dx-r0-surface,
+  .dx-r1-surface,
+  .dx-base-surface,
+  .dx-attention-surface,
   .dx-card-surface,
-  .dx-group-surface,
-  .dx-input-surface,
-  .dx-toolbar-surface,
   .dx-modal-surface,
   .dx-popover-surface,
-  .dx-attention-surface,
+  .dx-toolbar-surface,
+  .dx-group-surface,
+  .dx-input-surface,
+  .dx-input,
   .dx-main-sidebar {
-    --color-hover-surface: light-dark(
-      oklch(from var(--surface-bg) calc(l - 0.08) c h),
-      oklch(from var(--surface-bg) calc(l + 0.08) c h)
+    --color-hover-surface: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-state) * 0.08) c h
+    );
+    --color-hover-surface-subtle: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-state) * 0.02) c h
+    );
+    --color-current-surface: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-state) * 0.1) c h
+    );
+    --color-current-surface-hover: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-state) * 0.12) c h
+    );
+    --color-placeholder: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-placeholder) * 0.3) c h
+    );
+    --color-scrollbar-thumb: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-scrollbar) * 0.23) c h
+    );
+    --color-scrollbar-thumb-hover: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-scrollbar) * 0.3) c h
+    );
+    --color-scrollbar-thumb-active: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-scrollbar) * 0.34) c h
     );
-    --color-hover-surface-subtle: light-dark(
-      oklch(from var(--surface-bg) calc(l - 0.02) c h),
-      oklch(from var(--surface-bg) calc(l + 0.02) c h)
+    --color-separator: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-separator-line) * 0.166) c h
     );
-    --color-current-surface: light-dark(
-      oklch(from var(--surface-bg) calc(l - 0.1) c h),
-      oklch(from var(--surface-bg) calc(l + 0.1) c h)
+    --color-input-separator: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-separator) * 0.115) c h
     );
-    --color-current-surface-hover: light-dark(
-      oklch(from var(--surface-bg) calc(l - 0.12) c h),
-      oklch(from var(--surface-bg) calc(l + 0.12) c h)
+    --color-subdued-separator: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-separator) * 0.089) c h
     );
+    --color-primary-separator: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-separator) * 0.064) c h
+    );
+
+    /*
+     * Aliases must be re-declared, not inherited: a `--color-x: var(--color-y)` alias substitutes
+     * at the scope that DECLARES it, so one written only at `:root` freezes to the root value and
+     * ignores the zone it is used in.
+     */
+    --color-selected-surface: var(--color-current-surface);
+    --color-selected-surface-hover: var(--color-current-surface-hover);
+  }
+
+  /*
+   * Bar and well re-derive only in LEVEL zones. Deriving them inside an aspect zone would be
+   * circular — that zone's own `--surface-bg` is defined *from* one of these tokens — so a bar
+   * nested in a bar keeps the outer step rather than compounding.
+   */
+  [data-surface='sunken'],
+  [data-surface='chrome'],
+  [data-surface='base'],
+  [data-surface='raised'],
+  [data-surface='overlay'],
+  [data-surface='popup'],
+  .dx-deck-surface,
+  .dx-sidebar-surface,
+  .dx-header-surface,
+  .dx-l0-surface,
+  .dx-l1-surface,
+  .dx-r0-surface,
+  .dx-r1-surface,
+  .dx-base-surface,
+  .dx-attention-surface,
+  .dx-card-surface,
+  .dx-modal-surface,
+  .dx-popover-surface,
+  .dx-main-sidebar {
+    --color-toolbar-surface: oklch(
+      from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-bar) * 0.025) c h
+    );
+    --color-group-surface: oklch(from var(--surface-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-well) * 0.05) c h);
+    --color-group-alt-surface: oklch(from var(--surface-bg) calc(l + var(--dx-lift) * 0.08) c h);
+
+    /* Re-declared for the same reason as the state aliases above. */
+    --color-input-surface: var(--color-group-surface);
+    --color-focus-surface: var(--color-group-surface);
   }
 }

package/src/css/components/tag.css

@@ -11,7 +11,19 @@
 
   .dx-tag--anchor {
     /* NOTE: Margin offsets padding so that border is flush with text. This should only apply to anchor tags inside of Codemirror. */
-    @apply inline-block cursor-pointer px-[4px] py-0.5;
+    @apply inline-block cursor-pointer px-[8px];
+    /* 
+     * Vertical padding on an inline-block grows the line box, so a line carrying a chip would be
+     * taller than its neighbours. The negative margin cancels that contribution, keeping editor
+     * rows a uniform height whether or not an item has been converted to a link.
+     */
+    padding-block: 2px;
+    margin-block: -2px;
+    /* 
+     * `inline-block` makes this a block container, so an inherited hanging indent 
+     * (list rows set a negative `text-indent`) would shift the label out of its own box. 
+     */
+    text-indent: 0;
     /** TODO(burdon): Configure secondary color. */
     @apply bg-input-surface ring-inset ring ring-neutral-border rounded-sm;
     &:hover {

package/src/css/integrations/codemirror.css

@@ -26,6 +26,21 @@
   --color-cm-comment-surface: light-dark(var(--color-teal-200), var(--color-teal-200));
   --color-cm-comment-current-surface: light-dark(var(--color-orange-200), var(--color-orange-200));
 
+  /* Branch diff: oriented as a preview of accepting the compare branch into the current branch —
+     the compare branch's content (what accepting adds) is shown as an addition, the current
+     branch's deviating content (what accepting removes) as a removal. */
+  --color-cm-diff-add-surface: light-dark(
+    oklch(from var(--color-green-500) l c h / 0.18),
+    oklch(from var(--color-green-400) l c h / 0.22)
+  );
+  --color-cm-diff-remove-surface: light-dark(
+    oklch(from var(--color-red-500) l c h / 0.16),
+    oklch(from var(--color-red-400) l c h / 0.22)
+  );
+  /* Saturated variants for the change-gutter markers (thin bars), kept aligned with the surfaces. */
+  --color-cm-diff-add-gutter: light-dark(var(--color-green-600), var(--color-green-400));
+  --color-cm-diff-remove-gutter: light-dark(var(--color-red-500), var(--color-red-400));
+
   /* Markdown syntax highlighting */
   --color-cm-code: light-dark(var(--color-stone-600), var(--color-stone-400));
   --color-cm-code-inline: light-dark(var(--color-green-500), var(--color-green-500));

package/src/css/layout/main.css

@@ -80,9 +80,33 @@
     .dark & {
       @apply backdrop-blur-lg;
     }
-    background-color: var(--color-sidebar-surface);
+    /*
+     * The sidebars ARE L1/R1 — nothing else applies `dx-l1-surface`, so this is where those tokens
+     * have to land or they have no effect at all. Aspect derivation for the subtree keys off
+     * `--surface-bg` (see surface.css); the chrome default covers a sidebar rendered without a side.
+     */
+    --surface-bg: var(--dx-surface-chrome);
+    background-color: var(--surface-bg);
+
+    &[data-side='is'] {
+      --surface-bg: var(--color-l1-surface);
+
+      /* Collapsed, the sidebar is exactly the rail's width and the rail overlays it, so the only
+         pixels that show are the rail's own. Wearing the rail's tone keeps the edges and the rail's
+         border from revealing a second surface behind it. */
+      &[data-state='collapsed'] {
+        --surface-bg: var(--color-l0-surface);
+      }
+    }
+
+    &[data-side='ie'] {
+      --surface-bg: var(--color-r1-surface);
+
+      &[data-state='collapsed'] {
+        --surface-bg: var(--color-r0-surface);
+      }
+    }
     color: var(--color-sidebar-fg);
-    --surface-bg: var(--color-sidebar-surface);
 
     /* Current / selected items read one stop brighter than default body text. */
     & :is([aria-current]:not([aria-current='false']), [aria-selected='true']) {

package/src/css/layout/native.css

@@ -10,6 +10,7 @@
    * The CSS properties below are for Electron/PWA compatibility.
    */
   .dx-app-drag {
+    user-select: none;
     -webkit-user-select: none;
     -webkit-app-region: drag;
     --app-region: drag;

package/src/css/theme/roles.css

@@ -0,0 +1,92 @@
+/**
+ * Roles — named tokens that are not surfaces: text emphasis, control fills, accent, separators,
+ * scrollbar, and the off-ladder grid "paper" palette.
+ *
+ * The elevation ladder and everything derived from a host surface lives in `surfaces.css`.
+ *
+ * Naming convention: --color-{name}-{part}[-{state}] — see DESIGN_SYSTEM.md.
+ */
+
+@theme {
+  /*
+   * Text emphasis — foregrounds at decreasing emphasis, anchored on --color-base-fg (strongest):
+   *   base-fg → description → subdued (weakest). `placeholder` is host-derived — see surfaces.css.
+   * Tuned for legibility against the surfaces rather than mapped to the elevation ladder (which
+   * governs backgrounds, not text contrast), so these stay explicit neutrals.
+   */
+  --color-description: light-dark(var(--color-neutral-600), var(--color-neutral-400));
+  --color-subdued: light-dark(var(--color-neutral-500), var(--color-neutral-600));
+
+  /*
+   * Controls — the input/control fill is a deliberate off-ladder token (cf. the grid "paper"
+   * surfaces). It backs text inputs and the default/ghost button (bg-input-bg) and must contrast
+   * whatever surface it sits on: a subtle inset well in light mode, a raised fill in dark mode that
+   * reads lighter than the topmost surface. Do not map it to an elevation level.
+   */
+  /*
+   * Light is not a ramp stop: neutral-250 sat 0.14 below the near-white canvas, so a default button
+   * read as a dark slab next to an input fill 0.025 below it. Dark keeps neutral-700.
+   */
+  --color-input-bg: light-dark(oklch(0.87 0.001 190), var(--color-neutral-700));
+
+  /*
+   * A filled control's hover has to move ITS OWN fill. `--color-hover-surface` is derived from the
+   * host surface — correct for ghost/outline, which are transparent and let the host show through,
+   * but in light it sits above the fill, so a filled button lightened on hover into
+   * `--color-selected-surface`. Light-mode only: dark still uses the host tint (see button.css).
+   */
+  --color-input-bg-hover: oklch(
+    from var(--color-input-bg) calc(l + var(--dx-lift) * var(--dx-attenuate-state) * 0.08) c h
+  );
+  --color-input-fg: var(--color-base-fg);
+
+  /* Focus indicators are a global affordance, not a per-surface property. */
+  --color-focus-ring: light-dark(var(--color-blue-400), var(--color-blue-600));
+  --color-focus-ring-subtle: light-dark(var(--color-neutral-300), var(--color-neutral-600));
+
+  /* Accent (primary) */
+  --color-accent-bg: light-dark(var(--color-blue-600), var(--color-blue-700));
+  --color-accent-bg-hover: light-dark(var(--color-blue-700), var(--color-blue-800));
+  --color-accent-fg: var(--color-blue-100);
+  --color-accent-text: light-dark(var(--color-blue-600), var(--color-blue-400));
+  --color-accent-text-hover: light-dark(var(--color-blue-500), var(--color-blue-500));
+
+  /* Unaccented */
+  --color-un-accent: var(--color-neutral-400);
+  --color-un-accent-hover: var(--color-neutral-500);
+
+  /* Separator */
+  /* Surface-relative separators are host-derived — see the Aspects block in surfaces.css. */
+  --color-active-separator: light-dark(var(--color-blue-500), var(--color-blue-500));
+
+  /* Scrollbar */
+  /* The groove. The thumb is host-derived — see the Aspects block in surfaces.css. */
+  --color-scrollbar-track: light-dark(var(--color-neutral-50), var(--color-neutral-950));
+
+  /*
+   * Sheet / Grid — intentionally OFF the elevation ladder.
+   * NOTE: Update main.css when changing grid tokens (and restart dev server).
+   *
+   * These are "paper" surfaces for the data grid: maximum-contrast canvases (near-white in light,
+   * near-black in dark) plus saturated selection/comment accents. The elevation ladder is
+   * monotonic (light: lighter = higher), so it cannot express a surface that is simultaneously the
+   * lightest in light mode and the darkest in dark mode. Keep these as explicit neutrals/accents;
+   * do not fold them into --dx-surface-*.
+   */
+  --color-axis-surface: light-dark(var(--color-neutral-100), var(--color-neutral-900));
+  --color-axis-text: light-dark(var(--color-neutral-700), var(--color-neutral-300));
+  --color-axis-selected-surface: light-dark(var(--color-neutral-100), var(--color-neutral-900));
+  --color-axis-selected-text: light-dark(var(--color-neutral-100), var(--color-neutral-900));
+
+  --color-grid-surface: light-dark(var(--color-neutral-50), var(--color-neutral-950));
+  --color-grid-fg: light-dark(var(--color-neutral-950), var(--color-neutral-50));
+  --color-grid-line: light-dark(var(--color-neutral-200), var(--color-neutral-800));
+  --color-grid-highlight: oklch(from var(--color-emerald-500) l c h / 0.5);
+  --color-grid-selection-surface: light-dark(var(--color-blue-500), var(--color-blue-400));
+  --color-grid-selection-fg: light-dark(var(--color-neutral-50), var(--color-neutral-950));
+  --color-grid-comment: light-dark(var(--color-green-400), var(--color-green-600));
+  --color-grid-comment-active: light-dark(
+    oklch(from var(--color-green-400) l c h / 0.5),
+    oklch(from var(--color-green-600) l c h / 0.5)
+  );
+}

package/src/css/theme/spacing.css

@@ -23,10 +23,13 @@
 
   --spacing-tag-padding-block: 0.125rem;
 
+  /** The one spacing ramp: 4 / 8 / 12 / 16 / 24 / 32. Every other spacing family aliases onto it. */
   --spacing-trim-xs: 0.25rem;
   --spacing-trim-sm: 0.5rem;
   --spacing-trim-md: 0.75rem;
-  --spacing-trim-lg: 1.5rem;
+  --spacing-trim-lg: 1rem;
+  --spacing-trim-xl: 1.5rem;
+  --spacing-trim-2xl: 2rem;
 
   /** Minimal trim to allow for ring/outline. */
   --spacing-form-chrome: var(--spacing-trim-xs);
@@ -34,39 +37,53 @@
   --spacing-form-section-gap: var(--spacing-trim-md);
 
   /**
-   * Density: md (default).
+   * Control scale — the three canonical control heights. rem-based, so they scale with the
+   * pointer-coarse root font-size (16px fine / 20px coarse) and touch targets grow for free:
+   *   sm 1.5rem = 24px fine / 30px coarse
+   *   md 2rem   = 32px fine / 40px coarse
+   *   lg 2.5rem = 40px fine / 50px coarse
+   * The old 28px step and the `xs` density are gone; `sm` is the compact step.
    */
+  --dx-control-sm: 1.5rem;
+  --dx-control-md: 2rem;
+  --dx-control-lg: 2.5rem;
+
+  /**
+   * Density: md (default). One mechanism — a density class sets these two knobs and every control
+   * reads them, so density cascades to any subtree (including react-ui-menu items) with no React
+   * plumbing. `data-density` on a control remains a local override.
+   */
+  --dx-control: var(--dx-control-md);
+  --dx-control-pad: var(--spacing-trim-sm);
+  /* Text must fit inside --dx-control; at sm the default line box overshoots 24px. */
+  --dx-control-leading: normal;
   --spacing-form-padding: var(--spacing-trim-sm);
-  --spacing-icon-button-padding: var(--spacing-trim-xs);
-  --spacing-scroll-padding: 4px;
 }
 
 @layer dx-tokens {
-  /**
-   * Density: lg — large touch targets (~40px controls).
-   */
-  .dx-density-lg {
+  /** Density: lg — large touch targets. */
+  .dx-density-lg,
+  [data-density='lg'] {
+    --dx-control: var(--dx-control-lg);
+    --dx-control-pad: var(--spacing-trim-md);
     --spacing-form-padding: var(--spacing-trim-md);
-    --spacing-icon-button-padding: var(--spacing-trim-sm);
-    --spacing-scroll-padding: 8px;
   }
 
-  /**
-   * Density: sm — compact (~28px controls).
-   */
-  .dx-density-sm {
-    --spacing-form-padding: var(--spacing-trim-xs);
-    --spacing-icon-button-padding: var(--spacing-trim-xs);
-    --spacing-scroll-padding: 2px;
+  /** Density: md — explicit reset so a nested region can restore the default inside lg/sm. */
+  .dx-density-md,
+  [data-density='md'] {
+    --dx-control: var(--dx-control-md);
+    --dx-control-pad: var(--spacing-trim-sm);
+    --spacing-form-padding: var(--spacing-trim-sm);
   }
 
-  /**
-   * Density: xs — ultra-compact (~24px controls).
-   */
-  .dx-density-xs {
+  /** Density: sm — compact. */
+  .dx-density-sm,
+  [data-density='sm'] {
+    --dx-control: var(--dx-control-sm);
+    --dx-control-pad: var(--spacing-trim-xs);
+    --dx-control-leading: 22px;
     --spacing-form-padding: var(--spacing-trim-xs);
-    --spacing-icon-button-padding: var(--spacing-trim-xs);
-    --spacing-scroll-padding: 2px;
   }
 }
 
@@ -79,40 +96,30 @@
     --dx-line-1: 1px;
     --dx-line-2: 2px;
 
-    --dx-lacuna-12: 1.5rem;
-    --dx-lacuna-3: 0.375rem;
-    --dx-lacuna-4: 0.5rem;
-    --dx-lacuna-6: 0.75rem;
-
+    /*
+     * Gutters source from the spacing ramp rather than carrying their own literals. The names are
+     * the gutter's own scale (form / dialog / card), so they intentionally do not line up with the
+     * ramp step names — sm is one ramp step, md two, lg four.
+     */
     /* Form:   8px */
-    --dx-gutter-sm: 0.5rem;
+    --dx-gutter-sm: var(--spacing-trim-sm);
     /* Dialog: 16px */
-    --dx-gutter-md: 1rem;
+    --dx-gutter-md: var(--spacing-trim-lg);
     /* Card:   32px */
-    --dx-gutter-lg: 2rem;
+    --dx-gutter-lg: var(--spacing-trim-2xl);
   }
 
   :root {
-    --dx-hair-line: 1px;
-    --dx-landmark-line: 1px;
-    --dx-modal-line: 1px;
-    --dx-no-line: 0px;
-    --dx-thick-line: 2px;
-    --dx-focus-line: 2px;
-
     --dx-no-line: var(--dx-line-0);
     --dx-hair-line: var(--dx-line-1);
     --dx-thick-line: var(--dx-line-2);
 
+    --dx-landmark-line: var(--dx-hair-line);
     --dx-focus-offset: var(--dx-no-line);
     --dx-focus-line: var(--dx-thick-line);
     --dx-modal-line: var(--dx-hair-line);
     --dx-grid-focus-indicator-width: var(--dx-hair-line);
 
-    --dx-input-md: var(--dx-lacuna-3);
-    --dx-input-lg: var(--dx-lacuna-4);
-    --dx-input-sm: var(--dx-lacuna-3);
-
     --dx-default-icons-size: 1rem; /* size=4 */
   }
 
@@ -121,18 +128,20 @@
   }
 
   :root {
-    --dx-rail-content: 3rem;
-    /** TODO(burdon): Audit. */
-    /** TODO(burdon): Density (2 sizes). */
-    --dx-rail-size: calc(var(--dx-rail-content) + 1px);
-    --dx-rail-item: calc(var(--dx-rail-content) - 1rem);
-    /* TODO(burdon): Added 1px for border. */
-    /* TODO(burdon): Remove direct usage. */
-    --dx-rail-action: calc(var(--dx-rail-content) - 0.5rem);
-
-    --dx-topbar-size: var(--dx-rail-size); /* 50px */
-    --dx-toolbar-size: var(--dx-rail-action); /* 40px */
-    --dx-statusbar-size: var(--dx-rail-item); /* 32px */
+    /*
+     * Rails derive from the control scale rather than their own arithmetic, so a bar and the
+     * controls inside it land on the same grid. The old `+1px` border fudge is gone — a border
+     * belongs to the element's box, not to the size token (it leaked 49px into a dozen layouts).
+     * NOTE: px values assume the 16px (pointer: fine) root font-size; coarse is 20px (×1.25).
+     */
+    --dx-rail-content: 3rem; /* 48px — the rail gutter, not a control */
+    --dx-rail-size: var(--dx-rail-content); /* 48px */
+    --dx-rail-item: var(--dx-control-md); /* 32px */
+    --dx-rail-action: var(--dx-control-lg); /* 40px */
+
+    --dx-topbar-size: var(--dx-rail-size); /* 48px */
+    --dx-toolbar-size: var(--dx-control-lg); /* 40px */
+    --dx-statusbar-size: var(--dx-control-md); /* 32px */
 
     /** NOTE: Sidebar optimized to show plank + companion with sidebar open on 16" MBP. */
     --dx-nav-sidebar-size: 350px;