@apliteni/apliteni-ui 0.36.0 → 0.37.0

package/src/styles/footer.css

@@ -14,7 +14,7 @@
   --footer-title: var(--strong);
   --footer-text: var(--text);
 
-  background: var(--footer-surface);
+  background: var(--footer-surface); /* ring-gap: inherit — transparent footer inherits; the app variant composes its opaque surface. */
   border-top: 1px solid var(--footer-border);
   color: var(--footer-text);
   font-family: var(--font-sans);
@@ -55,7 +55,7 @@
   border-radius: 10px;
   border: 1px solid var(--footer-border);
   color: var(--footer-link);
-  background: var(--surface);
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   transition:
     color var(--dur-fast) var(--ease),
     border-color var(--dur-fast) var(--ease),
@@ -110,7 +110,7 @@
 
 /* app — compact, in-product: surface background + tighter padding. */
 .ui-footer--app {
-  --footer-surface: var(--surface);
+  --footer-surface: var(--surface); --ring-gap: var(--footer-surface);
   border-top: 1px solid var(--footer-border);
 }
 .ui-footer--app .ui-footer__in { max-width: none; padding: 12px clamp(14px, 2.4vw, 22px); }

package/src/styles/input.css

@@ -23,7 +23,7 @@
   font-family: var(--font-sans);
   font-size: var(--text-base);
   color: var(--strong);
-  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-md);
   padding: 12px 15px;
@@ -36,10 +36,10 @@
 .ui-textarea:hover,
 .ui-select:hover { border-color: var(--border-strong); }
 
-.ui-input:focus,
-.ui-textarea:focus,
-.ui-select:focus {
-  outline: none;
+.ui-input:focus-visible,
+.ui-textarea:focus-visible,
+.ui-select:focus-visible {
+  outline: 2px solid transparent;
   border-color: var(--accent);
   box-shadow: var(--ring);
 }
@@ -57,7 +57,7 @@
 .ui-input:disabled,
 .ui-select:disabled,
 .ui-textarea:disabled {
-  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;
@@ -65,7 +65,7 @@
 
 .ui-input.is-invalid,
 .ui-textarea.is-invalid { border-color: var(--pink); }
-.ui-input.is-invalid:focus { box-shadow: 0 0 0 3px var(--glow-pink); }
+/* Invalid fields keep the shared focus indicator; their border carries the error. */
 
 /* Input with a leading icon / adornment */
 .ui-input-group { position: relative; display: flex; align-items: center; }
@@ -117,7 +117,7 @@
   margin-top: 1px;
   border: 1.5px solid var(--border-strong);
   border-radius: var(--radius-xs);
-  background: var(--surface-2);
+  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   cursor: pointer;
   transition: border-color var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease);
   position: relative;
@@ -159,7 +159,7 @@
   border-radius: 50%;
   background: var(--accent-contrast);
 }
-.ui-check input:focus-visible { outline: none; box-shadow: var(--ring); }
+.ui-check input:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
 /* Toggle switch */
 .ui-switch {
@@ -175,7 +175,7 @@
 .ui-switch__track {
   position: absolute;
   inset: 0;
-  background: var(--surface-3);
+  background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border-radius: var(--radius-pill);
   cursor: pointer;
   transition: background var(--dur-med) var(--ease);
@@ -201,5 +201,5 @@
 .ui-switch input:checked + .ui-switch__track::before {
   transform: translateX(calc(var(--sw-w) - var(--sw-h)));
 }
-.ui-switch input:focus-visible + .ui-switch__track { box-shadow: var(--ring); }
+.ui-switch input:focus-visible + .ui-switch__track { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-switch input:disabled + .ui-switch__track { opacity: 0.5; cursor: not-allowed; }

package/src/styles/layout.css

@@ -13,7 +13,7 @@
   display: grid;
   grid-template-columns: max-content 1fr;
   min-height: calc(100vh - var(--ui-app-top, 0px));
-  background: var(--bg);
+  background: var(--bg); /* ring-gap: inherit — page background inherits root overrides. */
   color: var(--text);
   font-family: var(--font-sans);
   /* The rail's width, and the one property the fold moves: the nav's own column
@@ -39,7 +39,7 @@
   gap: var(--space-5);
   padding: var(--space-5) var(--space-4);
   border-right: var(--ui-rail-rule) solid var(--border);
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   position: sticky;
   top: var(--ui-app-top, 0px);
   height: calc(100vh - var(--ui-app-top, 0px));
@@ -63,7 +63,7 @@
    hovering a row do nothing. The danger row and the current row are left out by
    name, because this rule outranks the states nav.css writes for them.
    why: CONTRIBUTING.md#a-rule-that-outranks-another-cancels-every-state-that-other-one-writes */
-.ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: var(--surface-3); }
+.ui-app__rail .ui-nav__item:not(.is-danger):not(.is-active):hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-app__brand {
   display: flex;
   align-items: center;
@@ -109,7 +109,7 @@
    smallest of three weak signals doing the most work, so it grows with the row. */
 /* Re-tuned at #295, which took the light rail down a step with the page. Below 720px
    the glyph is the whole row, so it is held at text grade rather than at 1.4.11's bar —
-   stories/apps/shell-states.test.js:1400 `a resting glyph is dimmer but still legible`. */
+   stories/apps/shell-states.test.js:1403 `a resting glyph is dimmer but still legible`. */
 .ui-app__rail .ui-nav__ic svg { opacity: 0.66; }
 .ui-app__rail .ui-nav__item.is-active .ui-nav__ic svg,
 .ui-app__rail .ui-nav__item.is-current .ui-nav__ic svg { opacity: 1; stroke: currentColor; } /* motion: still — the glyph brightens with its row, whose own highlight already transitions */
@@ -153,7 +153,7 @@
   width: var(--ui-app-av); height: var(--ui-app-av); flex: none;
   margin-inline-start: calc((var(--ui-nav-strip) - var(--ui-app-av)) / 2);
   border-radius: var(--radius-pill);
-  background: var(--surface-3);
+  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   color: var(--strong);
   display: grid; place-items: center;
   font-size: calc(var(--text-xs) + 1px);
@@ -187,7 +187,7 @@
   font-weight: inherit;
   letter-spacing: normal;
 }
-.ui-app .ui-app__user-trigger:hover { background: var(--surface-3); }
+.ui-app .ui-app__user-trigger:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-app__user-trigger .ui-app__who { flex: 1 1 auto; text-align: left; }
 /* The panel is portalled onto <body>, so nothing here may hang off .ui-app: by the
    time it is open it is no longer inside the rail that drew it.
@@ -269,7 +269,7 @@
    why: docs/specification.md#elevation */
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
 :where(.ui-app.is-collapsed) .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who,
-.ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface-3); color: var(--strong); opacity: 1; pointer-events: none; }
+.ui-app__rail .ui-app__fold:is(:hover, :focus-visible) > .ui-nav__label { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
 @supports (anchor-name: --a) and (anchor-scope: --a) {
   .ui-app.is-collapsed,
   .ui-app:has(.ui-app__fold) { anchor-scope: --ui-rail; }
@@ -318,7 +318,7 @@
   height: var(--ui-app-band);
   flex: none;
   padding-inline: clamp(24px, 4vw, 56px);
-  background: var(--bg);
+  background: var(--bg); /* ring-gap: inherit — page background inherits root overrides. */
   border-bottom: 1px solid var(--border);
   /* Sticky for the reason the rail beside it is: chrome that scrolls away is chrome
      you scroll back up for. */
@@ -362,7 +362,7 @@
      Artur chose this over three alternatives on #318; the survey of what seven
      other systems do is docs/reviews/318-search-field.md.
      why: docs/specification.md#elevation */
-  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-md);
   cursor: pointer;
@@ -373,7 +373,7 @@
    without `.ui-btn`, so base.css's shared rule never reached it and focus fell
    through to the browser's own square outline, drawn around a 12px radius.
    why: docs/specification.md#the-focus-ring */
-.ui-app__search:focus-visible { outline: none; box-shadow: var(--ring); border-color: var(--accent); }
+.ui-app__search:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-color: var(--accent); }
 /* The same glyph the palette draws in its own search box, at the same box and the
    same stroke: the trigger and the thing it opens are not two search marks.
    src/styles/command-palette.css:107 `.ui-cmdk__search-ic svg` */
@@ -467,7 +467,7 @@
   .ui-app__rail .ui-nav__item,
   .ui-app__rail .ui-app__user-trigger { min-height: 44px; }
   .ui-app__rail .ui-nav__item:is(:hover, :focus-visible) > .ui-nav__label,
-  .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface-3); color: var(--strong); opacity: 1; pointer-events: none; }
+  .ui-app__rail .ui-app__user-trigger:is(:hover, :focus-visible) > .ui-app__who { position: fixed; left: calc(var(--ui-rail-w) + var(--space-2)); z-index: var(--z-dropdown); width: max-content; max-width: 15rem; margin-block: -7px; padding: 6px 10px; border: 1px solid var(--border-strong); box-shadow: inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); border-radius: var(--radius-xs); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); opacity: 1; pointer-events: none; }
   @supports (anchor-name: --a) and (anchor-scope: --a) {
     .ui-app { anchor-scope: --ui-rail; }
     .ui-app__rail { anchor-name: --ui-rail; }
@@ -501,7 +501,7 @@
   max-width: var(--panel-md);
   /* Floats over a spotlit page, so it takes the floating step and the hairline.
      why: docs/specification.md#elevation */
-  background: var(--bg-elevated);
+  background: var(--bg-elevated); --ring-gap: var(--bg-elevated);
   border: 1px solid var(--border);
   border-radius: 22px;
   padding: 38px 36px 32px;
@@ -523,7 +523,7 @@
   width: 38px; height: 38px; flex: none;
   border-radius: 11px;
   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);
 }
 .ui-scope__icon svg { width: 21px; height: 21px; stroke: currentColor; fill: none; stroke-width: 1.8; }
@@ -544,7 +544,7 @@
   font-size: calc(var(--text-xs) + 1px);
   letter-spacing: 0.06em;
   color: var(--purple-mid);
-  background: var(--glow-purple);
+  background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
   border-radius: 999px;
   padding: 6px 14px;
   margin-bottom: 26px;
@@ -589,7 +589,7 @@
   width: 46px; height: 46px;
   border-radius: 13px;
   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);
   margin-bottom: 16px;
 }

package/src/styles/loading.css

@@ -99,7 +99,7 @@
   display: grid;
   place-items: center;
   /* muted-ink: glyph — permission seal */ color: var(--dim);
-  background: color-mix(in srgb, var(--text) 7%, transparent);
+  background: color-mix(in srgb, var(--text) 7%, transparent); /* ring-gap: inherit — decorative paint has no nested focus target. */
 }
 .ui-denied__seal svg {
   width: 20px;

package/src/styles/motion.css

@@ -81,7 +81,7 @@
 .m-skeleton {
   position: relative;
   overflow: hidden;
-  background: color-mix(in srgb, var(--text) 8%, transparent);
+  background: color-mix(in srgb, var(--text) 8%, transparent); /* ring-gap: inherit — loading placeholder has no nested focus target. */
   border-radius: var(--radius-sm, 8px);
 }
 .m-skeleton::after {

package/src/styles/nav.css

@@ -69,9 +69,9 @@
   transition: background var(--dur-fast) var(--ease), color var(--dur-fast) var(--ease);
 }
 .ui-nav .ui-nav__item { color: var(--text); } /* (0,2,0): a host sheet's a:link is (0,1,1) — why: docs/specification.md#the-page-shell */
-.ui-nav__item:hover { background: var(--surface-2); color: var(--strong); }
+.ui-nav__item:hover { background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ color: var(--strong); }
 .ui-nav__item.is-active {
-  background: var(--surface-3);
+  background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--strong);
   font-weight: 500;
 }
@@ -88,8 +88,8 @@
   background: var(--accent);
   transform: translateY(-50%); /* motion: still — a mark on the current row, whose own highlight already transitions; this centres it, it does not travel */
 }
-.ui-nav__item:focus-visible { outline: none; box-shadow: var(--ring); }
-.ui-nav__item.is-active:focus-visible { box-shadow: var(--ring); }
+.ui-nav__item:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
+.ui-nav__item.is-active:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
 .ui-nav__ic { display: inline-flex; flex: none; }
 .ui-nav__ic svg { width: 17px; height: 17px; stroke: currentColor; fill: none; stroke-width: 2.2; opacity: 0.72; }
@@ -108,10 +108,10 @@
 /* Destructive row (sign out, revoke). Body ink at rest, --pink once a pointer or
    the keyboard reaches it — as .ui-btn--danger and .ui-dropdown__item do. */
 .ui-nav__item.is-danger { color: var(--text); }
-.ui-nav__item.is-danger:hover { background: var(--glow-pink); color: var(--pink); }
+.ui-nav__item.is-danger:hover { background: var(--glow-pink); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--pink); }
 /* Tabbing onto it is the same "about to click this" the pointer means. The ring
    says where you are; only this says what the row does. */
-.ui-nav__item.is-danger:focus-visible { background: var(--glow-pink); color: var(--pink); }
+.ui-nav__item.is-danger:focus-visible { background: var(--glow-pink); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--pink); }
 /* An unavailable row uses disabled ink directly; opacity would also fade its
    background and pull its label toward the rail behind it (#220). */
 .ui-nav__item.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: default; pointer-events: none; }
@@ -124,7 +124,7 @@
    rules so it cannot out-rank them — sign out is never the current row, but a
    rule that could take its wash would be one to argue with later. */
 .ui-nav__item.is-active:not(.is-danger):hover {
-  background: color-mix(in srgb, var(--text) 10%, var(--surface-3));
+  background: color-mix(in srgb, var(--text) 10%, var(--surface-3)); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
 }
 
 /* Per-item badge / counter */
@@ -140,17 +140,17 @@
   font-size: var(--text-xs);
   font-weight: 600;
   line-height: 1;
-  background: var(--surface-3);
+  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   color: var(--text);
   /* The count fades with the words. It is never lost: sidebarNav() spells it
      into the row's aria-label, so "Pending 3" is what a reader hears at either
      width. */
   transition: opacity var(--dur-fast) var(--ease);
 }
-.ui-nav__badge.is-accent { background: var(--glow-purple); color: var(--accent); }
-.ui-nav__badge.is-live { background: var(--chip-success-fill); color: var(--chip-success-ink); }
-.ui-nav__badge.is-danger { background: var(--glow-pink); color: var(--pink); }
-.ui-nav__item.is-active .ui-nav__badge.is-neutral { background: var(--surface-3); color: var(--strong); }
+.ui-nav__badge.is-accent { background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--accent); }
+.ui-nav__badge.is-live { background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--chip-success-ink); }
+.ui-nav__badge.is-danger { background: var(--glow-pink); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ color: var(--pink); }
+.ui-nav__item.is-active .ui-nav__badge.is-neutral { background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--strong); }
 /* Same shape, one row up: on an active row the accent counter takes the row's
    OWN surface instead of laying its wash over it. An active row is already
    painted --surface-3, so --glow-purple there is two tints stacked. Every
@@ -160,7 +160,7 @@
    it, the largest that clears being 0.06 in dark Nebula and 0.02 in light
    Emerald. So the accent wash is painted on a base surface, never a raised one.
    See #157 and docs/specification.md#colour-and-contrast. */
-.ui-nav__item.is-active .ui-nav__badge.is-accent { background: var(--surface-3); color: var(--accent); }
+.ui-nav__item.is-active .ui-nav__badge.is-accent { background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ color: var(--accent); }
 
 /* Collapsible group */
 .ui-nav__group { display: flex; flex-direction: column; }
@@ -275,7 +275,7 @@
   transition: color var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease);
 }
 .ui-nav__tab:hover { color: var(--strong); }
-.ui-nav__tab:focus-visible { outline: none; box-shadow: var(--ring); border-radius: 8px; }
+.ui-nav__tab:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-radius: 8px; }
 .ui-nav__tab.is-active { color: var(--strong); }
 
 /* underline variant */
@@ -294,9 +294,9 @@
 
 /* pill variant */
 .ui-nav--tabs.is-pill .ui-nav__tab { border-radius: var(--radius-pill); padding: 8px 15px; }
-.ui-nav--tabs.is-pill .ui-nav__tab:hover { background: var(--surface-2); }
+.ui-nav--tabs.is-pill .ui-nav__tab:hover { background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-nav--tabs.is-pill .ui-nav__tab.is-active {
-  background: var(--glow-purple);
+  background: var(--glow-purple); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */
   color: var(--accent);
 }
 
@@ -329,7 +329,7 @@
    does above: a linked crumb is an <a>, and a host stylesheet's `a:link` is
    (0,1,1), which outranks a bare (0,1,0) class. */
 .ui-nav .ui-nav__crumb { color: var(--text); }
-a.ui-nav__crumb:hover { color: var(--strong); background: var(--surface-2); }
-a.ui-nav__crumb:focus-visible { outline: none; box-shadow: var(--ring); }
+a.ui-nav__crumb:hover { color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+a.ui-nav__crumb:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-nav__crumb.is-current { color: var(--strong); font-weight: 500; }
 .ui-nav__crumb .ui-nav__ic svg { width: 15px; height: 15px; stroke: currentColor; fill: none; stroke-width: 2.5; }

package/src/styles/pagination.css

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

package/src/styles/segmented.css

@@ -5,7 +5,7 @@
 
 .ui-seg {
   display: inline-flex;
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   border-radius: var(--radius-2xl);
   padding: 3px;
   gap: 2px;
@@ -54,4 +54,4 @@
 .ui-accent-picker button.is-active {
   box-shadow: 0 0 0 2px var(--surface), 0 0 0 4px var(--swatch, var(--accent));
 }
-.ui-accent-picker button:focus-visible { outline: none; box-shadow: 0 0 0 2px var(--surface), 0 0 0 4px var(--swatch, var(--accent)); }
+.ui-accent-picker button:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }

package/src/styles/success.css

@@ -19,7 +19,7 @@
   position: relative;
   overflow: hidden;
   border-radius: 20px;
-  background: var(--bg-elevated);   /* the floating step carries it. #295 */
+  background: var(--bg-elevated); --ring-gap: var(--bg-elevated);   /* Elevated surface for the confirmation and its actions. */
   border: 1px solid var(--border);
   isolation: isolate;
 }
@@ -82,7 +82,7 @@
 }
 .ui-sx--split .ui-sx__visual {
   display: grid; place-items: center; padding: 40px 24px;
-  background: color-mix(in srgb, var(--green) 8%, transparent);
+  background: color-mix(in srgb, var(--green) 8%, transparent); /* ring-gap: inherit — decorative illustration has no nested focus target. */
   border-right: 1px solid var(--border);
 }
 .ui-sx--split .ui-sx__check { width: 120px; height: 120px; }
@@ -160,7 +160,7 @@
 .ui-sx--hero .ui-sx__count { justify-content: center; }
 .ui-sx__count-ring {
   flex: none; width: 16px; height: 16px; border-radius: 50%;
-  background: conic-gradient(var(--green) var(--sx-a, 360deg), var(--surface-2) 0);
+  background: conic-gradient(var(--green) var(--sx-a, 360deg), var(--surface-2) 0); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   mask: radial-gradient(circle, transparent 5px, #000 6px);
   -webkit-mask: radial-gradient(circle, transparent 5px, #000 6px);
   animation: ui-sx-sweep var(--sx-secs, 5s) linear forwards; /* motion: ambient — the caller sets the countdown; the ring just spends it */
@@ -176,7 +176,7 @@
   .ui-sx__tick { animation: none; stroke-dashoffset: 0; }
   .ui-sx__ring { display: none; }
   .ui-sx__confetti { display: none; }
-  .ui-sx__count-ring { animation: none; background: var(--surface-2); }
+  .ui-sx__count-ring { animation: none; background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 }
 
 /* ---- Narrow — split stacks -------------------------------------------- */

package/src/styles/table.css

@@ -42,7 +42,7 @@
   border-spacing: 0;
   padding: 0 var(--space-2);
 }
-.ui-table--hover:not(.ui-table--zebra) tbody tr:hover td { background: var(--surface-2); }
+.ui-table--hover:not(.ui-table--zebra) tbody tr:hover td { background: var(--surface-2); --ring-gap: var(--surface-2); }
 .ui-table--hover:not(.ui-table--zebra) tbody tr:hover td:first-child {
   border-top-left-radius: var(--radius-sm); border-bottom-left-radius: var(--radius-sm); }
 .ui-table--hover:not(.ui-table--zebra) tbody tr:hover td:last-child {
@@ -63,7 +63,7 @@
 
 .ui-table--zebra th { border-bottom-width: 2px; }
 .ui-table--zebra td { border-bottom: 0; }
-.ui-table--zebra tbody tr:nth-child(even) td { background: var(--surface-2); }
+.ui-table--zebra tbody tr:nth-child(even) td { background: var(--surface-2); --ring-gap: var(--surface-2); }
 /* The stripe stays full-bleed (the #71 inset above is hover only), but it only reads right
  * if the end cells are inset from the tint's own edge, and `.ui-table td` sets
  * `padding-left: 0`. Only `--dense` supplied that inset, so `--zebra` without `--dense` —
@@ -74,7 +74,7 @@
 .ui-table--zebra th:last-child,
 .ui-table--zebra td:last-child { padding-right: var(--space-3); }
 .ui-table--zebra.ui-table--hover tbody tr:hover td,
-.ui-table--zebra tbody tr:hover td { background: color-mix(in srgb, var(--accent) 8%, transparent); }
+.ui-table--zebra tbody tr:hover td { --ring-gap: inherit; background: color-mix(in srgb, var(--accent) 8%, transparent); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 
 .ui-table__num { text-align: right; font-variant-numeric: tabular-nums; }
 .ui-table th.ui-table__num { text-align: right; }

package/src/styles/tabs.css

@@ -22,7 +22,7 @@
 }
 .ui-tabs__tab:hover { color: var(--strong); }
 .ui-tabs__tab.is-active { color: var(--strong); border-bottom-color: var(--accent); }
-.ui-tabs__tab:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 7px 7px 0 0; }
+.ui-tabs__tab:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-radius: 7px 7px 0 0; }
 
 .ui-tabs__panels { padding-top: 20px; }
 .ui-tabs__panel[hidden] { display: none; }
@@ -31,4 +31,4 @@
 .ui-tabs__panel.is-entering { animation: m-fade var(--dur-fast) var(--ease-out) both; }
 /* The panel is focusable (tabindex="0", see tabs.js) so a keyboard user can
    reach text-only content. Show the ring when they land on it. */
-.ui-tabs__panel:focus-visible { outline: 2px solid var(--accent); outline-offset: 4px; border-radius: 8px; }
+.ui-tabs__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-radius: 8px; }

package/src/styles/tooltip.css

@@ -25,7 +25,7 @@
   width: max-content;
   max-width: var(--prose-caption);
   padding: var(--space-2) var(--space-3);
-  background: var(--ui-tip-bg);
+  background: var(--ui-tip-bg); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   /* 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);

package/src/styles/topbar.css

@@ -9,7 +9,7 @@
   height: 52px;
   display: flex;
   align-items: center;
-  background: var(--bg);
+  background: var(--bg); /* ring-gap: inherit — page background inherits root overrides. */
   border-bottom: 1px solid var(--border);
 }
 .topbar__in {
@@ -48,7 +48,7 @@
   display: none;
   align-items: center;
   gap: 2px;
-  background: var(--surface-2);
+  background: var(--surface-2); --ring-gap: var(--surface-2);
   border: 1px solid var(--border);
   border-radius: 24px;
   padding: 3px;
@@ -66,7 +66,7 @@
   transition: color var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease);
 }
 .dtsw a:hover { color: var(--strong); }
-.dtsw a.cur { color: var(--strong); background: var(--surface); }
+.dtsw a.cur { color: var(--strong); background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 
 /* Theme toggle — a single icon-only switch (no label). */
 .toggle {
@@ -75,7 +75,7 @@
   width: 34px;
   height: 34px;
   cursor: pointer;
-  background: var(--surface);
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   color: var(--text);
   border: 1px solid var(--border);
   border-radius: 10px;
@@ -100,7 +100,7 @@
   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: 24px;
   padding: 7px 11px 7px 13px;
@@ -122,7 +122,7 @@
   top: calc(100% + 9px);
   left: 0;
   min-width: 266px;
-  background: var(--bg-elevated);   /* the floating step — see dropdown.css. #295 */
+  background: var(--bg-elevated); --ring-gap: var(--bg-elevated);   /* the floating step — see dropdown.css. #295 */
   /* 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);
@@ -182,7 +182,7 @@
 /* The menu is raised, so a hovered row takes the step ABOVE it — see
    src/styles/dropdown.css:155 `.ui-dropdown__item:hover`.
    why: docs/specification.md#elevation */
-.vopt:hover { background: var(--surface-3); }
+.vopt:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .vopt .vname { font-family: var(--font-sans); font-size: calc(var(--text-sm) - 0.5px); color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
 .vopt .vmeta { font-size: var(--text-xs); color: var(--text); margin-top: 2px; }
 .vopt .vbadge {
@@ -195,8 +195,8 @@
   flex: none;
   margin-top: 1px;
 }
-.vbadge.live { color: var(--chip-success-ink); background: var(--chip-success-fill); }
-.vbadge.arch { /* muted-ink: state — archived version */ color: var(--muted); background: var(--surface-3); }
+.vbadge.live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
+.vbadge.arch { /* muted-ink: state — archived version */ color: var(--muted); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 /* The switcher keeps its glyph and drops its label where the shell folds — the
    same step the rail folds at: docs/specification.md#breakpoints. */
 @media (max-width: 720px) { .vsw__btn .lbl { display: none; } }
@@ -225,7 +225,7 @@
   position: absolute;
   right: 0; top: 44px;
   width: 252px;
-  background: var(--bg-elevated);   /* the floating step — see dropdown.css. #295 */
+  background: var(--bg-elevated); --ring-gap: var(--bg-elevated);   /* the floating step — see dropdown.css. #295 */
   /* 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);
@@ -258,7 +258,7 @@
 .amenu .ahead .anm { color: var(--strong); font-size: var(--text-sm); font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .amenu .ahead .aem { color: var(--text); font-size: calc(var(--text-xs) + 0.5px); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .amenu a { display: flex; align-items: center; gap: 11px; padding: 10px 15px; color: var(--text); text-decoration: none; font-family: var(--font-sans); font-size: var(--text-sm); cursor: pointer; }
-.amenu a:hover { background: var(--surface-3); }
+.amenu a:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .amenu a.cur { color: var(--accent); }
 .amenu a svg { width: 19px; height: 19px; flex: none; stroke: currentColor; fill: none; stroke-width: 2; opacity: 0.85; }
 .amenu .asep { height: 1px; background: var(--border); margin: 5px 0; }

package/src/tokens/tokens.css

@@ -172,7 +172,7 @@
   --disabled-ink-bare: #a39eb7;
 
   /* Lifted from #9b5dff, which cleared the flat surfaces and failed on its own wash over
-     a card; the value was already in the ramp. --ring is var(--accent) and follows by
+     a card; the value was already in the ramp. --ring-color is var(--accent) and follows by
      reference. Held by stories/accent-contrast.test.js. #157.
      why: docs/specification.md#colour-and-contrast */
   --accent: #b479ff;
@@ -229,12 +229,12 @@
   --shadow-lg: 0 0 #0000;
   --shadow-seg: 0 0 #0000;
   --shadow-card: 0 0 #0000;
-  /* THE ONLY --ring in the kit — light and every data-accent sub-theme declare an
-     --accent and inherit this line. Opaque because a translucent ring is a glow, and the
-     eight rgba() literals it replaced all missed WCAG 1.4.11's 3:1 (#218). Held by
-     stories/guidelines/accessibility-floor.test.js.
-     why: docs/specification.md#the-focus-ring */
-  --ring: 0 0 0 3px var(--accent);
+  /* G2: the band carries contrast; the halo decorates it. why: docs/specification.md#the-focus-ring */
+  --ring-width: 2px;
+  --ring-color: var(--accent);
+  --ring-gap-width: 1px;
+  --ring-gap: var(--bg);
+  --ring: 0 0 0 var(--ring-gap-width) var(--ring-gap), 0 0 0 calc(var(--ring-gap-width) + var(--ring-width)) var(--ring-color), 0 0 12px 2px color-mix(in srgb, var(--ring-color) 45%, transparent);
 
   /* The ink a cast shadow is made of, and the specular white that reads as gloss on a
      raised surface. Effects mix these instead of writing rgba(). */
@@ -405,3 +405,45 @@
   --prose-body: 62ch;
   --prose-dense: 72ch;
 }
+
+/* Recompose only at painted containers; controls inherit the outside gap.
+ * One recipe keeps surface propagation cheap and consistent.
+ * why: docs/specification.md#the-focus-ring */
+.amenu,
+.dtsw,
+.rx-modal,
+.ui-app__rail,
+.ui-auth__card,
+.ui-callout,
+.ui-card,
+.ui-card--accent,
+.ui-card--live,
+.ui-cmdk__panel,
+.ui-code,
+.ui-confirm__panel,
+.ui-drawer__footer,
+.ui-drawer__panel,
+.ui-dropdown__panel,
+.ui-fbcomposer,
+.ui-footer--app,
+.ui-seg,
+.ui-snippet,
+.ui-snippet--reveal,
+.ui-sx,
+.ui-table--hover:not(.ui-table--zebra) tbody tr:hover td,
+.ui-table--zebra tbody tr:nth-child(even) td,
+.ui-table--zebra tbody tr:hover td,
+.ui-table--zebra.ui-table--hover tbody tr:hover td,
+.ui-toast--outline,
+.ui-toast--solid,
+.vsw__menu {
+  --ring: 0 0 0 var(--ring-gap-width) var(--ring-gap), 0 0 0 calc(var(--ring-gap-width) + var(--ring-width)) var(--ring-color), 0 0 12px 2px color-mix(in srgb, var(--ring-color) 45%, transparent);
+}
+
+/* A container focused itself paints outside its own surface; descendants only
+ * inherit its inside gap again after focus moves to them. */
+.ui-card:focus-visible,
+.ui-cmdk__panel:focus-visible,
+.ui-confirm__panel:focus-visible,
+.ui-drawer__panel:focus-visible,
+.rx-modal:focus-visible { --ring-gap: inherit; }