@apliteni/apliteni-ui 0.35.0 → 0.37.0

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);
@@ -163,7 +163,7 @@
 .ui-app__who b { display: block; color: var(--strong); font-weight: var(--weight-semibold); }
 /* nowrap is what makes the ellipsis fire — without it the address wraps, and
    the rail column is max-content, so a long one widens the rail instead. */
-.ui-app__who span { display: block; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.ui-app__who span { display: block; color: var(--text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 
 /* -- the reader's menu ---------------------------------------------------- */
 /* The account block is a dropdown() trigger, so it takes the rail's own row skin
@@ -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.
@@ -198,7 +198,7 @@
    `text-overflow` would have nothing to fire against — the inert pair
    .ui-app__who's own comment warns about. `anywhere` keeps an address with no
    break in it from widening the panel instead. */
-.ui-app__user-panel .ui-dropdown__head span { display: block; color: var(--muted); font-size: var(--text-xs); overflow-wrap: anywhere; }
+.ui-app__user-panel .ui-dropdown__head span { display: block; color: var(--text); font-size: var(--text-xs); overflow-wrap: anywhere; }
 
 /* The toggle's cell, at the far end of the brand row: the auto margin puts it there
    with or without a wordmark beside it, and the offset below rides it back onto the
@@ -221,7 +221,7 @@
    row under it. The glyph box carries the line instead, in both states.
    why: docs/specification.md#the-page-shell */
 .ui-app__fold .ui-nav__ic { height: 1lh; }
-.ui-app .ui-app__fold { color: var(--dim); }
+.ui-app .ui-app__fold { color: var(--text); }
 .ui-app .ui-app__fold:hover,
 .ui-app .ui-app__fold:focus-visible { color: var(--strong); }
 /* The width's own clock, not the words', so the mark and the closing edge arrive
@@ -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. */
@@ -351,7 +351,7 @@
   font: inherit;
   font-size: var(--text-sm);
   text-align: start;
-  color: var(--muted);
+  color: var(--text);
   /* --surface, not the sunken --surface-2 every other field in the kit takes:
      those sit on a card and this one sits on the band, and the band IS --bg, the
      bottom of the ladder — so a sunken fill has nowhere to go but down into its
@@ -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` */
@@ -402,7 +402,7 @@
   letter-spacing: var(--tracking-tight);
   margin-bottom: 8px;
 }
-.ui-app__sub { color: var(--dim); font-size: calc(var(--text-base) + 0.5px); line-height: 1.6; max-width: var(--prose-body); margin-bottom: 32px; }
+.ui-app__sub { color: var(--text); font-size: calc(var(--text-base) + 0.5px); line-height: 1.6; max-width: var(--prose-body); margin-bottom: 32px; }
 .ui-app__body { display: flex; flex-direction: column; gap: var(--space-5); }
 /* A flex child's min-width is its content by default, so one wide block — a
    ledger, a code sample — pushes the whole page sideways instead of scrolling
@@ -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;
@@ -509,10 +509,10 @@
 .ui-auth__brand { display: inline-flex; align-items: center; gap: 10px; margin-bottom: 26px; }
 .ui-auth__brand span { font-size: calc(var(--text-base) + 0.5px); font-weight: 600; color: var(--strong); }
 .ui-auth__title { color: var(--strong); font-size: calc(var(--text-xl) + 2px); font-weight: 600; letter-spacing: -0.01em; margin-bottom: 7px; }
-.ui-auth__sub { color: var(--dim); font-size: var(--text-base); line-height: 1.55; margin-bottom: 26px; }
-.ui-auth__foot { margin-top: 24px; text-align: center; font-size: var(--text-sm); color: var(--muted); }
+.ui-auth__sub { color: var(--text); font-size: var(--text-base); line-height: 1.55; margin-bottom: 26px; }
+.ui-auth__foot { margin-top: 24px; text-align: center; font-size: var(--text-sm); color: var(--text); }
 .ui-auth__foot a { color: var(--accent); }
-.ui-divider { display: flex; align-items: center; gap: 14px; margin: 22px 0; color: var(--muted); font-size: calc(var(--text-xs) + 1px); }
+.ui-divider { display: flex; align-items: center; gap: 14px; margin: 22px 0; color: var(--text); font-size: calc(var(--text-xs) + 1px); }
 .ui-divider::before, .ui-divider::after { content: ""; flex: 1; height: 1px; background: var(--border); }
 
 /* App scope grant list (OAuth consent) */
@@ -523,12 +523,12 @@
   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; }
 .ui-scope__t { color: var(--strong); font-size: calc(var(--text-base) - 0.5px); font-weight: 500; }
-.ui-scope__d { color: var(--dim); font-size: var(--text-sm); margin-top: 2px; line-height: 1.5; }
+.ui-scope__d { color: var(--text); font-size: var(--text-sm); margin-top: 2px; line-height: 1.5; }
 
 /* -- Landing hero -------------------------------------------------------- */
 .ui-hero {
@@ -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;
@@ -567,7 +567,7 @@
 }
 .ui-hero__sub {
   font-size: clamp(16px, 2.1vw, 20px);
-  color: var(--dim);
+  color: var(--text);
   max-width: var(--prose-lede);
   margin: 0 auto 34px;
   line-height: 1.6;
@@ -589,14 +589,14 @@
   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;
 }
 .ui-feature__icon svg { width: 25px; height: 25px; stroke: currentColor; fill: none; stroke-width: 1.8; }
 .ui-feature h3 { color: var(--strong); font-size: calc(var(--text-lg) - 1px); font-weight: 600; margin-bottom: 7px; }
-.ui-feature p { color: var(--dim); font-size: var(--text-base); line-height: 1.6; }
+.ui-feature p { color: var(--text); font-size: var(--text-base); line-height: 1.6; }
 
 .ui-section-head { text-align: center; max-width: var(--panel-lg); margin: 0 auto clamp(40px, 6vh, 64px); }
 .ui-section-head h2 { color: var(--strong); font-size: clamp(28px, 4vw, 40px); font-weight: 700; letter-spacing: -0.02em; margin-bottom: 14px; }
-.ui-section-head p { color: var(--dim); font-size: calc(var(--text-lg) - 1px); line-height: 1.6; }
+.ui-section-head p { color: var(--text); font-size: calc(var(--text-lg) - 1px); line-height: 1.6; }

package/src/styles/loading.css

@@ -89,7 +89,7 @@
   text-align: center;
   gap: 8px;
   padding: 48px 24px;
-  color: var(--muted);
+  color: var(--text);
 }
 .ui-denied__seal {
   width: 44px;
@@ -98,8 +98,8 @@
   border-radius: 50%;
   display: grid;
   place-items: center;
-  color: var(--dim);
-  background: color-mix(in srgb, var(--text) 7%, transparent);
+  /* muted-ink: glyph — permission seal */ color: var(--dim);
+  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

@@ -41,7 +41,7 @@
   /* rank: label */
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
-  color: var(--muted);
+  color: var(--text);
   padding: 4px 12px 8px;
   /* Goes on the labels' clock — a section heading is words, and the fold takes
      every word on the rail together. */
@@ -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; }
@@ -105,16 +105,16 @@
   transition: opacity var(--dur-fast) var(--ease);
 }
 
-/* Destructive row (sign out, revoke). Quiet at rest, --pink once a pointer or
+/* 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(--muted); }
-.ui-nav__item.is-danger:hover { background: var(--glow-pink); color: var(--pink); }
+.ui-nav__item.is-danger { color: var(--text); }
+.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); }
-/* A row that is off. No opacity: the label was already --muted and the fade
-   only pulled it toward the rail behind it (#220). */
-.ui-nav__item.is-disabled { color: var(--disabled-ink); cursor: default; pointer-events: none; }
+.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; }
 
 /* The current row under the pointer. It rests on --surface-3, which is also what
    a resting row hovers to, so the one row with no hover response was the row the
@@ -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);
-  color: var(--dim);
+  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; }
@@ -267,7 +267,7 @@
   align-items: center;
   gap: 8px;
   padding: 11px 14px;
-  color: var(--dim);
+  color: var(--text);
   text-decoration: none;
   font-size: calc(var(--text-base) - 0.5px);
   font-weight: 500;
@@ -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,13 +294,13 @@
 
 /* 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);
 }
 
-.ui-nav__tab.is-disabled { color: var(--disabled-ink); cursor: default; }
+.ui-nav__tab.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: default; }
 .ui-nav__tab .ui-nav__badge { height: 18px; }
 
 /* -- Breadcrumbs --------------------------------------------------------- */
@@ -328,8 +328,8 @@
 /* Carries the block's class as well as its own, for the reason .ui-nav__item
    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(--dim); }
-a.ui-nav__crumb:hover { color: var(--strong); background: var(--surface-2); }
-a.ui-nav__crumb:focus-visible { outline: none; box-shadow: var(--ring); }
+.ui-nav .ui-nav__crumb { color: var(--text); }
+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

@@ -20,7 +20,7 @@
    target group in one place as the row count changes width. */
 .ui-pager__status {
   margin: 0 auto 0 0;
-  color: var(--muted);
+  color: var(--text);
   font-variant-numeric: tabular-nums;
 }
 
@@ -29,7 +29,7 @@
   align-items: center;
   gap: var(--space-2);
 }
-.ui-pager__size-label { color: var(--muted); }
+.ui-pager__size-label { color: var(--text); }
 
 /* .ui-select is a form field sized for a form — full width, 12px/15px padding.
    In a pager it sits in a row of sm buttons, so it takes their scale. Two things
@@ -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);
@@ -77,14 +77,14 @@
 
 .ui-pager__gap {
   padding: 0 var(--space-1);
-  color: var(--muted);
+  /* muted-ink: glyph — ellipsis for omitted page controls */ color: var(--muted);
 }
 
 .ui-pager__jump {
   display: inline-flex;
   align-items: center;
   gap: var(--space-2);
-  color: var(--muted);
+  color: var(--text);
   padding: 0 var(--space-1);
 }
 /* Wide enough for four digits and the spinner a number input draws beside them;
@@ -120,6 +120,6 @@
    discovered.
    why: docs/specification.md#pagination */
 a.ui-pager__step,
-a.ui-pager__page { color: var(--dim); }
+a.ui-pager__page { color: var(--text); }
 a.ui-pager__step:hover,
 a.ui-pager__page:hover { color: var(--strong); }

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;
@@ -15,7 +15,7 @@
   font-size: calc(var(--text-sm) + 0.5px);
   font-weight: var(--weight-semibold);
   letter-spacing: 0.02em;
-  color: var(--dim);
+  color: var(--text);
   background: none;
   border: 0;
   padding: 7px 18px;
@@ -23,7 +23,7 @@
   cursor: pointer;
   transition: color var(--dur-med) var(--ease), background var(--dur-med) var(--ease);
 }
-.ui-seg button:hover { color: var(--text); }
+.ui-seg button:hover { color: var(--strong); }
 /* aria-pressed is what segmented() emits now; aria-selected is kept so markup
    copied from an older release keeps painting its active pill. */
 .ui-seg button.is-active,
@@ -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/stat.css

@@ -27,7 +27,7 @@
    figure's parts are held close, so the label keeps the band's tighter line.
    It sits outside the rank table for that one reason, and claims no rank. */
 .ui-stat__label {
-  color: var(--dim);
+  color: var(--text);
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
   line-height: var(--leading-snug);
@@ -55,15 +55,15 @@
   align-items: center;
   gap: 2px var(--space-1);
   margin-top: var(--space-2);
-  color: var(--dim);
+  color: var(--text);
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
   line-height: var(--leading-snug);
 }
 .ui-stat__delta svg { width: 14px; height: 14px; flex: none; stroke-width: 2.7; } /* 2.7 of a 24 box drawn at 14px = 1.58 CSS px. docs/specification.md#icons-and-glyphs */
 .ui-stat__change { font-variant-numeric: tabular-nums; white-space: nowrap; }
-.ui-stat__basis { color: var(--muted); font-weight: var(--weight-normal); }
-.ui-stat__delta--none { color: var(--muted); font-weight: var(--weight-normal); }
+.ui-stat__basis { color: var(--text); font-weight: var(--weight-normal); }
+.ui-stat__delta--none { color: var(--text); font-weight: var(--weight-normal); }
 
 /* Tone is set by the caller and says good or bad news. Direction is the arrow's
    job, so an unset tone keeps the change neutral whichever way it points. */
@@ -72,7 +72,7 @@
 
 /* The trend is the caller's <svg>. margin-top: auto seats it on the bottom of
    the figure, so trends line up across figures whose text wraps differently. */
-.ui-stat__trend { margin-top: auto; padding-top: var(--space-4); color: var(--muted); }
+.ui-stat__trend { margin-top: auto; padding-top: var(--space-4); /* muted-ink: glyph — caller-supplied sparkline */ color: var(--muted); }
 .ui-stat__trend svg { display: block; width: 100%; height: 32px; overflow: visible; }
 .ui-stat--good .ui-stat__trend { color: var(--chip-success-ink); }
 .ui-stat--bad .ui-stat__trend { color: var(--chip-danger-ink); }
@@ -82,7 +82,7 @@
    margin is under it because it leads the row. */
 .ui-stats__basis {
   margin: 0 0 var(--space-5);
-  color: var(--muted);
+  color: var(--text);
   font-size: var(--text-xs);
   line-height: var(--leading-snug);
 }

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;
 }
@@ -64,7 +64,7 @@
   letter-spacing: -.02em; line-height: 1.2; margin: 0;
 }
 .ui-sx__body {
-  color: var(--dim); font-size: var(--text-base); line-height: 1.6; margin: 9px 0 0; max-width: var(--prose-caption);
+  color: var(--text); font-size: var(--text-base); line-height: 1.6; margin: 9px 0 0; max-width: var(--prose-caption);
 }
 .ui-sx__actions { display: flex; flex-wrap: wrap; gap: 10px; margin-top: 20px; }
 
@@ -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,14 +160,14 @@
 .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 */
 }
 @keyframes ui-sx-sweep { from { --sx-a: 360deg; } to { --sx-a: 0deg; } }
-.ui-sx__count-text { color: var(--muted); font-size: var(--text-sm); }
-.ui-sx__count-text b { color: var(--dim); font-weight: var(--weight-semibold); font-variant-numeric: tabular-nums; }
+.ui-sx__count-text { color: var(--text); font-size: var(--text-sm); }
+.ui-sx__count-text b { color: var(--text); font-weight: var(--weight-semibold); font-variant-numeric: tabular-nums; }
 
 /* ---- Reduced motion — static check, no burst / confetti / sweep ---------- */
 @media (prefers-reduced-motion: reduce) {
@@ -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

@@ -13,14 +13,14 @@
   /* rank: label */
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
-  color: var(--muted);
+  color: var(--text);
   padding: 0 var(--space-4) var(--space-3) 0;
   border-bottom: 1px solid var(--border);
 }
 .ui-table td {
   padding: var(--space-4) var(--space-4) var(--space-4) 0;
   border-bottom: 1px solid var(--border);
-  color: var(--dim);
+  color: var(--text);
   vertical-align: middle;
   white-space: nowrap;
 }
@@ -28,7 +28,7 @@
 .ui-table td.ui-table__title { color: var(--strong); font-weight: var(--weight-medium); width: 99%; white-space: normal; }
 .ui-table th:last-child,
 .ui-table td.ui-table__act { padding-right: 0; text-align: right; }
-.ui-table tr.is-dead td { color: var(--muted); }
+.ui-table tr.is-dead td { /* muted-ink: state — revoked row */ color: var(--muted); }
 .ui-table tr.is-dead td.ui-table__title { text-decoration: line-through; }
 .ui-table tbody tr { transition: background var(--dur-fast) var(--ease); }
 
@@ -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,12 +74,12 @@
 .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; }
 .ui-table__num--strong { color: var(--strong); font-weight: var(--weight-semibold); }
-.ui-table__code { font-family: var(--font-mono); font-size: var(--text-sm); color: var(--muted); }
+.ui-table__code { font-family: var(--font-mono); font-size: var(--text-sm); color: var(--text); }
 
 /* The empty state (.ui-empty) — shown when a table/list has no rows — now
    lives in styles/empty.css as a standalone component (illustration support). */