@signal9/era-ui 30.1.0 → 30.1.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [30.1.1](https://github.com/sig-nine/era-ui/compare/v30.1.0...v30.1.1) (2026-08-16)
+
+### Bug Fixes
+
+* **button:** caps is a descender fix, not a case fix — and it costs a baseline ([0759f70](https://github.com/sig-nine/era-ui/commit/0759f70b0c23078e89d187c26c0b0c619d77a2ba))
+
 ## [30.1.0](https://github.com/sig-nine/era-ui/compare/v30.0.1...v30.1.0) (2026-08-16)
 
 ### Features

package/dist/generated-docs/button.md

@@ -27,22 +27,35 @@ and screen-reader accessible names don't change shape mid-flight. |
 an icon in `children`: the label then gets its own box, which is the only
 place era's ink centring can reach (see era-label-ink). |
 | `trail?` | `Snippet` | — | Icon rendered AFTER the label, outside it. Same reason as `lead`. |
-| `caps?` | `boolean` | `false` | The label is ALL CAPS or an initialism — "PDF", "CSV", "OK", "API".
-Trims the label to the cap band instead of the x-height band. The
-default (`era-text-trim`, ex/alphabetic) centres the x-height band,
-which is the visual mass of mixed-case text; a string with no lowercase
-has ink standing entirely above that band, so the box centres correctly
-and the ink sits high. Measured on a bar-tier button with a lead icon:
-"PDF" landed 2.5px high on mono and 3.5px on sans, and the cap band
-brought both inside half a pixel.
-A PROP because nothing can infer it. `text-transform: uppercase` is
-detectable and is not the same question — a label that is literally
-typed "PDF" carries no transform — and a snippet's text cannot be read
-before it renders. The caller is the only one who knows.
-Named for the CONTENT rather than the band: a consumer knows their label
-is an initialism and should not have to learn which typographic box that
-implies. Same reason Badge and Chip reach for era-token-ink by default —
-a pill holds a token, so it is caps-shaped by construction.
+| `caps?` | `boolean` | `false` | Trim this label to the CAP band instead of the x-height band — for a
+label whose ink runs cap-to-baseline: "PDF", "CSV", "OK", "API".
+THE NAME SAYS CAPS AND THE MECHANISM IS DESCENDERS. Worth knowing before
+you reach for it, because it decides where it helps. A controlled A/B on
+one real button — same element, same classes, only the STRING changing —
+says case is not the variable at all:
+  Save   asc 9  desc 0   ink 1.28px high
+  SAVE   asc 9  desc 0   ink 1.28px high   ← identical to "Save"
+  Savg   asc 9  desc 3   ink 0.22px low
+  savg   asc 7  desc 3   ink 1.22px low
+The ex band runs x-height to baseline, so ink above the x-height pulls
+the visual centre up and ink below the baseline pushes it back down;
+(xh − asc + desc)/2 predicts every row within 0.3px. A caps string is
+simply one that always has an ascender and never a descender, which is
+why the cap band boxes it exactly. "Save" has the same offset and this
+prop would fix it too. Measured by signalnine.org and reproduced here.
+WHAT IT COSTS, and why it is not the default. A fixed band gives every
+label the SAME baseline whatever it contains — measured spread across
+Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px. Changing one
+label's band moves that label alone: in a Bar holding bold/italic/PDF/
+publish, the caps label sits 1.06px below the other three. So this trades
+a uniform offset the eye cannot see for a local misalignment it can, and
+it is the right trade only when the label has no neighbour to align with
+— a lone action, a label paired with an icon (the reported case, where
+the comparison is against an optically-centred glyph rather than against
+other text). Beside other labels in a bar, prefer leaving it off.
+A PROP because nothing can infer it: `text-transform: uppercase` is a
+different question (a label typed "PDF" carries no transform), and a
+snippet's text cannot be read before it renders.
 Only reaches the label when `lead`/`trail` give it its own box. Without
 one the label is an anonymous flex item that no selector can address,
 which is the whole reason those snippets exist. |

package/dist/generated-docs/llms-full.txt

@@ -440,7 +440,9 @@ The value is OPTICAL, not the derivation's: pure x-band centring computes
 to ~0.23em of padding, but pixel-measured against real Title-Case text it
 over-lifts — the eye weighs the cap-to-baseline mass, which x-band
 centring parks ~2px high (caps 2.75px off the top against 5.7px of air
-under the baseline, measured at dense). 0.08em splits the difference
+under the baseline, measured at dense; the general form of that offset,
+and why era-label-ink's note about "System" is not a contradiction of it,
+is derived at era-label-ink below). 0.08em splits the difference
 between the x-band ideal and the cap-band ideal, landing caps ~3.7px in an
 18px field with ~4.7px under the baseline — the reading where neither
 band's partisans win and neither complains.
@@ -532,6 +534,36 @@ class differs — a label is sentence case, so the x-height band is the visual
 mass to centre (cap-band reads low on "System"), and it is laid out against
 the row's padding rather than centred in it.
 
+THAT PARENTHESIS AND era-ink-center's "x-band centring parks ~2px high" READ
+AS A CONTRADICTION AND ARE NOT. Both are true, of their own example string,
+and each was generalised one step too far. Under an ex band the ink offset is
+
+    (xh − ascent + descent) / 2
+
+which predicts a controlled A/B — one real button, one class set, only the
+STRING changing — within 0.3px:
+
+    Save  asc 9 desc 0   1.28px high     SAVE  asc 9 desc 0   1.28px high
+    Savg  asc 9 desc 3   0.22px low      savg  asc 7 desc 3   1.22px low
+
+"System" has a descender and reads low under the cap band; "Save" has none
+and reads high under the ex band. Case is not the variable — "Save" and
+"SAVE" are identical to the hundredth of a pixel. No fixed band centres both
+a descender-less and a descender-bearing label, because they differ by ~1.5px
+in the same box.
+
+WHICH IS WHY THE BAND IS FIXED ANYWAY, and this is the part that decides it.
+A band gives every label the SAME baseline whatever it spells — measured
+spread across Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px —
+while ink-extent centring would move each label independently and leave a bar
+of buttons visibly ragged. A uniform offset the eye cannot see beats a local
+misalignment it can. So the offset is accepted, not corrected, and the only
+escape is per-label and opt-in (Button's `caps`), which buys optical centring
+for a lone label at the cost of ~1.06px against its neighbours.
+
+Measured by signalnine.org and reproduced here; see label-band.spec.ts, which
+pins both the 0.00px spread and the cost of breaking it.
+
 WHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare
 text is an ANONYMOUS flex item — a box no selector reaches and no
 non-inherited property touches. So `era-text-trim` on a flex row is inert,
@@ -1616,22 +1648,35 @@ and screen-reader accessible names don't change shape mid-flight. |
 an icon in `children`: the label then gets its own box, which is the only
 place era's ink centring can reach (see era-label-ink). |
 | `trail?` | `Snippet` | — | Icon rendered AFTER the label, outside it. Same reason as `lead`. |
-| `caps?` | `boolean` | `false` | The label is ALL CAPS or an initialism — "PDF", "CSV", "OK", "API".
-Trims the label to the cap band instead of the x-height band. The
-default (`era-text-trim`, ex/alphabetic) centres the x-height band,
-which is the visual mass of mixed-case text; a string with no lowercase
-has ink standing entirely above that band, so the box centres correctly
-and the ink sits high. Measured on a bar-tier button with a lead icon:
-"PDF" landed 2.5px high on mono and 3.5px on sans, and the cap band
-brought both inside half a pixel.
-A PROP because nothing can infer it. `text-transform: uppercase` is
-detectable and is not the same question — a label that is literally
-typed "PDF" carries no transform — and a snippet's text cannot be read
-before it renders. The caller is the only one who knows.
-Named for the CONTENT rather than the band: a consumer knows their label
-is an initialism and should not have to learn which typographic box that
-implies. Same reason Badge and Chip reach for era-token-ink by default —
-a pill holds a token, so it is caps-shaped by construction.
+| `caps?` | `boolean` | `false` | Trim this label to the CAP band instead of the x-height band — for a
+label whose ink runs cap-to-baseline: "PDF", "CSV", "OK", "API".
+THE NAME SAYS CAPS AND THE MECHANISM IS DESCENDERS. Worth knowing before
+you reach for it, because it decides where it helps. A controlled A/B on
+one real button — same element, same classes, only the STRING changing —
+says case is not the variable at all:
+  Save   asc 9  desc 0   ink 1.28px high
+  SAVE   asc 9  desc 0   ink 1.28px high   ← identical to "Save"
+  Savg   asc 9  desc 3   ink 0.22px low
+  savg   asc 7  desc 3   ink 1.22px low
+The ex band runs x-height to baseline, so ink above the x-height pulls
+the visual centre up and ink below the baseline pushes it back down;
+(xh − asc + desc)/2 predicts every row within 0.3px. A caps string is
+simply one that always has an ascender and never a descender, which is
+why the cap band boxes it exactly. "Save" has the same offset and this
+prop would fix it too. Measured by signalnine.org and reproduced here.
+WHAT IT COSTS, and why it is not the default. A fixed band gives every
+label the SAME baseline whatever it contains — measured spread across
+Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px. Changing one
+label's band moves that label alone: in a Bar holding bold/italic/PDF/
+publish, the caps label sits 1.06px below the other three. So this trades
+a uniform offset the eye cannot see for a local misalignment it can, and
+it is the right trade only when the label has no neighbour to align with
+— a lone action, a label paired with an icon (the reported case, where
+the comparison is against an optically-centred glyph rather than against
+other text). Beside other labels in a bar, prefer leaving it off.
+A PROP because nothing can infer it: `text-transform: uppercase` is a
+different question (a label typed "PDF" carries no transform), and a
+snippet's text cannot be read before it renders.
 Only reaches the label when `lead`/`trail` give it its own box. Without
 one the label is an anonymous flex item that no selector can address,
 which is the whole reason those snippets exist. |

package/dist/generated-docs/manifest.json

@@ -52,7 +52,7 @@
       "slug": "utilities",
       "title": "Utilities",
       "summary": "The CSS classes era ships alongside the components — links, ink-centred text, shimmer, hidden scrollbars.",
-      "tokenEstimate": 12608,
+      "tokenEstimate": 13037,
       "sections": [
         "Overview",
         "era-interactive",
@@ -207,7 +207,7 @@
       "slug": "button",
       "title": "Button",
       "summary": "A flexible button or link element.",
-      "tokenEstimate": 860,
+      "tokenEstimate": 1070,
       "sections": [
         "Import",
         "Props",
@@ -1095,7 +1095,7 @@
       ],
       "file": "index.css",
       "useCase": "on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.",
-      "description": "The EDITABLE counterpart of era-text-trim — for native <input>s, which the\ntrim is forbidden on (it collapses the UA's inner editor box and slices the\nglyphs; see typography/collapsed-text-trim).\n\nWithout help, a tier-height input centres its text by FONT BOX, and the ui\nstacks' font box is deeply asymmetric: ascent ≈1.07em against descent\n≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em\nLOW — so a field's text sat visibly below the trimmed label beside it.\n\nThe value is OPTICAL, not the derivation's: pure x-band centring computes\nto ~0.23em of padding, but pixel-measured against real Title-Case text it\nover-lifts — the eye weighs the cap-to-baseline mass, which x-band\ncentring parks ~2px high (caps 2.75px off the top against 5.7px of air\nunder the baseline, measured at dense). 0.08em splits the difference\nbetween the x-band ideal and the cap-band ideal, landing caps ~3.7px in an\n18px field with ~4.7px under the baseline — the reading where neither\nband's partisans win and neither complains.\n\nThe lift is padding, not a translateY: an icon-less Input paints the field\nchrome itself, and a transform would drag the field along with the ink.\npadding-bottom shrinks the content box from below, and a single-line input\nre-centres its line box in what remains — the ink rises by exactly half the\npadding, the chrome doesn't move, and the caret and selection follow the\ntext. In em on purpose: the correction is a fraction of the type, so it\nholds across every density and text size with one value.\n\nWHEN SOMEONE REPORTS A CORRECTLY-CENTRED FIELD AS \"TOO HIGH\", check the\nSTRING before the geometry. A placeholder like \"Filter…\" has no descender and\nno cap, so its ink occupies only the x-height band — and a box that centres\nthat band exactly still reads high, because the eye centres on the mass it\ncan see and expects the space a descender would have filled. Measured at the\npill tier on the shipped mono stack, \"Filter…\" sits within half a pixel of\ncentre while looking a little high; the pill suite documents the same effect\nfrom the other side (see OFF_BAND_LOW in ink-centering.spec.ts, where \"soon\"\ncannot be symmetric and is bounded by sign instead of magnitude).\n\nThat is not a licence to ignore the report — era-ink-center IS wrong by\n1.5–2px on the sans and serif stacks (pinned in FIELD_KNOWN_SKEW) — only a\nreason to measure the ink before touching the constant.",
+      "description": "The EDITABLE counterpart of era-text-trim — for native <input>s, which the\ntrim is forbidden on (it collapses the UA's inner editor box and slices the\nglyphs; see typography/collapsed-text-trim).\n\nWithout help, a tier-height input centres its text by FONT BOX, and the ui\nstacks' font box is deeply asymmetric: ascent ≈1.07em against descent\n≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em\nLOW — so a field's text sat visibly below the trimmed label beside it.\n\nThe value is OPTICAL, not the derivation's: pure x-band centring computes\nto ~0.23em of padding, but pixel-measured against real Title-Case text it\nover-lifts — the eye weighs the cap-to-baseline mass, which x-band\ncentring parks ~2px high (caps 2.75px off the top against 5.7px of air\nunder the baseline, measured at dense; the general form of that offset,\nand why era-label-ink's note about \"System\" is not a contradiction of it,\nis derived at era-label-ink below). 0.08em splits the difference\nbetween the x-band ideal and the cap-band ideal, landing caps ~3.7px in an\n18px field with ~4.7px under the baseline — the reading where neither\nband's partisans win and neither complains.\n\nThe lift is padding, not a translateY: an icon-less Input paints the field\nchrome itself, and a transform would drag the field along with the ink.\npadding-bottom shrinks the content box from below, and a single-line input\nre-centres its line box in what remains — the ink rises by exactly half the\npadding, the chrome doesn't move, and the caret and selection follow the\ntext. In em on purpose: the correction is a fraction of the type, so it\nholds across every density and text size with one value.\n\nWHEN SOMEONE REPORTS A CORRECTLY-CENTRED FIELD AS \"TOO HIGH\", check the\nSTRING before the geometry. A placeholder like \"Filter…\" has no descender and\nno cap, so its ink occupies only the x-height band — and a box that centres\nthat band exactly still reads high, because the eye centres on the mass it\ncan see and expects the space a descender would have filled. Measured at the\npill tier on the shipped mono stack, \"Filter…\" sits within half a pixel of\ncentre while looking a little high; the pill suite documents the same effect\nfrom the other side (see OFF_BAND_LOW in ink-centering.spec.ts, where \"soon\"\ncannot be symmetric and is bounded by sign instead of magnitude).\n\nThat is not a licence to ignore the report — era-ink-center IS wrong by\n1.5–2px on the sans and serif stacks (pinned in FIELD_KNOWN_SKEW) — only a\nreason to measure the ink before touching the constant.",
       "css": "@utility era-ink-center {\n\tpadding-bottom: 0.08em;\n}"
     },
     {
@@ -1115,7 +1115,7 @@
       ],
       "file": "index.css",
       "useCase": "the ink centring for a fixed-height control holding ONE line of sentence-case text and no icon — a menu item, a nav trigger, a button label. Never alongside `truncate` (the trimmed box becomes the clip).",
-      "description": "LABEL INK — era-token-ink's mixed-case sibling, and the general answer to\n\"this fixed-height control holds one line of text\".\n\nSame mechanism, same reason: `text-box-trim` needs a BLOCK box, so the row\nbecomes one and `align-content` (block-container alignment) does the\ncentring. What differs is the band and the alignment, because the content\nclass differs — a label is sentence case, so the x-height band is the visual\nmass to centre (cap-band reads low on \"System\"), and it is laid out against\nthe row's padding rather than centred in it.\n\nWHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare\ntext is an ANONYMOUS flex item — a box no selector reaches and no\nnon-inherited property touches. So `era-text-trim` on a flex row is inert,\ncontributing only its `line-height: 1`, and the ink falls back to line-box\ncentring by font metrics. era-token-ink already fixed that for centred\ntokens; this fixes it for everything else.\n\nTHE ICON CASE IS NOT SOLVED, and cannot be from CSS: an icon beside the text\nneeds the box to stay flex, which re-creates the anonymous item. A component\nwhose children are an opaque slot therefore guards it —\n`not-has-[svg]:era-label-ink` — and ink-centres the text-only case while\nleaving the icon case on line-box centring. Splitting icon and label into\nseparate slots is what would close it; typography/inert-trim reports every\nsite still on the fallback.",
+      "description": "LABEL INK — era-token-ink's mixed-case sibling, and the general answer to\n\"this fixed-height control holds one line of text\".\n\nSame mechanism, same reason: `text-box-trim` needs a BLOCK box, so the row\nbecomes one and `align-content` (block-container alignment) does the\ncentring. What differs is the band and the alignment, because the content\nclass differs — a label is sentence case, so the x-height band is the visual\nmass to centre (cap-band reads low on \"System\"), and it is laid out against\nthe row's padding rather than centred in it.\n\nTHAT PARENTHESIS AND era-ink-center's \"x-band centring parks ~2px high\" READ\nAS A CONTRADICTION AND ARE NOT. Both are true, of their own example string,\nand each was generalised one step too far. Under an ex band the ink offset is\n\n    (xh − ascent + descent) / 2\n\nwhich predicts a controlled A/B — one real button, one class set, only the\nSTRING changing — within 0.3px:\n\n    Save  asc 9 desc 0   1.28px high     SAVE  asc 9 desc 0   1.28px high\n    Savg  asc 9 desc 3   0.22px low      savg  asc 7 desc 3   1.22px low\n\n\"System\" has a descender and reads low under the cap band; \"Save\" has none\nand reads high under the ex band. Case is not the variable — \"Save\" and\n\"SAVE\" are identical to the hundredth of a pixel. No fixed band centres both\na descender-less and a descender-bearing label, because they differ by ~1.5px\nin the same box.\n\nWHICH IS WHY THE BAND IS FIXED ANYWAY, and this is the part that decides it.\nA band gives every label the SAME baseline whatever it spells — measured\nspread across Save/Savg/save/savg/SAVE/PDF/Cancel/\"Copy page\" is 0.00px —\nwhile ink-extent centring would move each label independently and leave a bar\nof buttons visibly ragged. A uniform offset the eye cannot see beats a local\nmisalignment it can. So the offset is accepted, not corrected, and the only\nescape is per-label and opt-in (Button's `caps`), which buys optical centring\nfor a lone label at the cost of ~1.06px against its neighbours.\n\nMeasured by signalnine.org and reproduced here; see label-band.spec.ts, which\npins both the 0.00px spread and the cost of breaking it.\n\nWHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare\ntext is an ANONYMOUS flex item — a box no selector reaches and no\nnon-inherited property touches. So `era-text-trim` on a flex row is inert,\ncontributing only its `line-height: 1`, and the ink falls back to line-box\ncentring by font metrics. era-token-ink already fixed that for centred\ntokens; this fixes it for everything else.\n\nTHE ICON CASE IS NOT SOLVED, and cannot be from CSS: an icon beside the text\nneeds the box to stay flex, which re-creates the anonymous item. A component\nwhose children are an opaque slot therefore guards it —\n`not-has-[svg]:era-label-ink` — and ink-centres the text-only case while\nleaving the icon case on line-box centring. Splitting icon and label into\nseparate slots is what would close it; typography/inert-trim reports every\nsite still on the fallback.",
       "css": "@utility era-label-ink {\n\tdisplay: block;\n\talign-content: center;\n\tline-height: 1;\n\ttext-box: trim-both ex alphabetic;\n}"
     },
     {

package/dist/generated-docs/utilities.json

@@ -67,7 +67,7 @@
       ],
       "file": "index.css",
       "useCase": "on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.",
-      "description": "The EDITABLE counterpart of era-text-trim — for native <input>s, which the\ntrim is forbidden on (it collapses the UA's inner editor box and slices the\nglyphs; see typography/collapsed-text-trim).\n\nWithout help, a tier-height input centres its text by FONT BOX, and the ui\nstacks' font box is deeply asymmetric: ascent ≈1.07em against descent\n≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em\nLOW — so a field's text sat visibly below the trimmed label beside it.\n\nThe value is OPTICAL, not the derivation's: pure x-band centring computes\nto ~0.23em of padding, but pixel-measured against real Title-Case text it\nover-lifts — the eye weighs the cap-to-baseline mass, which x-band\ncentring parks ~2px high (caps 2.75px off the top against 5.7px of air\nunder the baseline, measured at dense). 0.08em splits the difference\nbetween the x-band ideal and the cap-band ideal, landing caps ~3.7px in an\n18px field with ~4.7px under the baseline — the reading where neither\nband's partisans win and neither complains.\n\nThe lift is padding, not a translateY: an icon-less Input paints the field\nchrome itself, and a transform would drag the field along with the ink.\npadding-bottom shrinks the content box from below, and a single-line input\nre-centres its line box in what remains — the ink rises by exactly half the\npadding, the chrome doesn't move, and the caret and selection follow the\ntext. In em on purpose: the correction is a fraction of the type, so it\nholds across every density and text size with one value.\n\nWHEN SOMEONE REPORTS A CORRECTLY-CENTRED FIELD AS \"TOO HIGH\", check the\nSTRING before the geometry. A placeholder like \"Filter…\" has no descender and\nno cap, so its ink occupies only the x-height band — and a box that centres\nthat band exactly still reads high, because the eye centres on the mass it\ncan see and expects the space a descender would have filled. Measured at the\npill tier on the shipped mono stack, \"Filter…\" sits within half a pixel of\ncentre while looking a little high; the pill suite documents the same effect\nfrom the other side (see OFF_BAND_LOW in ink-centering.spec.ts, where \"soon\"\ncannot be symmetric and is bounded by sign instead of magnitude).\n\nThat is not a licence to ignore the report — era-ink-center IS wrong by\n1.5–2px on the sans and serif stacks (pinned in FIELD_KNOWN_SKEW) — only a\nreason to measure the ink before touching the constant.",
+      "description": "The EDITABLE counterpart of era-text-trim — for native <input>s, which the\ntrim is forbidden on (it collapses the UA's inner editor box and slices the\nglyphs; see typography/collapsed-text-trim).\n\nWithout help, a tier-height input centres its text by FONT BOX, and the ui\nstacks' font box is deeply asymmetric: ascent ≈1.07em against descent\n≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em\nLOW — so a field's text sat visibly below the trimmed label beside it.\n\nThe value is OPTICAL, not the derivation's: pure x-band centring computes\nto ~0.23em of padding, but pixel-measured against real Title-Case text it\nover-lifts — the eye weighs the cap-to-baseline mass, which x-band\ncentring parks ~2px high (caps 2.75px off the top against 5.7px of air\nunder the baseline, measured at dense; the general form of that offset,\nand why era-label-ink's note about \"System\" is not a contradiction of it,\nis derived at era-label-ink below). 0.08em splits the difference\nbetween the x-band ideal and the cap-band ideal, landing caps ~3.7px in an\n18px field with ~4.7px under the baseline — the reading where neither\nband's partisans win and neither complains.\n\nThe lift is padding, not a translateY: an icon-less Input paints the field\nchrome itself, and a transform would drag the field along with the ink.\npadding-bottom shrinks the content box from below, and a single-line input\nre-centres its line box in what remains — the ink rises by exactly half the\npadding, the chrome doesn't move, and the caret and selection follow the\ntext. In em on purpose: the correction is a fraction of the type, so it\nholds across every density and text size with one value.\n\nWHEN SOMEONE REPORTS A CORRECTLY-CENTRED FIELD AS \"TOO HIGH\", check the\nSTRING before the geometry. A placeholder like \"Filter…\" has no descender and\nno cap, so its ink occupies only the x-height band — and a box that centres\nthat band exactly still reads high, because the eye centres on the mass it\ncan see and expects the space a descender would have filled. Measured at the\npill tier on the shipped mono stack, \"Filter…\" sits within half a pixel of\ncentre while looking a little high; the pill suite documents the same effect\nfrom the other side (see OFF_BAND_LOW in ink-centering.spec.ts, where \"soon\"\ncannot be symmetric and is bounded by sign instead of magnitude).\n\nThat is not a licence to ignore the report — era-ink-center IS wrong by\n1.5–2px on the sans and serif stacks (pinned in FIELD_KNOWN_SKEW) — only a\nreason to measure the ink before touching the constant.",
       "css": "@utility era-ink-center {\n\tpadding-bottom: 0.08em;\n}"
     },
     {
@@ -87,7 +87,7 @@
       ],
       "file": "index.css",
       "useCase": "the ink centring for a fixed-height control holding ONE line of sentence-case text and no icon — a menu item, a nav trigger, a button label. Never alongside `truncate` (the trimmed box becomes the clip).",
-      "description": "LABEL INK — era-token-ink's mixed-case sibling, and the general answer to\n\"this fixed-height control holds one line of text\".\n\nSame mechanism, same reason: `text-box-trim` needs a BLOCK box, so the row\nbecomes one and `align-content` (block-container alignment) does the\ncentring. What differs is the band and the alignment, because the content\nclass differs — a label is sentence case, so the x-height band is the visual\nmass to centre (cap-band reads low on \"System\"), and it is laid out against\nthe row's padding rather than centred in it.\n\nWHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare\ntext is an ANONYMOUS flex item — a box no selector reaches and no\nnon-inherited property touches. So `era-text-trim` on a flex row is inert,\ncontributing only its `line-height: 1`, and the ink falls back to line-box\ncentring by font metrics. era-token-ink already fixed that for centred\ntokens; this fixes it for everything else.\n\nTHE ICON CASE IS NOT SOLVED, and cannot be from CSS: an icon beside the text\nneeds the box to stay flex, which re-creates the anonymous item. A component\nwhose children are an opaque slot therefore guards it —\n`not-has-[svg]:era-label-ink` — and ink-centres the text-only case while\nleaving the icon case on line-box centring. Splitting icon and label into\nseparate slots is what would close it; typography/inert-trim reports every\nsite still on the fallback.",
+      "description": "LABEL INK — era-token-ink's mixed-case sibling, and the general answer to\n\"this fixed-height control holds one line of text\".\n\nSame mechanism, same reason: `text-box-trim` needs a BLOCK box, so the row\nbecomes one and `align-content` (block-container alignment) does the\ncentring. What differs is the band and the alignment, because the content\nclass differs — a label is sentence case, so the x-height band is the visual\nmass to centre (cap-band reads low on \"System\"), and it is laid out against\nthe row's padding rather than centred in it.\n\nTHAT PARENTHESIS AND era-ink-center's \"x-band centring parks ~2px high\" READ\nAS A CONTRADICTION AND ARE NOT. Both are true, of their own example string,\nand each was generalised one step too far. Under an ex band the ink offset is\n\n    (xh − ascent + descent) / 2\n\nwhich predicts a controlled A/B — one real button, one class set, only the\nSTRING changing — within 0.3px:\n\n    Save  asc 9 desc 0   1.28px high     SAVE  asc 9 desc 0   1.28px high\n    Savg  asc 9 desc 3   0.22px low      savg  asc 7 desc 3   1.22px low\n\n\"System\" has a descender and reads low under the cap band; \"Save\" has none\nand reads high under the ex band. Case is not the variable — \"Save\" and\n\"SAVE\" are identical to the hundredth of a pixel. No fixed band centres both\na descender-less and a descender-bearing label, because they differ by ~1.5px\nin the same box.\n\nWHICH IS WHY THE BAND IS FIXED ANYWAY, and this is the part that decides it.\nA band gives every label the SAME baseline whatever it spells — measured\nspread across Save/Savg/save/savg/SAVE/PDF/Cancel/\"Copy page\" is 0.00px —\nwhile ink-extent centring would move each label independently and leave a bar\nof buttons visibly ragged. A uniform offset the eye cannot see beats a local\nmisalignment it can. So the offset is accepted, not corrected, and the only\nescape is per-label and opt-in (Button's `caps`), which buys optical centring\nfor a lone label at the cost of ~1.06px against its neighbours.\n\nMeasured by signalnine.org and reproduced here; see label-band.spec.ts, which\npins both the 0.00px spread and the cost of breaking it.\n\nWHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare\ntext is an ANONYMOUS flex item — a box no selector reaches and no\nnon-inherited property touches. So `era-text-trim` on a flex row is inert,\ncontributing only its `line-height: 1`, and the ink falls back to line-box\ncentring by font metrics. era-token-ink already fixed that for centred\ntokens; this fixes it for everything else.\n\nTHE ICON CASE IS NOT SOLVED, and cannot be from CSS: an icon beside the text\nneeds the box to stay flex, which re-creates the anonymous item. A component\nwhose children are an opaque slot therefore guards it —\n`not-has-[svg]:era-label-ink` — and ink-centres the text-only case while\nleaving the icon case on line-box centring. Splitting icon and label into\nseparate slots is what would close it; typography/inert-trim reports every\nsite still on the fallback.",
       "css": "@utility era-label-ink {\n\tdisplay: block;\n\talign-content: center;\n\tline-height: 1;\n\ttext-box: trim-both ex alphabetic;\n}"
     },
     {

package/dist/generated-docs/utilities.md

@@ -291,7 +291,9 @@ The value is OPTICAL, not the derivation's: pure x-band centring computes
 to ~0.23em of padding, but pixel-measured against real Title-Case text it
 over-lifts — the eye weighs the cap-to-baseline mass, which x-band
 centring parks ~2px high (caps 2.75px off the top against 5.7px of air
-under the baseline, measured at dense). 0.08em splits the difference
+under the baseline, measured at dense; the general form of that offset,
+and why era-label-ink's note about "System" is not a contradiction of it,
+is derived at era-label-ink below). 0.08em splits the difference
 between the x-band ideal and the cap-band ideal, landing caps ~3.7px in an
 18px field with ~4.7px under the baseline — the reading where neither
 band's partisans win and neither complains.
@@ -383,6 +385,36 @@ class differs — a label is sentence case, so the x-height band is the visual
 mass to centre (cap-band reads low on "System"), and it is laid out against
 the row's padding rather than centred in it.
 
+THAT PARENTHESIS AND era-ink-center's "x-band centring parks ~2px high" READ
+AS A CONTRADICTION AND ARE NOT. Both are true, of their own example string,
+and each was generalised one step too far. Under an ex band the ink offset is
+
+    (xh − ascent + descent) / 2
+
+which predicts a controlled A/B — one real button, one class set, only the
+STRING changing — within 0.3px:
+
+    Save  asc 9 desc 0   1.28px high     SAVE  asc 9 desc 0   1.28px high
+    Savg  asc 9 desc 3   0.22px low      savg  asc 7 desc 3   1.22px low
+
+"System" has a descender and reads low under the cap band; "Save" has none
+and reads high under the ex band. Case is not the variable — "Save" and
+"SAVE" are identical to the hundredth of a pixel. No fixed band centres both
+a descender-less and a descender-bearing label, because they differ by ~1.5px
+in the same box.
+
+WHICH IS WHY THE BAND IS FIXED ANYWAY, and this is the part that decides it.
+A band gives every label the SAME baseline whatever it spells — measured
+spread across Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px —
+while ink-extent centring would move each label independently and leave a bar
+of buttons visibly ragged. A uniform offset the eye cannot see beats a local
+misalignment it can. So the offset is accepted, not corrected, and the only
+escape is per-label and opt-in (Button's `caps`), which buys optical centring
+for a lone label at the cost of ~1.06px against its neighbours.
+
+Measured by signalnine.org and reproduced here; see label-band.spec.ts, which
+pins both the 0.00px spread and the cost of breaking it.
+
 WHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare
 text is an ANONYMOUS flex item — a box no selector reaches and no
 non-inherited property touches. So `era-text-trim` on a flex row is inert,

package/dist/styles/index.css

@@ -295,7 +295,9 @@
  * to ~0.23em of padding, but pixel-measured against real Title-Case text it
  * over-lifts — the eye weighs the cap-to-baseline mass, which x-band
  * centring parks ~2px high (caps 2.75px off the top against 5.7px of air
- * under the baseline, measured at dense). 0.08em splits the difference
+ * under the baseline, measured at dense; the general form of that offset,
+ * and why era-label-ink's note about "System" is not a contradiction of it,
+ * is derived at era-label-ink below). 0.08em splits the difference
  * between the x-band ideal and the cap-band ideal, landing caps ~3.7px in an
  * 18px field with ~4.7px under the baseline — the reading where neither
  * band's partisans win and neither complains.
@@ -377,6 +379,36 @@
  * mass to centre (cap-band reads low on "System"), and it is laid out against
  * the row's padding rather than centred in it.
  *
+ * THAT PARENTHESIS AND era-ink-center's "x-band centring parks ~2px high" READ
+ * AS A CONTRADICTION AND ARE NOT. Both are true, of their own example string,
+ * and each was generalised one step too far. Under an ex band the ink offset is
+ *
+ *     (xh − ascent + descent) / 2
+ *
+ * which predicts a controlled A/B — one real button, one class set, only the
+ * STRING changing — within 0.3px:
+ *
+ *     Save  asc 9 desc 0   1.28px high     SAVE  asc 9 desc 0   1.28px high
+ *     Savg  asc 9 desc 3   0.22px low      savg  asc 7 desc 3   1.22px low
+ *
+ * "System" has a descender and reads low under the cap band; "Save" has none
+ * and reads high under the ex band. Case is not the variable — "Save" and
+ * "SAVE" are identical to the hundredth of a pixel. No fixed band centres both
+ * a descender-less and a descender-bearing label, because they differ by ~1.5px
+ * in the same box.
+ *
+ * WHICH IS WHY THE BAND IS FIXED ANYWAY, and this is the part that decides it.
+ * A band gives every label the SAME baseline whatever it spells — measured
+ * spread across Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px —
+ * while ink-extent centring would move each label independently and leave a bar
+ * of buttons visibly ragged. A uniform offset the eye cannot see beats a local
+ * misalignment it can. So the offset is accepted, not corrected, and the only
+ * escape is per-label and opt-in (Button's `caps`), which buys optical centring
+ * for a lone label at the cost of ~1.06px against its neighbours.
+ *
+ * Measured by signalnine.org and reproduced here; see label-band.spec.ts, which
+ * pins both the 0.00px spread and the cost of breaking it.
+ *
  * WHY IT EXISTS AT ALL: era's controls are flex, and a flex container's bare
  * text is an ANONYMOUS flex item — a box no selector reaches and no
  * non-inherited property touches. So `era-text-trim` on a flex row is inert,

package/dist/ui/button/button.svelte

@@ -42,25 +42,40 @@
 		/** Icon rendered AFTER the label, outside it. Same reason as `lead`. */
 		trail?: Snippet;
 		/**
-		 * The label is ALL CAPS or an initialism — "PDF", "CSV", "OK", "API".
+		 * Trim this label to the CAP band instead of the x-height band — for a
+		 * label whose ink runs cap-to-baseline: "PDF", "CSV", "OK", "API".
 		 *
-		 * Trims the label to the cap band instead of the x-height band. The
-		 * default (`era-text-trim`, ex/alphabetic) centres the x-height band,
-		 * which is the visual mass of mixed-case text; a string with no lowercase
-		 * has ink standing entirely above that band, so the box centres correctly
-		 * and the ink sits high. Measured on a bar-tier button with a lead icon:
-		 * "PDF" landed 2.5px high on mono and 3.5px on sans, and the cap band
-		 * brought both inside half a pixel.
+		 * THE NAME SAYS CAPS AND THE MECHANISM IS DESCENDERS. Worth knowing before
+		 * you reach for it, because it decides where it helps. A controlled A/B on
+		 * one real button — same element, same classes, only the STRING changing —
+		 * says case is not the variable at all:
 		 *
-		 * A PROP because nothing can infer it. `text-transform: uppercase` is
-		 * detectable and is not the same question — a label that is literally
-		 * typed "PDF" carries no transform — and a snippet's text cannot be read
-		 * before it renders. The caller is the only one who knows.
+		 *   Save   asc 9  desc 0   ink 1.28px high
+		 *   SAVE   asc 9  desc 0   ink 1.28px high   ← identical to "Save"
+		 *   Savg   asc 9  desc 3   ink 0.22px low
+		 *   savg   asc 7  desc 3   ink 1.22px low
 		 *
-		 * Named for the CONTENT rather than the band: a consumer knows their label
-		 * is an initialism and should not have to learn which typographic box that
-		 * implies. Same reason Badge and Chip reach for era-token-ink by default —
-		 * a pill holds a token, so it is caps-shaped by construction.
+		 * The ex band runs x-height to baseline, so ink above the x-height pulls
+		 * the visual centre up and ink below the baseline pushes it back down;
+		 * (xh − asc + desc)/2 predicts every row within 0.3px. A caps string is
+		 * simply one that always has an ascender and never a descender, which is
+		 * why the cap band boxes it exactly. "Save" has the same offset and this
+		 * prop would fix it too. Measured by signalnine.org and reproduced here.
+		 *
+		 * WHAT IT COSTS, and why it is not the default. A fixed band gives every
+		 * label the SAME baseline whatever it contains — measured spread across
+		 * Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px. Changing one
+		 * label's band moves that label alone: in a Bar holding bold/italic/PDF/
+		 * publish, the caps label sits 1.06px below the other three. So this trades
+		 * a uniform offset the eye cannot see for a local misalignment it can, and
+		 * it is the right trade only when the label has no neighbour to align with
+		 * — a lone action, a label paired with an icon (the reported case, where
+		 * the comparison is against an optically-centred glyph rather than against
+		 * other text). Beside other labels in a bar, prefer leaving it off.
+		 *
+		 * A PROP because nothing can infer it: `text-transform: uppercase` is a
+		 * different question (a label typed "PDF" carries no transform), and a
+		 * snippet's text cannot be read before it renders.
 		 *
 		 * Only reaches the label when `lead`/`trail` give it its own box. Without
 		 * one the label is an anonymous flex item that no selector can address,

package/dist/ui/button/button.svelte.d.ts

@@ -21,25 +21,40 @@ type $$ComponentProps = Button.RootProps & {
     /** Icon rendered AFTER the label, outside it. Same reason as `lead`. */
     trail?: Snippet;
     /**
-     * The label is ALL CAPS or an initialism — "PDF", "CSV", "OK", "API".
+     * Trim this label to the CAP band instead of the x-height band — for a
+     * label whose ink runs cap-to-baseline: "PDF", "CSV", "OK", "API".
      *
-     * Trims the label to the cap band instead of the x-height band. The
-     * default (`era-text-trim`, ex/alphabetic) centres the x-height band,
-     * which is the visual mass of mixed-case text; a string with no lowercase
-     * has ink standing entirely above that band, so the box centres correctly
-     * and the ink sits high. Measured on a bar-tier button with a lead icon:
-     * "PDF" landed 2.5px high on mono and 3.5px on sans, and the cap band
-     * brought both inside half a pixel.
+     * THE NAME SAYS CAPS AND THE MECHANISM IS DESCENDERS. Worth knowing before
+     * you reach for it, because it decides where it helps. A controlled A/B on
+     * one real button — same element, same classes, only the STRING changing —
+     * says case is not the variable at all:
      *
-     * A PROP because nothing can infer it. `text-transform: uppercase` is
-     * detectable and is not the same question — a label that is literally
-     * typed "PDF" carries no transform — and a snippet's text cannot be read
-     * before it renders. The caller is the only one who knows.
+     *   Save   asc 9  desc 0   ink 1.28px high
+     *   SAVE   asc 9  desc 0   ink 1.28px high   ← identical to "Save"
+     *   Savg   asc 9  desc 3   ink 0.22px low
+     *   savg   asc 7  desc 3   ink 1.22px low
      *
-     * Named for the CONTENT rather than the band: a consumer knows their label
-     * is an initialism and should not have to learn which typographic box that
-     * implies. Same reason Badge and Chip reach for era-token-ink by default —
-     * a pill holds a token, so it is caps-shaped by construction.
+     * The ex band runs x-height to baseline, so ink above the x-height pulls
+     * the visual centre up and ink below the baseline pushes it back down;
+     * (xh − asc + desc)/2 predicts every row within 0.3px. A caps string is
+     * simply one that always has an ascender and never a descender, which is
+     * why the cap band boxes it exactly. "Save" has the same offset and this
+     * prop would fix it too. Measured by signalnine.org and reproduced here.
+     *
+     * WHAT IT COSTS, and why it is not the default. A fixed band gives every
+     * label the SAME baseline whatever it contains — measured spread across
+     * Save/Savg/save/savg/SAVE/PDF/Cancel/"Copy page" is 0.00px. Changing one
+     * label's band moves that label alone: in a Bar holding bold/italic/PDF/
+     * publish, the caps label sits 1.06px below the other three. So this trades
+     * a uniform offset the eye cannot see for a local misalignment it can, and
+     * it is the right trade only when the label has no neighbour to align with
+     * — a lone action, a label paired with an icon (the reported case, where
+     * the comparison is against an optically-centred glyph rather than against
+     * other text). Beside other labels in a bar, prefer leaving it off.
+     *
+     * A PROP because nothing can infer it: `text-transform: uppercase` is a
+     * different question (a label typed "PDF" carries no transform), and a
+     * snippet's text cannot be read before it renders.
      *
      * Only reaches the label when `lead`/`trail` give it its own box. Without
      * one the label is an anonymous flex item that no selector can address,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@signal9/era-ui",
-	"version": "30.1.0",
+	"version": "30.1.1",
 	"scripts": {
 		"dev": "vite dev --host",
 		"build": "vite build && npm run prepack",