basalt-ui 1.25.0 → 1.27.0

package/src/theme/density-relations.test.ts

@@ -161,9 +161,9 @@ describe('Fix 4 — every interactive target clears the WCAG 2.5.8 24px floor at
     }
   })
 
-  test('the mobile header actions row (appHeaderMobileActionsHeight)', () => {
+  test('the page bar row (pageBarRowHeight — the mobile header actions row it replaced is gone)', () => {
     for (const level of ALL_LEVELS) {
-      expect(deriveSpacing(level).step.appHeaderMobileActionsHeight).toBeGreaterThanOrEqual(24)
+      expect(deriveSpacing(level).step.pageBarRowHeight).toBeGreaterThanOrEqual(24)
     }
   })
 
@@ -183,6 +183,15 @@ describe('Fix 4 — every interactive target clears the WCAG 2.5.8 24px floor at
     }
   })
 
+  // `sheetRowHeight`'s own doc calls it "same floor family as `mobileNavRowHeight`" — same touch-only
+  // surface (the `Filters (n)` drawer, the mobile kebab sheet), same Apple HIG 44pt / WCAG 2.5.5 AAA
+  // floor, so it must clear it at every level too, not just coincidentally at level 0.
+  test('a Filters/kebab sheet row never drops below its own 44px floor', () => {
+    for (const level of ALL_LEVELS) {
+      expect(deriveSpacing(level).step.sheetRowHeight).toBeGreaterThanOrEqual(44)
+    }
+  })
+
   test('the resolved control/input height (size="md" Button/ActionIcon/Input) clears the floor too', () => {
     for (const level of ALL_LEVELS) {
       const { anchors } = deriveSpacing(level)
@@ -190,6 +199,25 @@ describe('Fix 4 — every interactive target clears the WCAG 2.5.8 24px floor at
       expect(anchors.inputHeight).toBeGreaterThanOrEqual(24)
     }
   })
+
+  // C15 (`docs/CONTROLS-SPEC.md` §5): "every touch target inside a home is ≥36px below `sm` (floor
+  // 30 at density −3)". Without the floor the 1 + 0.1*level multiplier takes 36 -> 25 at level -3,
+  // well under even the 24px WCAG floor above.
+  test('touchControlHeight never drops below its own 30px floor (C15)', () => {
+    for (const level of ALL_LEVELS) {
+      expect(deriveSpacing(level).anchors.touchControlHeight).toBeGreaterThanOrEqual(30)
+    }
+    expect(deriveSpacing(-3).anchors.touchControlHeight).toBe(30)
+  })
+
+  test('the remaining controls-tier anchors clear their own floors at every level', () => {
+    for (const level of ALL_LEVELS) {
+      const { anchors } = deriveSpacing(level)
+      expect(anchors.controlHeightTag).toBeGreaterThanOrEqual(18)
+      expect(anchors.controlHeightWidget).toBeGreaterThanOrEqual(22)
+      expect(anchors.controlHeightCtl).toBeGreaterThanOrEqual(28)
+    }
+  })
 })
 
 describe('Fix 5 — scaleSpace floors a sub-1 base at 1 (the inverted-clamp regression)', () => {
@@ -224,14 +252,14 @@ function oldLawFlatten(level: number): Record<string, number> {
   for (const [k, v] of Object.entries(SPACE_SCALE)) scale[k] = scaleSpace(v, level, multiplier)
   const step: Record<string, number> = {}
   for (const [k, v] of Object.entries(SPACE_STEP)) {
-    if (k === 'stickyHeaderClearance' || k === 'stickyHeaderClearanceMobile') continue
+    if (k === 'stickyHeaderClearance') continue
     step[k] = scaleSpace(v, level, multiplier)
   }
   step['sidebarSearchTriggerHeight'] = Math.max(24, step['sidebarSearchTriggerHeight']!)
   step['mobileNavBarHeight'] = Math.max(48, step['mobileNavBarHeight']!)
   step['mobileNavRowHeight'] = Math.max(44, step['mobileNavRowHeight']!)
+  step['sheetRowHeight'] = Math.max(44, step['sheetRowHeight']!)
   step['stickyHeaderClearance'] = step['appShellHeaderHeight']! + anchors['stackMd']!
-  step['stickyHeaderClearanceMobile'] = step['appShellHeaderMobileHeight']! + anchors['stackMd']!
   return { ...anchors, ...scale, ...step }
 }
 
@@ -298,10 +326,10 @@ describe("Fix 7 — the knob's resolution is honest at every notch", () => {
     expect(deriveSpacing(3).anchors.inputHeight).toBe(55)
     expect(deriveSpacing(-3).anchors.rowInsetX).toBe(7)
     expect(deriveSpacing(3).anchors.rowInsetX).toBe(13)
-    // `stickyHeaderClearance`/`stickyHeaderClearanceMobile` are EXCLUDED here on purpose — since both
-    // now DERIVE from their own AppShell header instead of scaling off an independent base (see
-    // `deriveSpacing`'s doc, third bullet, Decision 3), neither reproduced the old ±5 envelope to
-    // begin with; their own law is asserted by the dedicated describe block in `tokens/density.test.ts`
+    // `stickyHeaderClearance` is EXCLUDED here on purpose — since it now DERIVES from the AppShell
+    // header instead of scaling off an independent base (see `deriveSpacing`'s doc, third bullet),
+    // it never reproduced the old ±5 envelope to
+    // begin with; its own law is asserted by the dedicated describe block in `tokens/density.test.ts`
     // (specific low/zero/high values) AND by the "Fix 8" describe block below in this same file
     // (the generic `clearance = header + anchors.stackMd` relation, looped over every level).
     expect(deriveSpacing(-3).rowLineHeight).toBe(1.25)
@@ -309,32 +337,18 @@ describe("Fix 7 — the knob's resolution is honest at every notch", () => {
   })
 })
 
-describe('Fix 8 — the sticky-header clearance clears its OWN breakpoint header, exactly (Decision 3 — desktop/mobile split)', () => {
-  test('desktop clearance = appShellHeaderHeight + stackMd, exactly, at every level', () => {
+describe('Fix 8 — the sticky-header clearance clears the AppShell header, exactly', () => {
+  test('clearance = appShellHeaderHeight + stackMd, exactly, at every level', () => {
     for (const level of ALL_LEVELS) {
       const { step, anchors } = deriveSpacing(level)
       expect(step.stickyHeaderClearance).toBe(step.appShellHeaderHeight + anchors.stackMd)
     }
   })
 
-  test('mobile clearance = appShellHeaderMobileHeight + stackMd, exactly, at every level', () => {
-    for (const level of ALL_LEVELS) {
-      const { step, anchors } = deriveSpacing(level)
-      expect(step.stickyHeaderClearanceMobile).toBe(
-        step.appShellHeaderMobileHeight + anchors.stackMd,
-      )
-    }
-  })
-
-  test('mobile clearance exceeds desktop clearance at every level — catches a swap of the two formulas', () => {
-    // Both formulas add the SAME `anchors.stackMd` breathing room, so this reduces to
-    // `mobileHeader > desktopHeader`, which holds at every level today — but a bug that swapped
-    // which header feeds which key would flip this comparison immediately.
-    for (const level of ALL_LEVELS) {
-      const { step } = deriveSpacing(level)
-      expect(step.stickyHeaderClearanceMobile).toBeGreaterThan(step.stickyHeaderClearance)
-    }
-  })
+  // The "mobile clearance = appShellHeaderMobileHeight + stackMd" and "mobile exceeds desktop" tests
+  // that used to sit here are DELETED, not renamed: since 1.26.0 the AppShell header is ONE 48px row
+  // at every viewport (law C14, `docs/CONTROLS-SPEC.md` §2.1), so `stickyHeaderClearanceMobile` and
+  // the `appShellHeaderMobileHeight` it derived from no longer exist to assert anything about.
 
   // The "both breathing-room margins (clearance minus own header) are monotonically non-decreasing"
   // check used to live here as its own test — deleted, not merely renamed: the two tests above this
@@ -362,34 +376,29 @@ describe('Fix 6 — BasaltShell AppShell dimensions track density', () => {
     }
   })
 
-  test("mobile header row-1 budget never falls below Mantine's static default ActionIcon (22px)", () => {
-    // The 22px floor is `--ai-size-sm` — verified directly against the INSTALLED Mantine source
-    // (`@mantine/core/styles/ActionIcon.css`: `--ai-size-xs: 18px; --ai-size-sm: 22px; --ai-size-md:
-    // 28px; ...`), not recalled from memory. The budget at every level in `[-3, 3]` under the current
-    // law: 23 / 26 / 28 / 32 / 36 / 38 / 41 (level -3 through +3) — never below the floor, with the
-    // smallest margin (1px) at level -3, not at -2 as sometimes assumed by eye.
+  test('the header is ONE row at every viewport, and it holds a touch target below sm', () => {
+    // The invariant this replaced was a BUDGET: `appShellHeaderMobileHeight` was a documented SUM
+    // (row 1 + `SPACE_SCALE.sm` + `appHeaderMobileActionsHeight`), so row 1 was whatever the total
+    // left over, and raising an addend without raising the total silently ate the target-size margin
+    // — which is exactly what the component-roominess retune did (`SPACE_SCALE.sm` 12 -> 13 drove
+    // level -3 to 22px, flush against Mantine's 22px `--ai-size-sm` floor).
     //
-    // Row 1 is the REMAINDER of `appShellHeaderMobileHeight`'s documented sum (row 1 + `SPACE_SCALE.sm`
-    // + `appHeaderMobileActionsHeight`), so raising an addend without raising the total takes the
-    // difference straight out of this budget. That is exactly what the component-roominess retune did
-    // — `SPACE_SCALE.sm` 12 -> 13 briefly drove level -3 to 22, flush against the floor — and why the
-    // mobile header went 96 -> 97 in the same change. See that constant's JSDoc (`tokens/palette.ts`):
-    // it names this test as the thing that measures the drift, and computing the header from its
-    // addends as the fix that would make the drift impossible.
+    // 1.26.0 deletes the sum instead of re-tuning it: `PageBar` folds the page's overflow into a
+    // kebab and moves filters/tabs into the page flow, so there is no second mobile row to reserve
+    // (law C14) and the header is `appShellHeaderHeight` at EVERY width. Row 1's budget is therefore
+    // the whole header, and the thing worth asserting is what law C15 actually promises — that a
+    // `touchControlHeight` target fits inside it below `sm`.
     for (const level of ALL_LEVELS) {
-      const { step, scale } = deriveSpacing(level)
-      const budget = step.appShellHeaderMobileHeight - step.appHeaderMobileActionsHeight - scale.sm
-      expect(budget).toBeGreaterThanOrEqual(22)
+      const { step, anchors } = deriveSpacing(level)
+      expect(step.appShellHeaderHeight).toBeGreaterThanOrEqual(anchors.touchControlHeight)
+      expect(anchors.touchControlHeight).toBeGreaterThanOrEqual(anchors.controlHeightCtl)
     }
   })
 
-  test('the mobile header row-1 budget is monotonically non-decreasing across levels', () => {
-    const budgets = ALL_LEVELS.map((level) => {
-      const { step, scale } = deriveSpacing(level)
-      return step.appShellHeaderMobileHeight - step.appHeaderMobileActionsHeight - scale.sm
-    })
-    for (let i = 1; i < budgets.length; i++) {
-      expect(budgets[i]).toBeGreaterThanOrEqual(budgets[i - 1]!)
+  test('the header row is monotonically non-decreasing across levels', () => {
+    const heights = ALL_LEVELS.map((level) => deriveSpacing(level).step.appShellHeaderHeight)
+    for (let i = 1; i < heights.length; i++) {
+      expect(heights[i]).toBeGreaterThanOrEqual(heights[i - 1]!)
     }
   })
 
@@ -449,3 +458,49 @@ describe('Fix 9 — the Mantine spacing scale keeps its strict xs < sm < md < lg
     }
   })
 })
+
+describe('Fix 10 — ctl SegmentedControl matches the ctl Button/Input box at every level, not a fixed 30px', () => {
+  // `SegmentedControl.extend`'s function-form `styles` only sets a label `minHeight` when
+  // `props.size === 'ctl'` — everything else (`sm`/`md` in a form) must fall through untouched.
+  const stylesFn = baseTheme.components?.['SegmentedControl']?.styles as
+    | ((t: MantineTheme, props: { size?: string }, ctx: never) => Record<string, unknown>)
+    | undefined
+
+  test('a non-ctl size (e.g. the form default) gets no label override', () => {
+    const result = stylesFn?.(theme, { size: 'md' }, {} as never)
+    expect(
+      (result?.['label'] as Record<string, unknown> | undefined)?.['minHeight'],
+    ).toBeUndefined()
+  })
+
+  test("size='ctl' gets an inline-flex, vertically centred label — Mantine's label is `display: block`, so a bare minHeight alone would leave the text top-aligned", () => {
+    const result = stylesFn?.(theme, { size: 'ctl' }, {} as never)
+    const label = result?.['label'] as Record<string, unknown> | undefined
+    expect(label?.['display']).toBe('inline-flex')
+    expect(label?.['alignItems']).toBe('center')
+  })
+
+  test('the label minHeight formula, plus the root track padding on both sides, reconstructs EXACTLY the same scaled expression as `--button-height-ctl` — the algebraic identity that makes the two controls the same height at every density level, not just level 0', () => {
+    const result = stylesFn?.(theme, { size: 'ctl' }, {} as never)
+    const label = result?.['label'] as Record<string, unknown> | undefined
+    const minHeight = label?.['minHeight']
+    expect(typeof minHeight).toBe('string')
+    const rootPadding = 2 * SPACE_FIXED.segmentedTrackInset
+    expect(minHeight).toBe(
+      `calc(var(--vx-space-control-height-ctl) * var(--mantine-scale) - ${rootPadding}px)`,
+    )
+    // `--button-height-ctl` (`ctlSizeVars` in theme/index.ts) is the un-subtracted form — adding the
+    // root's own `2 * segmentedTrackInset` padding back to the label's minHeight must reproduce it,
+    // for every level, since neither term is level-dependent (the level only changes the CSS var's
+    // RESOLVED value at paint time, never this formula).
+    for (const level of ALL_LEVELS) {
+      // `anchors.controlHeightCtl` is the JS-side value `--vx-space-control-height-ctl` resolves to
+      // at this level (scale = 1, the JS-derivation default) — substituting it into both formulas
+      // must land on the same total.
+      const { anchors } = deriveSpacing(level)
+      const labelHeight = anchors.controlHeightCtl - rootPadding
+      const totalHeight = labelHeight + rootPadding
+      expect(totalHeight).toBe(anchors.controlHeightCtl)
+    }
+  })
+})

package/src/theme/divider-law.test.ts

@@ -0,0 +1,259 @@
+/**
+ * The divider law — a mechanical inventory of every HORIZONTAL hairline basalt draws
+ * (`docs/DESIGN-SPEC.md` §8: depth is a shadow, and a border-as-border is reserved for a layout
+ * divider).
+ *
+ * The bug this file exists to prevent, measured on the playground's `Controls (mobile)` page at
+ * 390px: the page carried five rules in its first 320px — a table box whose top edge sat directly
+ * under the table's own `WidgetHeader`, its bottom edge on the last row's own hairline, and a
+ * section rule 8px from the next one. None of them divided anything. Two rules stack into a band,
+ * and a band under a heading says "the heading is not part of what follows", which is the opposite
+ * of what a section header is for.
+ *
+ * So the law has two halves and this file pins both:
+ *
+ * 1. **A header never draws a rule under itself** — in the CHROME lane (shell, controls, dashboard,
+ *    data, widget-header, theme). The reader already has the heading's type scale, its weight and
+ *    the space below it; a line adds a fourth channel saying the same thing and costs a band.
+ * 2. **A between-rows family always drops its LAST rule** — the line after the final row is an
+ *    outer border pretending to be a separator, and it is the line that lands on top of whatever
+ *    frame the container already has.
+ *
+ * The guard is an INVENTORY, not a pattern match: every horizontal hairline in every CSS module has
+ * to be listed below with a `kind` and a reason, so a seventh one added next month fails here and
+ * gets classified rather than shipping unexamined. That is the same idiom `theme/border-coverage.test.ts`
+ * uses for Mantine's stock borders, applied to the ones basalt writes itself.
+ *
+ * Not in scope, deliberately: the `border` SHORTHAND (a box around a control or a card — that is an
+ * edge, not a rule, and `border-coverage.test.ts` owns it), vertical hairlines (a column rule
+ * divides two regions by construction), and Mantine's own `inset 0 -1px 0` redraw of a STICKY table
+ * head's `border-bottom`, which is a row line drawn as a shadow because `border-collapse: collapse`
+ * drops borders on sticky cells — it appears and disappears with `withRowBorders`, so it is the same
+ * line every other row gets and not a header rule.
+ */
+import { describe, expect, test } from 'bun:test'
+import { Glob } from 'bun'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const SRC = join(import.meta.dir, '..')
+
+type Hairline = { readonly file: string; readonly selector: string; readonly decl: string }
+
+/**
+ * Every `border-{top,bottom,block-start,block-end}` and every 1px inset `box-shadow` in a CSS
+ * module, with the selector it sits under. A hand-rolled scanner rather than a regex per file: the
+ * SELECTOR is half the classification (`.header` vs `.rows > *:not(:last-child)` are the two
+ * opposite verdicts), and a regex over declarations alone cannot see it.
+ */
+function scanHairlines(): { rules: Hairline[]; drops: Hairline[] } {
+  const rules: Hairline[] = []
+  const drops: Hairline[] = []
+  const files = [...new Glob('**/*.module.css').scanSync({ cwd: SRC })].sort()
+  for (const file of files) {
+    const css = readFileSync(join(SRC, file), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '')
+    const stack: string[] = []
+    let buf = ''
+    for (const ch of css) {
+      if (ch === '{') {
+        stack.push(buf.trim().replace(/\s+/g, ' '))
+        buf = ''
+        continue
+      }
+      if (ch === '}') {
+        stack.pop()
+        buf = ''
+        continue
+      }
+      if (ch !== ';') {
+        buf += ch
+        continue
+      }
+      const decl = buf.trim().replace(/\s+/g, ' ')
+      buf = ''
+      const border = /^border-(?:top|bottom|block-start|block-end):\s*(.+)$/.exec(decl)
+      const selector = stack.join(' >> ')
+      if (border !== null) {
+        ;(border[1] === 'none' ? drops : rules).push({ file, selector, decl })
+        continue
+      }
+      if (decl.startsWith('box-shadow:') && decl.includes('inset') && /\b-?1px\b/.test(decl)) {
+        rules.push({ file, selector, decl })
+      }
+    }
+  }
+  return { rules, drops }
+}
+
+/**
+ * `between-rows` — the line sits BETWEEN two members of a list and the family drops its last one.
+ * `region-boundary` — it separates two layout regions that are not a header and its content (the
+ *   mobile bar and the page it floats over, an article's body and its footer).
+ * `prose-typography` — an AUTHORED document, not app chrome: an `<hr>` the author wrote, the rule
+ *   under an article's `h2`, a code block's filename bar. A document's conventions are the reader's
+ *   expectations there (`docs/CONTENT-SPEC.md`), and `content/**` is out of the chrome lane for
+ *   exactly that reason. Nothing in this kind may appear outside `content/`.
+ */
+type Kind = 'between-rows' | 'region-boundary' | 'prose-typography'
+
+const LEDGER: readonly { file: string; selector: string; kind: Kind; why: string }[] = [
+  {
+    file: 'shell/app-mobile-nav.module.css',
+    selector: '.bar',
+    kind: 'region-boundary',
+    why: 'The mobile bar is a fixed region floating over a scrolling page — the rule is the only thing that says the page ends there, and it is the boundary between two regions, not a header and its content.',
+  },
+  {
+    file: 'controls/controls.module.css',
+    selector:
+      '.sheetOption + .sheetOption, .sheetDisclosureBody + .sheetOption, .sheetOption + .sheetDisclosureBody',
+    kind: 'between-rows',
+    why: "The filter sheet's option rows. Written as an adjacent-sibling rule so the FIRST row has no top line — the group label above it is a header and gets no rule (C15).",
+  },
+  {
+    file: 'controls/controls.module.css',
+    selector: '.sheetRow',
+    kind: 'between-rows',
+    why: 'A 44px sheet row. Paired with `.sheetRow:last-child { border-bottom: none }` below, which the last-rule assertion checks.',
+  },
+  {
+    file: 'dashboard/settings-section.module.css',
+    selector: '.rows > *:not(:last-child)',
+    kind: 'between-rows',
+    why: 'A settings list. The `:not(:last-child)` IS the last-rule drop, written into the selector rather than as a second rule.',
+  },
+  {
+    file: 'content/article-layout.module.css',
+    selector: '.header',
+    kind: 'prose-typography',
+    why: "An article's masthead rule — the title-block convention of a printed document, and the one place a reader expects a line under a heading.",
+  },
+  {
+    file: 'content/article-layout.module.css',
+    selector: '.footer',
+    kind: 'region-boundary',
+    why: 'Prev/next navigation below the article body — two regions, and the rule is above the footer rather than under a heading.',
+  },
+  {
+    file: 'content/guide.module.css',
+    selector: '.footer',
+    kind: 'region-boundary',
+    why: 'Same shape as the article footer: the boundary between a document and the navigation after it.',
+  },
+  {
+    file: 'content/prose.module.css',
+    selector: '.root hr',
+    kind: 'prose-typography',
+    why: 'An `<hr>` the AUTHOR wrote in their markdown. basalt does not get to drop a divider the document asked for.',
+  },
+  {
+    file: 'content/prose.module.css',
+    selector: '.root.article h2',
+    kind: 'prose-typography',
+    why: "The `article` prose variant's section rule — a long-form document convention, scoped to that variant and never applied to app chrome.",
+  },
+  {
+    file: 'content/code-block.module.css',
+    selector: '.header',
+    kind: 'prose-typography',
+    why: "A code block's filename/language bar. The block is a quoted artifact inside a document, and the bar is its frame's top row rather than a section heading.",
+  },
+]
+
+const CHROME_LANES = ['shell/', 'controls/', 'dashboard/', 'data/', 'widget-header/', 'theme/']
+
+function isChrome(file: string): boolean {
+  return CHROME_LANES.some((lane) => file.startsWith(lane))
+}
+
+const { rules, drops } = scanHairlines()
+
+describe('every horizontal hairline is inventoried and classified', () => {
+  test('no hairline exists that the ledger does not name', () => {
+    const listed = new Set(LEDGER.map((e) => `${e.file}|${e.selector}`))
+    const unlisted = rules
+      .filter((r) => !listed.has(`${r.file}|${r.selector}`))
+      .map((r) => `${r.file} → ${r.selector} { ${r.decl} }`)
+    // Do NOT silence this by adding an entry with a hand-wave. Decide which `kind` the line is: a
+    // `between-rows` family (then add the last-rule drop too), a `region-boundary`, or — only inside
+    // `content/**` — `prose-typography`. A rule under a heading in the chrome lane is none of the
+    // three, and the fix is to delete it and let the type scale and the space do the work.
+    expect(unlisted).toEqual([])
+  })
+
+  test('the ledger names nothing that no longer exists', () => {
+    const found = new Set(rules.map((r) => `${r.file}|${r.selector}`))
+    expect(LEDGER.filter((e) => !found.has(`${e.file}|${e.selector}`)).map((e) => e.file)).toEqual(
+      [],
+    )
+  })
+
+  test('`prose-typography` is confined to content/ — app chrome has no authored-document lane', () => {
+    expect(
+      LEDGER.filter((e) => e.kind === 'prose-typography' && !e.file.startsWith('content/')).map(
+        (e) => `${e.file} → ${e.selector}`,
+      ),
+    ).toEqual([])
+  })
+
+  test('every ledger entry carries a real reason', () => {
+    expect(LEDGER.filter((e) => e.why.length < 40).map((e) => e.selector)).toEqual([])
+  })
+})
+
+describe('a header never draws a rule under itself in the chrome lane', () => {
+  // The five class names the chrome lane uses for "the heading row of a thing" — `WidgetHeader`'s
+  // root/titleRow/subtitle, `Section`'s, the filter sheet's, the table toolbar's. A `border-bottom`
+  // on any of them is the exact regression this describe block exists for.
+  const HEADER_SELECTOR =
+    /^\.(?:root|header|titleRow|title|subtitle|sheetHeader|sheetTitle|toolbar|thead|head)\b/
+
+  test('no chrome-lane hairline sits under a header-shaped selector', () => {
+    const offenders = rules
+      .filter((r) => isChrome(r.file) && HEADER_SELECTOR.test(r.selector))
+      .map((r) => `${r.file} → ${r.selector} { ${r.decl} }`)
+    expect(offenders).toEqual([])
+  })
+
+  test('the chrome lane holds ONLY between-rows and region-boundary lines', () => {
+    const kinds = LEDGER.filter((e) => isChrome(e.file)).map((e) => e.kind)
+    expect([...new Set(kinds)].sort()).toEqual(['between-rows', 'region-boundary'])
+  })
+})
+
+describe('a between-rows family drops its last rule', () => {
+  for (const entry of LEDGER.filter((e) => e.kind === 'between-rows')) {
+    test(`${entry.file} → ${entry.selector}`, () => {
+      // Either the selector itself excludes the last member (`:not(:last-child)`, or an
+      // adjacent-sibling combinator, which draws the line as the SECOND row's top edge and so has no
+      // trailing rule by construction), or the module carries an explicit `border: none` drop.
+      const selfLimiting = /:not\(:last-child\)|\+/.test(entry.selector)
+      const dropped = drops.some(
+        (d) => d.file === entry.file && d.selector.startsWith(`${entry.selector}:last`),
+      )
+      expect(selfLimiting || dropped).toBe(true)
+    })
+  }
+
+  test('the themed Table drops its last body row — the rule that used to land on the outer box', () => {
+    // `BasaltDataTable`'s `withTableBorder` went to `false` by default in the same minor (see
+    // `data/data-table.test.tsx`); while both shipped, the two lines sat on top of each other and the
+    // doubling hid which of them was drawing it. `tbody` scoped so a `tfoot` totals row keeps the
+    // BETWEEN rule above it.
+    const css = readFileSync(join(SRC, 'theme/controls.module.css'), 'utf8')
+    expect(css).toContain('html .tableRoot tbody tr:last-of-type')
+    expect(drops).toContainEqual({
+      file: 'theme/controls.module.css',
+      selector: 'html .tableRoot tbody tr:last-of-type',
+      decl: 'border-bottom: none',
+    })
+  })
+
+  test('the themed Accordion drops its last item — the same law, already shipped', () => {
+    expect(drops).toContainEqual({
+      file: 'theme/controls.module.css',
+      selector: '.accordionItem:last-of-type',
+      decl: 'border-bottom: none',
+    })
+  })
+})

package/src/theme/icon-slot.module.css

@@ -0,0 +1,47 @@
+/*
+ * The framework's ONE icon box (`docs/CONTROLS-SPEC.md` §3) — see `icon-slot.tsx` for why every
+ * `icon` prop in the public API renders through it.
+ *
+ * The box is a FIXED square, not a shrink-to-fit inline box: `width`/`height` are declared on the
+ * slot itself so the row's geometry is decided by the SLOT and never by the glyph the caller
+ * happened to pass. `--vx-space-icon-size` is the host's override hook (a `WidgetHeader` tier, a
+ * collapsed rail), defaulting to the 16px the control tier draws; it is deliberately NOT a
+ * `--vx-space-*` token declared by `tokens/index.ts` — no home needs it globally, and a token would
+ * invite a call site to set it.
+ */
+.slot {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: var(--vx-space-icon-size, 1rem);
+  height: var(--vx-space-icon-size, 1rem);
+  /* The glyph is `display: block` below, so the slot has no text to lead — a residual line box is
+   * what pushed a 16px icon a fraction below the optical centre of a 30px button. */
+  line-height: 0;
+}
+
+/*
+ * `width`/`height: 100%` is what makes ANY consumer glyph land on the tier. An inline `<svg>`
+ * carries its own `width`/`height` attributes (14, 20, 24 — or none at all, which paints at the
+ * `viewBox`'s intrinsic size, or 300×150 with no `viewBox` either), and those attributes are
+ * PRESENTATION attributes: they lose to any CSS declaration. So the slot restates them from the
+ * box, and the caller's own numbers stop mattering.
+ *
+ * `display: block` removes the baseline the glyph would otherwise sit on. An inline `<svg>` aligns
+ * its own bottom edge to the parent's text baseline, which leaves the descender gap BELOW it inside
+ * the box — the icon then paints high or low of centre by a fraction of the line box, and by a
+ * DIFFERENT fraction per font stack. `object-fit: contain` keeps a non-square glyph whole rather
+ * than stretching it to the square box.
+ *
+ * `img` and `picture` are covered too: an icon slot filled from a sprite sheet or a remote asset is
+ * the same geometry problem, and a consumer's icon set is as likely to be one as the other.
+ */
+.slot > svg,
+.slot > img,
+.slot > picture {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}

package/src/theme/icon-slot.module.css.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly slot: string
+}
+export default classes