@apliteni/apliteni-ui 0.35.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.35.0",
+  "version": "0.37.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -101,6 +101,11 @@ each other on the same page.
 
 ## Dropdown
 
+Use `badge: { text: 'Archivado', tone: 'state' }` for off, unset, disabled or archived
+states, including translated labels. Explicit `tone: 'neutral'` uses body ink. When tone
+is omitted, exact English off/unset/disabled/archive/archived labels fall back to state
+ink and Live to live ink; other labels use body ink. This also applies to vanilla `dropdown()`.
+
 `Dropdown` renders the kit's `dropdown()` markup, class for class, and carries
 `wireDropdown()`'s keyboard: the arrows open it onto the first row or the selected one and
 then walk the ring, stepping over a disabled row and wrapping at both ends; Home and End go

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,10 +93,11 @@
   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 {
   margin-left: 2px;
+  color: var(--muted);
 }

package/react/dist/index.js

@@ -1064,7 +1064,8 @@ var Glyph2 = ({ name, className, hidden }) => /* @__PURE__ */ jsx12(
 function RowBadge({ badge }) {
   const text2 = typeof badge === "string" ? badge : badge.text;
   const given = typeof badge === "string" ? "" : badge.tone || "";
-  const tone = given || (/^live$/i.test(String(text2)) ? "live" : "neutral");
+  let tone = given || (/^live$/i.test(String(text2)) ? "live" : "neutral");
+  if (!given && tone === "neutral" && /^(?:off|unset|disabled|archive|archived)$/i.test(text2)) tone = "state";
   return /* @__PURE__ */ jsx12("span", { className: `ui-dropdown__badge is-${tone}`, children: text2 });
 }
 var keyOf = (it) => it.value != null ? `v:${it.value}` : `l:${it.label}`;

package/src/components/dropdown.js

@@ -22,7 +22,8 @@ function ddBadge(badge) {
   if (!badge) return '';
   const text = typeof badge === 'string' ? badge : badge.text;
   let tone = typeof badge === 'string' ? '' : (badge.tone || '');
-  if (!tone) tone = /^live$/i.test(text) ? 'live' : 'neutral';
+  if (!tone) tone = /^live$/i.test(text) ? 'live'
+    : /^(?:off|unset|disabled|archive|archived)$/i.test(text) ? 'state' : 'neutral';
   return `<span class="${cx('ui-dropdown__badge', `is-${tone}`)}">${esc(text)}</span>`;
 }
 

package/src/styles/back.css

@@ -30,9 +30,9 @@
    and outranks a bare class: it would paint this in the host's link colour.
    (0,2,0) wins without !important — the argument `.ui-nav .ui-nav__item` makes
    in nav.css. */
-.ui-back[href] { color: var(--dim); }
-.ui-back[href]:hover { color: var(--strong); background: var(--surface-2); }
-.ui-back:focus-visible { outline: none; box-shadow: var(--ring); }
+.ui-back[href] { color: var(--text); }
+.ui-back[href]:hover { color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-back: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

@@ -14,30 +14,30 @@
   font-weight: var(--weight-semibold);
   padding: 3px 9px;
   border-radius: var(--radius-pill);
-  color: var(--muted);
-  background: var(--surface-2);
+  color: var(--text);
+  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 { 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(--muted); 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 their ink is plain --muted. */
-:root[data-theme="light"] .ui-badge--neutral,
-:root[data-theme="light"] .ui-badge--archive { color: var(--muted); background: var(--surface-3); }
+   surface scale (--surface-3), and only archive uses muted state ink. */
+:root[data-theme="light"] .ui-badge--neutral { background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+:root[data-theme="light"] .ui-badge--archive { /* muted-ink: state — archived record */ color: var(--muted); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* Pill: same shape, sentence case, a touch larger — a metadata chip */
 .ui-pill {
@@ -46,8 +46,8 @@
   gap: 7px;
   /* rank: chip */
   font-size: var(--text-xs);
-  color: var(--muted);
-  background: var(--surface-2);
+  color: var(--text);
+  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 */
@@ -120,7 +120,7 @@ strong {
   /* rank: label */
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
-  color: var(--muted);
+  color: var(--text);
 }
 
 /* Sensible default size for inline icons that a parent rule doesn't size.
@@ -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); }
@@ -56,19 +56,19 @@
 .ui-btn--ghost {
   background: transparent;
   border-color: transparent;
-  color: var(--dim);
+  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);
 }
 
-.ui-btn--danger { color: var(--muted); }
+.ui-btn--danger { color: var(--text); }
 .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,9 +93,9 @@
    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);
-  color: var(--disabled-ink);
+  /* muted-ink: state — unavailable control */ color: var(--disabled-ink);
   cursor: not-allowed;
   pointer-events: none;
 }
@@ -104,12 +104,12 @@
 .ui-btn--ghost[aria-disabled="true"] {
   background: transparent;
   border-color: transparent;
-  color: var(--disabled-ink-bare);
+  /* muted-ink: state — unavailable control */ color: var(--disabled-ink-bare);
 }
 /* With no box, the ink is read on whatever is behind it, so the ghost takes an ink
    set for the dullest ground: in dark 7.49 / 6.31 / 7.00 / 5.44 on --bg / --surface /
-   --surface-2 / --surface-3, in light 5.70 / 6.17 / 5.20 / 5.39. The enabled ghost's
-   --dim reads about 1.5 times that in both themes. #273 cut this ink to rescue two
+   --surface-2 / --surface-3, in light 5.70 / 6.17 / 5.20 / 5.39. The enabled ghost now uses body
+   ink, keeping its words readable without changing the disabled pair. #273 cut this ink to rescue two
    dark pairs from under #220's floor; #295 re-picked --muted against the elevation
    ladder and lifted both clear, so it is the margin now rather than the rescue.
 
@@ -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,23 +7,23 @@
   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(--dim);
+  color: var(--text);
 }
-.ui-callout__icon { width: 18px; height: 18px; flex: none; margin-top: 1px; color: var(--muted); }
+.ui-callout__icon { width: 18px; height: 18px; flex: none; margin-top: 1px; /* muted-ink: glyph — nonverbal callout icon */ color: var(--muted); }
 .ui-callout__icon svg { width: 100%; height: 100%; stroke: currentColor; fill: none; stroke-width: 2.1; } /* 2.1 of a 24 box drawn at 18px = 1.58 CSS px, which is what buys the 3:1 graphic bar rather than the 4.5:1 text one. docs/specification.md#icons-and-glyphs */
 .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); }
 
 /* ----------------------------------------------------------------------------
@@ -61,7 +61,7 @@
 .ui-toast--danger  { --toast-accent: var(--pink);  --toast-action-ink: var(--chip-danger-ink);  --toast-glow: var(--glow-pink);  --toast-on: var(--danger-contrast); --toast-solid: var(--signal-solid-danger); }
 .ui-toast--warn    { --toast-accent: var(--amber); --toast-action-ink: var(--chip-warn-ink);    --toast-glow: color-mix(in srgb, var(--amber) 14%, transparent); --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-warn); }
 .ui-toast--info    { --toast-accent: var(--cyan);  --toast-action-ink: var(--chip-info-ink);    --toast-glow: var(--glow-cyan);  --toast-on: var(--signal-contrast); --toast-solid: var(--signal-solid-info); }
-.ui-toast--neutral { --toast-accent: var(--muted); --toast-action-ink: var(--muted);            --toast-glow: var(--surface-2); --toast-on: var(--signal-solid-ink); --toast-solid: var(--signal-solid-neutral); }
+.ui-toast--neutral { --toast-accent: var(--muted); --toast-action-ink: var(--text);            --toast-glow: var(--surface-2); --toast-on: var(--signal-solid-ink); --toast-solid: var(--signal-solid-neutral); }
 
 /* left status marker (soft + outline; solid is already a full fill) */
 .ui-toast--soft::before,
@@ -74,7 +74,7 @@
 .ui-toast__icon svg { width: 13px; height: 13px; stroke: currentColor; fill: none; stroke-width: 2.8; } /* 2.8 of a 24 box drawn at 13px = 1.52 CSS px. The circle has no room for a bigger glyph, so the weight comes out of the stroke. docs/specification.md#icons-and-glyphs */
 .ui-toast__body { flex: 1; min-width: 0; }
 .ui-toast__title { font-weight: var(--weight-medium); color: var(--strong); }
-.ui-toast__text { color: var(--dim); }
+.ui-toast__text { color: var(--text); }
 
 /* trailing action ("Undo" / "Retry") — status-coloured TEXT, so it takes the
    text-grade ink rather than the accent.
@@ -85,9 +85,9 @@
    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; color: var(--muted); cursor: pointer; padding: 2px; display: grid; place-items: center; position: relative; font: inherit; }
+.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; }
 /* The target, not the ink. WCAG 2.5.8 measures what a pointer can land on, and
    the drawn button is 19x19 — a 15px glyph in 2px of padding. Growing the box
@@ -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;
@@ -142,19 +142,19 @@
    (--chip-success-ink in light). The opacity: 0.82 this replaced measured 4.19
    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: color-mix(in srgb, var(--toast-ink) 90%, transparent); }
-.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__text { 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__close { color: color-mix(in srgb, var(--toast-ink) 68%, 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;
@@ -191,4 +191,4 @@
 }
 .ui-success__check svg { width: 22px; height: 22px; stroke: currentColor; fill: none; stroke-width: 2.4; }
 .ui-success__title { color: var(--strong); font-size: var(--text-lg); font-weight: var(--weight-semibold); margin-bottom: 5px; }
-.ui-success__sub { color: var(--dim); font-size: var(--text-base); }
+.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) */
@@ -64,7 +64,7 @@
   margin: 0 0 5px;
 }
 .ui-card__sub {
-  color: var(--dim);
+  color: var(--text);
   font-size: var(--text-base);
   line-height: var(--leading-snug);
   margin-bottom: var(--space-5);
@@ -80,7 +80,7 @@
 }
 .ui-card__row + .ui-card__row { border-top: 1px solid var(--border); }
 .ui-card__row .lab { color: var(--strong); font-size: var(--text-md); font-weight: var(--weight-medium); }
-.ui-card__row .hint { color: var(--dim); font-size: calc(var(--text-sm) + 0.5px); margin-top: 3px; }
+.ui-card__row .hint { color: var(--text); font-size: calc(var(--text-sm) + 0.5px); margin-top: 3px; }
 
 /* Icon chip that leads a card header */
 .ui-card__icon {
@@ -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;
 }
@@ -18,7 +18,7 @@
   /* rank: label */
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
-  color: var(--muted);
+  color: var(--text);
 }
 .ui-snippet pre {
   margin: 0;
@@ -33,7 +33,7 @@
 .ui-snippet__copy {
   background: none;
   border: 0;
-  color: var(--muted);
+  color: var(--text);
   cursor: pointer;
   font-family: var(--font-sans);
   font-size: calc(var(--text-xs) + 1px);
@@ -57,11 +57,11 @@
 .ui-snippet pre .f { color: var(--cyan); }
 .ui-snippet pre .s { color: var(--green); }
 .ui-snippet pre .u { color: var(--cyan); }
-.ui-snippet pre .c { color: var(--muted); }
+.ui-snippet pre .c { color: var(--text); font-style: italic; }
 
 /* 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);