@apliteni/apliteni-ui 0.36.0 → 0.37.1

package/README.md

@@ -105,6 +105,10 @@ import { tokensCss, topbarCss, cssText } from '@apliteni/apliteni-ui/inline';
 // …inline tokensCss + topbarCss into the <style> you serve.
 ```
 
+`cssText` includes every sheet. When selecting individual sheets from `styles`,
+`successPanel()` needs both `styles.callout` (panel layout) and `styles.success`
+(shared glowing check and reduced-motion styles), after `tokensCss` and `baseCss`.
+
 ## React components (stateful surfaces)
 
 `DataTable`, `Pagination`, `Modal`, `Button`, `Badge`, `Card` and `Icon` — same `.ui-*` classes,
@@ -151,6 +155,13 @@ Each accent re-points only the accent family (`--accent`, `--purple*`, `--glow-p
 stay put — so **every accent works in both themes** and every component follows with no
 component-level change.
 
+Focus uses a surface-coloured gap, a solid band and a decorative glow. Tune
+`--ring-width`, `--ring-color`, `--ring-gap-width` and `--ring-gap` at the root;
+`--ring` remains the composed shadow. Kit surfaces recompose it to match their
+background, so an ancestor's custom `--ring` must also be applied on those surfaces.
+The page shell inherits root overrides; it does not introduce another composition.
+See [the focus-ring contract](docs/specification.md#the-focus-ring).
+
 Both attributes are overrides, not requirements: with neither present the kit paints dark
 Nebula, and `data-accent` alone paints that accent on the dark theme. An absent `data-theme`
 is *not* "follow the system" — the kit ships no `prefers-color-scheme` rule, so a host that

package/package.json

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

package/react/dist/index.css

@@ -44,6 +44,7 @@
 .rx-modal {
   width: min(480px, 92vw);
   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);
@@ -92,8 +93,8 @@
   color: inherit;
 }
 .rx-sort:focus-visible {
-  outline: 2px solid var(--accent);
-  outline-offset: 2px;
+  outline: 2px solid transparent;
+  box-shadow: var(--ring);
   border-radius: 4px;
 }
 .rx-caret {

package/src/components/index.js

@@ -2,10 +2,10 @@
 // viz/ server-render idiom so the portal can adopt them with no framework.
 import { icon } from '../assets/icons.js';
 import { illo } from '../assets/illustrations.js';
+import { successCheck } from './success.js';
 const HTML_ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
 const cx = (...a) => a.filter(Boolean).join(' ');
 export const esc = (s) => String(s == null ? '' : s).replace(/[&<>"]/g, (c) => HTML_ENTITIES[c]);
-
 // ---- Button --------------------------------------------------------------
 // `iconSvg` is a raw leading-icon SVG string (trusted markup, not escaped) for
 // branded glyphs the kit's icon set doesn't own — e.g. a Google "G". It takes
@@ -261,9 +261,9 @@ export function toast({
 // The kit also publishes success() from components/success.js, which is the same
 // idea at page size: layouts, a backdrop, follow-up buttons and an auto-redirect
 // countdown. Pick by how much of the screen the confirmation owns. The two share
-// no CSS, so changing one never moves the other.
+// the glowing check; their layout and content remain independent.
 export function successPanel({ title = 'Done', sub = '' } = {}) {
-  return `<div class="ui-success"><div class="ui-success__check">${icon('check')}</div><div class="ui-success__title">${esc(title)}</div>${sub ? `<div class="ui-success__sub">${esc(sub)}</div>` : ''}</div>`;
+  return `<div class="ui-success"><div class="ui-success__check">${successCheck()}</div><div class="ui-success__title">${esc(title)}</div>${sub ? `<div class="ui-success__sub">${esc(sub)}</div>` : ''}</div>`;
 }
 
 // ---- Empty state ---------------------------------------------------------

package/src/components/success.js

@@ -60,8 +60,8 @@ function countdownEl({ seconds = 5, label = 'Redirecting' } = {}) {
 // For a confirmation that stays inside the page the user is already on, the kit
 // publishes successPanel() from components/index.js — a check, a title and one
 // line of sub, and nothing to configure. Pick by how much of the screen the
-// confirmation owns. The two share no CSS (.ui-sx here, .ui-success there), so
-// changing one never moves the other.
+// confirmation owns. The two share the glowing check, while their layout
+// and content remain independent.
 export function success({
   layout = 'hero',          // 'hero' | 'split' | 'compact'
   level,                    // heading level of the title; see the note below

package/src/inline.js

@@ -25,7 +25,7 @@ export const baseCss = read('styles/base.css');
 // Canonical topbar (same class names the portal already uses).
 export const topbarCss = read('styles/topbar.css');
 
-// Individual component stylesheets, addressable by name.
+// Individual sheets; successPanel() needs both styles.callout and styles.success.
 export const styles = {
   base: baseCss,
   reducedMotion: read('styles/reduced-motion.css'),

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-2); }
-.ui-back:focus-visible { outline: none; box-shadow: var(--ring); }
+.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: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
    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,29 +15,29 @@
   padding: 3px 9px;
   border-radius: var(--radius-pill);
   color: var(--text);
-  background: var(--surface-2);
+  background: var(--surface-2); /* 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); }
-.ui-badge--soon { color: var(--purple-mid); background: var(--glow-purple); }
-.ui-badge--info { color: var(--chip-info-ink); background: var(--chip-info-fill); }
+.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--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); }
-.ui-badge--archive { /* muted-ink: state — archived record */ color: var(--muted); background: var(--surface); }
+.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. */ }
 
 /* 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); }
+.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); }
+.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); }
-:root[data-theme="light"] .ui-badge--archive { /* muted-ink: state — archived record */ color: var(--muted); background: var(--surface-3); }
+: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. */ }
 
 /* Pill: same shape, sentence case, a touch larger — a metadata chip */
 .ui-pill {
@@ -47,7 +47,7 @@
   /* rank: chip */
   font-size: var(--text-xs);
   color: var(--text);
-  background: var(--surface-2);
+  background: var(--surface-2); /* 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);
@@ -55,8 +55,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); }
-.ui-pill--soon { color: var(--purple-mid); background: var(--glow-purple); }
+.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. */ }
 
 /* Status dot */
 .ui-dot {

package/src/styles/base.css

@@ -15,7 +15,7 @@ html {
 }
 
 body {
-  background: var(--bg);
+  background: var(--bg); /* ring-gap: 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);
+  background: color-mix(in srgb, var(--accent) 30%, transparent); /* ring-gap: 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%);
+  background: radial-gradient(620px 340px at 50% -12%, var(--glow-purple), transparent 70%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
 }
 /* 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%);
+  background: linear-gradient(180deg, var(--glow-purple), transparent 45%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
 }
 
 /* Layout helpers used by the example apps */
@@ -142,6 +142,6 @@ svg:where(:not([width]):not([height])) {
 .ui-input:focus-visible,
 .ui-seg button:focus-visible,
 .ui-switch:focus-visible {
-  outline: none;
+  outline: 2px solid transparent;
   box-shadow: var(--ring);
 }

package/src/styles/button.css

@@ -20,7 +20,7 @@
   padding: var(--btn-pad-y) var(--btn-pad-x);
   cursor: pointer;
   border: 1px solid var(--border);
-  background: var(--surface-2);
+  background: var(--surface-2); /* 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 +32,7 @@
 
 .ui-btn:hover {
   border-color: var(--accent);
-  background: color-mix(in srgb, var(--accent) 14%, var(--surface-2));
+  background: color-mix(in srgb, var(--accent) 14%, var(--surface-2)); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--strong);
 }
 .ui-btn:active { transform: translateY(1px); }
@@ -59,7 +59,7 @@
   color: var(--text);
 }
 .ui-btn--ghost:hover {
-  background: var(--surface-2);
+  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border-color: transparent;
   color: var(--strong);
 }
@@ -68,7 +68,7 @@
 .ui-btn--danger:hover {
   color: var(--pink);
   border-color: var(--pink);
-  background: color-mix(in srgb, var(--pink) 10%, transparent);
+  background: color-mix(in srgb, var(--pink) 10%, transparent); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
 }
 
 /* -- Sizes -------------------------------------------------------------- */
@@ -93,7 +93,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);
+  background: var(--disabled-surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border-color: var(--disabled-border);
   /* muted-ink: state — unavailable control */ color: var(--disabled-ink);
   cursor: not-allowed;
@@ -137,7 +137,7 @@
   left: 10px; right: 10px; bottom: 5px;
   height: 3px;
   border-radius: 999px;
-  background: color-mix(in srgb, var(--accent) 22%, transparent);
+  background: color-mix(in srgb, var(--accent) 22%, transparent); /* ring-gap: inherit — decorative paint has no nested focus target. */
   overflow: hidden;
   /* Clean entrance: grow + fade in on state change, once. */
   transform-origin: center;
@@ -156,7 +156,7 @@
 /* On the filled primary the surface IS the accent, so shimmer in the contrast
    colour instead — otherwise the bars vanish into the button. */
 .ui-btn--primary .ui-btn__bars {
-  background: color-mix(in srgb, var(--accent-contrast) 26%, transparent);
+  background: color-mix(in srgb, var(--accent-contrast) 26%, transparent); /* ring-gap: inherit — decorative paint has no nested focus target. */
 }
 .ui-btn--primary .ui-btn__bars i {
   background: linear-gradient(90deg,

package/src/styles/callout.css

@@ -7,7 +7,7 @@
   gap: 12px;
   padding: 15px 17px;
   border-radius: var(--radius-md);
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   font-size: calc(var(--text-sm) + 0.5px);
   line-height: 1.55;
   color: var(--text);
@@ -17,13 +17,13 @@
 .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 { background: var(--glow-cyan); }
+.ui-callout--info { --ring-gap: inherit; background: var(--glow-cyan); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 .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 { background: var(--glow-green); }
+.ui-callout--success { --ring-gap: inherit; background: var(--glow-green); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 .ui-callout--success .ui-callout__icon { color: var(--chip-success-ink); }
-.ui-callout--warn { background: color-mix(in srgb, var(--amber) 13%, transparent); }
+.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 .ui-callout__icon { color: var(--chip-warn-ink); }
-.ui-callout--danger { background: var(--glow-pink); }
+.ui-callout--danger { --ring-gap: inherit; background: var(--glow-pink); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 .ui-callout--danger .ui-callout__icon { color: var(--chip-danger-ink); }
 
 /* ----------------------------------------------------------------------------
@@ -85,7 +85,7 @@
    the ink is dark and darkens it where the ink is bright — the hovered pair is
    at or above the resting pair in both. */
 .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); }
+.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__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; }
@@ -117,7 +117,7 @@
 /* style: soft — tinted surface. The shadow used to be its edge, so it takes the
    status-tinted hairline the outline style carries, at half the weight. #295 */
 .ui-toast--soft {
-  background: var(--toast-glow);
+  background: var(--toast-glow); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
   border: 1px solid color-mix(in srgb, var(--toast-accent) 22%, transparent);
   --elev-edge: color-mix(in srgb, var(--toast-accent) 11%, transparent);
 }
@@ -130,8 +130,8 @@
    clear each other — and four of the ten status x theme combinations did not.
    Gated for all ten in stories/signal-contrast.test.js. See #149. */
 .ui-toast--solid {
-  --toast-ink: var(--signal-solid-ink);
-  background: var(--toast-solid);
+  --toast-ink: var(--signal-solid-ink); --ring-color: var(--toast-ink);
+  background: var(--toast-solid); --ring-gap: var(--toast-solid);
   color: var(--toast-ink);
   /* No inner line: a solid toast has no outer one either. It keeps the drop. */
   --elev-edge: transparent;
@@ -143,18 +143,18 @@
    there, and 2.25 on the dark danger fill — the pair was correct and the
    dilution then spent it. */
 .ui-toast--solid .ui-toast__text { color: var(--toast-ink); }
-.ui-toast--solid .ui-toast__icon { background: color-mix(in srgb, var(--toast-ink) 22%, transparent); color: var(--toast-ink); }
+.ui-toast--solid .ui-toast__icon { background: color-mix(in srgb, var(--toast-ink) 22%, transparent); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--toast-ink); }
 .ui-toast--solid .ui-toast__action { color: var(--toast-ink); }
 /* Hover darkens the FILL rather than lightening the ink. Washing the ink over
    itself was the one surface #149 did not reach, and it worked against the pair
    it was drawn from: it pulled the fill towards the ink it has to clear. */
-.ui-toast--solid .ui-toast__action:hover { background: color-mix(in srgb, var(--signal-contrast) 14%, transparent); }
+.ui-toast--solid .ui-toast__action:hover { background: color-mix(in srgb, var(--signal-contrast) 14%, transparent); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-toast--solid .ui-toast__close { /* muted-ink: glyph — dismiss icon on solid toast */ color: color-mix(in srgb, var(--toast-ink) 68%, transparent); }
 .ui-toast--solid .ui-toast__close:hover { color: var(--toast-ink); }
-.ui-toast--solid .ui-toast__timer { background: color-mix(in srgb, var(--toast-ink) 55%, transparent); }
+.ui-toast--solid .ui-toast__timer { background: color-mix(in srgb, var(--toast-ink) 55%, transparent); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* style: outline — elevated card with a status-tinted border */
-.ui-toast--outline { background: var(--bg-elevated); border: 1px solid color-mix(in srgb, var(--toast-accent) 40%, transparent); --elev-edge: color-mix(in srgb, var(--toast-accent) 20%, transparent); }
+.ui-toast--outline { background: var(--bg-elevated); --ring-gap: var(--bg-elevated); border: 1px solid color-mix(in srgb, var(--toast-accent) 40%, transparent); --elev-edge: color-mix(in srgb, var(--toast-accent) 20%, transparent); }
 
 /* compact — single line, no body text */
 .ui-toast--compact { align-items: center; padding-top: 10px; padding-bottom: 10px; }
@@ -178,17 +178,13 @@
   border-radius: var(--radius-lg);
   padding: 30px;
   text-align: center;
-  background: var(--glow-green);
+  background: var(--glow-green); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
 }
 .ui-success__check {
+  --sx-green: var(--chip-success-ink);
   width: 48px; height: 48px;
-  border-radius: 50%;
-  background: var(--green);
-  color: var(--signal-contrast);
-  display: grid;
-  place-items: center;
   margin: 0 auto 14px;
 }
-.ui-success__check svg { width: 22px; height: 22px; stroke: currentColor; fill: none; stroke-width: 2.4; }
+.ui-success__check .ui-sx__check { width: 100%; height: 100%; }
 .ui-success__title { color: var(--strong); font-size: var(--text-lg); font-weight: var(--weight-semibold); margin-bottom: 5px; }
 .ui-success__sub { color: var(--text); font-size: var(--text-base); }

package/src/styles/card.css

@@ -6,7 +6,7 @@
 /* Flat since #284 and edged in both themes since #295: the surface is the step, the
    line is what makes it legible. why: docs/specification.md#elevation */
 .ui-card {
-  background: var(--surface);
+  background: var(--surface); --ring-gap: var(--surface);
   border: 1px solid var(--border);
   border-radius: var(--radius-xl);
   padding: var(--space-6) 26px;
@@ -28,11 +28,11 @@
 /* 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 */
 .ui-card--accent {
-  background: color-mix(in srgb, var(--accent) 9%, var(--surface));
+  background: color-mix(in srgb, var(--accent) 9%, var(--surface)); --ring-gap: color-mix(in srgb, var(--accent) 9%, 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));
+  background: color-mix(in srgb, var(--green) 10%, var(--surface)); --ring-gap: color-mix(in srgb, var(--green) 10%, var(--surface));
 }
 
 /* Interactive card (link / button semantics) */
@@ -89,7 +89,7 @@
   border-radius: var(--radius-md);
   display: grid;
   place-items: center;
-  background: var(--glow-purple);
+  background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
   color: var(--accent);
   flex: none;
 }

package/src/styles/code.css

@@ -4,7 +4,7 @@
  * ========================================================================== */
 
 .ui-snippet {
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   border-radius: var(--radius-md);
   overflow: hidden;
 }
@@ -61,7 +61,7 @@
 
 /* Reveal: a live secret/token, tinted green */
 .ui-snippet--reveal {
-  background: color-mix(in srgb, var(--green) 10%, var(--surface));
+  background: color-mix(in srgb, var(--green) 10%, var(--surface)); --ring-gap: color-mix(in srgb, var(--green) 10%, var(--surface));
 }
 .ui-snippet--reveal .ui-snippet__bar span { color: var(--green); }
 .ui-snippet--reveal pre { color: var(--green); word-break: break-all; white-space: pre-wrap; }
@@ -70,7 +70,7 @@
 .ui-code {
   font-family: var(--font-mono);
   font-size: 0.9em;
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   padding: 2px 6px;
   border-radius: var(--radius-xs);
   color: var(--text);

package/src/styles/command-palette.css

@@ -68,7 +68,7 @@
   display: flex;
   flex-direction: column;
   font-family: var(--font-sans);
-  background: var(--cmdk-surface);
+  background: var(--cmdk-surface); --ring-gap: var(--cmdk-surface);
   /* The two-step edge and the drop: --border-strong outside, --border one pixel
      inside it, then the broad faint drop. why: docs/specification.md#elevation */
   border: 1px solid var(--border-strong);
@@ -86,7 +86,7 @@
    box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
    took the panel's edge and its drop off for as long as it held focus.
    why: docs/specification.md#elevation */
-.ui-cmdk__panel:focus-visible { outline: none; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
+.ui-cmdk__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
 
 /* -- The text box --------------------------------------------------------- */
 
@@ -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); }
+.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 .ui-cmdk__label { color: var(--strong); }
 
 .ui-cmdk__ic {
@@ -258,7 +258,7 @@
   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);
+  background: var(--surface-3); /* 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;
@@ -301,10 +301,10 @@
   align-items: center;
   justify-content: center;
   border-radius: var(--radius-sm);
-  background: var(--surface);
+  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); }
+.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. */ }
 
 /* -- Narrow --------------------------------------------------------------- */
 /* At the kit's narrowest step the palette is the page: full width, off the top

package/src/styles/confirm.css

@@ -61,7 +61,7 @@
   flex-direction: column;
   gap: var(--space-2);
   padding: var(--space-5);
-  background: var(--confirm-surface);
+  background: var(--confirm-surface); --ring-gap: var(--confirm-surface);
   /* The two-step edge and the drop: --border-strong outside, --border one pixel
      inside it, then the broad faint drop. why: docs/specification.md#elevation */
   border: 1px solid var(--border-strong);
@@ -78,7 +78,7 @@
    box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
    took the panel's edge and its drop off for as long as it held focus.
    why: docs/specification.md#elevation */
-.ui-confirm__panel:focus-visible { outline: none; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
+.ui-confirm__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
 
 /* -- Slots ----------------------------------------------------------------- */
 /* The question and the answers keep their size; the consequence between them is

package/src/styles/drawer.css

@@ -57,7 +57,7 @@
   position: absolute;
   display: flex;
   flex-direction: column;
-  background: var(--drawer-surface);
+  background: var(--drawer-surface); --ring-gap: var(--drawer-surface);
   /* A drawer is flush to a screen edge, so it has one edge rather than four and the
      two-step edge runs along that one: --border-strong on the edge rule below, the
      inner line one pixel inside it. This is the one floating surface that writes no
@@ -115,7 +115,7 @@
    box-shadow list replaces the whole list, so a bare `box-shadow: var(--ring)` would
    take the drawer's edge and its drop off for as long as it held focus.
    why: docs/specification.md#elevation */
-.ui-drawer__panel:focus-visible { outline: none; box-shadow: var(--ring), var(--drawer-line), var(--elev-drop); }
+.ui-drawer__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), var(--drawer-line), var(--elev-drop); }
 
 /* -- Sizes ----------------------------------------------------------------- */
 /* left|right → width; top|bottom → height. Same names, axis chosen by side. */
@@ -169,8 +169,8 @@
     background var(--dur-fast) var(--ease),
     border-color var(--dur-fast) var(--ease);
 }
-.ui-drawer__close:hover { color: var(--strong); background: var(--surface-3); }
-.ui-drawer__close:focus-visible { outline: none; box-shadow: var(--ring); border-color: var(--accent); }
+.ui-drawer__close:hover { color: var(--strong); background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-drawer__close:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-color: var(--accent); }
 .ui-drawer__close svg { width: 18px; height: 18px; stroke: currentColor; fill: none; stroke-width: 2.1; }
 
 .ui-drawer__body {
@@ -191,7 +191,7 @@
   gap: 10px;
   padding: 16px 20px;
   border-top: 1px solid var(--border);
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   flex: none;
 }
 

package/src/styles/dropdown.css

@@ -17,14 +17,14 @@
   font-size: calc(var(--text-sm) - 0.5px);
   font-weight: 500;
   color: var(--text);
-  background: var(--surface);
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--border);
   border-radius: var(--radius-pill);
   padding: 7px 11px 7px 13px;
   transition: border-color var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease);
 }
 .ui-dropdown__trigger:hover { border-color: var(--accent); }
-.ui-dropdown__trigger:focus-visible { outline: none; box-shadow: var(--ring); border-color: var(--accent); }
+.ui-dropdown__trigger:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-color: var(--accent); }
 .ui-dropdown__pre { color: var(--text); }
 .ui-dropdown__value { color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
 
@@ -70,7 +70,7 @@
   min-width: 240px;
   /* The floating step, not the sunken one — a panel held open over a card cannot be
      painted the colour of an inset. why: docs/specification.md#elevation */
-  background: var(--bg-elevated);
+  background: var(--bg-elevated); --ring-gap: var(--bg-elevated);
   /* The two-step edge and the drop: --border-strong outside, --border one pixel
      inside it, then the broad faint drop. why: docs/specification.md#elevation */
   border: 1px solid var(--border-strong);
@@ -152,8 +152,8 @@
   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); }
-.ui-dropdown__item:focus-visible { outline: none; background: var(--surface-3); box-shadow: var(--ring); }
+.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); }
 .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);
+  background: var(--surface-3); /* 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); }
+.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.
    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); }
+.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. */ }
 
 /* Disabled + danger rows */
 .ui-dropdown__item.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: not-allowed; pointer-events: none; }
@@ -258,7 +258,7 @@
   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);
+  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--border);
   border-radius: var(--radius-sm);
   padding: 8px 12px 8px 34px;
@@ -271,11 +271,11 @@
    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); }
+:root[data-theme="light"] .ui-dropdown__search-input { background: var(--bg); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 
 .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:focus-visible { outline: none; border-color: var(--accent); box-shadow: var(--ring); }
+.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; }
 /* A row is `display: flex`, which outranks the UA's [hidden], so a row the
@@ -284,7 +284,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); box-shadow: inset 2px 0 0 var(--accent); }
+.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); }
 
 /* No match — a nudge and no action, per Guidelines / Microcopy. Empty while
    anything matches, so it takes no room. */