@apliteni/apliteni-ui 0.86.0 → 0.88.0

package/guidelines/button-labels.md

@@ -0,0 +1,35 @@
+# Button labels
+
+## Keep the words
+
+<!-- rule: words-first -->
+
+**Rule:** Give every button words, and add a glyph only to help those words.
+
+**Do:** Export, Rename and Share, named at rest.
+
+**Don't:** The same three, each name waiting on a hover a finger never performs.
+
+## Let the glyph repeat the verb
+
+<!-- rule: glyph-repeats-the-verb -->
+
+**Rule:** Add a glyph beside a label only when it depicts that label’s action, and treat every button in a row the same way.
+
+**Except:** A dismissing action beside a committing one is not a peer, and stays plain.
+
+**Do:** The arrow downloads, the sheets copy.
+
+**Don't:** A table is what is exported, not the export, and the plain neighbour reads as lesser.
+
+## Earn a wordless button
+
+<!-- rule: wordless-earns-it -->
+
+**Rule:** Drop a button’s words only when its glyph is learned everywhere, its action is on the closed list, and its name is left to assistive technology and a hover title.
+
+**Except:** [Icon-only controls](https://ui.apli.tech/storybook/?path=/story/guidelines-iconography--iconography) is the list, and it grows by decision. The folded rail shows its names beside the glyphs instead, so those carry no title.
+
+**Do:** Overflow is on that list; the funnel is not.
+
+**Don't:** A funnel could filter, sort or export, and the cog gave up the word that said which.

package/guidelines/iconography.md

@@ -8,7 +8,7 @@
 
 **Why:** Without a legend, readers need labels for unfamiliar glyphs.
 
-**Except:** The list grows by decision, not review debate. Today: `x` (close or dismiss), `copy` (copy to clipboard), `moreHorizontal` (overflow menu), `moreVertical` (overflow menu), `chevronDown` (expand or collapse), `chevronUp` (expand or collapse), and the shell’s theme toggle, sidebar toggle and collapsed-rail links.
+**Except:** The list grows by decision, not review debate, and [Earn a wordless button](https://ui.apli.tech/storybook/?path=/story/guidelines-button-labels--button-labels) states the three tests an entry passes. Today: `x` (close or dismiss), `copy` (copy to clipboard), `moreHorizontal` (overflow menu), `moreVertical` (overflow menu), `chevronDown` (expand or collapse), `chevronUp` (expand or collapse). The shell’s own chrome — theme toggle, sidebar toggle, collapsed-rail links — is wordless by a separate decision, not by passing those tests.
 
 **Do:** Show an overflow menu without words; keep the Settings label.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "workspaces": [
     "react"
   ],

package/react/README.md

@@ -515,11 +515,12 @@ instead, and the word goes to the track's accessible name. The file reads as a
 stack: the name on top with the actions at its end, the size — or the failure
 message — under it, and the track the full width below. No tier takes a second
 line. The name truncates its stem and keeps its extension, with the whole name in
-a `title`, and nothing is hidden or moved at any width. `Remove` is the icon-only
-`x`, named by `removeLabel`; `Retry` keeps its word. Both appear only when you
-handle them. Children render above the row, inside the region the target covers;
-pass `dragging` to drive that target from a parent. `accept` filters the system
-picker only — validate type and size yourself.
+a `title`, and nothing is hidden or moved at any width. `Remove` is the kit's
+small text button, worded by `removeLabel`; `Retry` keeps its word beside a
+glyph. Both appear only when you handle them. Children render above the row,
+inside the region the target covers; pass `dragging` to drive that target from
+a parent. `accept` filters the system picker only — validate type and size
+yourself.
 
 Use `Field` when an existing labelled control needs the kit frame. Spread its
 render-prop attributes onto one labelable control, and apply the existing control

package/react/dist/index.css

@@ -58,6 +58,10 @@
     --tap-clear-x: var(--space-1, 4px);
     --tap-clear-y: var(--tap-gap);
   }
+  .ui-seg--underline {
+    row-gap: var(--space-1, 4px) !important;
+    --tap-clear-y: var(--space-1, 4px);
+  }
   .ui-tabs__list {
     --tap-clear-x: 2px;
     --tap-clear-y: var(--tap-gap);

package/react/dist/index.d.ts

@@ -698,7 +698,7 @@ type FileDropProps = {
     accept?: string;
     /** The words on the drop target. */
     dropLabel?: string;
-    /** Names the icon-only remove button; it carries no visible word. */
+    /** The word on the remove button. */
     removeLabel?: string;
     retryLabel?: string;
     /** The file the consumer is holding. Left out, the row is at rest. */

package/react/dist/index.js

@@ -2412,7 +2412,7 @@ function Segmented({ options, value, onChange, label, appearance = "pill", disab
 
 // src/FilterBar.tsx
 import { useRef as useRef12, useState as useState8 } from "react";
-import { filterChipText, filterChipName, filterChipUnset } from "@apliteni/apliteni-ui";
+import { filterChipText, filterChipName, filterChipUnset, focusNextStop } from "@apliteni/apliteni-ui";
 import { jsx as jsx24, jsxs as jsxs19 } from "react/jsx-runtime";
 function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters", disabled = false, busy = false, onRemove, onClear, onChange }) {
   const bar = useRef12(null);
@@ -2428,7 +2428,8 @@ function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters
     const next = chips.slice(prior.index).find((chip) => !chip.disabled) || chips.slice(0, prior.index).reverse().find((chip) => !chip.disabled);
     const target = !blocked && next?.querySelector("[data-dropdown-trigger]");
     focused.current = null;
-    (target || bar.current)?.focus();
+    if (target) target.focus();
+    else focusNextStop(bar.current);
   });
   return /* @__PURE__ */ jsx24("div", { children: /* @__PURE__ */ jsxs19(
     "fieldset",
@@ -2486,9 +2487,9 @@ function FilterBar({ filters, label = "Filters", clearLabel = "Clear all filters
           },
           filter.id
         )),
-        /* @__PURE__ */ jsx24("span", { "data-filter-clear": "", onFocus: () => {
+        filters.length > 0 && /* @__PURE__ */ jsx24("span", { "data-filter-clear": "", onFocus: () => {
           focused.current = { id: null, index: 0 };
-        }, children: /* @__PURE__ */ jsx24(Button, { size: "sm", variant: "ghost", disabled: !filters.length, onClick: () => {
+        }, children: /* @__PURE__ */ jsx24(Button, { size: "sm", onClick: () => {
           if (!blocked) onClear();
         }, children: clearLabel }) })
       ]
@@ -2870,7 +2871,7 @@ function FileDrop({
   note,
   accept,
   dropLabel = "Drop to upload",
-  removeLabel = "Remove file",
+  removeLabel = "Remove",
   retryLabel = "Retry",
   file,
   dragging,
@@ -2927,11 +2928,9 @@ function FileDrop({
                   {
                     variant: "ghost",
                     size: "sm",
-                    icon: "x",
-                    iconOnly: true,
-                    "aria-label": removeLabel,
                     onClick: onRemove,
-                    disabled
+                    disabled,
+                    children: removeLabel
                   }
                 )
               ] })

package/src/assets/icons.js

@@ -150,6 +150,24 @@ export const iconNames = Object.keys(ICONS);
 // `gear` or `externalLink`, because a reader meets them one at a time and a
 // toolbar is not a legend. Adding an entry is a decision recorded here, which
 // is the point: the alternative rules read well and could not be gated.
+//
+// Guidelines / Button labels states the three tests an entry passes: the glyph is
+// learned everywhere, its action is on this list, and the control keeps a name
+// assistive technology reads and a hover shows. button({ iconOnly }) writes
+// `aria-label` and `title` together, so a control built from the list below has
+// both — and neither reaches a keyboard reader who is not running one.
+//
+// The shell's folded-rail links and its sidebar toggle are the stated exception:
+// they show the label itself beside the glyph on hover and on focus, so they carry
+// no `title` — stories/apps/shell-rail.test.js holds them to that. They are a
+// separate decision about the shell's own chrome, not entries that passed the
+// tests above.
+//
+// `filter` — Lucide's funnel — fails the first test. Depicting a thing is not the
+// fault; `copy` is on this list and depicts one too. The kit reads the funnel alone
+// as not saying whether the control filters, sorts or exports — its own inference
+// from the sources in docs/specification.md, not a measured recognition finding.
+// See #565.
 export const iconOnlyAllowed = {
   x: 'close or dismiss',
   copy: 'copy to clipboard',
@@ -159,6 +177,21 @@ export const iconOnlyAllowed = {
   chevronUp: 'expand or collapse',
 };
 
+// The word a wordless control's name may open with. The list above says which
+// ACTIONS may drop their text; without this, a glyph on it carries any action a
+// caller likes — `copy` for Duplicate, `x` for Cancel — and the gate stays green,
+// which is what #566's review found. The opening word, not the whole name, so
+// "Copy project ID" is Copy naming what it copies.
+// stories/guidelines/iconography.test.js reads call sites against both maps.
+export const iconOnlyNames = {
+  x: ['close', 'dismiss'],
+  copy: ['copy'],
+  moreHorizontal: ['more'],
+  moreVertical: ['more'],
+  chevronDown: ['expand', 'collapse', 'show', 'hide'],
+  chevronUp: ['expand', 'collapse', 'show', 'hide'],
+};
+
 // What a glyph means when a component picks it for the reader rather than a
 // caller naming it. Two rules hold the map together:
 //

package/src/components/filter-bar.js

@@ -1,6 +1,6 @@
 import { button, esc } from './index.js';
 import { dropdown, wireDropdown } from './dropdown.js';
-import { filterChipText, filterChipName, filterChipUnset } from '../logic/filter-bar.js';
+import { filterChipText, filterChipName, filterChipUnset, focusNextStop } from '../logic/filter-bar.js';
 
 export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear all filters', disabled = false, busy = false } = {}) {
   return `<fieldset class="ui-filter-bar" data-filter-bar${disabled || busy ? ' disabled' : ''}${busy ? ' aria-busy="true"' : ''}>`
@@ -13,7 +13,17 @@ export function filterBar({ filters = [], label = 'Filters', clearLabel = 'Clear
         triggerContent: `<span class="${filterChipUnset(filter) ? 'ui-dropdown__value is-placeholder' : 'ui-dropdown__value'}">${esc(filterChipText(filter))}</span>`,
         ariaLabel: filterChipName(filter), open: !!filter.open && !disabled && !busy && !filter.disabled })
       + `<button type="button" class="ui-filter-bar__remove" data-filter-remove aria-label="${esc(`Remove ${filter.label} filter`)}">×</button></fieldset>`).join('')
-    + `<span data-filter-clear>${button({ label: clearLabel, size: 'sm', variant: 'ghost', disabled: !filters.length })}</span></fieldset>`;
+    // Nothing to clear, no control: an unavailable action standing in an empty
+    // row is the only thing in it, and it reads as a bar that has been turned
+    // off rather than one with no filters on it. It is the kit's own `one-page`
+    // rule — a control with no action to offer is not shown. It returns with
+    // the first chip, in the bordered skin rather than the ghost one, because a
+    // live action beside two chips has to read as live.
+    // why: docs/specification.md#a-filter-row-holds-its-panels
+    + (filters.length
+      ? `<span data-filter-clear>${button({ label: clearLabel, size: 'sm' })}</span>`
+      : '')
+    + '</fieldset>';
 }
 
 // The host stays mounted; update() restores the action's focus after controlled removal.
@@ -38,7 +48,9 @@ export function initFilterBar(host, options = {}) {
     const control = target?.querySelector(same && focus.remove ? '[data-filter-remove]' : '[data-dropdown-trigger]')
       || host.querySelector('[data-filter-clear] button');
     if (control && !control.disabled && !control.closest('fieldset:disabled')) control.focus();
-    else { const bar = host.querySelector('[data-filter-bar]'); bar.tabIndex = -1; bar.focus(); }
+    // No control of its own left to hold it: the shared pair decides where the
+    // focus goes and checks that it arrived. why: src/logic/filter-bar.js
+    else focusNextStop(host);
   };
   const emit = (type, detail) => host.dispatchEvent(new host.ownerDocument.defaultView.CustomEvent(type, { bubbles: true, detail }));
   const click = e => {

package/src/index.d.ts

@@ -10,6 +10,8 @@ export declare function initFilterBar(host: Element, opts?: Record<string, unkno
 export declare function filterChipText(filter?: { label?: string; value?: string }): string;
 export declare function filterChipName(filter?: { label?: string; value?: string }): string;
 export declare function filterChipUnset(filter?: { value?: string }): boolean;
+export declare function nextFocusStop(host: Element | null | undefined): HTMLElement | null;
+export declare function focusNextStop(host: Element | null | undefined): HTMLElement | null;
 export declare function segmentedNextIndex(key: string, index: number, length: number): number | null;
 export declare function icon(name: string, className?: string): string;
 export declare function snippet(opts?: Record<string, unknown>): string;
@@ -43,6 +45,7 @@ export declare const SCORE: Record<'exact' | 'prefix' | 'wordStart' | 'contains'
 export declare const iconNames: string[];
 export declare const iconCategories: { name: string; names: string[] }[];
 export declare const iconOnlyAllowed: Record<string, string>;
+export declare const iconOnlyNames: Record<string, string[]>;
 export declare const iconMeanings: Record<string, string>;
 export declare const sun: string;
 export declare const moon: string;

package/src/index.js

@@ -30,7 +30,7 @@ export * from './components/filter-bar.js';
 export { dropdownMatch, dropdownFiltering } from './logic/dropdown.js';
 export { SCORE, rankGroups, rankCommands, scoreCommand, paletteHotkey } from './logic/command-palette.js';
 export { segmentedNextIndex } from './logic/segmented.js';
-export { filterChipText, filterChipName, filterChipUnset } from './logic/filter-bar.js';
+export { filterChipText, filterChipName, filterChipUnset, nextFocusStop, focusNextStop } from './logic/filter-bar.js';
 export { PAGE_SIZES, DEFAULT_PAGE_SIZE } from './logic/pagination.js';
 export { calloutIcons } from './logic/callout.js';
 export { formatNumericValue, formatDeltaValue } from './logic/table-values.js';

package/src/logic/filter-bar.js

@@ -1,4 +1,5 @@
-/* What a filter chip shows, what it is called, and when it counts as unset.
+/* What a filter chip shows, what it is called, when it counts as unset, and
+ * where the focus goes when the bar runs out of controls.
  * The chip prints the chosen value by itself — never the field's name beside it
  * — and the field's name stands in while nothing is chosen. Both faces ask
  * these, so a chip reads the same in vanilla and in React.
@@ -27,3 +28,78 @@ export function filterChipName(filter = {}) {
   if (!field) return text(filter.value);
   return filterChipUnset(filter) ? `${field}: any` : `${field}: ${text(filter.value)}`;
 }
+
+/* compareDocumentPosition's own flags, without reaching for a `Node` global
+   that a test environment need not define. */
+const FOLLOWING = 4;
+const PRECEDING = 2;
+
+/** A tab stop the focus cannot actually land on. `hidden`, a disabled fieldset and
+ *  `inert` are read off the document; `visibility` and `display` are read off the
+ *  cascade, because a `visibility: hidden` control keeps its box and so passes any
+ *  test made of rectangles. Each of them refuses `focus()` in a browser, and a
+ *  refusal is silent: the focus lands on the body, with no ring on anything and
+ *  the next Tab starting over from the top of the page. */
+function unreachable(el) {
+  if (el.tabIndex < 0 || el.disabled || el.inert) return true;
+  if (el.closest('[hidden],[inert],fieldset:disabled')) return true;
+  const view = el.ownerDocument.defaultView;
+  const style = view && view.getComputedStyle(el);
+  return !!style && (style.visibility === 'hidden' || style.visibility === 'collapse'
+    || style.display === 'none');
+}
+
+/** The controls a reader's Tab reaches from `host`, in the order the focus should
+ *  try them: forward in document order, then back from `host`.
+ *
+ *  It reads the document, not the layout. Where boxes are measurable, a control
+ *  that draws nothing is skipped; where nothing has a box — JSDOM has no layout
+ *  — every tab stop counts, so the answer stays the document's order rather than
+ *  becoming empty. */
+function stopsAround(host) {
+  const doc = host && host.ownerDocument;
+  if (!doc) return [];
+  const stops = [...doc.querySelectorAll('a[href],button,input,select,textarea,[tabindex]')]
+    .filter(el => !host.contains(el) && !unreachable(el));
+  const drawn = stops.filter(el => el.getClientRects().length);
+  const order = drawn.length ? drawn : stops;
+  return [...order.filter(el => host.compareDocumentPosition(el) & FOLLOWING),
+    ...order.filter(el => host.compareDocumentPosition(el) & PRECEDING).reverse()];
+}
+
+/** The control a reader's next Tab would reach from `host`: forward in document
+ *  order, else the nearest one behind it. A filter bar that has just dropped its
+ *  last control keeps no box the focus ring can sit on, so the focus has to
+ *  leave the bar rather than land on a line with no height.
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+export function nextFocusStop(host) {
+  return stopsAround(host)[0] || null;
+}
+
+/** Puts the focus where an emptied bar hands it on, and answers with the element
+ *  it ended on, or null if nothing took it.
+ *
+ *  A bar that still holds chips draws a box around them, so it takes the focus
+ *  itself, made focusable for that moment. Emptied, it has only an out-of-flow
+ *  legend left and measures 0 high, so the focus goes to the first control
+ *  outside it that will have it — on the Stock screener the caller's own
+ *  `Add filter`, in the React Finance composition the view strip's chosen tab.
+ *
+ *  Being reachable is not the same as taking the focus: a control can be visible
+ *  and enabled and still refuse, so each candidate is asked and then checked, and
+ *  the next one tried.
+ *  why: docs/specification.md#a-filter-row-holds-its-panels */
+export function focusNextStop(host) {
+  const doc = host && host.ownerDocument;
+  if (!doc) return null;
+  const bar = host.matches('[data-filter-bar]') ? host : host.querySelector('[data-filter-bar]');
+  if (bar && bar.querySelector('[data-filter-id]')) {
+    bar.tabIndex = -1; bar.focus();
+    return doc.activeElement === bar ? bar : null;
+  }
+  for (const stop of stopsAround(host)) {
+    stop.focus();
+    if (doc.activeElement === stop) return stop;
+  }
+  return null;
+}

package/src/styles/filter-bar.css

@@ -23,3 +23,19 @@
    and off the page. It inherits, reaching an option's label and description.
    why: docs/specification.md#a-filter-row-holds-its-panels */
 .ui-filter-bar .ui-dropdown__panel { min-width: 100%; max-width: 100%; overflow-wrap: anywhere; }
+/* The clear action takes the kit's bordered skin minus its fill: words belong on
+   the page, not on a grey block, in any state — Artur, round r28. Rest stays at
+   (0,1,1) so `.ui-btn:hover`'s accent wash still outranks it; the rules under it
+   answer each state that paints a NEUTRAL fill, one step above the kit rule
+   writing it. Held by filter-bar.test.js. why: docs/specification.md#a-filter-row-holds-its-panels */
+[data-filter-clear] button { background: transparent; }
+.ui-filter-bar [data-filter-clear] button:disabled,
+.ui-filter-bar [data-filter-clear] button[aria-disabled="true"],
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"],
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"]:hover,
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"]:active,
+.ui-filter-bar [data-filter-clear] button[aria-busy="true"][data-btn-disabled] { background: transparent; }
+/* No fill, so the label is read on the page: the ink button-disabled.test.js
+   measures on every ground. The edge stays the kit's --disabled-border. */
+.ui-filter-bar [data-filter-clear] button:disabled,
+.ui-filter-bar [data-filter-clear] button[aria-disabled="true"] { /* muted-ink: state — the clear action is off and its words sit on the page */ color: var(--disabled-ink-bare); }

package/src/styles/segmented.css

@@ -90,9 +90,58 @@
 }
 .ui-accent-picker button:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 
-.ui-seg--underline { flex-wrap: nowrap; align-self: stretch; justify-self: stretch; background: transparent; --ring-gap: inherit; border-radius: 0; border-bottom: 1px solid var(--border); padding: var(--space-1); overflow: auto; max-width: 100%; }
-.ui-seg--underline button { border-radius: var(--radius-xs); border-bottom: 2px solid transparent; padding: var(--space-3); white-space: nowrap; }
+/* Underline tabs wrap for the reason the pills above do — #435 — and draw no
+   rule of their own: the chosen tab carries the selection. #527, #545
+   why: docs/specification.md#the-chosen-tab-in-an-underline-strip */
+.ui-seg--underline { flex-wrap: wrap; overflow: visible; row-gap: var(--space-1); align-self: stretch; justify-self: stretch; background: transparent; --ring-gap: inherit; border-radius: 0; padding: var(--space-1); max-width: 100%; }
+/* `anywhere` is the half `break-word` cannot do: it lowers the tab's min-content
+   width, so one unbreakable word narrows rather than widening the page. The
+   padding is the scale's own step and the height is the tap floor, so the tab
+   draws 44 whatever line box its font hands it: the off-scale `--space-3 + 1px`
+   this replaces drew 44 with the webfont loaded and 41 without, which is under
+   the floor it claimed. The radius is left for the focus ring; the tab paints no
+   box. #527
+   why: guidelines/layout-and-density.md, the spacing scale */
+.ui-seg--underline button { position: relative; border-radius: var(--radius-sm); padding: var(--space-3); min-height: var(--tap-min, 44px); white-space: normal; overflow-wrap: anywhere; font-weight: var(--weight-medium); }
+/* The chosen tab is its label and one bar under it: no plate, no hairline, no
+   upright rail — those read as a list-row grip. `outline: 0` cancels the accent
+   outline the pill rule gives every chosen button, which is #544's second mark.
+   #527 r31. why: docs/specification.md#the-chosen-tab-in-an-underline-strip */
 .ui-seg--underline button.is-active,
-.ui-seg--underline button[aria-pressed="true"] { background: transparent; border-bottom-color: var(--accent); }
+.ui-seg--underline button[aria-pressed="true"] {
+  background: none;
+  color: var(--strong);
+  font-weight: var(--weight-semibold);
+  outline: 0;
+}
+/* Every tab reserves the bar and hides it, so the mark grows in place when the
+   choice moves rather than appearing — the structure and the timing
+   .ui-nav--tabs.is-underline already uses for the same 2px bar. ::before, not
+   ::after: below the phone step tap-zone.css sizes ::after to the 44px floor,
+   and a bar drawn there collapses that layer to 2px. Inset from the tab's
+   bottom edge, which is the line two wrapped rows share. */
+.ui-seg--underline button::before {
+  content: "";
+  position: absolute;
+  left: var(--space-3); right: var(--space-3); bottom: 3px;
+  height: 2px;
+  border-radius: 2px;
+  background: var(--accent);
+  opacity: 0;
+  transform: scaleX(0.4);
+  transition: opacity var(--dur-fast) var(--ease), transform var(--dur-fast) var(--ease);
+}
+.ui-seg--underline button.is-active::before,
+.ui-seg--underline button[aria-pressed="true"]::before { opacity: 1; transform: scaleX(1); }
+/* `outline: 0` above outranks the kit's :focus-visible rule — (0,3,0) against
+   (0,2,1) — so the chosen tab would focus with no indicator. Restated here. */
+.ui-seg--underline button.is-active:focus-visible,
+.ui-seg--underline button[aria-pressed="true"]:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
+/* The mode repaints an author colour, so the bar comes back as the labels' own
+   ink. `Highlight` is kept where it is named: one mark the mode cannot flatten. */
+@media (forced-colors: active) {
+  .ui-seg--underline button.is-active::before,
+  .ui-seg--underline button[aria-pressed="true"]::before { background: Highlight; }
+}
 .ui-seg button:focus-visible { outline: 2px solid transparent; box-shadow: var(--ring); }
 .ui-seg button:disabled { /* muted-ink: state — unavailable choice */ color: var(--disabled-ink); cursor: not-allowed; }

package/src/styles/tap-zone.css

@@ -110,6 +110,17 @@
     --tap-clear-y: var(--tap-gap);
   }
 
+  /* The underline appearance keeps the gap it draws, at every width and under
+     both pointers, so a wrapped strip reads as one block. It can because the tab
+     draws the floor itself — segmented.css gives it `min-height: var(--tap-min)`
+     — leaving its layer inside the drawn box. The clearance is still declared,
+     and declared SMALL on purpose: the pill rule above hands every strip
+     --tap-gap, and this one has 4px of row to give, not 20. So a layer here can
+     never reach past the gap it was promised, whatever a tab draws. A pill draws
+     31 tall and does want the full 20. #527, measured in
+     stories/segmented-wrap.test.js. */
+  .ui-seg--underline { row-gap: var(--space-1, 4px) !important; --tap-clear-y: var(--space-1, 4px); }
+
   /* Tabs are wide enough across; down, the panel under them has the room. */
   .ui-tabs__list { --tap-clear-x: 2px; --tap-clear-y: var(--tap-gap); }