@junoput01/junoui 0.6.0 → 0.7.0

package/docs/ios-pwa.md

@@ -0,0 +1,273 @@
+# junoui on iOS, and in a Home-Screen web app
+
+The bounded claim, in one page: **what you get for free, what you must supply,
+and what junoui explicitly does not do.** Read it before integrating; the pages
+it links carry the detail and the derivations.
+
+Every line here carries a number or a source. Where a claim has neither, it is
+not on this page.
+
+**What the numbers were measured against.** junoui **v0.5.0**; the CSS feature
+audit is against the built `dist/css/juno.css` on **2026-08-15**; the device
+readings are an **iPhone 16 Pro (402×874 pt), iOS 18.7 / Safari 26.6**; the
+touch-ergonomics assertions run in Playwright at **390×844** with `hasTouch` +
+`isMobile`. One device, one build. Nothing here is extrapolated to iPads or to
+Android.
+
+---
+
+## The floor
+
+|                                                       | Safari / iOS | What that line means                                |
+| ----------------------------------------------------- | ------------ | --------------------------------------------------- |
+| **Hard floor** — below this, things break             | **17.0**     | the Popover API. Overlays stop being overlays       |
+| **Supported floor** — put this in your support matrix | **17.5**     | everything works; entry animations missing below it |
+| **Full fidelity**                                     | **26.0**     | CSS anchor positioning                              |
+
+**The interesting gap is 17.5 → 26.0, not 16.x → 17.5.** Between 17.5 and 26.0
+menus, popovers and tooltips open, close and light-dismiss correctly — and land
+at their **static position** instead of beside their trigger, because
+`position-area` / `position-try-fallbacks` / `position-anchor` (**10 uses**) are
+Safari 26. The surface works; it is in the wrong place. That is a real visual
+defect and it is easy to mistake for a break.
+
+Below **17.0** the Popover API is absent and junoui **hides** `.juno-menu`,
+`.juno-popover` and the top-layer tooltip behind
+`@supports not selector(:popover-open)`. That is not a fix. Unguarded, the UA
+rule that hides a closed popover does not exist either, so a **256–280 px
+invisible fixed panel** sits at its static position swallowing taps on whatever
+it covers. junoui trades that for "the panel is absent" — absent beats
+invisibly-present — and your app branches on
+`CSS.supports('selector(:popover-open)')`.
+
+Full per-feature audit, with the degrade-or-break verdict for all 15 features:
+[browser-support.md](./browser-support.md).
+
+---
+
+## What you get for free
+
+### Touch ergonomics
+
+- **44 px tap targets on coarse pointers.** `--juno-size-tap-min` is **24 px**
+  (the WCAG 2.2 **2.5.8** AA floor) and flips to `--juno-size-tap-comfortable` =
+  **44 px** under `@media (pointer: coarse)`. Everything that sizes off it
+  inherits the promotion: `.juno-btn` (`min-height`), `.juno-input` and
+  `textarea` (`min-block-size`, the latter at 3×), `.juno-menu__item`,
+  `.juno-navbar__actions > *`, and `.juno-modal__close` on both axes.
+  **One exception, stated so you can size around it:** `.juno-pagination`'s
+  items take the promotion on the **inline** axis only — their `block-size` is a
+  fixed `--juno-space-32`, so they are 44 × 32 on touch. That clears the 24 px
+  AA floor and not the 44 px comfortable one (ticket 20260815-040).
+- **Verified numerically, not by screenshot.**
+  `test/visual/tap-targets.spec.mjs` asserts the computed `min-height` **and**
+  the rendered box under **both** Playwright projects — `44px` under
+  `chromium-coarse`, `24px` under `chromium`. Keying the expectation by project
+  is what makes it a check rather than a baseline: if the coarse project ever
+  stops emulating touch it starts producing desktop numbers and **fails**
+  instead of quietly re-recording them.
+- **A 16 px floor on text entry**, so iOS Safari does not zoom the page onto a
+  focused field: `.juno-input { font-size: max(16px, …) }`. Two caveats, both
+  load-bearing. **No primary WebKit or Apple source states the zoom behaviour** —
+  it is empirical, and the mitigation is kept because it is harmless, not
+  because it is documented. And it **never applied on any touch device until
+  2026-08-15**: the rule sat in `base.css`'s `@media (pointer: coarse)` block,
+  where a media query adds no specificity, so `input.css`'s own `.juno-input`
+  font-size beat it on source order. The numeric check above is what found it.
+- **The UA tap-highlight square is off** on `.juno-btn`, `.juno-dock__item`,
+  `.juno-pillbar__item`, `.juno-tabs__tab`, `.juno-list__item`,
+  `.juno-menu__item`. Community convention — **no Apple source** — so it is
+  listed as a default, not a conformance claim.
+
+### Safe areas
+
+`env(safe-area-inset-*)` is used **21 times across 8 files**, and the rule for
+which arithmetic applies is not one rule but **three buckets**:
+
+| Bucket                                         | Arithmetic                                       | Why                                                          |
+| ---------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
+| Padding on a surface that reaches the edge     | `max(baseline, env(…))` — the inset **replaces** | the inset's job is to clear the cutout, not to stack         |
+| A floating element positioned **off** the edge | `calc(baseline + env(…))` — **additive**         | `max()` would park the pill flush against the home indicator |
+| The clearance tokens                           | `calc(height + … + env(…))` — **additive**       | content must clear the control's height _and_ the inset      |
+
+Get this wrong in either direction and nothing errors. The derivation, with the
+WebKit source: [ios-conformance.md](./ios-conformance.md#max-vs-addition--the-rule).
+
+**All of it is inert until you ship `viewport-fit=cover`** — WebKit reports
+every inset as `0` until then, and `contain` does not opt out. See
+[what you must supply](#what-you-must-supply).
+
+### Floating-nav clearance, derived rather than constant
+
+A page under a floating dock or pillbar reserves room at its foot with
+`padding-block-end: var(--juno-dock-clearance)`. Those tokens are **computed
+from the bar's own parts**, not hardcoded:
+
+```
+--juno-dock-h     = tap-comfortable + 4×space-4 + 2×border-1   = 62px at defaults
+--juno-pillbar-h  = tap-comfortable + 2×space-4 + 2×border-1   = 54px at defaults
+
+--juno-dock-clearance    = dock-h    × scale + 16 + 8 + env(safe-area-inset-bottom)
+--juno-pillbar-clearance = pillbar-h × scale + 16 + 8 + env(safe-area-inset-bottom)
+```
+
+— 86 px and 78 px plus the inset, at default tokens. **Why derived matters:**
+the old constants (`space-72 + space-20 + env()`) promised in a code comment to
+"stay correct when the dock geometry changes" and could not. junoui explicitly
+invites you to re-parameterise the bubble via `--juno-size-tap-comfortable`, and
+past a **58 px** bubble the constant reserved **less** than the pill's own
+height plus its margin — content hid under the dock, silently, on exactly the
+consumers who took the invitation (ticket 20260815-026).
+
+`--juno-dock-clearance-scale` (default `1`) is the knob for a bar that **shrinks
+while scrolling**: set it to the shrunken ratio so the reservation is made at
+the small size. Reserving against a live height means relayouting content under
+a finger that has already stopped moving.
+
+### The Home-Screen standalone unlock
+
+In `display-mode: standalone`, iOS sizes the window from the document's
+**resting** scrollability at launch and letterboxes a document that cannot
+scroll by exactly `env(safe-area-inset-top)` — measured **874 − 812 = 62**, a
+black strip at the bottom of the glass on every screen. `base.css` keeps the
+document scrollable behind your fixed shell with an invisible `body::after`
+spacer, behind a **three-condition gate, all required**:
+
+```
+@media (display-mode: standalone)   only installed apps letterbox
+  and (pointer: coarse)             keeps macOS Dock apps out
+@supports (-webkit-touch-callout: none)   iOS/iPadOS WebKit only
+```
+
+**A bundled stylesheet cannot satisfy the obligation this creates** — see
+[what you must supply](#what-you-must-supply). The measurements, the
+four-structure A/B, and the 201 device readings behind it:
+[ios-conformance.md](./ios-conformance.md#home-screen-standalone-the-letterbox-and-why-basecss-unlocks-it).
+
+### Phone-shaped component behaviour
+
+| Behaviour                                                               | Triggered by                                                    |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Modal becomes a bottom sheet — full width, bottom-anchored, `85dvh` cap | `@media (width <= 639.98px)`                                    |
+| Toast stack goes full width at the bottom edge and slides up            | `@media (width <= 639.98px)`                                    |
+| Table stacks into rows                                                  | `@container (max-width: 480px)`                                 |
+| Tab strip scrolls sideways instead of wrapping                          | `overflow: auto hidden` + `overscroll-behavior-inline: contain` |
+
+Note the third row is a **container** query, not a viewport one: it reflows by
+the space the table is in, not by the size of the phone. And the first is
+deliberately _not_ — a modal is always in the top layer, so the screen **is**
+its container.
+
+### Silent-failure guards already paid for
+
+Two defects of this class shipped and were found by looking at a phone, not by
+any tool — both fixed 2026-08-05, both now permanent:
+
+- `-webkit-backdrop-filter` ships beside **all 7** unprefixed
+  `backdrop-filter` declarations (unsupported below Safari 18.0 — every glass
+  surface rendered flat on iOS 17).
+- A `::-webkit-scrollbar { display: none }` companion ships beside **all 3**
+  `scrollbar-width` declarations (unsupported below Safari 18.2 — the
+  scrollable tab strip kept a visible scrollbar on iOS 17 through 18.1).
+
+> Both are 7 and 3 **declarations**, verified in `dist/css/juno.css`. The audit
+> table in [browser-support.md](./browser-support.md) reports 14 and 4 because
+> it counts string occurrences, and `-webkit-backdrop-filter` contains
+> `backdrop-filter` — so each guarded pair is counted twice. Same fact, two
+> units.
+
+And **zero raw `vh`** — grep the bundle and there are none. Full-height surfaces
+use `dvh` (**9 uses**) because `vh == lvh` normatively and a `100vh` box is
+sized as if the toolbar were retracted; the single `lvh` in the bundle is the
+standalone unlock's spacer, which is _supposed_ to overflow. The reasoning, and
+the rule for a component that does not exist yet:
+[ios-conformance.md](./ios-conformance.md#the-rule-for-a-component-that-does-not-exist-yet).
+
+---
+
+## What you must supply
+
+junoui is a stylesheet. Everything below is outside what CSS can reach.
+
+| #   | You ship                                                                                                                   | If you don't                                                                                                  |
+| --- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| 1   | `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`                                 | every safe-area guarantee becomes a no-op, silently; and 1 CSS px stops equalling 1 pt                        |
+| 2   | A standalone declaration — manifest `"display": "standalone"` or `apple-mobile-web-app-capable` — **or a decision not to** | from iOS 26 the **user** grants standalone at add-to-Home-Screen time and junoui's standalone CSS runs anyway |
+| 3   | **An inline copy of the letterbox unlock in `<head>`**, if your shell paints before its CSS bundle                         | iOS samples the document at launch; `juno.css` arrives after, so the app letterboxes with the unlock present  |
+| 4   | Leave `body::after` alone, or reproduce the spacer at the same gate                                                        | the unlock has no spacer and the window letterboxes                                                           |
+| 5   | `overscroll-behavior: contain` on your real scrollers                                                                      | an inner fling chains into the unlock's ghost scroller                                                        |
+| 6   | A popover fallback below Safari 17.0, branched on `CSS.supports('selector(:popover-open)')`                                | overflow navigation is unreachable — junoui hid the panel rather than leave it eating taps                    |
+| 7   | Pinning `inset` on the `toggle` event below Safari 26.0                                                                    | anchored surfaces open at their static position                                                               |
+| 8   | `data-juno-letterboxed` on `<html>`, if you want to react to a letterboxed window                                          | nothing; the flag is opt-in — but invent your own attribute name and your CSS can never move into junoui      |
+
+**#3 is the one that catches people**, because it is silent in both directions:
+miss it and the app letterboxes with a correct stylesheet installed, ship it and
+nothing confirms it worked except a screenshot of the device. Rows 2, 3 and 8
+are specified in full — declarations, status-bar-style semantics, the exact
+letterbox predicate — in
+[the consumer `<head>` contract](./ios-conformance.md#becoming-a-home-screen-web-app-the-consumer-head-contract).
+
+---
+
+## What junoui explicitly does not do
+
+This half is why the page exists. None of the following is planned, partial, or
+"coming to the roadmap" — it is out of scope by design.
+
+**No JS behaviour.** No focus traps, no scroll locking, no gesture or swipe
+handling, no runtime popover positioning, no list virtualization, no state. Every
+component renders with zero JS; what is stateful is the platform's (`<dialog>`,
+`popover`, `<details>`) or yours. junoui does ship two JS entry points —
+`icons/inline` and `icons/install` — and they are **icon-sprite helpers, nothing
+more**.
+
+**No service worker, no offline story, no cache.** No precaching, no purge, no
+versioning, no `skipWaiting` policy. [boot-shell.md](./boot-shell.md) documents
+the five-rung boot pattern including an app-shell service worker — that is a
+**recipe your app implements**, with a reference implementation in another
+repository. junoui ships none of that code.
+
+**No native chrome.** `dist/ios/JunoTokens.swift` is **token values only**. There
+are no UIKit or SwiftUI components. `.juno-dock` and `.juno-navbar` are CSS that
+_looks_ like a bar; they are not the system bar and do not inherit its
+behaviours.
+
+**Nothing about in-app browsers.** SFSafariViewController and WKWebView-based
+in-app browsers (Instagram, Facebook) are a **separate, unfixed path** and
+junoui has tested neither. The one datum on record: Safari 26.0's notes claim a
+fix for `lvh`/`vh` being sized against the small viewport in
+SFSafariViewController, but **WebKit bug 255708 (filed 2023) is still open**, so
+that "Fixed" is stronger than the tracker supports.
+
+**No app-shell assets.** No web app manifest, no Home-Screen icons, no splash
+screens, no install prompt. `src/icons/` is a **UI icon sprite** — the icons
+inside your interface, not the icon on the Home Screen.
+
+**No guarantee below Safari / iOS 17.0**, and the losses compound rather than
+arriving all at once: **16.2** drops `color-mix()` (**28 uses** — every role
+tint, border and shadow built from `var(--juno-role)`, which is the contract
+junoui exists to encode); **16.0** drops `@container`; **15.4** drops `oklch()`
+(**190 uses** — every token value) and `dvh`/`lvh` (**10 uses** — the app shell
+collapses to content height). There is no fallback layer for any of them, and
+none is planned. If you are on iOS 15 you are not using junoui.
+
+**No verified iOS 26 story.** The claim "iOS 26 changed nothing about safe
+areas, viewport-fit, touch behaviour or focus zoom" was **refuted** during
+verification, so junoui's iOS 26 behaviour is _unverified_, not
+_confirmed-safe_. Open leads — `vh` reportedly pinning to `window.outerHeight`,
+three new tab modes yielding different `innerHeight`, iPadOS 26 windowed mode
+reportedly returning nothing for `env(safe-area-inset-*)` — need a physical
+device, not more documentation.
+
+---
+
+## Where the detail lives
+
+| Page                                       | What it settles                                                                            |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| [ios-conformance.md](./ios-conformance.md) | every iOS metric with its source, the folklore named, the letterbox, the `<head>` contract |
+| [browser-support.md](./browser-support.md) | the three floors, all 15 features with degrade-or-break, the two shipped silent failures   |
+| [getting-started.md](./getting-started.md) | the required viewport meta and what depends on it                                          |
+| [accessibility.md](./accessibility.md)     | the WCAG 2.2 criterion behind each target size, and the per-component ARIA contract        |
+| [integration.md](./integration.md)         | import order, the token bridge, and where app-specific things go                           |
+| [boot-shell.md](./boot-shell.md)           | the boot ladder — a pattern to implement, not code junoui ships                            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoput01/junoui",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "junoui — a token-driven design system. Color carries semantic meaning, never decoration: every hue has one assigned role (NOMINAL / ACTIVE / TARGET / CAUTION / WARNING). Ships multi-platform tokens (CSS, SCSS, JS/TS, JSON, Android, iOS, Flutter) plus a framework-agnostic CSS component layer.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,8 @@
     "./flutter": "./dist/flutter/juno_tokens.dart",
     "./icons": "./dist/icons/juno-icons.svg",
     "./subset": "./tools/subset-sprite.mjs",
+    "./testing": "./tools/testing.mjs",
+    "./classes.json": "./dist/classes.json",
     "./icons/inline": "./dist/icons/inline.js",
     "./icons/install": "./dist/icons/install.js",
     "./package.json": "./package.json"
@@ -68,7 +70,8 @@
     "build:tokens": "node style-dictionary.config.mjs",
     "build:icons": "node scripts/build-icons.mjs",
     "build:css": "node scripts/bundle-css.mjs",
-    "build": "npm run build:tokens && npm run build:icons && npm run build:css",
+    "build:classes": "node scripts/build-classes.mjs",
+    "build": "npm run build:tokens && npm run build:icons && npm run build:css && npm run build:classes",
     "gen-docs": "node scripts/gen-docs.mjs",
     "clean": "node -e \"import('node:fs').then(fs=>fs.rmSync('dist',{recursive:true,force:true}))\"",
     "lint:css": "stylelint \"src/css/**/*.css\"",

package/src/css/base.css

@@ -47,9 +47,30 @@
     var(--juno-size-tap-comfortable) + 4 * var(--juno-space-4) + 2 * var(--juno-border-width-1)
   );
   --juno-dock-clearance-scale: 1;
+
+  /* The bar's own offset from the bottom edge — declared ONCE and consumed by
+     both the bar's margin (dock.css) and the clearance below, so the two cannot
+     disagree about where the bar sits.
+
+     That is the whole reason this is a token rather than a literal in each
+     place. junoui's default is additive, per docs/ios-conformance.md: a
+     FLOATING element sits off the edge, so its gap and the inset stack. A
+     consumer whose design wants the bar flush above the home indicator instead
+     writes `max(8px, env(safe-area-inset-bottom, 0px))` here and BOTH the
+     margin and the reservation follow it. Before this token the form was baked
+     into each site separately, so a consumer that changed one silently
+     disagreed with the other — measured at 16px of dead band at inset 0 and
+     24px at inset 34 (20260815-055), and no single --juno-dock-h could
+     reconcile them because one side added the inset and the other maxed it. */
+  --juno-dock-edge-offset: calc(var(--juno-space-16) + env(safe-area-inset-bottom, 0px));
+
+  /* Gap between the bar's top edge and the last row of content. Zero is a
+     legitimate setting: a translucent bar that content is MEANT to scroll under
+     wants overlap, not breathing room. */
+  --juno-dock-clearance-breathing: var(--juno-space-8);
   --juno-dock-clearance: calc(
-    var(--juno-dock-h) * var(--juno-dock-clearance-scale) + var(--juno-space-16) +
-      var(--juno-space-8) + env(safe-area-inset-bottom, 0px)
+    var(--juno-dock-h) * var(--juno-dock-clearance-scale) + var(--juno-dock-edge-offset) +
+      var(--juno-dock-clearance-breathing)
   );
 
   /* The pillbar is the same shape one size down: no bubble, so its height is
@@ -58,8 +79,8 @@
     var(--juno-size-tap-comfortable) + 2 * var(--juno-space-4) + 2 * var(--juno-border-width-1)
   );
   --juno-pillbar-clearance: calc(
-    var(--juno-pillbar-h) * var(--juno-dock-clearance-scale) + var(--juno-space-16) +
-      var(--juno-space-8) + env(safe-area-inset-bottom, 0px)
+    var(--juno-pillbar-h) * var(--juno-dock-clearance-scale) + var(--juno-dock-edge-offset) +
+      var(--juno-dock-clearance-breathing)
   );
 
   /* JS-readable motion contract. CSS-only `prefers-reduced-motion` never reaches
@@ -176,7 +197,7 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
     .juno-dock__item,
     .juno-pillbar__item,
     .juno-tabs__tab,
-    .juno-list__item,
+    .juno-list__row,
     .juno-menu__item
   ) {
     -webkit-tap-highlight-color: transparent;
@@ -201,9 +222,9 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
   .juno-pillbar__item,
   .juno-pillbar__overflow,
   .juno-tabs__tab,
-  .juno-list__item,
+  .juno-list__row,
   .juno-menu__item,
-  .juno-seg__option,
+  .juno-seg__opt,
   .juno-chip,
   .juno-toggle-btn
 ) {

package/src/css/components/button.css

@@ -40,8 +40,10 @@
 .juno-btn--ghost:hover { background: var(--juno-s2); filter: none; }
 
 /* Small — for dense desktop toolbars (40–46px bars) where the default
-   control would not fit. Deliberately under the WCAG tap-min target:
-   keep the default size for touch surfaces. Combines with --ghost + roles. */
+   control would not fit. Combines with --ghost + roles.
+   On a FINE pointer this is 24px: the WCAG 2.2 AA floor (2.5.8) exactly, and
+   no more. On a coarse pointer it promotes to the comfortable target — see
+   below. */
 .juno-btn--sm {
   min-height: var(--juno-space-24);
   font-size: var(--juno-font-size-11);
@@ -50,6 +52,44 @@
   border-radius: var(--juno-radius-3);
 }
 
+/* --sm names a DENSITY, and consumers reach for it as a SEMANTIC. Audited
+   across one app: 40 call sites, nearly all of them `--sm --ghost` meaning
+   "secondary", shipping a 24px target on a phone — and junoui's own showcase
+   does it twice in a navbar action slot. A size modifier should not quietly
+   become a tap-target decision, so on touch it holds the same floor every
+   other control does. Type and padding still shrink: --sm stays a density
+   modifier, it just stops being a touch-target one (20260826-026).
+
+   THE RULE LIVES HERE, not in base.css's (pointer: coarse) block: a media
+   query adds no specificity, so a `.juno-btn--sm` there would lose to this
+   file's own `.juno-btn--sm` later in the bundle. That is not a guess — it is
+   what silently happened to the .juno-input font floor until 20260815-006
+   measured it.
+
+   --dense is the opt-out, and it is deliberately only meaningful ON --sm:
+   a dense touch toolbar is a real thing (a media scrubber, an editor rail),
+   but it is a decision someone has to make by name rather than inherit from a
+   size.
+
+   The two rules below are REDUNDANT ON PURPOSE, and mutation testing is how
+   that became a decision rather than an accident: deleting either one leaves
+   --dense at 24px. The `:not()` excludes a dense button from the promotion, so
+   the pairing below it is dead weight — until the `:not()` names the wrong
+   class, at which point the pairing (also (0,2,0), and later in the file) is
+   the only thing holding the opt-out. Each covers the other's failure, so a
+   single edit to either cannot silently promote a --dense button. Both
+   selectors are (0,2,0) and mutually exclusive in the correct state, so they
+   never race. */
+@media (pointer: coarse) {
+  .juno-btn--sm:not(.juno-btn--dense) {
+    min-height: var(--juno-size-tap-min);
+  }
+
+  .juno-btn--sm.juno-btn--dense {
+    min-height: var(--juno-space-24);
+  }
+}
+
 .juno-btn:disabled {
   background: var(--juno-muted);
   color: var(--juno-label);

package/src/css/components/dock.css

@@ -29,6 +29,55 @@
      media query. */
   --juno-dock-scale: 1;
 
+  /* ── Horizontal budget contract ──────────────────────────────────────
+     Published so a consumer's capacity planner ("how many items fit, and
+     do they still hold a tap target?") reads junoui's real geometry
+     instead of re-deriving it from the numbers in this file. Two
+     consumers had derived it by hand, twice, in prose — and both had
+     drifted: they subtracted 12px of inline padding where the pill
+     actually spends 8, so their per-item width came out ~0.8px low at
+     every viewport (20260826-027).
+
+     --juno-dock-items      the item budget. junoui does not enforce it —
+                            __item is `flex: 1 1 0`, so the layout divides
+                            by however many items are present — it is the
+                            number the DERIVATIONS below are about, and the
+                            consumer sets it to what it renders.
+     --juno-dock-item-inline  the width one item gets. A prediction of what
+                            the flex layout produces, not an input to it;
+                            asserted against the measured box in the test
+                            suite so it cannot drift from the layout.
+     --juno-dock-fit-inline  the narrowest viewport at which every item
+                            still holds --juno-size-tap-comfortable. Use it
+                            in a media query and DROP an item; that is the
+                            answer junoui can give exactly.
+
+     A SCALE floor (44px / the item's width) is deliberately not published:
+     it is a ratio of two lengths, and CSS cannot divide by a length. A
+     consumer that must scale rather than drop compares
+     --juno-dock-item-inline against --juno-size-tap-comfortable itself.
+
+     The three inline terms are declared ONCE here and consumed by both the
+     variants' own margin/padding/border and the sums below, so the budget
+     cannot disagree with the bar it describes — the same reason
+     --juno-dock-edge-offset exists (20260815-055). The base bar is
+     full-bleed with a top-edge border only, so all three are zero; --pill
+     and --float set them. */
+  --juno-dock-items: 5;
+  --juno-dock-margin-inline: 0px;
+  --juno-dock-pad-inline: 0px;
+  --juno-dock-border-inline: 0px;
+  --juno-dock-chrome-inline: calc(
+    2 * (var(--juno-dock-margin-inline) + var(--juno-dock-pad-inline) + var(--juno-dock-border-inline))
+  );
+  --juno-dock-avail: 100vw;
+  --juno-dock-item-inline: calc(
+    (var(--juno-dock-avail) - var(--juno-dock-chrome-inline)) / var(--juno-dock-items)
+  );
+  --juno-dock-fit-inline: calc(
+    var(--juno-dock-items) * var(--juno-size-tap-comfortable) + var(--juno-dock-chrome-inline)
+  );
+
   position: sticky;
   inset-block-end: 0;
   z-index: var(--juno-z-raised);
@@ -123,16 +172,21 @@
 .juno-dock--pill {
   --juno-role: var(--juno-active);
 
+  /* the three inline terms the budget contract sums — see .juno-dock */
+  --juno-dock-margin-inline: var(--juno-space-12);
+  --juno-dock-pad-inline: var(--juno-space-4);
+  --juno-dock-border-inline: var(--juno-border-width-1);
+
   position: fixed;
   inset-inline: 0;
   inset-block-end: 0;
   z-index: var(--juno-z-raised);
-  margin: 0 var(--juno-space-12) calc(var(--juno-space-16) + env(safe-area-inset-bottom, 0px));
-  padding: var(--juno-space-4);
+  margin: 0 var(--juno-dock-margin-inline) var(--juno-dock-edge-offset);
+  padding: var(--juno-dock-pad-inline);
   background: color-mix(in srgb, var(--juno-s1) 88%, transparent);
   -webkit-backdrop-filter: blur(12px);
   backdrop-filter: blur(12px);
-  border: var(--juno-border-width-1) solid var(--juno-border);
+  border: var(--juno-dock-border-inline) solid var(--juno-border);
   border-radius: 999px;
   box-shadow: var(--juno-shadow-2);
 }
@@ -226,17 +280,22 @@
    Out of flow (fixed) so the page scrolls UNDER it — reserve room on the
    scroller with padding-block-end: var(--juno-dock-clearance). */
 .juno-dock--float {
+  /* the three inline terms the budget contract sums — see .juno-dock */
+  --juno-dock-margin-inline: var(--juno-space-12);
+  --juno-dock-pad-inline: var(--juno-space-4);
+  --juno-dock-border-inline: var(--juno-border-width-1);
+
   position: fixed;
   inset-inline: 0;
   inset-block-end: 0;
   z-index: var(--juno-z-raised);
-  margin: 0 var(--juno-space-12) calc(var(--juno-space-16) + env(safe-area-inset-bottom, 0px));
-  padding: var(--juno-space-4);
+  margin: 0 var(--juno-dock-margin-inline) var(--juno-dock-edge-offset);
+  padding: var(--juno-dock-pad-inline);
   overflow: hidden;
   background: color-mix(in srgb, var(--juno-s1) 88%, transparent);
   -webkit-backdrop-filter: blur(12px);
   backdrop-filter: blur(12px);
-  border: var(--juno-border-width-1) solid var(--juno-border);
+  border: var(--juno-dock-border-inline) solid var(--juno-border);
   border-radius: 999px;
   box-shadow: var(--juno-shadow-2);
 }

package/src/css/components/fold-slot.css

@@ -12,17 +12,44 @@
  *  gap, the folded slot still occupies one gap — name it in
  *  --juno-fold-gap and the fold swallows it with a negative margin.
  *
+ *  COMPOSITION. The canonical use puts .juno-fold on an element that is
+ *  already a component — a .juno-pillbar__item, a .juno-btn, a .juno-chip
+ *  — because that is where the capsule chrome (tap floor, padding, hover,
+ *  focus ring, aria-pressed) lives. Two things follow, and both are
+ *  load-bearing rather than defensive:
+ *
+ *  1. The fold's own declarations are stated at ATTRIBUTE specificity
+ *     (0,2,0), on both branches of data-juno-in, i.e. always. A component
+ *     class is (0,1,0), and `transition` is a SHORTHAND: a later rule does
+ *     not add to the list, it replaces it. Measured in Chromium against the
+ *     built bundle, before this was raised: on a
+ *     .juno-fold.juno-pillbar__item, transition-property resolved to
+ *     `color, background-color` — pillbar.css sorts after this file, so the
+ *     fold had no transition at all and jumped shut instead of folding.
+ *     inline-size and overflow would lose the same way to a component that
+ *     sets either.
+ *
+ *  2. Owning `transition` means owning ALL of it, so the capsule chrome
+ *     properties are in the fold's list too, at the quick duration the
+ *     components themselves use. Dropping them would trade a broken fold
+ *     for a broken hover.
+ *
+ *  Which floors the fold RELEASES when folded — see the folded rule below:
+ *  min-inline-size, padding-inline, border-inline-width. Those are exactly
+ *  the three inputs that can hold a border-box inline size above zero.
+ *
  *  Canonical use: a transient action in a toolbar/pill row (a
  *  scroll-to-top arrow, a contextual button) whose arrival should slide
  *  the row open rather than jump it.
  *  Usage:
  *    <div style="display:flex; gap:4px">                  (any row)
- *      <button class="juno-fold" data-juno-in aria-label="Scroll to top">…</button>
+ *      <button class="juno-fold juno-pillbar__item" data-juno-in aria-label="Scroll to top">…</button>
  *      …other members…
  *    </div>
  *  prefers-reduced-motion needs nothing component-local — the base
  *  layer zeroes every transition duration. */
-.juno-fold {
+.juno-fold[data-juno-in],
+.juno-fold:not([data-juno-in]) {
   --juno-fold-size: var(--juno-size-tap-comfortable);
   --juno-fold-gap: 0px;
 
@@ -31,13 +58,32 @@
   overflow: hidden;
   transition:
     inline-size var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
+    min-inline-size var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
+    padding var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
+    border-width var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
     margin var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
     opacity var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
-    visibility var(--juno-motion-duration-base) var(--juno-motion-ease-standard);
+    visibility var(--juno-motion-duration-base) var(--juno-motion-ease-standard),
+    color var(--juno-motion-duration-quick) var(--juno-motion-ease-standard),
+    background-color var(--juno-motion-duration-quick) var(--juno-motion-ease-standard);
 }
 
+/* Folded away. A min-* floor clamps the USED value whichever rule won the
+   cascade, and a border-box inline size can never resolve below its own
+   padding plus border — so a composed capsule holds the slot open however
+   hard the fold pushes. Measured against the built bundle, composed with
+   .juno-pillbar__item at a 390px viewport: 44px with both floors in place
+   (the tap target), 20px with min-inline-size released (the padding alone),
+   0px with all of them released.
+   min-inline-size is in the transition list above for the OPENING half:
+   released to 0 it would otherwise snap back to the capsule's tap floor the
+   instant data-juno-in returns, and the used width — max(inline-size,
+   min-inline-size) — would jump to full width with nothing to animate. */
 .juno-fold:not([data-juno-in]) {
   inline-size: 0;
+  min-inline-size: 0;
+  padding-inline: 0;
+  border-inline-width: 0;
   margin-inline-end: calc(-1 * var(--juno-fold-gap));
   opacity: 0;
   visibility: hidden;

package/src/css/components/segmented.css

@@ -38,11 +38,20 @@
   opacity: 0;
 }
 
-/* the pill — a span after the radio, or the aria-pressed button itself */
+/* the pill — a span after the radio, or the aria-pressed button itself.
+   The tap floor is on the PAINTED box, not on the label that wraps it: the
+   label is a bare inline-flex and takes its height from this. Segmented is a
+   phone-first control and is routinely the only control on a whole settings
+   section, so it holds --juno-size-tap-min like .juno-btn does — 24px (WCAG
+   2.2 AA, 2.5.8) on a fine pointer, promoted to the 44px comfortable target
+   under (pointer: coarse) by base.css. Without it the pill computed ~25px
+   from its padding alone, which is the AA floor by accident and nothing on
+   touch. See 20260826-025. */
 .juno-seg__opt input + span,
 button.juno-seg__opt {
   display: inline-flex;
   align-items: center;
+  min-block-size: var(--juno-size-tap-min);
   gap: var(--juno-gap-control);
   font-family: var(--juno-font-family-sans);
   font-size: var(--juno-font-size-11);
@@ -90,7 +99,11 @@ button.juno-seg__opt:disabled {
   cursor: not-allowed;
 }
 
-/* Small — matches .juno-btn--sm; for dense toolbars */
+/* Small — dense toolbars: less type, tighter padding. UNLIKE .juno-btn--sm it
+   does NOT drop below the tap floor, which the base rule above holds: --sm is a
+   density modifier here, not an opt-out of the touch target. A segmented row is
+   often the only control on a settings section, so a sub-tap variant of it has
+   no safe use on a phone. */
 .juno-seg--sm .juno-seg__opt input + span,
 .juno-seg--sm > button.juno-seg__opt {
   font-size: var(--juno-font-size-10);