@apliteni/apliteni-ui 0.35.0 → 0.37.0

package/src/styles/command-palette.css

@@ -68,7 +68,7 @@
   display: flex;
   flex-direction: column;
   font-family: var(--font-sans);
-  background: var(--cmdk-surface);
+  background: var(--cmdk-surface); --ring-gap: var(--cmdk-surface);
   /* The two-step edge and the drop: --border-strong outside, --border one pixel
      inside it, then the broad faint drop. why: docs/specification.md#elevation */
   border: 1px solid var(--border-strong);
@@ -86,7 +86,7 @@
    box-shadow list replaces the whole list, so `box-shadow: var(--ring)` alone
    took the panel's edge and its drop off for as long as it held focus.
    why: docs/specification.md#elevation */
-.ui-cmdk__panel:focus-visible { outline: none; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
+.ui-cmdk__panel:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring), inset 0 0 0 1px var(--elev-edge, var(--border)), var(--elev-drop); }
 
 /* -- The text box --------------------------------------------------------- */
 
@@ -99,7 +99,7 @@
 }
 .ui-cmdk__search-ic {
   display: inline-flex;
-  color: var(--muted);
+  /* muted-ink: glyph — search icon */ color: var(--muted);
   flex: none;
 }
 /* 2.2 of a 24 box drawn at 17px = 1.56 CSS px, which is what keeps the mark a
@@ -130,7 +130,7 @@
      already carries one, and the caret says where the typing goes. */
   outline: none;
 }
-.ui-cmdk__input::placeholder { color: var(--muted); }
+.ui-cmdk__input::placeholder { /* muted-ink: placeholder — empty command search */ color: var(--muted); }
 
 /* -- The list ------------------------------------------------------------- */
 
@@ -149,7 +149,7 @@
   padding: var(--space-2) var(--space-3) var(--space-1);
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
-  color: var(--muted);
+  color: var(--text);
 }
 
 /* Row — [icon] [label + description] [badge] [keys]. A <div role="option">, so
@@ -178,12 +178,12 @@
   background: none;
 }
 .ui-cmdk__item[hidden] { display: none; } /* motion: still — a row the query no longer answers is gone on the next keystroke */
-.ui-cmdk__item.is-active { background: var(--surface-3); }
+.ui-cmdk__item.is-active { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-cmdk__item.is-active .ui-cmdk__label { color: var(--strong); }
 
 .ui-cmdk__ic {
   display: inline-flex;
-  color: var(--dim);
+  /* muted-ink: glyph — result icon */ color: var(--dim);
   flex: none;
 }
 /* 2.3 of a 24 box drawn at 16px = 1.53 CSS px. Same arithmetic as the dropdown's
@@ -208,10 +208,10 @@
 }
 .ui-cmdk__desc {
   font-size: var(--text-sm);
-  /* --dim and not --muted: a row's note is how two rows called INV-4812 and
+  /* Body ink: a row's note is how two rows called INV-4812 and
      INV-4809 are told apart, which is not something a reader may skip.
-     why: docs/specification.md#colour-and-contrast */
-  color: var(--dim);
+     why: docs/specification.md#text-ink */
+  color: var(--text);
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -224,7 +224,7 @@
   border-radius: var(--radius-pill);
   border: 1px solid var(--border);
   font-size: var(--text-xs);
-  color: var(--dim);
+  color: var(--text);
 }
 
 /* Destructive rows take the kit's danger ink, never the accent, and stay quiet
@@ -232,8 +232,8 @@
    writes with :hover. A palette row is reached with an arrow key far more often
    than with a pointer, so `.is-active` carries the signal beside :hover: it is
    the same moment, and it is the row Enter would run.
-   why: docs/specification.md#colour-and-contrast */
-.ui-cmdk__item.is-danger .ui-cmdk__label { color: var(--muted); }
+   why: docs/specification.md#text-ink */
+.ui-cmdk__item.is-danger .ui-cmdk__label { color: var(--text); }
 .ui-cmdk__item.is-danger:hover .ui-cmdk__label,
 .ui-cmdk__item.is-danger.is-active .ui-cmdk__label { color: var(--pink); }
 .ui-cmdk__item.is-danger.is-active .ui-cmdk__ic { color: var(--pink); }
@@ -242,11 +242,11 @@
    for a control with no box of its own: --disabled-surface IS --surface-2,
    which is the panel behind it, so a disabled row paints no box a reader can
    see and its label is read on whatever the panel is.
-   why: docs/specification.md#colour-and-contrast */
-.ui-cmdk__item.is-disabled { cursor: default; color: var(--disabled-ink-bare); }
+   why: docs/specification.md#text-ink */
+.ui-cmdk__item.is-disabled { cursor: default; /* muted-ink: state — unavailable control */ color: var(--disabled-ink-bare); }
 .ui-cmdk__item.is-disabled .ui-cmdk__label,
 .ui-cmdk__item.is-disabled .ui-cmdk__desc,
-.ui-cmdk__item.is-disabled .ui-cmdk__ic { color: var(--disabled-ink-bare); }
+.ui-cmdk__item.is-disabled .ui-cmdk__ic { /* muted-ink: state — unavailable control */ color: var(--disabled-ink-bare); }
 
 /* -- Keys, empty state, legend -------------------------------------------- */
 
@@ -258,11 +258,11 @@
   border-radius: var(--radius-xs);
   /* A key cap reads as raised, so it takes the step above the panel rather than
      the card step below it. why: docs/specification.md#elevation */
-  background: var(--surface-3);
+  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   font-family: var(--font-sans);
   font-size: var(--text-xs);
   line-height: 1.5;
-  color: var(--dim);
+  color: var(--text);
   text-align: center;
 }
 
@@ -271,7 +271,7 @@
   padding: var(--space-6) var(--space-4) var(--space-8);
   text-align: center;
   font-size: var(--text-base);
-  color: var(--dim);
+  color: var(--text);
 }
 
 .ui-cmdk__foot {
@@ -281,7 +281,7 @@
   padding: var(--space-2) var(--space-4);
   border-top: 1px solid var(--border);
   font-size: var(--text-xs);
-  color: var(--muted);
+  color: var(--text);
 }
 .ui-cmdk__foot span { display: inline-flex; align-items: center; gap: 5px; }
 
@@ -301,10 +301,10 @@
   align-items: center;
   justify-content: center;
   border-radius: var(--radius-sm);
-  background: var(--surface);
+  background: var(--surface); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
   border: 1px solid var(--border);
 }
-.ui-cmdk--roomy .ui-cmdk__item.is-active .ui-cmdk__ic { background: var(--surface-2); }
+.ui-cmdk--roomy .ui-cmdk__item.is-active .ui-cmdk__ic { background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* -- Narrow --------------------------------------------------------------- */
 /* At the kit's narrowest step the palette is the page: full width, off the top

package/src/styles/confirm.css

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

package/src/styles/drawer.css

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

package/src/styles/dropdown.css

@@ -17,15 +17,15 @@
   font-size: calc(var(--text-sm) - 0.5px);
   font-weight: 500;
   color: var(--text);
-  background: var(--surface);
+  background: var(--surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--border);
   border-radius: var(--radius-pill);
   padding: 7px 11px 7px 13px;
   transition: border-color var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease);
 }
 .ui-dropdown__trigger:hover { border-color: var(--accent); }
-.ui-dropdown__trigger:focus-visible { outline: none; box-shadow: var(--ring); border-color: var(--accent); }
-.ui-dropdown__pre { color: var(--muted); }
+.ui-dropdown__trigger:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); border-color: var(--accent); }
+.ui-dropdown__pre { color: var(--text); }
 .ui-dropdown__value { color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
 
 /* Chevron — border caret that flips when the container is .open. Its ink is an L
@@ -70,7 +70,7 @@
   min-width: 240px;
   /* The floating step, not the sunken one — a panel held open over a card cannot be
      painted the colour of an inset. why: docs/specification.md#elevation */
-  background: var(--bg-elevated);
+  background: var(--bg-elevated); --ring-gap: var(--bg-elevated);
   /* The two-step edge and the drop: --border-strong outside, --border one pixel
      inside it, then the broad faint drop. why: docs/specification.md#elevation */
   border: 1px solid var(--border-strong);
@@ -152,12 +152,12 @@
   transition: background var(--dur-fast) var(--ease);
 }
 /* A row in a raised panel lifts: the step above it, never the card step below. why: docs/specification.md#elevation */
-.ui-dropdown__item:hover { background: var(--surface-3); }
-.ui-dropdown__item:focus-visible { outline: none; background: var(--surface-3); box-shadow: var(--ring); }
+.ui-dropdown__item:hover { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
+.ui-dropdown__item:focus-visible { outline: 2px solid transparent; background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: var(--ring); }
 .ui-dropdown__main { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
 .ui-dropdown__label { font-family: var(--font-sans); font-size: calc(var(--text-sm) - 0.5px); color: var(--strong); font-weight: 600; letter-spacing: 0.01em; }
-.ui-dropdown__desc { font-size: var(--text-xs); color: var(--muted); line-height: 1.35; }
-.ui-dropdown__ic { display: inline-flex; flex: none; color: var(--muted); }
+.ui-dropdown__desc { font-size: var(--text-xs); color: var(--text); line-height: 1.35; }
+.ui-dropdown__ic { display: inline-flex; flex: none; /* muted-ink: glyph — option icon */ color: var(--muted); }
 .ui-dropdown__ic svg { width: 18px; height: 18px; stroke: currentColor; fill: none; stroke-width: 2.1; }
 
 /* Trailing selected tick (listbox variant) */
@@ -178,25 +178,25 @@
   border-radius: var(--radius-pill);
   margin-left: auto;
   flex: none;
-  color: var(--muted);
+  color: var(--text);
   /* A chip is the top step. why: docs/specification.md#elevation */
-  background: var(--surface-3);
+  background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */
 }
-.ui-dropdown__badge.is-live { color: var(--chip-success-ink); background: var(--chip-success-fill); }
+.ui-dropdown__badge.is-live { color: var(--chip-success-ink); background: var(--chip-success-fill); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 /* The accent counter keeps the badge's flat surface and changes only the ink — the shape
    src/styles/nav.css:163 `.ui-nav__item.is-active .ui-nav__badge.is-accent` already holds.
    The accent wash goes on a base surface, never a raised one, and #295 made this panel a
    raised one. why: docs/specification.md#elevation */
-.ui-dropdown__badge.is-accent { color: var(--accent); background: var(--surface-3); }
+.ui-dropdown__badge.is-accent { color: var(--accent); background: var(--surface-3); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ }
 
 /* Disabled + danger rows */
-.ui-dropdown__item.is-disabled { color: var(--disabled-ink); cursor: not-allowed; pointer-events: none; }
+.ui-dropdown__item.is-disabled { /* muted-ink: state — unavailable control */ color: var(--disabled-ink); cursor: not-allowed; pointer-events: none; }
 .ui-dropdown__item.is-disabled .ui-dropdown__label,
 .ui-dropdown__item.is-disabled .ui-dropdown__desc { color: inherit; }
-/* Quiet at rest, --pink on the way to being pressed. Both states, not hover alone:
+/* Body ink at rest, --pink on the way to being pressed. Both states, not hover alone:
    the ring says where the reader is, not that this row ends something.
    why: docs/specification.md#a-dropdown-row-is-a-div-a-link-or-a-button */
-.ui-dropdown__item.is-danger .ui-dropdown__label { color: var(--muted); }
+.ui-dropdown__item.is-danger .ui-dropdown__label { color: var(--text); }
 .ui-dropdown__item.is-danger:hover .ui-dropdown__label,
 .ui-dropdown__item.is-danger:focus-visible .ui-dropdown__label { color: var(--pink); }
 
@@ -207,7 +207,7 @@
   /* rank: label */
   font-size: var(--text-sm);
   font-weight: var(--weight-medium);
-  color: var(--muted);
+  color: var(--text);
   padding: 7px 12px 4px;
 }
 
@@ -244,7 +244,7 @@
   position: absolute;
   left: 11px;
   display: inline-flex;
-  color: var(--muted);
+  /* muted-ink: glyph — search icon */ color: var(--muted);
   pointer-events: none;
 }
 /* 16px at 2.4 paints 1.6px, over the 1.5px floor stories/glyph-stroke.test.js holds. */
@@ -258,7 +258,7 @@
   font-size: calc(var(--text-sm) - 0.5px);
   color: var(--strong);
   /* A field is the sunken step, the same one .ui-input takes. why: docs/specification.md#elevation */
-  background: var(--surface-2);
+  background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
   border: 1px solid var(--border);
   border-radius: var(--radius-sm);
   padding: 8px 12px 8px 34px;
@@ -271,11 +271,11 @@
    kit paints, so --surface-2 falls two rungs under it rather than one. The
    numbers are in the spec and the gate is stories/dropdown-field-ground.test.js.
    why: docs/specification.md#elevation */
-:root[data-theme="light"] .ui-dropdown__search-input { background: var(--bg); }
+:root[data-theme="light"] .ui-dropdown__search-input { background: var(--bg); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 
-.ui-dropdown__search-input::placeholder { color: var(--muted); }
+.ui-dropdown__search-input::placeholder { /* muted-ink: placeholder — empty search field */ color: var(--muted); }
 .ui-dropdown__search-input:hover { border-color: var(--border-strong); }
-.ui-dropdown__search-input:focus-visible { outline: none; border-color: var(--accent); box-shadow: var(--ring); }
+.ui-dropdown__search-input:focus-visible { outline: 2px solid transparent; border-color: var(--accent); box-shadow: var(--ring); }
 
 .ui-dropdown__list { max-height: 300px; overflow-y: auto; }
 /* A row is `display: flex`, which outranks the UA's [hidden], so a row the
@@ -284,11 +284,13 @@
 
 /* The row Enter would pick. Focus stays in the field, which carries the ring,
    so this row takes the hover fill and a bar rather than a second ring. */
-.ui-dropdown__item.is-active { background: var(--surface-3); box-shadow: inset 2px 0 0 var(--accent); }
+.ui-dropdown__item.is-active { background: var(--surface-3); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ box-shadow: inset 2px 0 0 var(--accent); }
 
 /* No match — a nudge and no action, per Guidelines / Microcopy. Empty while
    anything matches, so it takes no room. */
 .ui-dropdown__none { display: flex; flex-direction: column; gap: 3px; padding: 14px 12px 10px; text-align: center; }
 .ui-dropdown__none:empty { display: none; }
 .ui-dropdown__none-title { font-size: calc(var(--text-sm) - 0.5px); font-weight: 600; color: var(--strong); }
-.ui-dropdown__none-hint { font-size: var(--text-xs); color: var(--muted); line-height: 1.35; }
+.ui-dropdown__none-hint { font-size: var(--text-xs); color: var(--text); line-height: 1.35; }
+
+.ui-dropdown__badge.is-state { /* muted-ink: state — off, unset, disabled or archived badge */ color: var(--muted); }

package/src/styles/empty.css

@@ -22,7 +22,7 @@
   text-align: center;
   gap: 8px;
   padding: 48px 24px;
-  color: var(--muted);
+  color: var(--text);
 }
 
 /* Duotone illustration slot. */
@@ -77,7 +77,7 @@
   width: 32px;
   height: 32px;
   margin: 0 auto 14px;
-  color: var(--muted);
+  /* muted-ink: glyph — empty-state illustration */ color: var(--muted);
   opacity: 0.6;
 }
 .ui-empty__icon svg {

package/src/styles/feedback.css

@@ -66,7 +66,7 @@
 /* The composer panel (bottom-centre) */
 .ui-fbcomposer {
   position: fixed; z-index: 71; left: 50%; bottom: 26px; transform: translateX(-50%) translateY(14px);
-  width: min(520px, calc(100vw - 32px)); background: var(--bg-elevated); border-radius: 18px;
+  width: min(520px, calc(100vw - 32px)); background: var(--bg-elevated); --ring-gap: var(--bg-elevated); border-radius: 18px;
   /* The shadow was its only edge until #295; now it takes the hairline. */
   border: 1px solid var(--border); opacity: 0; pointer-events: none;
   transition: opacity var(--dur-med) var(--ease), transform var(--dur-med) var(--ease); overflow: hidden;
@@ -76,30 +76,30 @@
 .ui-fbc__head { display: flex; align-items: center; gap: 12px; padding: 17px 20px 0; }
 .ui-fbc__chip { display: inline-flex; align-items: center; gap: 8px; color: var(--accent); font-size: var(--text-sm); font-weight: var(--weight-semibold); letter-spacing: .01em; white-space: nowrap; min-width: 0; overflow: hidden; text-overflow: ellipsis; }
 .ui-fbc__chip svg { width: 14px; height: 14px; flex: none; opacity: .85; stroke-width: 2.7; }
-.ui-fbc__x { margin-left: auto; background: var(--surface-2); color: var(--dim); border: 0; width: 28px; height: 28px; border-radius: 8px; cursor: pointer; display: grid; place-items: center; flex: none; font: inherit; }
+.ui-fbc__x { margin-left: auto; background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ /* muted-ink: glyph — dismiss icon */ color: var(--dim); border: 0; width: 28px; height: 28px; border-radius: 8px; cursor: pointer; display: grid; place-items: center; flex: none; font: inherit; }
 .ui-fbc__x:hover { color: var(--strong); }
 .ui-fbc__x svg { width: 14px; height: 14px; stroke-width: 2.7; }
-.ui-fbc__quote { margin: 14px 20px 0; background: var(--surface-2); border-radius: 12px; padding: 12px 15px; display: flex; gap: 11px; }
+.ui-fbc__quote { margin: 14px 20px 0; background: var(--surface-2); /* ring-gap: inherit — decorative or text-only surface has no nested focus target. */ border-radius: 12px; padding: 12px 15px; display: flex; gap: 11px; }
 .ui-fbc__qm { color: var(--accent); font-size: var(--text-xl); font-weight: var(--weight-bold); line-height: .9; flex: none; opacity: .55; }
-.ui-fbc__quote q { quotes: none; color: var(--dim); font-style: italic; font-size: calc(var(--text-sm) + 0.5px); line-height: 1.55; }
+.ui-fbc__quote q { quotes: none; color: var(--text); font-style: italic; font-size: calc(var(--text-sm) + 0.5px); line-height: 1.55; }
 .ui-fbc__body { padding: 14px 20px 0; }
 .ui-fbcomposer textarea {
   width: 100%; min-height: 96px; resize: vertical; font-family: var(--font-sans); font-size: var(--text-base); line-height: 1.55;
-  color: var(--strong); background: var(--surface-2); border: 0; border-radius: 12px; padding: 13px 15px; transition: box-shadow var(--dur-fast) var(--ease);
+  color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ border: 0; border-radius: 12px; padding: 13px 15px; transition: box-shadow var(--dur-fast) var(--ease);
 }
-.ui-fbcomposer textarea::placeholder { color: var(--muted); }
-.ui-fbcomposer textarea:focus { outline: none; box-shadow: 0 0 0 2px var(--accent); }
+.ui-fbcomposer textarea::placeholder { /* muted-ink: placeholder — empty feedback field */ color: var(--muted); }
+.ui-fbcomposer textarea:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-fbc__foot { display: flex; align-items: center; justify-content: flex-end; gap: 12px; padding: 16px 20px 18px; }
 
 .ui-fbbtn { font-family: var(--font-sans); font-size: calc(var(--text-sm) + 0.5px); font-weight: var(--weight-semibold); border-radius: 10px; padding: 9px 17px; cursor: pointer; border: 0; transition: filter var(--dur-fast) var(--ease), background var(--dur-fast) var(--ease), color var(--dur-fast) var(--ease); }
-.ui-fbbtn.ghost { background: transparent; color: var(--dim); }
-.ui-fbbtn.ghost:hover { color: var(--strong); background: var(--surface-2); }
+.ui-fbbtn.ghost { background: transparent; color: var(--text); }
+.ui-fbbtn.ghost:hover { color: var(--strong); background: var(--surface-2); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */ }
 .ui-fbbtn.primary { background: var(--accent-strong); color: var(--accent-contrast); display: inline-flex; align-items: center; gap: 9px; }
 .ui-fbbtn.primary:hover { filter: brightness(1.08); }
 /* Same flat pair as .ui-btn:disabled, for the same reason (#220). */
 .ui-fbbtn.primary:disabled {
-  background: var(--disabled-surface);
-  color: var(--disabled-ink);
+  background: var(--disabled-surface); /* ring-gap: inherit — control paint; its focus indicator uses the containing surface. */
+  /* muted-ink: state — unavailable control */ color: var(--disabled-ink);
   cursor: default;
   filter: none;
 }
@@ -108,14 +108,14 @@
 @keyframes uiFbSpin { to { transform: rotate(360deg); } }
 
 /* Success state */
-.ui-fbc__done { padding: 30px 26px 24px; text-align: center; background: radial-gradient(112% 60% at 50% 0%, var(--glow-green), transparent 62%); }
+.ui-fbc__done { padding: 30px 26px 24px; text-align: center; background: radial-gradient(112% 60% at 50% 0%, var(--glow-green), transparent 62%); /* ring-gap: inherit — translucent wash retains the opaque containing gap. */ }
 .ui-fbc__ck { width: 88px; height: 88px; margin: 0 auto 13px; display: grid; place-items: center; }
 .ui-fbck { width: 88px; height: 88px; overflow: visible; display: block; transform-origin: center; animation: uiFbCkSpring 1s cubic-bezier(.22,1,.3,1) both; } /* motion: choreographed — the frame the mark and the comet are timed against */
 .ui-fbck-t { fill: none; stroke: var(--surface-2); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; }
 .ui-fbck-m { fill: none; stroke: var(--green); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 118; stroke-dashoffset: 118; animation: uiFbCkDraw .6s cubic-bezier(.5,0,.3,1) .1s forwards; /* motion: choreographed — the mark draws while the spring is still settling */ }
 .ui-fbck-s { fill: none; stroke: var(--sheen); stroke-width: 9; stroke-linecap: round; stroke-linejoin: round; stroke-dasharray: 15 400; stroke-dashoffset: 133; filter: drop-shadow(0 0 8px var(--green)) drop-shadow(0 0 15px var(--green)); opacity: 0; animation: uiFbCkComet .6s cubic-bezier(.5,0,.3,1) .1s forwards; /* motion: choreographed — the comet rides the mark, so it shares its duration and delay exactly */ }
 .ui-fbc__done h4 { color: var(--strong); font-size: calc(var(--text-lg) + 1px); font-weight: var(--weight-semibold); letter-spacing: -.01em; margin-bottom: 7px; }
-.ui-fbc__done p { color: var(--dim); font-size: calc(var(--text-sm) + 0.5px); line-height: 1.55; max-width: var(--prose-caption); margin: 0 auto; }
+.ui-fbc__done p { color: var(--text); font-size: calc(var(--text-sm) + 0.5px); line-height: 1.55; max-width: var(--prose-caption); margin: 0 auto; }
 .ui-fbc__done p b { color: var(--text); font-weight: var(--weight-semibold); }
 .ui-fbc__done .row { margin-top: 18px; display: flex; gap: 10px; justify-content: center; }
 @keyframes uiFbCkDraw { to { stroke-dashoffset: 0; } }
@@ -123,7 +123,7 @@
 @keyframes uiFbCkSpring { 0% { transform: scale(1.32); } 62% { transform: scale(.965); } 82% { transform: scale(1.02); } 100% { transform: scale(1); } }
 
 /* Error banner */
-.ui-fbc__err { margin: 14px 20px 0; background: color-mix(in srgb, var(--pink) 14%, transparent); color: var(--pink); font-size: var(--text-sm); padding: 11px 15px; border-radius: 11px; display: none; }
+.ui-fbc__err { margin: 14px 20px 0; background: color-mix(in srgb, var(--pink) 14%, transparent); /* ring-gap: inherit — text-only validation message has no nested focus target. */ color: var(--pink); font-size: var(--text-sm); padding: 11px 15px; border-radius: 11px; display: none; }
 .ui-fbc__err.show { display: block; }
 /* A failed send's line fades in; wireFeedback() adds the class as it shows it. */
 .ui-fbc__err.is-entering { animation: m-fade var(--dur-fast) var(--ease-out) both; }

package/src/styles/footer.css

@@ -9,12 +9,12 @@
 .ui-footer {
   --footer-surface: transparent;
   --footer-border: var(--border);
-  --footer-link: var(--muted);
+  --footer-link: var(--text);
   --footer-link-hover: var(--strong);
   --footer-title: var(--strong);
-  --footer-text: var(--dim);
+  --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

@@ -13,7 +13,7 @@
 /* Required marker. Decoration only — the control carries `required`, which is
    what assistive technology reads, so this asterisk is aria-hidden. */
 .ui-field__req { color: var(--pink); margin-left: 4px; }
-.ui-field__hint { color: var(--muted); font-size: var(--text-sm); margin-top: 7px; line-height: 1.5; }
+.ui-field__hint { color: var(--text); font-size: var(--text-sm); margin-top: 7px; line-height: 1.5; }
 .ui-field__error { color: var(--pink); font-size: var(--text-sm); margin-top: 7px; display: flex; align-items: center; gap: 6px; }
 .ui-field__error svg { width: 16px; height: 16px; flex: none; stroke-width: 2.4; }
 
@@ -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,16 +36,16 @@
 .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);
 }
 
 .ui-input::placeholder,
-.ui-textarea::placeholder { color: var(--muted); opacity: 0.9; }
+.ui-textarea::placeholder { /* muted-ink: placeholder — empty form field */ color: var(--muted); opacity: 0.9; }
 
 /* The value a reader typed is still the value; it goes quiet, it does not fade
    into the field under it the way an opacity would take both down together. #220 */
@@ -57,15 +57,15 @@
 .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);
-  color: var(--disabled-ink);
+  /* muted-ink: state — unavailable control */ color: var(--disabled-ink);
   cursor: not-allowed;
 }
 
 .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; }
@@ -75,7 +75,7 @@
   left: 14px;
   width: 17px;
   height: 17px;
-  color: var(--muted);
+  /* muted-ink: glyph — field icon */ color: var(--muted);
   pointer-events: none;
 }
 .ui-input-group__icon svg { width: 100%; height: 100%; stroke: currentColor; fill: none; stroke-width: 2.2; }
@@ -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; }