@junoput01/junoui 0.2.0 → 0.4.0

package/docs/design-guidelines.md

@@ -0,0 +1,173 @@
+# Design guidelines
+
+Buildable in any tool — these are rules, not code. Pair with exact values in
+[tokens-reference.md](./tokens-reference.md).
+
+## First principle: color encodes status, never decoration
+
+Every hue has one assigned role. Never reuse a status color as styling.
+
+| Role      | Meaning           | When                                                                    |
+| --------- | ----------------- | ----------------------------------------------------------------------- |
+| `nominal` | Normal / OK       | Nominal readings, confirmed-good, success.                              |
+| `active`  | Selected / active | Current selection, armed state, focus rings, live status.               |
+| `target`  | Managed / goal    | Computed set-points, automated targets. Use sparingly.                  |
+| `caution` | Non-normal, watch | Approaching limits, degraded — no immediate action.                     |
+| `warning` | Critical          | Limit exceeded, act now. Reserve strictly — overuse destroys authority. |
+
+Neutral / structural roles carry no status meaning:
+
+| Role            | Use                                                                |
+| --------------- | ------------------------------------------------------------------ |
+| `data`          | Primary numeric readouts and live values — the brightest text.     |
+| `data-dim`      | Faint metadata — timestamps, tick labels. Decorative; below muted. |
+| `label`         | Labels, units, helper and secondary text. Never for values.        |
+| `muted`         | Disabled, placeholder, decorative separators.                      |
+| `border`        | Hairline borders and dividers.                                     |
+| `border-strong` | Divider / stronger rule — heavier than the hairline border.        |
+| `s0`–`s3`       | Surface depth: base → panel → elevated card → selected/overlay.    |
+
+## More principles
+
+- **Hierarchy via contrast, not scale.** Brightness/weight separate levels before size does.
+- **Density is intentional.** Choose spacing deliberately; don't pad by accident.
+  Switch the whole UI between comfortable and compact with one attribute (below).
+- **Designed for long sessions.** The `soft` palette and dark mode reduce fatigue.
+
+## Typography
+
+- **B612 Mono** — every number, timestamp, identifier, code. Fixed-width digits
+  stop value-change jitter. Use `tabular-nums`.
+- **B612** — all non-numeric UI: headings, labels, navigation, buttons.
+- Headings are uppercase with wide tracking; values are mono and bright (`data`).
+- `.juno-label` reads an optional `--juno-label-size` knob (falls back to
+  `--juno-font-size-13`) so a context can resize labels — e.g. a compact list —
+  without forking the class: set the custom property on an ancestor, never on
+  `.juno-label` itself.
+  ```html
+  <div style="--juno-label-size: var(--juno-font-size-11)">
+    <span class="juno-label">Signal strength</span>
+  </div>
+  ```
+
+## Date & time
+
+One fixed house format everywhere — no locale drift between screens. This is a
+**content convention**, not code: apps do the formatting; junoui specifies what it
+looks like.
+
+| What     | Format                    | Example              |
+| -------- | ------------------------- | -------------------- |
+| Date     | `dd.mm.yyyy`, zero-padded | `05.07.2026`         |
+| Time     | 24-hour `HH:MM`(`:SS`)    | `14:32` · `14:32:07` |
+| Combined | date first, interpunct    | `05.07.2026 · 14:32` |
+| Range    | en-dash, no spaces        | `14:00–15:30`        |
+| Open     | trailing en-dash          | `14:00–`             |
+
+Rendering rules:
+
+- Always mono + `tabular-nums` (the [Typography](#typography) value rule) — use
+  `.juno-value` or `.juno-mono`, wrapped in `<time>` with the machine-readable ISO
+  value: `<time class="juno-mono" datetime="2026-07-05T14:32">05.07.2026 · 14:32</time>`.
+- Never AM/PM, never month names in data UI (prose may spell them out).
+- Relative time ("2h ago") is app policy; when used, pair it with the absolute
+  timestamp in a `title` or adjacent text.
+
+App-side recipe (the `de-DE` locale happens to produce exactly this format):
+
+```js
+const fmt = new Intl.DateTimeFormat('de-DE', {
+  day: '2-digit',
+  month: '2-digit',
+  year: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+  hour12: false,
+});
+fmt.format(date).replace(', ', ' · '); // "05.07.2026 · 14:32"
+```
+
+This is the junoui house format. Locale-sensitive consumer products may override it
+with `Intl` defaults — deviating is a per-app decision; log it like any other
+extension (see [integration.md](./integration.md)).
+
+## Foundation tokens (motion, layering, depth, opacity)
+
+These scales exist so transitions, overlays, and surfaces stay consistent. junoui
+ships the values; stateful behavior (open/close, positioning, focus traps) lives in
+apps. Exact values: [tokens-reference.md](./tokens-reference.md).
+
+- **Motion.** Durations `--juno-motion-duration-{instant,quick,base,deliberate}`
+  (80·140·200·300ms) and easings `--juno-motion-ease-{decel,accel,standard,spring}`.
+  `instant` for state feedback, `quick` for tooltip/menu, `base` for popover/drawer,
+  `deliberate` for modal/scrim. Enter with `decel`, exit with `accel`, reposition with
+  `standard`, toggle with `spring`. Always inside a `transition`/`animation`;
+  `prefers-reduced-motion` already collapses these in `base.css`.
+- **Z-index.** `--juno-z-*` is the single layering source of truth — never invent raw
+  z-index. Layer stack: `surface` (0) < `raised` (100) < `anchored` (2000, menu ·
+  popover · tooltip) < `overlay` (4000, modal · drawer + scrim) < `alert` (5000, toast).
+  Large gaps leave room for app layers.
+- **Elevation.** Depth is **border-first** by design; elevation = z-index + shadow,
+  paired. Reach for `--juno-shadow-{1,2,3}` only when a surface lifts off the glass —
+  `1` raised card, `2` anchored (menu/popover/tooltip), `3` overlay (modal/drawer).
+- **Opacity.** `--juno-opacity-disabled` for inert controls, `--juno-opacity-muted`
+  for de-emphasised content, `--juno-opacity-scrim` for a modal/drawer backdrop.
+
+## Density
+
+One attribute on any ancestor swaps the internal padding of every component
+underneath it — no per-component class:
+
+```html
+<body data-juno-density="compact">
+  <!-- comfortable (default) needs no attribute -->
+</body>
+```
+
+Components read **semantic padding aliases** (`--juno-pad-control-*`,
+`--juno-pad-surface-*`, `--juno-gap-control`) instead of raw `--juno-space-*`;
+`data-juno-density` redefines that set. Density is deliberately **non-linear** —
+compact removes more block (vertical) than inline padding, so text never crowds its
+edges. Interactive controls keep their `min-height` (WCAG tap target); only padding
+shrinks. New components should use the aliases for internal padding to inherit
+density for free; add a new archetype only when one is genuinely needed.
+
+A third value, `auto`, re-densifies for small **coarse-pointer** viewports (phone,
+`pointer: coarse` and width ≤ 640px) — a data-heavy layout gets its compact-ish
+padding back on a phone without the consumer hand-tracking breakpoints:
+
+```html
+<body data-juno-density="auto">
+  <!-- comfortable everywhere else; re-densifies only on a narrow touch phone -->
+</body>
+```
+
+`auto` is **opt-in only** — existing `comfortable`/compact-pinned consumers render
+byte-identical, nothing changes silently. It never touches a control's
+`min-height`; `--juno-size-tap-min` still only grows (never shrinks) under
+`base.css`'s own `@media (pointer: coarse)` rule, so `auto` can't undo the WCAG
+tap-target work. Only `--juno-tile-min` / `--juno-gap-content` /
+`--juno-pad-surface-inline` shrink, same as `compact`.
+
+## Accessibility
+
+Accessibility is a core design goal, held to published standards — **WCAG 2.2** and
+**WAI-ARIA** — with the exact success criteria cited in
+[accessibility.md](./accessibility.md).
+
+- The `colorblind` palette is the IBM Carbon universal set — distinguishable across
+  deuteranopia, protanopia, tritanopia, and AAA-contrast (≥ 7:1) on dark surfaces
+  (WCAG 1.4.6).
+- **Never make color the sole signal** (WCAG 1.4.1). Always pair it with a text label,
+  icon, or shape.
+- Interactive targets: `size.tap.min` = 24px (WCAG 2.5.8, AA); `size.tap.comfortable`
+  = 44px (WCAG 2.5.5, AAA) recommended for primary mobile actions.
+- Focus is always visible — the `active` role, 2px outline (WCAG 2.4.7 / 2.4.11).
+
+## Choosing a palette
+
+| Palette      | Use                                                |
+| ------------ | -------------------------------------------------- |
+| `standard`   | Default. Vivid, high-contrast OKLCH.               |
+| `colorblind` | Accessibility-critical or universal audiences.     |
+| `soft`       | Long viewing sessions; lower chroma, less fatigue. |

package/docs/flutter.md

@@ -0,0 +1,42 @@
+# Flutter
+
+Colors are pre-converted to sRGB hex at build time (Dart has no `oklch`).
+
+## Add the file
+
+Copy the generated file into your project:
+
+```
+dist/flutter/juno_tokens.dart   →  lib/theme/juno_tokens.dart
+```
+
+## Use it
+
+```dart
+import 'theme/juno_tokens.dart';
+
+Container(
+  color: JunoTokens.standardDarkS1,
+  padding: const EdgeInsets.all(JunoTokens.space16),
+  child: Text(
+    '89.3',
+    style: TextStyle(
+      color: JunoTokens.standardDarkNominal,
+      fontSize: JunoTokens.fontSize38,
+      fontFamily: 'B612 Mono',
+    ),
+  ),
+)
+```
+
+- Colors are `Color` constants named `<palette><Mode><Role>` (camelCase),
+  fully opaque (`0xFF…`).
+- Dimensions are `double` constants (`space16`, `fontSize14`, `radius8`, …).
+
+## Theming
+
+Map the active palette/mode to a helper that returns the right constant, or build a
+`ThemeExtension` keyed on palette+mode. All constants derive from the same source,
+so they stay in lockstep with web and native.
+
+Exact values for every token: [tokens-reference.md](./tokens-reference.md).

package/docs/getting-started.md

@@ -0,0 +1,93 @@
+# Getting started
+
+junoui is a design system for **modern, futuristic, highly readable and accessible**
+UIs — usable for critical systems and everyday apps alike. Mechanically it is the
+single graphics source for your UIs: colors, spacing, typography, radii, sizing. You
+build the UI skeleton; junoui defines how it looks. Tokens are authored once in
+`tokens/` and compiled to every platform.
+
+Accessibility is a first-class goal, held to the international standards (WCAG 2.2 +
+WAI-ARIA) with the exact criteria cited per component — see
+[accessibility.md](./accessibility.md).
+
+## Install
+
+```sh
+npm install @junoput01/junoui
+```
+
+Or as a git submodule (then build once):
+
+```sh
+git submodule add git@github.com:junoput/junoui.git vendor/junoui
+cd vendor/junoui && npm install   # `prepare` builds dist/
+```
+
+`npm install` runs the `prepare` script, so `dist/` is always built for you.
+
+## Required: the viewport meta
+
+Ship this on every page. It is not optional if you use anything that touches a
+phone edge — the dock, pillbar, navbar, drawer, bottom sheet, toast, or the
+app-shell:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+Two things depend on it, and both fail **silently**:
+
+- **`viewport-fit=cover` turns the safe area on.** iOS defaults `viewport-fit`
+  to `auto`, and WebKit reports every `env(safe-area-inset-*)` as `0` unless you
+  opt in with `cover` (`contain` does _not_ opt out). junoui is a stylesheet — it
+  cannot set this meta for you. Without it, every safe-area guarantee in the
+  library quietly becomes a no-op and content sits under the home indicator.
+- **`width=device-width, initial-scale=1` makes 1 CSS px equal 1 Apple point**,
+  which is what makes junoui's `44px` tap targets actually 44pt on the device.
+  Without it iOS Safari lays out at ~980px wide and every metric is off.
+
+Details and sources: [ios-conformance.md](./ios-conformance.md).
+
+## The model
+
+- **Palette** — `standard` · `colorblind` · `soft`
+- **Mode** — `dark` · `light`
+- **Role** — `nominal` `active` `target` `caution` `warning` (semantic) and
+  `data` `label` `muted` `border` `s0`–`s3` (neutral/surface)
+
+A theme is one palette × one mode. Color always encodes status — see
+[design-guidelines.md](./design-guidelines.md).
+
+## Pick your platform
+
+| You're building in…                    | Read                                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Web (CSS, SCSS, JS/TS)                 | [web.md](./web.md)                                                                                           |
+| Android / iOS                          | [native.md](./native.md)                                                                                     |
+| Flutter                                | [flutter.md](./flutter.md)                                                                                   |
+| Figma / Sketch / any tool without code | [tokens-reference.md](./tokens-reference.md) (exact values) + [design-guidelines.md](./design-guidelines.md) |
+
+Responsive behavior (how blocks adapt on resize) is its own layer:
+[layout.md](./layout.md).
+
+## What ships
+
+`npm install @junoput01/junoui` delivers `dist/` (all platform outputs), `src/css/` (authored
+stylesheet sources), `src/icons/` (SVG icon sources + license), and `src/fonts/`
+(self-hosted B612 woff2 + OFL license). The interactive demo in `showcase/` is **not**
+shipped — it lives in the repo for development only.
+
+## Build outputs
+
+| Path                                      | Platform                                                      |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| `dist/css/juno.css`                       | Web — tokens + base + utilities + components                  |
+| `dist/css/juno-tokens.css`                | Web — CSS variables only                                      |
+| `dist/css/juno-fonts.css` + `dist/fonts/` | Web — opt-in self-hosted B612 (`@junoput01/junoui/fonts.css`) |
+| `dist/icons/juno-icons.svg`               | Web — icon sprite (`@junoput01/junoui/icons`)                 |
+| `dist/scss/_juno-tokens.scss`             | Web — SCSS variables                                          |
+| `dist/js/tokens.js` + `.d.ts`             | JS / TS — `TOKENS`, `CORE`, `getTokens()`                     |
+| `dist/json/tokens.json`                   | W3C DTCG — any tool                                           |
+| `dist/android/colors.xml` · `dimens.xml`  | Android                                                       |
+| `dist/ios/JunoTokens.swift`               | iOS                                                           |
+| `dist/flutter/juno_tokens.dart`           | Flutter                                                       |

package/docs/integration.md

@@ -0,0 +1,95 @@
+# Integrating junoui into an app
+
+junoui is **presentational**: tokens + a CSS component layer, zero JS. It dresses a UI
+your app builds. This is the recipe for consuming it cleanly — and the rules for
+extending it without breaking the "one design across all apps" goal.
+
+## 1. Import order (app shell)
+
+`@junoput01/junoui/css` sets a small reset + document defaults on `:root`/`body`. Load it **first**,
+your app styles **after**, so your shell wins where it must:
+
+```js
+import '@junoput01/junoui/css'; // tokens + base + components — FIRST
+import '@junoput01/junoui/fonts.css'; // optional self-hosted B612 (see §2)
+import './app.css'; // your shell + app-specific styles — AFTER
+```
+
+What junoui's base layer touches: `box-sizing`, margin/padding reset, `body`
+font/color/background, link color, focus-visible ring, and `prefers-reduced-motion` /
+`forced-colors` handling. It does **not** position or lay out your shell — that's yours.
+If a body default fights your shell, override it in your app CSS (loaded after).
+
+## 2. Fonts (opt-in, CSP-safe)
+
+junoui never fetches fonts. Either bring your own B612, or opt into the self-hosted set:
+
+```js
+import '@junoput01/junoui/fonts.css'; // local @font-face → woff2 in the package, no network
+```
+
+Safe under a strict CSP (`font-src 'self'`). Skip it and the UI falls back to system
+sans/mono until you provide the family.
+
+## 3. Theming — two attributes
+
+```html
+<html data-juno-palette="standard" data-juno-mode="dark" data-juno-density="comfortable"></html>
+```
+
+- `data-juno-palette`: `standard` · `colorblind` · `soft`
+- `data-juno-mode`: `dark` · `light`
+- `data-juno-density`: `comfortable` · `compact`
+- `data-juno-text`: `base` · `large` · `xl` (type scale)
+
+Flip these at runtime and the whole UI re-themes. Persist them if you want (localStorage);
+the value is yours to manage.
+
+## 4. Token bridge (aliasing app variables)
+
+If your app already has design aliases, redefine them in terms of `--juno-*` so one system
+drives everything:
+
+```css
+:root {
+  --bg: var(--juno-s0);
+  --ink: var(--juno-data);
+  --ink-dim: var(--juno-data-dim); /* timestamps, metadata */
+  --line: var(--juno-border);
+  --line-strong: var(--juno-border-strong); /* dividers */
+  --accent: var(--juno-active); /* see §5 — accent is semantic */
+}
+```
+
+Prefer a shipped token over `color-mix()`. junoui exposes the full neutral ramp
+(`data` · `data-dim` · `label` · `muted`) and two border tones (`border` ·
+`border-strong`), so most dense-UI needs don't require mixing.
+
+## 5. Accent is semantic — not a brand hue
+
+junoui has **no decorative brand-accent knob**, on purpose. Color encodes _status_, never
+decoration: every hue is a role (`nominal` · `active` · `target` · `caution` · `warning`).
+The "accent" is the `active` role, and it changes with the palette.
+
+If you want a different accent, **switch palette** (`soft` reads calmer) or add your own
+brand color as an app-local variable used only for non-semantic chrome (a logo, a splash).
+Do not remap junoui's roles to a brand hue — that erases the shared meaning across apps.
+
+## 6. Extending — where new things go
+
+| Need                                                     | Where                                                                                                                    |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| New **status meaning**, reusable across apps             | Propose a new role in junoui core (semver: additive = minor). Rare.                                                      |
+| A full **alternate theme** (same role names, new values) | A new **palette** (like `standard`/`colorblind`/`soft`) — the sanctioned expansion slot.                                 |
+| App-specific **decorative** color                        | App-local, **namespaced** (`--myapp-*`), layered on top; alias to `--juno-*` where you can. Never redefine junoui roles. |
+| A **component** junoui lacks (e.g. chat bubble)          | Build it locally against the token contract until junoui (or a `junoui-<domain>` layer) ships it.                        |
+
+Rule of thumb: extend **additively and namespaced**. If every app injects its own palette
+into junoui, the single-design guarantee dies.
+
+## 7. Stateful behavior stays in your app
+
+junoui ships no JS. Focus traps, list virtualization, popover positioning, data — all
+yours (or a future sibling `junoui-<framework>` package). junoui gives you the stable,
+semantic DOM (real elements, BEM classes, ARIA hooks) to wire behavior + analytics onto;
+see [accessibility.md](./accessibility.md) for the per-component ARIA contract.

package/docs/ios-conformance.md

@@ -0,0 +1,224 @@
+# iOS conformance
+
+What junoui encodes for iOS, **with sources**, and — just as important — what it
+deliberately does _not_ encode because no primary source supports it.
+
+Most numbers the design community attributes to Apple are not in Apple's text.
+This page exists so nobody re-derives folklore, and so nobody "fixes" a correct
+value into a wrong one later.
+
+> **Verifying anything here.** Apple's HIG is a JavaScript app: a plain `curl`
+> returns an empty shell. Check the backing DocC JSON instead —
+> `developer.apple.com/tutorials/data/design/human-interface-guidelines/<page>.json`.
+> Also pin a Wayback snapshot: the HIG silently drops guidance (see the 44pt
+> story below). State verified 2026-08-03.
+
+## The units question, first
+
+**One Apple point = one CSS pixel.** Apple's `pt` is a density-independent
+point, not the CSS typographic point; `devicePixelRatio` absorbs @2x/@3x. So
+Apple's 44pt is CSS `44px`.
+
+Converting through the CSS unit (`1pt = 1/72in`, `1px = 1/96in` → 44pt =
+58.67px) is **wrong**. If you ever see 58.67 in this codebase, it is a bug.
+
+This identity holds only when the page ships
+`<meta name="viewport" content="width=device-width, initial-scale=1">`. Without
+it iOS Safari lays out at ~980px and every metric drifts.
+
+- Source: [css-values-4](https://www.w3.org/TR/css-values-4/) for the CSS units,
+  [WebKit iPhone X guide](https://webkit.org/blog/7929/designing-websites-for-iphone-x/)
+  for the viewport model.
+
+## Touch targets
+
+| What                                          | Value                                                    | Status                      |
+| --------------------------------------------- | -------------------------------------------------------- | --------------------------- |
+| WCAG 2.2 SC 2.5.8 Target Size (Minimum)       | **24×24 CSS px**                                         | **Hard requirement** for AA |
+| WCAG 2.2 SC 2.5.5 Target Size (Enhanced)      | **44×44 CSS px**                                         | AAA (recommendation tier)   |
+| HIG Buttons — hit region                      | **44×44 pt** ("needs a hit region of at least 44×44 pt") | Recommendation              |
+| HIG Accessibility — control size (iOS/iPadOS) | **44×44 pt default, 28×28 pt minimum**                   | Recommendation              |
+| HIG Accessibility — padding between controls  | **~12 pt** bezeled, **~24 pt** non-bezeled               | Recommendation, hedged      |
+
+junoui encodes `--juno-size-tap-min` = 24px (the AA floor) and
+`--juno-size-tap-comfortable` = 44px, and promotes the former to the latter
+under `@media (pointer: coarse)` — see [accessibility.md](./accessibility.md).
+
+- Sources: [WCAG 2.5.8](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html),
+  [WCAG 2.5.5](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html),
+  [HIG Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility),
+  [HIG Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons).
+
+### Folklore, named
+
+- **"Apple mandates a 44pt _minimum_ tap target — see HIG Layout."** That
+  sentence has been **deleted**. The current Layout page contains no tap-target
+  number at all (`"44x44"` and `"tappable"` both return zero hits); a 2023
+  Wayback snapshot of the same endpoint still has it. Every checklist citing
+  that URL cites a dead page. What survives is the Buttons wording above.
+- **"44px because WCAG."** Wrong at AA — the AA floor is 24px. 44 is Apple's
+  number, which WCAG AAA happens to match. W3C never says it derived 44 from
+  Apple.
+
+## Spacing
+
+**Apple publishes no numeric spacing scale for iOS.** No 4pt or 8pt grid, no
+named spacing steps, no layout-margin or gutter constants, no readable-width
+number. Standard margins are delegated to system layout guides.
+
+The only Apple-published numbers found anywhere:
+
+- **~12 pt / ~24 pt** control padding (HIG Accessibility, hedged: "in general",
+  "about", "works well").
+- **8 pt** — `UIView.directionalLayoutMargins` default. This is a **UIKit API
+  default, not an HIG design rule**; cite it as such.
+
+So: **"Apple's 8pt grid" and "HIG standard margins are 16–20pt" are folklore.**
+junoui's spacing scale is junoui's own; do not claim Apple provenance for it.
+
+- Source: [HIG Layout](https://developer.apple.com/design/human-interface-guidelines/layout),
+  [UIView.directionalLayoutMargins](https://developer.apple.com/documentation/uikit/uiview/directionallayoutmargins).
+
+## Safe areas
+
+`env(safe-area-inset-top|right|bottom|left)` — four variables, iOS 11 (shipped
+as `constant()` in 11.0, renamed `env()` in 11.2). There is no numeric constant
+to hardcode; values are system-supplied and vary by device.
+
+**They are inert unless the page opts in.** `viewport-fit` defaults to `auto`,
+and WebKit reports every inset as `0` until you set `cover`. `contain` does
+_not_ opt out — only `cover` does. junoui is a stylesheet and cannot set this
+for you, so it is stated as a hard requirement in
+[getting-started.md](./getting-started.md), every showcase page carries it, and
+a build test enforces that.
+
+- Sources: [WebKit iPhone X guide](https://webkit.org/blog/7929/designing-websites-for-iphone-x/),
+  [WebKit bug 272779](https://bugs.webkit.org/show_bug.cgi?id=272779),
+  [css-env-1](https://www.w3.org/TR/css-env-1/).
+- Spec ownership, for citation hygiene: `env()` and `safe-area-inset-*` are
+  **css-env-1**; `viewport-fit` is **css-round-display-1**. CSS Viewport Module
+  L1 defines none of them — citing it is misattribution.
+
+### `max()` vs addition — the rule
+
+WebKit's documented pattern is `padding-left: max(12px, env(safe-area-inset-left))`
+— "the default padding **or** the safe area inset, whichever is greater". (The
+`12px` there is an arbitrary demo value, not an Apple metric.)
+
+That pattern applies to **padding on a surface that reaches the screen edge**:
+the inset's job is to push content clear of the cutout, so it _replaces_ your
+baseline rather than stacking on it.
+
+It does **not** apply to a **floating element positioned off the edge**, where
+addition is correct:
+
+```css
+/* floating pill: sit 16px ABOVE the home-indicator region */
+inset-block-end: calc(var(--juno-space-16) + env(safe-area-inset-bottom, 0px));
+
+/* NOT max() — that would park the pill flush against the indicator */
+```
+
+Nor to the **clearance tokens** (`--juno-dock-clearance`,
+`--juno-pillbar-clearance`), where content must clear the control's height _and_
+the inset beneath it — genuinely additive.
+
+junoui's call sites were audited against this rule (2026-08-03) and the additive
+ones are correct as written. Do not "fix" them to `max()` without re-reading
+this section.
+
+### The unit trap
+
+Inside `calc()`, an env() fallback **must carry a unit**:
+
+```css
+/* WRONG — unitless 0 is a <number>, the sum is invalid, and the whole
+   DECLARATION is dropped (it does not evaluate to zero) */
+padding-block-end: calc(var(--juno-space-12) + env(safe-area-inset-bottom, 0));
+
+/* RIGHT */
+padding-block-end: calc(var(--juno-space-12) + env(safe-area-inset-bottom, 0px));
+```
+
+A bare (non-`calc`) value may keep a unitless `0`. A build test enforces this.
+Note this follows from ordinary CSS type rules; no Apple/WebKit source states it
+specifically. The adjacent _confirmed_ unit pitfall is that the
+`@supports (padding: max(0px))` feature test needs a unit — and that `@supports`
+wrapper is itself obsolete boilerplate in 2026.
+
+## Viewport units
+
+CSS defines three families by how dynamic browser chrome is treated:
+`sv*` (chrome assumed **expanded** — smallest), `lv*` (assumed **retracted** —
+largest), `dv*` (tracked live). **The unprefixed `vh`/`vw` are normatively equal
+to `lv*`** — that is the spec-level cause of the classic `100vh` overflow: a
+`100vh` box is sized as if the toolbar were retracted.
+
+junoui uses **zero raw `vh`**. Full-height surfaces use `dvh`
+(`layout.css`, `drawer.css`) and `85dvh` caps the bottom sheet.
+
+Caveats worth knowing before changing any of that:
+
+- `dv*` is explicitly **not stable** and not guaranteed to update every frame,
+  so it can churn while the address bar collapses. `sv*` is the calm choice when
+  a surface must never overflow.
+- iOS shipped viewport-unit bugs into the **iOS 26** era: Safari 26.0 fixed
+  `lvh`/`vh` being sized against the _small_ viewport in `SFSafariViewController`.
+  The underlying WebKit bug (255708, filed 2023) is **still open**, so Apple's
+  "Fixed" is stronger than the tracker supports. Scope is the in-app browser used
+  by Slack/X — not standalone Safari, and not `WKWebView`-based in-app browsers
+  (Instagram/Facebook), a separate unfixed path.
+- Do **not** reach for `env(safe-area-max-inset-*)` as a fix. It is in css-env-1
+  but could not be confirmed shipping in any engine.
+
+- Sources: [css-values-4 §6.1.2.1](https://www.w3.org/TR/css-values-4/),
+  [csswg-drafts#6454](https://github.com/w3c/csswg-drafts/issues/6454),
+  [Safari 26.0 release notes](https://developer.apple.com/documentation/safari-release-notes/safari-26-release-notes),
+  [WebKit bug 255708](https://bugs.webkit.org/show_bug.cgi?id=255708).
+
+## Typography
+
+iOS: **17 pt default body size, 11 pt minimum**; Dynamic Type must accommodate
+enlargement to **200%**. Contrast minimums are 4.5:1 up to 17pt, 3:1 at 18pt or
+bold. Since 1pt = 1 CSS px, that is 17px / 11px.
+
+Confidence: medium — extracted from the HIG Accessibility page but not
+adversarially re-verified. Re-check before encoding as a hard constraint.
+
+### The 16px input rule
+
+junoui holds text-entry controls at a 16px floor on coarse pointers, because
+iOS Safari is widely observed to zoom the page onto a focused field under 16px.
+
+**No primary WebKit or Apple source for this was found.** It is empirical
+behavior, not published spec. The mitigation is harmless, so it stays — but do
+not cite it as documented, and re-verify it on iOS 26.
+
+## Things a stylesheet controls that Apple says nothing about
+
+No primary Apple source was found for any of: `touch-action`,
+`-webkit-tap-highlight-color`, `overscroll-behavior`, momentum scrolling, or
+`scroll-snap` on iOS. Where junoui uses these (the coarse-pointer tap-highlight
+reset, `overscroll-behavior: contain` on the modal body), it is **community
+convention** — sensible, but do not attribute it to Apple.
+
+`-webkit-overflow-scrolling: touch` is legacy and must not be reintroduced.
+
+## Open risk: iOS 26
+
+The claim "iOS 26 changed nothing about safe areas, viewport-fit, touch
+behavior, or focus zoom" was **refuted** during verification, so junoui's iOS 26
+behavior is unverified rather than confirmed-safe.
+
+One confirmed change raises the stakes: as of iOS/iPadOS 26, **every website
+added to the Home Screen opens as a web app by default** — "there are now zero
+requirements for 'installability'". junoui's CSS may therefore run in a
+standalone context, where `viewport-fit` and `env()` govern home-indicator and
+Dynamic Island clearance, for sites that never opted in.
+
+Unconfirmed leads, tracked in ticket 20260803-034: `vh` reportedly pinning to
+`window.outerHeight`; three new tab modes yielding different `innerHeight`; a
+reported iPadOS 26 windowed-mode bug where `env(safe-area-inset-*)` returns
+nothing. Resolving these needs a physical device, not more documentation.
+
+- Source: [WebKit features in Safari 26.0](https://webkit.org/blog/17333/webkit-features-in-safari-26-0/).