@apliteni/apliteni-ui 0.53.4 → 0.55.0

package/guidelines/colour-and-theming.md

@@ -54,3 +54,15 @@
 
 
 <!-- rule: both-themes -->
+
+## Keep text off grey fills
+
+<!-- rule: text-surface -->
+
+**Rule:** Put text on the page or card surface, never on a grey fill.
+
+**Why:** Grey blocks make reading areas look disabled.
+
+**Do:** Draw inputs with an edge. Keep grey fills for non-text states, such as disabled tracks and dividers.
+
+**Don't:** Put text on grey fields, chips, headers or footers.

package/guidelines/component-choice.md

@@ -20,7 +20,7 @@
 
 **Why:** A confirm keeps keyboard focus until answered; a callout does not interrupt.
 
-**Except:** Use a drawer when the answer needs a form instead of two buttons.
+**Except:** Use a content-sized modal for a short form and a drawer for a long form.
 
 **Do:** Ask “Rotate this token?” in a confirm with “Keep token” and “Rotate token” buttons.
 

package/guidelines/drawer.md

@@ -26,15 +26,15 @@
 
 **Don't:** Put each group in a card inside the drawer.
 
-## Three divider lines
+## Header and group dividers
 
 <!-- rule: three-lines -->
 
-**Rule:** Draw lines under the header, over the footer, and between each group; draw no other lines.
+**Rule:** Add lines below the header and between groups. Leave the footer unfilled and without a rule.
 
-**Why:** These lines mark scrolling boundaries and separate groups, not rows.
+**Why:** The header line marks the scrolling body; group lines separate content, and actions share the panel surface.
 
-**Do:** Separate header, footer and groups.
+**Do:** Separate the header and groups.
 
 **Don't:** Add dividers between every row.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.53.4",
+  "version": "0.55.0",
   "workspaces": [
     "react"
   ],

package/react/dist/index.css

@@ -30,8 +30,7 @@
 .rx-scrim {
   position: fixed;
   inset: 0;
-  background: rgba(0, 0, 0, .55);
-  backdrop-filter: blur(2px);
+  background: color-mix(in srgb, var(--shadow-ink) 82%, transparent);
   display: grid;
   place-items: center;
   z-index: calc(var(--z-overlay) + 1);
@@ -42,14 +41,18 @@
   opacity: 1;
 }
 .rx-modal {
-  width: min(480px, 92vw);
+  width: min(calc(var(--panel-lg) - var(--space-10) * 2), 96vw);
+  max-height: 96vh;
+  max-height: 96dvh;
+  display: flex;
+  flex-direction: column;
   background: var(--bg-elevated);
   --ring-gap: var(--bg-elevated);
-  border: 1px solid var(--border-strong);
-  box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop);
-  border-radius: var(--radius-xl);
+  border: 0;
+  box-shadow: var(--elev-drop);
+  border-radius: var(--radius-md);
   overflow: hidden;
-  transform: translateY(8px);
+  transform: translateY(var(--space-2));
   transition: transform var(--dur-med) var(--ease);
 }
 .rx-scrim.is-open .rx-modal {
@@ -59,25 +62,38 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: 16px 20px;
+  gap: var(--space-3);
+  flex: none;
+  padding: var(--space-2) var(--space-2) var(--space-2) var(--space-4);
   border-bottom: 1px solid var(--border);
 }
 .rx-modal__title {
-  font-weight: 600;
-  font-size: var(--text-lg);
+  font-weight: var(--weight-normal);
+  font-size: var(--text-base);
+  color: var(--text);
 }
 .rx-modal__body {
-  padding: 20px;
+  padding: var(--space-4);
   display: flex;
   flex-direction: column;
-  gap: 16px;
+  gap: var(--space-4);
+  min-height: 0;
+  overflow: auto;
+}
+.rx-modal__body > * {
+  flex-shrink: 0;
 }
 .rx-modal__foot {
   display: flex;
   justify-content: flex-end;
-  gap: 12px;
-  padding: 16px 20px;
-  border-top: 1px solid var(--border);
+  gap: var(--space-3);
+  flex: none;
+  padding: var(--space-4);
+}
+.rx-modal__head > .ui-btn {
+  width: calc(var(--space-10) + var(--space-1));
+  height: calc(var(--space-10) + var(--space-1));
+  flex: none;
 }
 
 /* src/DataTable.css */
@@ -250,8 +266,8 @@
   font-family: var(--font-sans);
   font-size: var(--text-base);
   color: var(--strong);
-  background: var(--surface-2);
-  border: 1px solid var(--border);
+  background: var(--field-bg);
+  border: 1px solid var(--field-edge);
   border-radius: var(--radius-md);
   padding: 12px 15px;
   width: 100%;
@@ -265,7 +281,7 @@
 .ui-input:hover,
 .ui-textarea:hover,
 .ui-select:hover {
-  border-color: var(--border-strong);
+  border-color: var(--field-edge-hover);
 }
 .ui-input:focus-visible,
 .ui-textarea:focus-visible,
@@ -461,16 +477,16 @@
   align-items: center;
   gap: 8px;
   padding: 24px;
-  border: 1px dashed var(--border);
+  border: 1px dashed var(--field-edge);
   border-radius: var(--radius-md);
-  background: var(--surface-2);
+  background: var(--field-bg);
   color: var(--text);
   font-size: var(--text-base);
   text-align: center;
   overflow-wrap: anywhere;
 }
 .ui-file:hover {
-  border-color: var(--border-strong);
+  border-color: var(--field-edge-hover);
 }
 .ui-file:focus-within,
 .ui-file.is-dragging {

package/src/styles/back.css

@@ -31,7 +31,7 @@
    (0,2,0) wins without !important — the argument `.ui-nav .ui-nav__item` makes
    in nav.css. */
 .ui-back[href] { color: var(--text); }
-.ui-back[href]:hover { color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-back[href]:hover { color: var(--strong); background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-back:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
 /* 16px, with the stroke raised to match: the glyph set draws at 1.7 on a 24-unit

package/src/styles/badge.css

@@ -15,14 +15,14 @@
   padding: 3px 9px;
   border-radius: var(--radius-pill);
   color: var(--text);
-  background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   white-space: nowrap;
 }
 /* Status chips take the --chip-* pairs, so the light app's solid fills live in
    tokens.css rather than in a theme override down here: on white the glow-tints
    wash out and the ink has to deepen to clear AA, and that is a token decision. */
 .ui-badge--live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
-.ui-badge--soon { color: var(--purple-mid); background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-badge--soon { color: var(--accent); background: var(--surface); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 .ui-badge--info { color: var(--chip-info-ink); background: var(--chip-info-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 .ui-badge--warn { color: var(--chip-warn-ink); background: var(--chip-warn-fill); }
 .ui-badge--danger { color: var(--chip-danger-ink); background: var(--chip-danger-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
@@ -32,12 +32,7 @@
    (paid / verified / pending / failed …). Same chip, mapped to meaning. */
 .ui-badge--success { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 .ui-badge--pending { color: var(--chip-warn-ink); background: var(--chip-warn-fill); }
-.ui-badge--neutral { color: var(--text); background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
-
-/* The two neutral chips are the exception: their light fill is already in the
-   surface scale (--surface-3), and only archive uses muted state ink. */
-:root[data-theme="light"] .ui-badge--neutral { background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
-:root[data-theme="light"] .ui-badge--archive { /* muted-ink: state — archived record */ color: var(--muted); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.ui-badge--neutral { color: var(--text); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* Pill: same shape, sentence case, a touch larger — a metadata chip */
 .ui-pill {
@@ -47,7 +42,7 @@
   /* rank: chip */
   font-size: var(--text-xs);
   color: var(--text);
-  background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   border-radius: var(--radius-pill);
   padding: 4px 11px;
   font-weight: var(--weight-semibold);
@@ -56,7 +51,7 @@
    same pair. On its own it was --green on --glow-green, which is 3.97:1 over
    white — under AA, while the badge beside it cleared at 4.64:1. See issue #131. */
 .ui-pill--live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
-.ui-pill--soon { color: var(--purple-mid); background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-pill--soon { color: var(--accent); background: var(--surface); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 
 /* Status dot */
 .ui-dot {

package/src/styles/button.css

@@ -19,8 +19,10 @@
   border-radius: var(--radius-sm);
   padding: var(--btn-pad-y) var(--btn-pad-x);
   cursor: pointer;
-  border: 1px solid var(--border);
-  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  /* Light needs a stronger line here: --border on this fill measures 1.047:1.
+     why: docs/specification.md#elevation */
+  border: 1px solid var(--control-edge);
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--text);
   white-space: nowrap;
   transition: background var(--dur-fast) var(--ease),
@@ -32,7 +34,7 @@
 
 .ui-btn:hover {
   border-color: var(--accent);
-  background: color-mix(in srgb, var(--accent) 14%, var(--surface-2)); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: color-mix(in srgb, var(--accent) 14%, var(--surface)); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--strong);
 }
 .ui-btn:active { transform: translateY(1px); }
@@ -59,7 +61,7 @@
   color: var(--text);
 }
 .ui-btn--ghost:hover {
-  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border-color: transparent;
   color: var(--strong);
 }
@@ -108,7 +110,7 @@
 }
 /* With no box, the ink is read on whatever is behind it, so the ghost takes an ink
    set for the dullest ground: in dark 7.49 / 6.31 / 7.00 / 5.44 on --bg / --surface /
-   --surface-2 / --surface-3, in light 5.70 / 6.17 / 5.20 / 5.39. The enabled ghost now uses body
+   --surface-2 / --surface-3, in light 5.85 / 6.50 / 5.49 / 5.70. The enabled ghost now uses body
    ink, keeping its words readable without changing the disabled pair. #273 cut this ink to rescue two
    dark pairs from under #220's floor; #295 re-picked --muted against the elevation
    ladder and lifted both clear, so it is the margin now rather than the rescue.
@@ -135,7 +137,7 @@
 .ui-btn[aria-busy="true"],
 .ui-btn[aria-busy="true"]:hover,
 .ui-btn[aria-busy="true"]:active {
-  background: var(--surface-2); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  background: var(--surface); /* ring-gap: inherit — busy paint retains the button's containing gap. */
   border-color: var(--border);
   color: var(--text);
   filter: none;
@@ -158,7 +160,7 @@
 .ui-btn[aria-busy="true"].ui-btn--danger,
 .ui-btn[aria-busy="true"].ui-btn--danger:hover,
 .ui-btn[aria-busy="true"].ui-btn--danger:active {
-  background: var(--surface-2); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  background: var(--surface); /* ring-gap: inherit — busy paint retains the button's containing gap. */
   border-color: var(--border);
   color: var(--text);
 }

package/src/styles/callout.css

@@ -7,7 +7,7 @@
   gap: 12px;
   padding: 15px 17px;
   border-radius: var(--radius-md);
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  background: var(--surface); --ring-gap: var(--surface);
   font-size: calc(var(--text-sm) + 0.5px);
   line-height: 1.55;
   color: var(--text);
@@ -56,7 +56,7 @@
 .ui-toast--danger  { --toast-accent: var(--pink);  --toast-action-ink: var(--chip-danger-ink);  --toast-glow: var(--glow-pink);  --toast-on: var(--danger-contrast); --toast-solid: var(--signal-solid-danger); }
 .ui-toast--warn    { --toast-accent: var(--amber); --toast-action-ink: var(--chip-warn-ink);    --toast-glow: color-mix(in srgb, var(--amber) 14%, transparent); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-warn); }
 .ui-toast--info    { --toast-accent: var(--cyan);  --toast-action-ink: var(--chip-info-ink);    --toast-glow: var(--glow-cyan);  --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-info); }
-.ui-toast--neutral { --toast-accent: var(--muted); --toast-action-ink: var(--text);            --toast-glow: var(--surface-2); --toast-on: var(--signal-solid-ink); --toast-solid: var(--signal-solid-neutral); }
+.ui-toast--neutral { --toast-accent: var(--muted); --toast-action-ink: var(--text);            --toast-glow: var(--surface); --toast-on: var(--signal-solid-ink); --toast-solid: var(--signal-solid-neutral); }
 
 .ui-toast__icon { width: 22px; height: 22px; flex: none; display: grid; place-items: center; background: transparent; color: var(--toast-action-ink); }
 .ui-toast__icon svg { width: var(--space-4); height: var(--space-4); stroke: currentColor; fill: none; stroke-width: 2.25; } /* 16px × 2.25 / 24 = 1.5 CSS px. */

package/src/styles/card.css

@@ -9,7 +9,9 @@
   background: var(--surface); --ring-gap: var(--surface);
   border: 1px solid var(--border);
   border-radius: var(--radius-xl);
-  padding: var(--space-6) 26px;
+  /* Was `var(--space-6) 26px`; 26 is off the scale and broke the column's text edge.
+     why: docs/specification.md#spacing-and-rhythm */
+  padding: var(--space-6);
   position: relative;
 }
 
@@ -22,17 +24,25 @@
    (No `.ui-card + .ui-card` margin: it leaks into grid/flex rows and misaligns.) */
 .ui-card-stack { display: flex; flex-direction: column; gap: var(--space-5); }
 
-.ui-card--pad-sm { padding: var(--space-5); }
+/* A padding modifier moves the vertical rhythm and keeps the text edge, so cards of
+   different padding line up in one column. --pad-lg is the centred landing card, never
+   stacked with plain ones, and keeps its own inset.
+   why: docs/specification.md#spacing-and-rhythm */
+.ui-card--pad-sm { padding: var(--space-5) var(--space-6); }
 .ui-card--pad-lg { padding: var(--space-8) var(--space-10); }
 
 /* An accent-tinted card, e.g. a highlighted plan / success surface. The accent edge is
-   the card's own hairline re-coloured: an inset ring over it would draw two. #295 */
+   the card's own hairline re-coloured: an inset ring over it would draw two. #295
+   The strength is --card-tint, per theme: light mixes down from white, so a tint that
+   works in dark sinks a light card below the page. Each variant edges itself in its own
+   colour. why: docs/specification.md#elevation */
 .ui-card--accent {
-  background: color-mix(in srgb, var(--accent) 9%, var(--surface)); --ring-gap: color-mix(in srgb, var(--accent) 9%, var(--surface));
+  background: color-mix(in srgb, var(--accent) var(--card-tint), var(--surface)); --ring-gap: color-mix(in srgb, var(--accent) var(--card-tint), var(--surface));
   border-color: color-mix(in srgb, var(--accent) 22%, transparent);
 }
 .ui-card--live {
-  background: color-mix(in srgb, var(--green) 10%, var(--surface)); --ring-gap: color-mix(in srgb, var(--green) 10%, var(--surface));
+  background: color-mix(in srgb, var(--green) var(--card-tint), var(--surface)); --ring-gap: color-mix(in srgb, var(--green) var(--card-tint), var(--surface));
+  border-color: color-mix(in srgb, var(--green) 22%, transparent);
 }
 
 /* Interactive card (link / button semantics) */

package/src/styles/code.css

@@ -4,7 +4,7 @@
  * ========================================================================== */
 
 .ui-snippet {
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  background: var(--surface); --ring-gap: var(--surface);
   border-radius: var(--radius-md);
   overflow: hidden;
 }
@@ -71,7 +71,7 @@
 .ui-code {
   font-family: var(--font-mono);
   font-size: 0.9em;
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  background: var(--surface); --ring-gap: var(--surface);
   padding: 2px 6px;
   border-radius: var(--radius-xs);
   color: var(--text);

package/src/styles/command-palette.css

@@ -178,7 +178,7 @@
   background: none;
 }
 .ui-cmdk__item[hidden] { display: none; } /* motion: still — a row the query no longer answers is gone on the next keystroke */
-.ui-cmdk__item.is-active { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-cmdk__item.is-active { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-cmdk__item.is-active .ui-cmdk__label { color: var(--strong); }
 
 .ui-cmdk__ic {
@@ -239,9 +239,9 @@
 .ui-cmdk__item.is-danger.is-active .ui-cmdk__ic { color: var(--pink); }
 
 /* A disabled row is painted, never faded. It takes --disabled-ink-bare, the ink
-   for a control with no box of its own: --disabled-surface IS --surface-2,
-   which is the panel behind it, so a disabled row paints no box a reader can
-   see and its label is read on whatever the panel is.
+   for a control with no box of its own. Disabled rows keep the panel's
+   surface and their labels remain readable on that ground without
+   adding a grey box behind the text.
    why: docs/specification.md#text-ink */
 .ui-cmdk__item.is-disabled { cursor: default; /* muted-ink: state — unavailable control */ color: var(--disabled-ink-bare); }
 .ui-cmdk__item.is-disabled .ui-cmdk__label,
@@ -256,9 +256,9 @@
   padding: 2px 5px;
   border: 1px solid var(--border);
   border-radius: var(--radius-xs);
-  /* A key cap reads as raised, so it takes the step above the panel rather than
-     the card step below it. why: docs/specification.md#elevation */
-  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  /* Key caps use an edge on the card surface, keeping the shortcut readable.
+     why: docs/specification.md#elevation */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   font-family: var(--font-sans);
   font-size: var(--text-xs);
   line-height: 1.5;
@@ -304,7 +304,7 @@
   background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   border: 1px solid var(--border);
 }
-.ui-cmdk--roomy .ui-cmdk__item.is-active .ui-cmdk__ic { background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.ui-cmdk--roomy .ui-cmdk__item.is-active .ui-cmdk__ic { background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* -- Narrow --------------------------------------------------------------- */
 /* At the kit's narrowest step the palette is the page: full width, off the top

package/src/styles/drawer.css

@@ -127,16 +127,13 @@
 .ui-drawer--top.ui-drawer--lg, .ui-drawer--bottom.ui-drawer--lg { --drawer-h: 72vh; }
 
 /* -- Slots ----------------------------------------------------------------- */
-/* The header keeps its rule, and the footer keeps its. A drawer's normal state is a
-   long record scrolling, and those two lines are what say where the scrolling body
-   ends: the one place inside the panel a line still earns.
-   why: docs/specification.md#the-drawer */
+/* The header marks the scroll boundary; actions share the panel surface. */
 .ui-drawer__header {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 12px;
-  padding: 18px 20px;
+  gap: var(--space-3);
+  padding: var(--space-4) var(--space-5);
   border-bottom: 1px solid var(--border);
   flex: none;
 }
@@ -188,10 +185,8 @@
   display: flex;
   align-items: center;
   justify-content: flex-end;
-  gap: 10px;
-  padding: 16px 20px;
-  border-top: 1px solid var(--border);
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  gap: var(--space-3);
+  padding: var(--space-4) var(--space-5);
   flex: none;
 }
 

package/src/styles/dropdown.css

@@ -151,9 +151,9 @@
   color: var(--text);
   transition: background var(--dur-fast) var(--ease);
 }
-/* A row in a raised panel lifts: the step above it, never the card step below. why: docs/specification.md#elevation */
-.ui-dropdown__item:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
-.ui-dropdown__item:focus-visible { outline: 2px solid transparent; background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: var(--ring); }
+/* Rows keep a reading surface; hover adds an edge. why: docs/specification.md#elevation */
+.ui-dropdown__item:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-dropdown__item:focus-visible { outline: 2px solid transparent; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: var(--ring); }
 .ui-dropdown__main { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
 .ui-dropdown__label { font-family: var(--font-sans); font-size: calc(var(--text-sm) - 0.5px); color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
 .ui-dropdown__desc { font-size: var(--text-xs); color: var(--text); line-height: 1.35; }
@@ -180,14 +180,14 @@
   flex: none;
   color: var(--text);
   /* A chip is the top step. why: docs/specification.md#elevation */
-  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
 }
 .ui-dropdown__badge.is-live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 /* The accent counter keeps the badge's flat surface and changes only the ink — the shape
-   src/styles/nav.css:163 `.ui-nav__item.is-active .ui-nav__badge.is-accent` already holds.
+   src/styles/nav.css:158 `.ui-nav__item.is-active .ui-nav__badge.is-accent` already holds.
    The accent wash goes on a base surface, never a raised one, and #295 made this panel a
    raised one. why: docs/specification.md#elevation */
-.ui-dropdown__badge.is-accent { color: var(--accent); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.ui-dropdown__badge.is-accent { color: var(--accent); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* Disabled + danger rows */
 .ui-dropdown__item.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: not-allowed; pointer-events: none; }
@@ -257,9 +257,9 @@
   font: inherit;
   font-size: calc(var(--text-sm) - 0.5px);
   color: var(--strong);
-  /* A field is the sunken step, the same one .ui-input takes. why: docs/specification.md#elevation */
-  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
-  border: 1px solid var(--border);
+  /* The ground and line .ui-input takes. why: docs/specification.md#elevation */
+  background: var(--field-bg); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  border: 1px solid var(--field-edge);
   border-radius: var(--radius-sm);
   padding: 8px 12px 8px 34px;
   /* The height Chromium paints (38.25px), stated so the target-size gate, which
@@ -267,14 +267,12 @@
   min-height: 38px;
   transition: border-color var(--dur-fast) var(--ease), box-shadow var(--dur-fast) var(--ease);
 }
-/* Light sinks the field one rung less far: its panel is the only pure white the
-   kit paints, so --surface-2 falls two rungs under it rather than one. The
-   numbers are in the spec and the gate is stories/dropdown-field-ground.test.js.
-   why: docs/specification.md#elevation */
-:root[data-theme="light"] .ui-dropdown__search-input { background: var(--bg); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+/* The light-only `background: var(--bg)` override this field used to carry is gone:
+   --field-bg says the same thing for every field. Gated by
+   stories/dropdown-field-ground.test.js. why: docs/specification.md#elevation */
 
 .ui-dropdown__search-input::placeholder { /* muted-ink: placeholder — empty search field */ color: var(--muted); }
-.ui-dropdown__search-input:hover { border-color: var(--border-strong); }
+.ui-dropdown__search-input:hover { border-color: var(--field-edge-hover); }
 .ui-dropdown__search-input:focus-visible { outline: 2px solid transparent; border-color: var(--accent); box-shadow: var(--ring); }
 
 .ui-dropdown__list { max-height: 300px; overflow-y: auto; }
@@ -284,7 +282,7 @@
 
 /* The row Enter would pick. Focus stays in the field, which carries the ring,
    so this row takes the hover fill and a bar rather than a second ring. */
-.ui-dropdown__item.is-active { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: inset 2px 0 0 var(--accent); }
+.ui-dropdown__item.is-active { background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: inset 2px 0 0 var(--accent); }
 
 /* No match — a nudge and no action, per Guidelines / Microcopy. Empty while
    anything matches, so it takes no room. */

package/src/styles/feedback.css

@@ -76,16 +76,16 @@
 .ui-fbc__head { display: flex; align-items: center; gap: 12px; padding: 17px 20px 0; }
 .ui-fbc__chip { display: inline-flex; align-items: center; gap: 8px; color: var(--accent); font-size: var(--text-sm); font-weight: var(--weight-semibold); letter-spacing: .01em; white-space: nowrap; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
 .ui-fbc__chip svg { width: 14px; height: 14px; flex: none; opacity: .85; stroke-width: 2.7; }
-.ui-fbc__x { margin-left: auto; background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ /* muted-ink: glyph — dismiss icon */ color: var(--dim); border: 0; width: 28px; height: 28px; border-radius: 8px; cursor: pointer; display: grid; place-items: center; flex: none; font: inherit; }
+.ui-fbc__x { margin-left: auto; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ /* muted-ink: glyph — dismiss icon */ color: var(--dim); border: 0; width: 28px; height: 28px; border-radius: 8px; cursor: pointer; display: grid; place-items: center; flex: none; font: inherit; }
 .ui-fbc__x:hover { color: var(--strong); }
 .ui-fbc__x svg { width: 14px; height: 14px; stroke-width: 2.7; }
-.ui-fbc__quote { margin: 14px 20px 0; background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ border-radius: 12px; padding: 12px 15px; display: flex; gap: 11px; }
+.ui-fbc__quote { margin: 14px 20px 0; background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ border-radius: 12px; padding: 12px 15px; display: flex; gap: 11px; }
 .ui-fbc__qm { color: var(--accent); font-size: var(--text-xl); font-weight: var(--weight-bold); line-height: .9; flex: none; opacity: .55; }
 .ui-fbc__quote q { quotes: none; color: var(--text); font-style: italic; font-size: calc(var(--text-sm) + 0.5px); line-height: 1.55; }
 .ui-fbc__body { padding: 14px 20px 0; }
 .ui-fbcomposer textarea {
   width: 100%; min-height: 96px; resize: vertical; font-family: var(--font-sans); font-size: var(--text-base); line-height: 1.55;
-  color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ border: 0; border-radius: 12px; padding: 13px 15px; transition: box-shadow var(--dur-fast) var(--ease);
+  color: var(--strong); background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ border: 1px solid var(--field-edge); border-radius: 12px; padding: 13px 15px; transition: box-shadow var(--dur-fast) var(--ease);
 }
 .ui-fbcomposer textarea::placeholder { /* muted-ink: placeholder — empty feedback field */ color: var(--muted); }
 .ui-fbcomposer textarea:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
@@ -93,7 +93,7 @@
 
 .ui-fbbtn { font-family: var(--font-sans); font-size: calc(var(--text-sm) + 0.5px); font-weight: var(--weight-semibold); border-radius: 10px; padding: 9px 17px; cursor: pointer; border: 0; transition: filter var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease), color var(--dur-fast) var(--ease); }
 .ui-fbbtn.ghost { background: transparent; color: var(--text); }
-.ui-fbbtn.ghost:hover { color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-fbbtn.ghost:hover { color: var(--strong); background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-fbbtn.primary { background: var(--accent-strong); color: var(--accent-contrast); display: inline-flex; align-items: center; gap: 9px; }
 .ui-fbbtn.primary:hover { filter: brightness(1.08); }
 /* Same flat pair as .ui-btn:disabled, for the same reason (#220). */
@@ -111,7 +111,7 @@
 .ui-fbc__done { padding: 30px 26px 24px; text-align: center; background: radial-gradient(112% 60% at 50% 0%, var(--glow-green), transparent 62%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 .ui-fbc__ck { width: 88px; height: 88px; margin: 0 auto 13px; display: grid; place-items: center; }
 .ui-fbck { width: 88px; height: 88px; overflow: visible; display: block; transform-origin: center; animation: uiFbCkSpring 1s cubic-bezier(.22,1,.3,1) both; } /* motion: choreographed — the frame the mark and the comet are timed against */
-.ui-fbck-t { fill: none; stroke: var(--surface-2); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; }
+.ui-fbck-t { fill: none; stroke: var(--surface); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; }
 .ui-fbck-m { fill: none; stroke: var(--green); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 118; stroke-dashoffset: 118; animation: uiFbCkDraw .6s cubic-bezier(.5,0,.3,1) .1s forwards; /* motion: choreographed — the mark draws while the spring is still settling */ }
 .ui-fbck-s { fill: none; stroke: var(--sheen); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 15 400; stroke-dashoffset: 133; filter: drop-shadow(0 0 8px var(--green)) drop-shadow(0 0 15px var(--green)); opacity: 0; animation: uiFbCkComet .6s cubic-bezier(.5,0,.3,1) .1s forwards; /* motion: choreographed — the comet rides the mark, so it shares its duration and delay exactly */ }
 .ui-fbc__done h4 { color: var(--strong); font-size: calc(var(--text-lg) + 1px); font-weight: var(--weight-semibold); letter-spacing: -.01em; margin-bottom: 7px; }

package/src/styles/input.css

@@ -23,8 +23,10 @@
   font-family: var(--font-sans);
   font-size: var(--text-base);
   color: var(--strong);
-  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
-  border: 1px solid var(--border);
+  /* Fields use the card surface and an edge in both themes.
+     why: docs/specification.md#elevation */
+  background: var(--field-bg); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  border: 1px solid var(--field-edge);
   border-radius: var(--radius-md);
   padding: 12px 15px;
   width: 100%;
@@ -34,7 +36,7 @@
 
 .ui-input:hover,
 .ui-textarea:hover,
-.ui-select:hover { border-color: var(--border-strong); }
+.ui-select:hover { border-color: var(--field-edge-hover); }
 
 .ui-input:focus-visible,
 .ui-textarea:focus-visible,

package/src/styles/layout.css

@@ -27,8 +27,8 @@
 .ui-app-page { --ui-app-top: 52px; }
 .ui-app-page .topbar { position: sticky; top: 0; z-index: var(--z-sticky); }
 
-/* --surface-2, not --bg-elevated: elevated resolves to --bg itself in the light
-   theme, an exact no-op that left the border as the whole of the rail.
+/* The rail uses the card surface so its labels stay on a reading ground.
+   Its border separates navigation from the page in both themes.
    overflow-y, because the box is pinned at the viewport's height for the whole
    scroll of .ui-app — without it a row past that height paints below the fold
    and no amount of document scrolling brings it back. The rail's own padding is
@@ -39,7 +39,7 @@
   gap: var(--space-5);
   padding: var(--space-5) var(--space-4);
   border-right: var(--ui-rail-rule) solid var(--border);
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  background: var(--surface); --ring-gap: var(--surface);
   position: sticky;
   top: var(--ui-app-top, 0px);
   height: calc(100vh - var(--ui-app-top, 0px));
@@ -59,11 +59,11 @@
 .ui-app__rail > .ui-app__head,
 .ui-app__rail > .ui-app__user,
 .ui-app__rail > .ui-app__foot { width: var(--ui-nav-col); flex: none; }
-/* The rail's hover WAS --surface-2, so moving the rail onto it would have made
-   hovering a row do nothing. The danger row and the current row are left out by
-   name, because this rule outranks the states nav.css writes for them.
+/* Hover keeps the reading surface and uses the edge declared in nav.css.
+   The danger row and the current row are left out by name because this
+   rule outranks the states nav.css writes for them.
    */
-.ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-app__brand {
   display: flex;
   align-items: center;
@@ -109,7 +109,7 @@
    smallest of three weak signals doing the most work, so it grows with the row. */
 /* Re-tuned at #295, which took the light rail down a step with the page. Below 720px
    the glyph is the whole row, so it is held at text grade rather than at 1.4.11's bar —
-   stories/apps/shell-states.test.js:1403 `a resting glyph is dimmer but still legible`. */
+   stories/apps/shell-states.test.js:1377 `a resting glyph is dimmer but still legible`. */
 .ui-app__rail .ui-nav__ic svg { opacity: 0.66; }
 .ui-app__rail .ui-nav__item.is-active .ui-nav__ic svg,
 .ui-app__rail .ui-nav__item.is-current .ui-nav__ic svg { opacity: 1; stroke: currentColor; } /* motion: still — the glyph brightens with its row, whose own highlight already transitions */
@@ -153,7 +153,7 @@
   width: var(--ui-app-av); height: var(--ui-app-av); flex: none;
   margin-inline-start: calc((var(--ui-nav-strip) - var(--ui-app-av)) / 2);
   border-radius: var(--radius-pill);
-  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   color: var(--strong);
   display: grid; place-items: center;
   font-size: calc(var(--text-xs) + 1px);
@@ -187,7 +187,7 @@
   font-weight: inherit;
   letter-spacing: normal;
 }
-.ui-app .ui-app__user-trigger:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-app .ui-app__user-trigger:hover { background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-app__user-trigger .ui-app__who { flex: 1 1 auto; text-align: left; }
 /* The panel is portalled onto <body>, so nothing here may hang off .ui-app: by the
    time it is open it is no longer inside the rail that drew it.
@@ -269,7 +269,7 @@
    why: docs/specification.md#elevation */
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who,
-.ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
+.ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
 @supports (anchor-name: --a) and (anchor-scope: --a) {
   .ui-app.is-collapsed,
   .ui-app:has(.ui-app__fold) { anchor-scope: --ui-rail; }
@@ -352,15 +352,7 @@
   font-size: var(--text-sm);
   text-align: start;
   color: var(--text);
-  /* --surface, not the sunken --surface-2 every other field in the kit takes:
-     those sit on a card and this one sits on the band, and the band IS --bg, the
-     bottom of the ladder — so a sunken fill has nowhere to go but down into its
-     own ground. Measured in light, the field was 1.10:1 BELOW the band and its
-     key cap 1.04:1 against the field it sits in; they are 1.08 above and 1.14 now.
-     Dark trades the other way and is stated rather than hidden: the cap goes
-     1.29 -> 1.16, because --surface-3 and --surface are adjacent rungs there.
-     Artur chose this over three alternatives on #318; the survey of what seven
-     other systems do is docs/reviews/318-search-field.md.
+  /* The band search uses the same reading surface as other text controls.
      why: docs/specification.md#elevation */
   background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--border);
@@ -467,7 +459,7 @@
   .ui-app__rail .ui-nav__item,
   .ui-app__rail .ui-app__user-trigger { min-height: 44px; }
   .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
-  .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
+  .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
   @supports (anchor-name: --a) and (anchor-scope: --a) {
     .ui-app { anchor-scope: --ui-rail; }
     .ui-app__rail { anchor-name: --ui-rail; }

package/src/styles/nav.css

@@ -69,9 +69,9 @@
   transition: background var(--dur-fast) var(--ease), color var(--dur-fast) var(--ease);
 }
 .ui-nav .ui-nav__item { color: var(--text); } /* (0,2,0): a host sheet's a:link is (0,1,1) — why: docs/specification.md#the-page-shell */
-.ui-nav__item:hover { background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ color: var(--strong); }
+.ui-nav__item:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ color: var(--strong); }
 .ui-nav__item.is-active {
-  background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--strong);
   font-weight: 500;
 }
@@ -116,15 +116,10 @@
    background and pull its label toward the rail behind it (#220). */
 .ui-nav__item.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: default; pointer-events: none; }
 
-/* The current row under the pointer. It rests on --surface-3, which is also what
-   a resting row hovers to, so the one row with no hover response was the row the
-   reader is standing on. There is no surface above --surface-3, so the step is
-   mixed: --text is near-white in dark and near-black in light, and both themes
-   raise a surface by moving it away from the page. Written after the danger
-   rules so it cannot out-rank them — sign out is never the current row, but a
-   rule that could take its wash would be one to argue with later. */
+/* Hover adds an edge without changing the current row's reading surface.
+   The danger row keeps its own state treatment. */
 .ui-nav__item.is-active:not(.is-danger):hover {
-  background: color-mix(in srgb, var(--text) 10%, var(--surface-3)); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--surface); outline: 1px solid var(--control-edge); outline-offset: -1px; /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
 }
 
 /* Per-item badge / counter */
@@ -140,7 +135,7 @@
   font-size: var(--text-xs);
   font-weight: 600;
   line-height: 1;
-  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   color: var(--text);
   /* The count fades with the words. It is never lost: sidebarNav() spells it
      into the row's aria-label, so "Pending 3" is what a reader hears at either
@@ -150,17 +145,17 @@
 .ui-nav__badge.is-accent { background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--accent); }
 .ui-nav__badge.is-live { background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--chip-success-ink); }
 .ui-nav__badge.is-danger { background: var(--glow-pink); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--pink); }
-.ui-nav__item.is-active .ui-nav__badge.is-neutral { background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); }
+.ui-nav__item.is-active .ui-nav__badge.is-neutral { background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); }
 /* Same shape, one row up: on an active row the accent counter takes the row's
    OWN surface instead of laying its wash over it. An active row is already
-   painted --surface-3, so --glow-purple there is two tints stacked. Every
+   painted --surface, so an opaque counter avoids stacking tinted fills. Every
    figure here is measured against the tokens this kit now ships. The accent on
    that pair falls under WCAG AA in four of the eight theme x accent cells —
    4.08 in dark Nebula, where the flat surface reads 4.92 — and no alpha reaches
    it, the largest that clears being 0.06 in dark Nebula and 0.02 in light
    Emerald. So the accent wash is painted on a base surface, never a raised one.
    See #157 and docs/specification.md#colour-and-contrast. */
-.ui-nav__item.is-active .ui-nav__badge.is-accent { background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--accent); }
+.ui-nav__item.is-active .ui-nav__badge.is-accent { background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--accent); }
 
 /* Collapsible group */
 .ui-nav__group { display: flex; flex-direction: column; }
@@ -294,7 +289,7 @@
 
 /* pill variant */
 .ui-nav--tabs.is-pill .ui-nav__tab { border-radius: var(--radius-pill); padding: 8px 15px; }
-.ui-nav--tabs.is-pill .ui-nav__tab:hover { background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-nav--tabs.is-pill .ui-nav__tab:hover { background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-nav--tabs.is-pill .ui-nav__tab.is-active {
   background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
   color: var(--accent);
@@ -304,7 +299,9 @@
 .ui-nav__tab .ui-nav__badge { height: 18px; }
 
 /* -- Breadcrumbs --------------------------------------------------------- */
-.ui-nav__crumbs { display: flex; flex-wrap: wrap; align-items: center; gap: 2px; }
+/* The chip hangs out by its own padding so the first LABEL lands on the column's edge,
+   level with the page title under it. */
+.ui-nav__crumbs { display: flex; flex-wrap: wrap; align-items: center; gap: 2px; margin-inline-start: -6px; }
 .ui-nav__crumb-item { display: inline-flex; align-items: center; }
 .ui-nav__crumb-item + .ui-nav__crumb-item::before {
   content: "";
@@ -329,7 +326,7 @@
    does above: a linked crumb is an <a>, and a host stylesheet's `a:link` is
    (0,1,1), which outranks a bare (0,1,0) class. */
 .ui-nav .ui-nav__crumb { color: var(--text); }
-a.ui-nav__crumb:hover { color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+a.ui-nav__crumb:hover { color: var(--strong); background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 a.ui-nav__crumb:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-nav__crumb.is-current { color: var(--strong); font-weight: 500; }
 .ui-nav__crumb .ui-nav__ic svg { width: 15px; height: 15px; stroke: currentColor; fill: none; stroke-width: 2.5; }

package/src/styles/pagination.css

@@ -69,7 +69,7 @@
    rule about an ENABLED control out of the disabled-rule sweep in
    stories/guidelines/accessibility-floor.test.js, which reads selector text. */
 .ui-pager__page.is-current:not([disabled]) {
-  background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border-color: var(--border);
   color: var(--strong);
   font-weight: var(--weight-semibold);

package/src/styles/segmented.css

@@ -1,11 +1,15 @@
 /* ============================================================================
  * Segmented control — .ui-seg  (the deck's pill switch: theme, Deck/Text, plan)
- * The selected button rides on a raised surface with a soft shadow.
+ * The selected button keeps the reading surface and gains an accent edge.
  * ========================================================================== */
 
 .ui-seg {
   display: inline-flex;
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  /* `inline-flex` sizes the track to its pills, but a flex or grid parent stretches a
+     child whatever its display says — and .ui-app__body is a flex column. The control
+     states its own alignment; --block and --underline ask for the width back. */
+  align-self: start;
+  background: var(--surface); --ring-gap: var(--surface);
   border-radius: var(--radius-2xl);
   padding: 3px;
   gap: 2px;
@@ -30,11 +34,12 @@
 .ui-seg button[aria-pressed="true"],
 .ui-seg button[aria-selected="true"] {
   color: var(--strong);
-  background: var(--seg-active-bg);   /* the step is the lift; nothing casts. #295 */
+  background: var(--surface); /* ring-gap: inherit — the button ring meets its containing track. */
+  outline: 1px solid var(--accent);
 }
 
 .ui-seg--sm button { padding: 5px 13px; font-size: calc(var(--text-xs) + 1px); }
-.ui-seg--block { display: flex; }
+.ui-seg--block { display: flex; align-self: stretch; }
 .ui-seg--block button { flex: 1; }
 
 /* Accent picker — round colour swatches, active gets a ring */
@@ -56,7 +61,7 @@
 }
 .ui-accent-picker button:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
-.ui-seg--underline { background: transparent; --ring-gap: inherit; border-radius: 0; border-bottom: 1px solid var(--border); padding: var(--space-1); overflow: auto; max-width: 100%; }
+.ui-seg--underline { align-self: stretch; background: transparent; --ring-gap: inherit; border-radius: 0; border-bottom: 1px solid var(--border); padding: var(--space-1); overflow: auto; max-width: 100%; }
 .ui-seg--underline button { border-radius: var(--radius-xs); border-bottom: 2px solid transparent; padding: var(--space-3); white-space: nowrap; }
 .ui-seg--underline button.is-active,
 .ui-seg--underline button[aria-pressed="true"] { background: transparent; border-bottom-color: var(--accent); }

package/src/styles/table.css

@@ -65,10 +65,11 @@
 .ui-table--zebra td { border-bottom: 0; }
 .ui-table--zebra tbody tr:nth-child(even) td { background: var(--surface-2); --ring-gap: var(--surface-2); }
 /* The stripe stays full-bleed (the #71 inset above is hover only), but it only reads right
- * if the end cells are inset from the tint's own edge, and `.ui-table td` sets
+ * if the end cells are inset from the row's own edge, and `.ui-table td` sets
  * `padding-left: 0`. Only `--dense` supplied that inset, so `--zebra` without `--dense` —
- * `DataTable`'s composition — sat its checkboxes at x=0 of the stripe. Head and body are
- * inset together, or the columns stop lining up. */
+ * `DataTable`'s composition — sat its checkboxes at x=0 of the row. Head and body are
+ * inset together, or the columns stop lining up. Held by src/styles/table.test.js, and
+ * kept off the card's text edge by the bleed rule at the end of this file. */
 .ui-table--zebra th:first-child,
 .ui-table--zebra td:first-child { padding-left: var(--space-3); }
 .ui-table--zebra th:last-child,
@@ -76,6 +77,19 @@
 .ui-table--zebra.ui-table--hover tbody tr:hover td,
 .ui-table--zebra tbody tr:hover td { --ring-gap: inherit; background: color-mix(in srgb, var(--accent) 8%, transparent); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 
+/* A link in a cell is a value that happens to open something: the row's ink, underlined
+   on hover — what .ui-identity below has always done. Without it, base.css's bare
+   `a { color: var(--accent) }` reached the ledger's IDs.
+   why: guidelines/density-and-accents.md#give-accents-a-job */
+.ui-table :where(td, th) a:not(.ui-btn):not(.ui-identity) {
+  color: inherit;
+  text-decoration: none;
+}
+.ui-table :where(td, th) a:not(.ui-btn):not(.ui-identity):hover {
+  color: var(--strong);
+  text-decoration: underline;
+}
+
 .ui-table__num { text-align: right; font-variant-numeric: tabular-nums; }
 .ui-table th.ui-table__num { text-align: right; }
 .ui-table__num--strong { color: var(--strong); font-weight: var(--weight-semibold); }
@@ -93,6 +107,15 @@
   background: var(--table-bg); --ring-gap: var(--table-bg);
 }
 .ui-table tbody tr:hover { outline: 1px solid var(--border-strong); outline-offset: -1px; }
+
+/* The end-cell inset above gives a row's highlight room; the bleed is what stops the grid
+   paying for it. The table hangs out by the same --space-3, into the card's 20-24px
+   padding and never past it, so the columns start on the card's own text edge and the
+   scroll region stays empty at rest. why: docs/specification.md#spacing-and-rhythm */
+.ui-card > :where(.ui-table--dense, .ui-table--zebra) {
+  width: calc(100% + 2 * var(--space-3));
+  margin-inline: calc(-1 * var(--space-3));
+}
 .ui-table td.ui-table__num { text-align: right; }
 .ui-table--compact td { padding: var(--space-1) var(--space-3); font-size: var(--text-sm); line-height: var(--leading-snug); height: 33px; }
 .ui-table--compact th { padding: var(--space-2) var(--space-3); }

package/src/styles/tooltip.css

@@ -14,7 +14,7 @@
   /* One number for the mark-to-readout distance, read by both placements here
      and by the wiring's flip test, so above and below cannot drift apart. */
   --ui-tip-gap: 8px;
-  --ui-tip-bg: var(--surface-3);
+  --ui-tip-bg: var(--bg-elevated);
   position: absolute;
   top: var(--ui-tip-y, 0px);
   left: var(--ui-tip-x, 50%);
@@ -47,9 +47,9 @@
     visibility var(--dur-fast) linear;
 }
 
-/* No light override: it re-pointed the readout at --surface, which #295 made the card
-   step, so a readout over a card was painted the card's own colour. --surface-3 is the
-   readout's step in both themes. why: docs/specification.md#elevation */
+/* The readout uses the floating panel surface in both themes. Its edge
+   and shadow separate it from the card underneath.
+   why: docs/specification.md#elevation */
 
 /* Below the mark: the wiring's flip when above would be clipped, or the
    author's own choice. */

package/src/styles/topbar.css

@@ -48,7 +48,7 @@
   display: none;
   align-items: center;
   gap: 2px;
-  background: var(--surface-2); --ring-gap: var(--surface-2);
+  background: var(--surface); --ring-gap: var(--surface);
   border: 1px solid var(--border);
   border-radius: 24px;
   padding: 3px;
@@ -179,10 +179,10 @@
   font: inherit;
   transition: background var(--dur-fast) var(--ease);
 }
-/* The menu is raised, so a hovered row takes the step ABOVE it — see
+/* Menu rows use the reading surface and an edge on hover — see
    src/styles/dropdown.css:155 `.ui-dropdown__item:hover`.
    why: docs/specification.md#elevation */
-.vopt:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.vopt:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .vopt .vname { font-family: var(--font-sans); font-size: calc(var(--text-sm) - 0.5px); color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
 .vopt .vmeta { font-size: var(--text-xs); color: var(--text); margin-top: 2px; }
 .vopt .vbadge {
@@ -196,7 +196,7 @@
   margin-top: 1px;
 }
 .vbadge.live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
-.vbadge.arch { /* muted-ink: state — archived version */ color: var(--muted); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.vbadge.arch { /* muted-ink: state — archived version */ color: var(--muted); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 /* The switcher keeps its glyph and drops its label where the shell folds — the
    same step the rail folds at: docs/specification.md#breakpoints. */
 @media (max-width: 720px) { .vsw__btn .lbl { display: none; } }
@@ -258,7 +258,7 @@
 .amenu .ahead .anm { color: var(--strong); font-size: var(--text-sm); font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .amenu .ahead .aem { color: var(--text); font-size: calc(var(--text-xs) + 0.5px); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .amenu a { display: flex; align-items: center; gap: 11px; padding: 10px 15px; color: var(--text); text-decoration: none; font-family: var(--font-sans); font-size: var(--text-sm); cursor: pointer; }
-.amenu a:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.amenu a:hover { outline: 1px solid var(--control-edge); outline-offset: -1px; background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .amenu a.cur { color: var(--accent); }
 .amenu a svg { width: 19px; height: 19px; flex: none; stroke: currentColor; fill: none; stroke-width: 2; opacity: 0.85; }
 .amenu .asep { height: 1px; background: var(--border); margin: 5px 0; }

package/src/tokens/tokens.css

@@ -139,10 +139,10 @@
      line and nothing else in the kit does. why: docs/specification.md#elevation */
   --bg: #0e0d14;
   --table-bg: var(--bg);
-  --surface-2: #161520;     /* SUNKEN — fields, tracks, disabled, code */
+  --surface-2: #161520;     /* non-text sunken marks and tracks */
   --surface: #211e2d;       /* the card */
   --bg-elevated: #2a2639;   /* FLOATING — menus, panels, drawer, modal, toasts */
-  --surface-3: #2d293c;     /* the top step — the hover readout, chips, the nav rail */
+  --surface-3: #2d293c;     /* non-text quiet fills */
   --seg-active-bg: #383350; /* raised pill — clearly above the inset track in dark */
   /* The raised handle on a control track (switch knob). White in both themes and under
      every accent: it reads on the plain track AND on the accent fill of an on control. */
@@ -150,6 +150,16 @@
   --border: #332f45;
   --border-strong: #453f5c;
 
+  /* Fields use the card surface and an edge in both themes. why: docs/specification.md#elevation */
+  --field-bg: var(--surface);
+  --field-edge: var(--border);
+  --field-edge-hover: var(--border-strong);
+  --control-edge: var(--border);
+
+  /* How much of its own colour a tinted card mixes in. Dark mixes upward off a mid-grey
+     card, so it can afford this much. why: docs/specification.md#elevation */
+  --card-tint: 9%;
+
   --text: #e9e7f0;
   --strong: #ffffff;
   --dim: #c6c2d6;
@@ -164,7 +174,7 @@
      ink read on the surface beside it. Held by guidelines/accessibility-floor.test.js.
      why: docs/specification.md#colour-and-contrast */
   --disabled-ink: var(--muted);
-  --disabled-surface: var(--surface-2);
+  --disabled-surface: var(--surface);
   --disabled-border: var(--border);
   /* The ink of a disabled control that paints no box of its own — a ghost button. With
      no surface beside it, it is read on whatever is behind it, so it is set to clear the
@@ -281,29 +291,47 @@
   --pink: #a92d59;
   --amber: #b5730a;
 
-  /* The same ladder, run the only way light can run it: nothing is brighter than the
-     white a card already was, so light moves DOWN and keeps white for the top step.
+  /* The same ladder, run the only way light can run it: nothing is brighter than
+     white, so light moves DOWN from it. #307 ran it downwards from the CARD, which
+     put the page at #eef0f5 and left the card at #f8f9fc — a grey canvas under a
+     surface only 1.08:1 above it, so the grey was what the screen read as and the
+     card never arrived. The card takes the white instead, and the page is the
+     lightest ground that still leaves it a step: 1.11:1, on a page lighter and less
+     blue than the one it replaces. Light spends its white on the surface you read
+     ON, and separates the panel that floats over it by role — its two-step edge and
+     its drop — rather than by a rung it has nothing left to pay for. See issue #448.
      why: docs/specification.md#elevation */
-  --bg: #eef0f5;
+  --bg: #f2f3f6;
   --table-bg: #ffffff;
-  --surface-2: #e3e6ee;     /* SUNKEN — fields, tracks, disabled, code */
-  --surface: #f8f9fc;       /* the card */
+  --surface-2: #e9ecf3;     /* non-text sunken marks and tracks */
+  --surface: #ffffff;       /* the card */
   --bg-elevated: #ffffff;   /* FLOATING — menus, panels, drawer, modal, toasts */
-  --surface-3: #e7eaf1;     /* the hover readout, chips, the nav rail */
+  --surface-3: #eef0f5;     /* non-text quiet fills */
   --seg-active-bg: #ffffff; /* white pill raised above the grey track in light */
   --control-knob: #ffffff;
   --border: #e4e7ee;
   --border-strong: #cdd2dc;
 
+  /* Light draws a field with its EDGE, because since #448 it has no well left to draw it
+     with: a card and a panel are both white, the sunken step falls two rungs under either,
+     and --border on it measures 1.047:1. why: docs/specification.md#elevation */
+  --field-bg: var(--surface);
+  --field-edge: var(--border-strong);
+  --field-edge-hover: var(--muted);
+  --control-edge: var(--border-strong);
+
+  /* Light mixes DOWN from white, so tint costs lightness: 5% is the most a card can spend
+     and stay above the page. why: docs/specification.md#elevation */
+  --card-tint: 5%;
+
   --text: #1a1e27;
   --strong: #0c0e13;
   --dim: #3a404b;
   --muted: #5c6270;
 
-  /* Same three aliases as dark. Light moves the disabled surface AWAY from white for the
-     same reason dark moves it away from the card: a control that is off should sink. */
+  /* Disabled text stays on the card surface; its ink marks the unavailable state. */
   --disabled-ink: var(--muted);
-  --disabled-surface: var(--surface-2);
+  --disabled-surface: var(--surface);
   --disabled-border: var(--border);
   --disabled-ink-bare: #585e6c;
 
@@ -361,8 +389,8 @@
   --shadow-ink: #1e1e32;
   --sheen: #ffffff;
 
-  /* 18% / 10% against dark's 62% / 50%. Light's ink is #1e1e32 on a card at
-     #f8f9fc, and 18% is what puts the drop core at #d1d2d8 — 1.44, the strongest
+  /* 18% / 10% against dark's 62% / 50%. Light's ink is #1e1e32 on a card that is
+     now #ffffff, and 18% is what puts the drop core at #d7d7da — 1.44, the strongest
      separation either theme gets. why: docs/specification.md#elevation */
   --elev-drop:
     0 14px 30px -12px color-mix(in srgb, var(--shadow-ink) 18%, transparent),