@apliteni/apliteni-ui 0.93.0 → 0.95.0

package/guidelines/accessibility-floor.md

@@ -46,11 +46,11 @@
 
 **Rule:** Keep a focus indicator at least 3:1 against every ground it reaches.
 
-**Do:** The solid band, with a surface-coloured gap around an accent-filled control.
+**Do:** One solid accent band, drawn 1px off the control it marks.
 
-**Don't:** The halo on its own, with no solid band inside it to measure.
+**Don't:** A glow on its own, with no solid band inside it to measure.
 
-**Except:** The band must clear the bar against the gap and halo pixels too, not only against flat ground.
+**Except:** The band must clear the bar against the surface its offset leaves showing, not only flat ground.
 
 ## Disabled control legibility
 

package/guidelines/colour-and-theming.md

@@ -66,3 +66,5 @@
 **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.
+
+**Except:** The sidebar rail's current row. Its mark may be neither an accent nor an edge — an outline there means focus — and in the page shell the rail is the card surface already. It takes the quiet fill a rung off its rail, label and all. Artur, r34 of [#475](https://github.com/apliteni/apliteni-ui/issues/475).

package/guidelines/state-set.md

@@ -6,13 +6,13 @@
 
 **Rule:** Give every focusable control the same `--ring`, and show it only on `:focus-visible`.
 
-**Why:** One solid band and halo keep focus consistent while the browser decides when to show it.
+**Why:** One solid band keeps focus consistent while the browser decides when to show it.
 
-**Do:** Apply `--ring` to both the button and input on keyboard focus.
+**Do:** Apply `--ring`, with `--ring-offset`, to both the button and input on keyboard focus.
 
 **Don't:** Give the input a separate muted outline while the button uses `--ring`.
 
-**Except:** A scroll region inside a surface takes `--ring-scroll`: the same 1px gap and 2px band, drawn inward, without the halo. `--ring` is drawn for a 32px control, where the halo is a glint; around a 400px region it spreads 14px past the band and lights the surface instead of the box that scrolls. A box that is itself the outermost surface — a panel, a card — keeps `--ring`. Text-entry controls may match `:focus-visible` on mouse focus. Surface backgrounds set the gap colour and recompose `--ring`; adjust width and colour at the root.
+**Except:** A scroll region inside a surface takes `--ring-scroll`: the same band drawn inward, with `--ring-scroll-offset`. An inset shadow paints under a box's own children, so a table scrolling under one erases the band; an outline survives it. A box that is itself the outermost surface — a panel, a card — keeps `--ring`. Text-entry controls may match `:focus-visible` on mouse focus. Both bands are declared once at the root and recomposed nowhere, because an outline leaves its offset unpainted. Adjust width and colour there.
 
 ## Busy controls
 

package/package.json

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

package/react/dist/index.css

@@ -207,7 +207,6 @@
   display: flex;
   flex-direction: column;
   background: var(--bg-elevated);
-  --ring-gap: var(--bg-elevated);
   border: 0;
   box-shadow: var(--elev-drop);
   border-radius: var(--radius-md);
@@ -275,13 +274,13 @@
   color: inherit;
 }
 .rx-sort:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--ring);
+  outline: var(--ring);
+  outline-offset: var(--ring-offset);
   border-radius: 4px;
 }
 .ui-table__selection input[type=checkbox]:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--ring);
+  outline: var(--ring);
+  outline-offset: var(--ring-offset);
   border-radius: var(--radius-xs);
 }
 .rx-caret {
@@ -384,7 +383,8 @@
   color: var(--strong);
 }
 .ui-datepicker__opt:focus-visible {
-  outline: 2px solid transparent;
+  outline: var(--ring);
+  outline-offset: var(--ring-offset);
 }
 .ui-datepicker__opt.is-inside {
   background: color-mix(in srgb, var(--accent) 14%, var(--bg-elevated));
@@ -394,7 +394,7 @@
   border-color: var(--accent-strong);
   color: var(--accent-contrast);
 }
-.ui-datepicker__opt.is-selected:hover {
+.ui-datepicker__opt.is-selected:hover:not(:focus-visible) {
   outline-color: transparent;
   background: var(--accent-strong);
   color: var(--accent-contrast);
@@ -402,12 +402,15 @@
 .ui-datepicker__opt.is-today {
   border-color: var(--accent);
 }
-.ui-datepicker__opt.is-today:hover {
+.ui-datepicker__opt.is-today:hover:not(:focus-visible) {
   outline-color: transparent;
 }
 .ui-datepicker__opt.is-selected.is-today {
   border-color: var(--accent-contrast);
 }
+.ui-datepicker__opt.is-today:focus-visible {
+  border-color: transparent;
+}
 .ui-datepicker__opt.is-disabled {
   color: var(--disabled-ink-bare);
   cursor: not-allowed;
@@ -416,11 +419,13 @@
   text-decoration: line-through;
 }
 .ui-datepicker__opt.is-disabled:hover {
-  outline-color: transparent;
   background: transparent;
   border-color: transparent;
   color: var(--disabled-ink-bare);
 }
+.ui-datepicker__opt.is-disabled:hover:not(:focus-visible) {
+  outline-color: transparent;
+}
 .ui-datepicker__opt.is-disabled.is-selected,
 .ui-datepicker__opt.is-disabled.is-selected:hover,
 .ui-datepicker__opt.is-disabled.is-inside,
@@ -645,11 +650,13 @@
 .ui-file:hover {
   border-color: var(--field-edge-hover);
 }
-.ui-file:focus-within,
 .ui-file.is-dragging {
   border-color: var(--accent);
-  box-shadow: var(--ring);
-  outline: 2px solid transparent;
+}
+.ui-file:focus-within,
+.ui-file.is-dragging {
+  outline: var(--ring);
+  outline-offset: var(--ring-offset);
 }
 .ui-file.is-invalid {
   border-color: var(--pink);

package/src/styles/back.css

@@ -31,8 +31,8 @@
    (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); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
-.ui-back:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
+.ui-back[href]:hover { color: var(--strong); background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */ }
+.ui-back:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
 
 /* 16px, with the stroke raised to match: the glyph set draws at 1.7 on a 24-unit
    box, which is 1.13 CSS px at this size and under the kit's 1.5 for a stroked

package/src/styles/badge.css

@@ -15,24 +15,24 @@
   padding: 3px 9px;
   border-radius: var(--radius-pill);
   color: var(--text);
-  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */
   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(--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--live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
+.ui-badge--soon { color: var(--accent); background: var(--surface); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */ }
+.ui-badge--info { color: var(--chip-info-ink); background: var(--chip-info-fill); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
 .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. */ }
-.ui-badge--archive { /* muted-ink: state — archived record */ color: var(--muted); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.ui-badge--danger { color: var(--chip-danger-ink); background: var(--chip-danger-fill); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
+.ui-badge--archive { /* muted-ink: state — archived record */ color: var(--muted); background: var(--surface); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
 
 /* Semantic status variants — for record/row status in data tables
    (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--success { color: var(--chip-success-ink); background: var(--chip-success-fill); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
 .ui-badge--pending { color: var(--chip-warn-ink); background: var(--chip-warn-fill); }
-.ui-badge--neutral { color: var(--text); background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.ui-badge--neutral { color: var(--text); background: var(--surface); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
 
 /* Pill: same shape, sentence case, a touch larger — a metadata chip */
 .ui-pill {
@@ -42,7 +42,7 @@
   /* rank: chip */
   font-size: var(--text-xs);
   color: var(--text);
-  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
+  background: var(--surface); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */
   border-radius: var(--radius-pill);
   padding: 4px 11px;
   font-weight: var(--weight-semibold);
@@ -50,8 +50,8 @@
 /* The live pill is the same status paint as the live badge, so it takes the
    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(--accent); background: var(--surface); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-pill--live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* code-bg: inherit — decorative or text-only paint; nothing nested reads a ground from it. */ }
+.ui-pill--soon { color: var(--accent); background: var(--surface); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */ }
 
 /* Status dot */
 .ui-dot {

package/src/styles/base.css

@@ -15,7 +15,7 @@ html {
 }
 
 body {
-  background: var(--bg); /* ring-gap: inherit — page background inherits root overrides. */
+  background: var(--bg); /* code-bg: inherit — page background inherits root overrides. */
   color: var(--text);
   font-family: var(--font-sans);
   font-weight: var(--weight-normal);
@@ -27,7 +27,7 @@ body {
 }
 
 ::selection {
-  background: color-mix(in srgb, var(--accent) 30%, transparent); /* ring-gap: inherit — selection paint is not a focus container. */
+  background: color-mix(in srgb, var(--accent) 30%, transparent); /* code-bg: inherit — selection paint is not a focus container. */
   color: var(--strong);
 }
 
@@ -87,7 +87,7 @@ strong {
 
 /* Spotlight — a soft radial from the top-centre (auth cards, focused heroes). */
 .ui-bg-spotlight::before {
-  background: radial-gradient(620px 340px at 50% -12%, var(--glow-purple), transparent 70%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
+  background: radial-gradient(620px 340px at 50% -12%, var(--glow-purple), transparent 70%); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */
 }
 /* Grid — a faint token-coloured grid, masked to fade at the edges. */
 .ui-bg-grid::before {
@@ -107,7 +107,7 @@ strong {
 }
 /* Accent wash — a gentle top-down tint in the current accent. */
 .ui-bg-wash::before {
-  background: linear-gradient(180deg, var(--glow-purple), transparent 45%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
+  background: linear-gradient(180deg, var(--glow-purple), transparent 45%); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */
 }
 
 /* Layout helpers used by the example apps */
@@ -148,6 +148,6 @@ svg:where(:not([width]):not([height])) {
 .ui-seg button:focus-visible,
 .toggle:focus-visible,
 .ui-switch:focus-visible {
-  outline: 2px solid transparent;
-  box-shadow: var(--ring);
+  outline: var(--ring);
+  outline-offset: var(--ring-offset);
 }

package/src/styles/button.css

@@ -22,7 +22,7 @@
   /* Light needs a stronger line here: --border on this fill measures 1.047:1.
      why: docs/foundations.md#elevation */
   border: 1px solid var(--control-edge);
-  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */
   color: var(--text);
   white-space: nowrap;
   transition: background var(--dur-fast) var(--ease),
@@ -33,10 +33,14 @@
 }
 
 .ui-btn:hover {
-  border-color: var(--accent);
-  background: color-mix(in srgb, var(--accent) 14%, var(--surface)); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: color-mix(in srgb, var(--accent) 14%, var(--surface)); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */
   color: var(--strong);
 }
+/* The hover edge steps aside under the band: an accent edge one pixel inside an
+   accent band is the second band #578 round r34 took off the focus rules, and a
+   pointer resting on a focused button would put it back. The fill above is not an
+   edge and stays. why: docs/foundations.md#the-focus-ring */
+.ui-btn:hover:not(:focus-visible) { border-color: var(--accent); }
 .ui-btn:active { transform: translateY(1px); }
 
 .ui-btn svg { width: 16px; height: 16px; flex: none; stroke-width: 2.4; }
@@ -61,7 +65,7 @@
   color: var(--text);
 }
 .ui-btn--ghost:hover {
-  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */
   border-color: transparent;
   color: var(--strong);
 }
@@ -70,7 +74,7 @@
 .ui-btn--danger:hover, .ui-btn--danger:focus-visible {
   color: var(--pink);
   border-color: var(--pink);
-  background: color-mix(in srgb, var(--pink) 10%, transparent); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: color-mix(in srgb, var(--pink) 10%, transparent); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */
 }
 
 /* -- Sizes -------------------------------------------------------------- */
@@ -95,7 +99,7 @@
    makes this read as inert; the quiet ink is the rest. #220 */
 .ui-btn:disabled,
 .ui-btn[aria-disabled="true"] {
-  background: var(--disabled-surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  background: var(--disabled-surface); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */
   border-color: var(--disabled-border);
   /* muted-ink: state — unavailable control */ color: var(--disabled-ink);
   cursor: not-allowed;
@@ -137,7 +141,7 @@
 .ui-btn[aria-busy="true"],
 .ui-btn[aria-busy="true"]:hover,
 .ui-btn[aria-busy="true"]:active {
-  background: var(--surface); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  background: var(--surface); /* code-bg: inherit — busy paint retains the button's containing gap. */
   border-color: var(--border);
   color: var(--text);
   filter: none;
@@ -146,35 +150,35 @@
 .ui-btn[aria-busy="true"].ui-btn--primary,
 .ui-btn[aria-busy="true"].ui-btn--primary:hover,
 .ui-btn[aria-busy="true"].ui-btn--primary:active {
-  background: var(--accent-strong); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  background: var(--accent-strong); /* code-bg: inherit — busy paint retains the button's containing gap. */
   border-color: var(--accent-strong);
   color: var(--accent-contrast);
 }
 .ui-btn[aria-busy="true"].ui-btn--ghost,
 .ui-btn[aria-busy="true"].ui-btn--ghost:hover,
 .ui-btn[aria-busy="true"].ui-btn--ghost:active {
-  background: transparent; /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  background: transparent; /* code-bg: inherit — busy paint retains the button's containing gap. */
   border-color: transparent;
   color: var(--text);
 }
 .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); /* ring-gap: inherit — busy paint retains the button's containing gap. */
+  background: var(--surface); /* code-bg: inherit — busy paint retains the button's containing gap. */
   border-color: var(--border);
   color: var(--text);
 }
 /* A caller can mark a control both busy and unavailable. The explicit marker
    keeps that ordinary disabled state from inheriting the busy variant paint. */
 .ui-btn[aria-busy="true"][data-btn-disabled] {
-  background: var(--disabled-surface); /* ring-gap: inherit — busy+disabled keeps its containing gap. */
+  background: var(--disabled-surface); /* code-bg: inherit — busy+disabled keeps its containing gap. */
   border-color: var(--disabled-border);
   /* muted-ink: state — busy+disabled control */ color: var(--disabled-ink);
   cursor: not-allowed;
   pointer-events: none;
 }
 .ui-btn--ghost[aria-busy="true"][data-btn-disabled] {
-  background: transparent; /* ring-gap: inherit — busy+disabled keeps its containing gap. */
+  background: transparent; /* code-bg: inherit — busy+disabled keeps its containing gap. */
   border-color: transparent;
   /* muted-ink: state — busy+disabled ghost */ color: var(--disabled-ink-bare);
 }
@@ -182,7 +186,6 @@
 .ui-btn__label {
   grid-area: 1 / 1;
   transform: translateY(0);
-
 }
 .ui-btn[data-btn-ready] .ui-btn__label { animation: ui-btn-label-in var(--dur-med) var(--ease-out) both; }
 .ui-btn[aria-busy="true"] .ui-btn__label {

package/src/styles/callout.css

@@ -7,7 +7,7 @@
   gap: 12px;
   padding: 15px 17px;
   border-radius: var(--radius-md);
-  background: var(--surface); --ring-gap: var(--surface);
+  background: var(--surface);
   font-size: calc(var(--text-sm) + 0.5px);
   line-height: 1.55;
   color: var(--text);
@@ -19,14 +19,14 @@
 .ui-callout b { color: var(--text); font-weight: var(--weight-semibold); }
 .ui-callout code { font-family: var(--font-mono); font-size: 0.92em; color: var(--text); }
 
-.ui-callout--info { --ring-gap: inherit; background: var(--glow-cyan); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-callout--info { background: var(--glow-cyan); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */ }
 .ui-callout--info .ui-callout__icon { color: var(--chip-info-ink); } /* the chip inks, not the raw signals: in light the raw signal cleared the graphic bar by a tenth on its own wash and read as a smudge, and a stroke is read the way text is. The two are the same value in dark by construction, so only light moves. #206 */
-.ui-callout--success { --ring-gap: inherit; background: var(--glow-green); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-callout--success { background: var(--glow-green); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */ }
 .ui-callout--success .ui-callout__icon { color: var(--chip-success-ink); }
 .ui-callout--success a { /* muted-ink: state — opaque accent/text blend keeps links above 4.5:1 on the success wash. */ color: color-mix(in srgb, var(--accent) 95%, var(--text)); }
-.ui-callout--warn { --ring-gap: inherit; background: color-mix(in srgb, var(--amber) 13%, transparent); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-callout--warn { background: color-mix(in srgb, var(--amber) 13%, transparent); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */ }
 .ui-callout--warn .ui-callout__icon { color: var(--chip-warn-ink); }
-.ui-callout--danger { --ring-gap: inherit; background: var(--glow-pink); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
+.ui-callout--danger { background: var(--glow-pink); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */ }
 .ui-callout--danger .ui-callout__icon { color: var(--chip-danger-ink); }
 
 /* ----------------------------------------------------------------------------
@@ -45,7 +45,7 @@
   width: 100%;
   max-width: var(--panel-md);
   overflow: hidden; /* clips the timer bar to the rounded corners */
-  background: var(--surface); --ring-gap: var(--surface);
+  background: var(--surface);
   border: 1px solid var(--float-edge);
   box-shadow: inset 0 0 0 1px var(--elev-edge, var(--float-edge-inner)), var(--elev-drop);
   animation: ui-toast-in var(--dur-med) var(--ease-out) both;
@@ -66,8 +66,8 @@
 
 /* Tone ink keeps actions readable on the neutral surface. */
 .ui-toast__action { flex: none; align-self: center; background: none; border: 0; padding: 4px 9px; border-radius: var(--radius-xs); font: inherit; font-weight: var(--weight-medium); color: var(--toast-action-ink); cursor: pointer; }
-.ui-toast__action:hover { background: color-mix(in srgb, var(--bg) 55%, transparent); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
-.ui-toast__action:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
+.ui-toast__action:hover { background: color-mix(in srgb, var(--bg) 55%, transparent); /* code-bg: inherit — control paint; the containing surface is the ground, for a chip and for a band alike. */ }
+.ui-toast__action:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
 
 .ui-toast__close { flex: none; align-self: flex-start; background: none; border: 0; /* muted-ink: glyph — dismiss icon */ color: var(--muted); cursor: pointer; padding: 2px; display: grid; place-items: center; position: relative; font: inherit; }
 .ui-toast__close svg { width: 15px; height: 15px; stroke: currentColor; fill: none; stroke-width: 2.5; }
@@ -91,14 +91,14 @@
   transform: translate(-50%, -50%);
 }
 .ui-toast__close:hover { color: var(--text); }
-.ui-toast__close:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-radius: var(--radius-xs); }
+.ui-toast__close:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); border-radius: var(--radius-xs); }
 
 /* auto-dismiss progress bar — .is-running is added by wireToastStack() */
 .ui-toast__timer { position: absolute; left: 0; bottom: 0; height: 3px; width: 100%; background: var(--toast-accent); opacity: 0.85; transform-origin: left; }
 .ui-toast__timer.is-running { animation: ui-toast-timer var(--toast-dur, 5s) linear forwards; /* motion: ambient — the bar spends the toast's dismiss timer, which the caller sets */ }
 
 /* Legacy style classes share the neutral card. */
-.ui-toast--soft, .ui-toast--solid, .ui-toast--outline { background: var(--surface); --ring-gap: var(--surface); color: var(--text); }
+.ui-toast--soft, .ui-toast--solid, .ui-toast--outline { background: var(--surface); color: var(--text); }
 
 /* compact — single line, no body text */
 .ui-toast--compact { align-items: center; }
@@ -121,7 +121,7 @@
   border-radius: var(--radius-lg);
   padding: 30px;
   text-align: center;
-  background: var(--glow-green); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
+  background: var(--glow-green); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */
 }
 .ui-success__check {
   --sx-green: var(--chip-success-ink);

package/src/styles/card.css

@@ -8,7 +8,7 @@
    instead — a 22px penumbra off a 10px offset, the width Artur's reference uses on a
    card. Chosen by him on #490 round t3. why: docs/foundations.md#elevation */
 .ui-card {
-  background: var(--surface); --ring-gap: var(--surface);
+  background: var(--surface);
   border: 1px solid var(--card-edge);
   box-shadow: var(--elev-rest);
   border-radius: var(--radius-xl);
@@ -46,11 +46,11 @@
    works in dark sinks a light card below the page. Each variant edges itself in its own
    colour. why: docs/foundations.md#elevation */
 .ui-card--accent {
-  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));
+  background: 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) var(--card-tint), var(--surface)); --ring-gap: color-mix(in srgb, var(--green) var(--card-tint), var(--surface));
+  background: color-mix(in srgb, var(--green) var(--card-tint), var(--surface));
   border-color: color-mix(in srgb, var(--green) 22%, transparent);
 }
 
@@ -68,7 +68,7 @@
 /* The lift alone: the card's own rung is what says it is raised, and hover is not a
    change of level. why: docs/foundations.md#elevation */
 .ui-card--interactive:hover { transform: translateY(-2px); }
-.ui-card--interactive:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
+.ui-card--interactive:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); }
 
 /* card() emits the title as an h2, so the text face is named here rather than
    left to the element. why: docs/foundations.md#labels-and-titles */
@@ -111,7 +111,7 @@
   border-radius: var(--radius-md);
   display: grid;
   place-items: center;
-  background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
+  background: var(--glow-purple); /* code-bg: inherit — a wash paints over a ground and behind a chip, so the opaque ground below it is the step. */
   color: var(--accent);
   flex: none;
 }

package/src/styles/code.css

@@ -4,7 +4,7 @@
  * ========================================================================== */
 
 .ui-snippet {
-  background: var(--surface); --ring-gap: var(--surface);
+  background: var(--surface);
   border-radius: var(--radius-md);
   overflow: hidden;
 }
@@ -34,22 +34,12 @@
    without its radius draws a square ring that cuts across the card and squares
    its corners. The card carries the ring instead, so it follows --radius-md and
    survives `overflow: hidden`, which clips descendants and not the card's own
-   shadow. --ring-gap comes from the page here, matching the container rule in
-   tokens.css: a ring outside its own surface cannot use that surface as its gap.
-   The card also keeps a transparent outline, which forced colors repaints as the
-   focus signal once box-shadow is gone; the block below is why only one box has
-   one there. See stories/snippet-focus.test.js. */
-.ui-snippet pre:focus-visible { box-shadow: none; }
-.ui-snippet:has(pre:focus-visible) { outline: 2px solid transparent; --ring-gap: inherit; box-shadow: var(--ring); }
-
-/* Forced colors drops box-shadow, so both boxes fall back to their outlines and
-   the system repaints the pre's transparent one as the square this rule set out
-   to remove — with the card's rounded one 2px further out, two indicators for one
-   focus. The card's outline is the one that survives, so the pre keeps none.
-   Emulated in stories/snippet-focus.test.js and captured in Chromium. #474 */
-@media (forced-colors: active) {
-  .ui-snippet pre:focus-visible { outline: none; }
-}
+   outline. The pre takes none, in every colour mode: the ring is a real outline
+   since #578, so `outline: none` here is what forced colors reads too, and the
+   @media block that used to say so is gone with the transparent stand-in it was
+   written for. See stories/snippet-focus.test.js. */
+.ui-snippet pre:focus-visible { outline: none; }
+.ui-snippet:has(pre:focus-visible) { outline: var(--ring); outline-offset: var(--ring-offset); }
 
 .ui-snippet__copy {
   background: none;
@@ -74,7 +64,7 @@
 }
 .ui-snippet__copy:hover { color: var(--accent); }
 .ui-snippet--reveal .ui-snippet__copy:hover { color: var(--strong); }
-.ui-snippet__copy:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-radius: var(--radius-xs); }
+.ui-snippet__copy:focus-visible { outline: var(--ring); outline-offset: var(--ring-offset); border-radius: var(--radius-xs); }
 .ui-snippet__copy svg { width: 13px; height: 13px; stroke: currentColor; fill: none; stroke-width: 2.8; }
 
 /* Shell token highlighting (matches viz/account.mjs classes) */
@@ -86,7 +76,7 @@
 
 /* Reveal: a live secret/token, tinted green */
 .ui-snippet--reveal {
-  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) 10%, var(--surface));
 }
 .ui-snippet--reveal .ui-snippet__bar > span { color: var(--chip-success-ink); }
 .ui-snippet--reveal pre { color: var(--chip-success-ink); word-break: break-all; white-space: pre-wrap; }
@@ -95,17 +85,16 @@
    identifier keeps its chip on the page and inside a card, with no edge of its own. The
    container hands the surface over in --code-bg; see src/tokens/tokens.css. #537
 
-   The chip READS --code-bg and never declares it, which is why its gap can match its paint
-   and its ring is composed here instead of in the shared recipe: a chip that re-pointed the
-   hand-off would hand the page to itself and paint the page everywhere. Backticks become a
-   chip wherever the kit renders prose (fmt() in site/changelog.mjs), so a link inside one is
-   ordinary markup and gets the gap of the surface it is actually on. */
+   The chip READS --code-bg and never declares it: a chip that re-pointed the hand-off would
+   hand the page to itself and paint the page everywhere. Backticks become a chip wherever
+   the kit renders prose (fmt() in site/changelog.mjs), so a link inside one is ordinary
+   markup, and the ring it draws needs nothing from the chip now that an outline leaves its
+   1px of offset unpainted. */
 .ui-code {
   font-family: var(--font-mono);
   font-size: 0.9em;
-  background: var(--code-bg); --ring-gap: var(--code-bg);
+  background: var(--code-bg);
   padding: 2px 6px;
   border-radius: var(--radius-xs);
   color: var(--text);
-  --ring: 0 0 0 var(--ring-gap-width) var(--ring-gap), 0 0 0 calc(var(--ring-gap-width) + var(--ring-width)) var(--ring-color), 0 0 12px 2px color-mix(in srgb, var(--ring-color) 45%, transparent);
 }