@apliteni/apliteni-ui 0.36.0 → 0.37.0

package/README.md

@@ -151,6 +151,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.0",
   "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/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,7 +178,7 @@
   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 {
   width: 48px; height: 48px;

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. */

package/src/styles/feedback.css

@@ -66,7 +66,7 @@
 /* The composer panel (bottom-centre) */
 .ui-fbcomposer {
   position: fixed; z-index: 71; left: 50%; bottom: 26px; transform: translateX(-50%) translateY(14px);
-  width: min(520px, calc(100vw - 32px)); background: var(--bg-elevated); border-radius: 18px;
+  width: min(520px, calc(100vw - 32px)); background: var(--bg-elevated); --ring-gap: var(--bg-elevated); border-radius: 18px;
   /* The shadow was its only edge until #295; now it takes the hairline. */
   border: 1px solid var(--border); opacity: 0; pointer-events: none;
   transition: opacity var(--dur-med) var(--ease), transform var(--dur-med) var(--ease); overflow: hidden;
@@ -76,29 +76,29 @@
 .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); /* 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-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: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); border-radius: 12px; padding: 12px 15px; display: flex; gap: 11px; }
+.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__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); border: 0; border-radius: 12px; padding: 13px 15px; transition: box-shadow var(--dur-fast) var(--ease);
+  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);
 }
 .ui-fbcomposer textarea::placeholder { /* muted-ink: placeholder — empty feedback field */ color: var(--muted); }
-.ui-fbcomposer textarea:focus { outline: none; box-shadow: 0 0 0 2px var(--accent); }
+.ui-fbcomposer textarea:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-fbc__foot { display: flex; align-items: center; justify-content: flex-end; gap: 12px; padding: 16px 20px 18px; }
 
 .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); }
+.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.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). */
 .ui-fbbtn.primary:disabled {
-  background: var(--disabled-surface);
+  background: var(--disabled-surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   /* muted-ink: state — unavailable control */ color: var(--disabled-ink);
   cursor: default;
   filter: none;
@@ -108,7 +108,7 @@
 @keyframes uiFbSpin { to { transform: rotate(360deg); } }
 
 /* Success state */
-.ui-fbc__done { padding: 30px 26px 24px; text-align: center; background: radial-gradient(112% 60% at 50% 0%, var(--glow-green), transparent 62%); }
+.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; }
@@ -123,7 +123,7 @@
 @keyframes uiFbCkSpring { 0% { transform: scale(1.32); } 62% { transform: scale(.965); } 82% { transform: scale(1.02); } 100% { transform: scale(1); } }
 
 /* Error banner */
-.ui-fbc__err { margin: 14px 20px 0; background: color-mix(in srgb, var(--pink) 14%, transparent); color: var(--pink); font-size: var(--text-sm); padding: 11px 15px; border-radius: 11px; display: none; }
+.ui-fbc__err { margin: 14px 20px 0; background: color-mix(in srgb, var(--pink) 14%, transparent); /* ring-gap: inherit — text-only validation message has no nested focus target. */ color: var(--pink); font-size: var(--text-sm); padding: 11px 15px; border-radius: 11px; display: none; }
 .ui-fbc__err.show { display: block; }
 /* A failed send's line fades in; wireFeedback() adds the class as it shows it. */
 .ui-fbc__err.is-entering { animation: m-fade var(--dur-fast) var(--ease-out) both; }