@junoput01/junoui 0.2.0 → 0.3.0

package/docs/roadmap.md

@@ -0,0 +1,106 @@
+# Roadmap — missing capabilities
+
+Gap analysis vs mature design systems (Material, Carbon, Radix, Polaris, Tailwind).
+What junoui does **not** yet have, prioritised. The framework line holds throughout:
+junoui ships the **look + the accessibility/structure contract**; stateful behavior
+(focus traps, open/close, positioning, data) lives in apps or a sibling
+`junoui-<framework>` package.
+
+Priority key: 🔴 must · 🟡 high · 🟢 nice.
+
+## Have today
+
+Tokens (color · spacing · type · radius · border · size · breakpoints · motion ·
+z-index · elevation · opacity), density modes, themes (3 palettes × dark/light), CSS
+components (badge, button, card, readout, status dot, loaders, **form controls** —
+field · input · select · checkbox · radio · switch · slider; **overlays** — modal ·
+drawer · tooltip · popover · menu), layout primitives + container queries,
+multi-platform outputs, docs, lint + tests + CI.
+
+## Foundations (token gaps) — ✅ shipped 2026-06
+
+All foundation token gaps are now built. Values: [tokens-reference.md](./tokens-reference.md);
+usage: [design-guidelines.md](./design-guidelines.md).
+
+| Done                              | What shipped                                                                                                   |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **Motion** (duration + easing)    | `--juno-motion-duration-{instant,quick,base,deliberate}` + `--juno-motion-ease-{decel,accel,standard,spring}`. |
+| **Z-index scale**                 | `--juno-z-*` layer stack: surface · raised · anchored · overlay · alert.                                       |
+| **Elevation / shadow**            | `--juno-shadow-{1,2,3}` (e1–e3) — border-first depth; shadow for lifted surfaces.                              |
+| **Opacity scale**                 | `--juno-opacity-{disabled,muted,scrim}`.                                                                       |
+| **Density modes** (compact/comfy) | `data-juno-density` swaps semantic padding aliases (`--juno-pad-*`, `--juno-gap-control`).                     |
+
+## Components
+
+| Missing                                                                                                                                                                                                          | Priority   |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| ~~**Form controls** — input, textarea, select, checkbox, radio, switch, slider~~                                                                                                                                 | ✅ shipped |
+| ~~**Field** wrapper — label + control + help + error + required~~                                                                                                                                                | ✅ shipped |
+| ~~**Overlays** — modal/dialog, drawer, tooltip, popover, menu/dropdown~~                                                                                                                                         | ✅ shipped |
+| ~~**Table / data grid** styling~~                                                                                                                                                                                | ✅ shipped |
+| ~~**Alert / toast / inline notification**~~                                                                                                                                                                      | ✅ shipped |
+| ~~**Tabs**, accordion / disclosure~~                                                                                                                                                                             | ✅ shipped |
+| ~~**Skeleton** loading placeholder (pairs with loaders)~~                                                                                                                                                        | ✅ shipped |
+| ~~Avatar, chip/tag, divider, breadcrumb, pagination, stepper~~                                                                                                                                                   | ✅ shipped |
+| **Chat layer** (`junoui-chat`) — message bubble, list, day separator, system pill, attachment cards, conversation header, chat-row, rail. Requested by the buzz integration; highest-leverage gap for chat apps. | 🟡         |
+| Calendar **visuals** (event chip, day-cell)                                                                                                                                                                      | 🟢         |
+
+## Field-driven — ✅ shipped 2026-07
+
+Gaps surfaced by the first production consumer (a media-server web client, 2026-07):
+everything a real app had to hand-roll on top of junoui, rebuilt here as generic,
+reusable pieces. The rule stands — features land app-agnostic; only the origin is
+logged.
+
+| Done                   | What shipped                                                                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Dense sizes**        | `.juno-btn--sm` + `.juno-switch--sm` for 40–46px toolbar chrome / per-row toggles.                                                                                                               |
+| **Segmented control**  | `.juno-seg` — radio-driven exclusive pill row, zero JS; `aria-pressed` button flavor.                                                                                                            |
+| **Gauge**              | `.juno-gauge` — determinate metric ring (conic-gradient), value centered, threshold recipe doc.                                                                                                  |
+| **Spark**              | `.juno-spark` — sparkline size/stroke/color contract (app supplies points; no charting shipped).                                                                                                 |
+| **Micro badge**        | `.juno-badge--micro` — mono data-UI atom for provenance/kind tags + threshold values.                                                                                                            |
+| **Rail + app shell**   | `.juno-rail` (collapsible, `aria-current`-styled) + `layout.md#app-shell` recipe.                                                                                                                |
+| **Content density**    | `--juno-tile-min`/`--juno-gap-content` archetype + `.juno-grid-auto--tiles`.                                                                                                                     |
+| **Slide-over recipe**  | Drawer doc: scrim + header/body/pinned-footer composition from existing parts.                                                                                                                   |
+| **Media/system icons** | 14 Phosphor glyphs: squares-four · images · hexagon · puzzle-piece · play · film-strip · cloud · cloud-arrow-down · arrows-clockwise · cpu · hard-drives · sliders · arrows-out · upload-simple. |
+
+## Mobile — ✅ shipped 2026-07
+
+Mobile-first structures for narrow viewports and touch, automatic where safe,
+opt-in where markup is needed:
+
+| Done                 | What shipped                                                                                                          |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Dock**             | `.juno-dock` — bottom nav, phone counterpart of the rail; sticky, safe-area padded; shell swap recipe in `layout.md`. |
+| **Bottom sheet**     | Modal auto-converts below `bp.sm`: full-width, top-rounded, slides up, stretched footer actions.                      |
+| **Drawer phone fit** | Side drawers cap at `85vw` (scrim stays tappable); bottom drawer pads for the home indicator.                         |
+| **Toast snackbar**   | Full-width bottom stack on phones; slides up instead of sideways.                                                     |
+| **Scrollable tabs**  | Tab strip scrolls sideways instead of overflowing.                                                                    |
+| **Stacked table**    | `.juno-table--stack` + `data-label` — card rows below a 480px container; real `<table>` semantics kept.               |
+| **Touch ergonomics** | `pointer: coarse` raises `--juno-size-tap-min` → 44px; `hover: none` keeps table row actions visible.                 |
+| **Pillbar**          | `.juno-pillbar` — floating pill bar (iOS-style): 2–5 icon destinations/actions, translucent + blurred, safe-area.     |
+| **Navbar**           | `.juno-navbar` — stack top bar: back control always on the start edge, centered truncating title, trailing actions.   |
+| **List**             | `.juno-list` — grouped rows (settings pattern): icon + label/support + trailing value/control/chevron.                |
+| **Tab + stack**      | Shell recipe in `layout.md`: dock/pillbar switches sections, navbar backs out of pushed views.                        |
+
+## Quality / infra
+
+| Missing                                          | Why                                                                                              | Priority |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------ | -------- |
+| ~~**Visual regression** snapshots (Playwright)~~ | ✅ shipped — `npm run test:visual` diffs every showcase page (dark + light).                     | ✅       |
+| ~~**Changesets**~~                               | ✅ shipped — `npm run changeset`; manual Version PR (`npm run version`) → CI publishes on merge. | ✅       |
+| ~~**Icon convention / set**~~                    | ✅ shipped — `.juno-icon` + SVG sprite (Phosphor bold, MIT).                                     | ✅       |
+| **eslint** (flat config)                         | JS surface is small; prettier + tests cover most.                                                | 🟢       |
+
+Done already: stylelint + prettier, `node:test` integrity suite, a11y doc + ARIA
+contract, forced-colors, RTL via logical properties, CI gate.
+
+## Recommended order
+
+1. ~~**Foundation tokens** — motion, z-index, elevation, opacity, density.~~ ✅ done.
+2. ~~**Form controls + field** — the single biggest capability gap.~~ ✅ done.
+3. ~~**Overlays** — modal, tooltip, menu.~~ ✅ done.
+4. ~~**Table / data grid** — sortable header, cell types, row states, overflow, skeleton/empty.~~ ✅ done.
+5. ~~**Quality** — visual-regression snapshots + changesets.~~ ✅ done.
+
+Biggest leverage: **#1 + #2.**

package/docs/tokens-reference.md

@@ -0,0 +1,223 @@
+<!-- GENERATED by scripts/gen-docs.mjs — do not edit by hand. Run `npm run gen-docs`. -->
+
+# Token reference
+
+Every junoui token with its value and the identifier to use on each platform.
+Colors show the authored value and the resolved sRGB hex (use the hex in any
+tool that does not understand `oklch()`).
+
+## How names map across platforms
+
+| Platform | Pattern | Example (`color.standard.dark.nominal`) |
+|---|---|---|
+| CSS — semantic | `var(--juno-<role>)` (switches with theme attrs) | `var(--juno-nominal)` |
+| SCSS | `$juno-color-<palette>-<mode>-<role>` | `$juno-color-standard-dark-nominal` |
+| JS / TS | `TOKENS.<palette>.<mode>.<role>` | `TOKENS.standard.dark.nominal` |
+| JSON (DTCG) | `color.<palette>.<mode>.<role>` | `color.standard.dark.nominal` |
+| Android | `@color/<palette>_<mode>_<role>` | `@color/standard_dark_nominal` |
+| iOS (Swift) | `JunoTokens.<camelCase>` | `JunoTokens.standardDarkNominal` |
+| Flutter (Dart) | `JunoTokens.<camelCase>` | `JunoTokens.standardDarkNominal` |
+
+Core tokens (spacing, radius, typography, …) use `--juno-<path-joined-by->`,
+e.g. `space.16` → `var(--juno-space-16)`, `@dimen/space_16`, `JunoTokens.space16`.
+
+## Color roles
+
+Color encodes status, never decoration. Each role has exactly one meaning.
+
+### Palette: colorblind
+
+| Role | Dark value | Dark hex | Light value | Light hex |
+|---|---|---|---|---|
+| `nominal` | `#78A9FF` | `#78A9FF` | `#0043CE` | `#0043CE` |
+| `active` | `#BE95FF` | `#BE95FF` | `#6929C4` | `#6929C4` |
+| `target` | `#FF7EB6` | `#FF7EB6` | `#9F1853` | `#9F1853` |
+| `caution` | `#F1C21B` | `#F1C21B` | `#7D4F00` | `#7D4F00` |
+| `warning` | `#FF832B` | `#FF832B` | `#BA4300` | `#BA4300` |
+| `data` | `oklch(93% 0.008 85)` | `#EAE7E2` | `oklch(14% 0.008 85)` | `#0B0906` |
+| `data-dim` | `oklch(38% 0.010 85)` | `#45423C` | `oklch(70% 0.008 85)` | `#A19E99` |
+| `label` | `oklch(63% 0.012 85)` | `#8C8981` | `oklch(42% 0.010 85)` | `#504D47` |
+| `muted` | `oklch(48.5% 0.010 85)` | `#625F59` | `oklch(63% 0.008 85)` | `#8B8984` |
+| `border` | `oklch(30% 0.012 85)` | `#312D27` | `oklch(82% 0.010 85)` | `#C7C4BD` |
+| `border-strong` | `oklch(40% 0.012 85)` | `#4B4740` | `oklch(74% 0.010 85)` | `#AEAAA4` |
+| `s0` | `oklch(11% 0.010 85)` | `#060402` | `oklch(97% 0.008 85)` | `#F8F5EF` |
+| `s1` | `oklch(15% 0.012 85)` | `#0D0B06` | `oklch(93% 0.010 85)` | `#EBE7E0` |
+| `s2` | `oklch(19% 0.012 85)` | `#16130E` | `oklch(89% 0.010 85)` | `#DEDAD3` |
+| `s3` | `oklch(24% 0.012 85)` | `#221F19` | `oklch(85% 0.010 85)` | `#D1CDC7` |
+
+### Palette: soft
+
+| Role | Dark value | Dark hex | Light value | Light hex |
+|---|---|---|---|---|
+| `nominal` | `oklch(63% 0.13 155)` | `#38A065` | `oklch(40% 0.11 155)` | `#00582C` |
+| `active` | `oklch(67% 0.12 210)` | `#00A8BE` | `oklch(44% 0.11 210)` | `#006174` |
+| `target` | `oklch(58% 0.14 318)` | `#9C5CAF` | `oklch(42% 0.12 318)` | `#673477` |
+| `caution` | `oklch(72% 0.12 75)` | `#D09945` | `oklch(50% 0.12 75)` | `#8A5700` |
+| `warning` | `oklch(62% 0.15 30)` | `#D15D4D` | `oklch(42% 0.13 30)` | `#86281D` |
+| `data` | `oklch(90% 0.008 88)` | `#E0DED8` | `oklch(14% 0.008 88)` | `#0A0906` |
+| `data-dim` | `oklch(39% 0.010 88)` | `#47453F` | `oklch(69% 0.008 88)` | `#9D9B96` |
+| `label` | `oklch(63% 0.010 88)` | `#8C8982` | `oklch(44% 0.010 88)` | `#55524C` |
+| `muted` | `oklch(48.5% 0.010 88)` | `#615F59` | `oklch(62.5% 0.008 88)` | `#8A8782` |
+| `border` | `oklch(31% 0.010 88)` | `#32302B` | `oklch(84% 0.010 88)` | `#CDCAC3` |
+| `border-strong` | `oklch(41% 0.010 88)` | `#4D4A44` | `oklch(76% 0.010 88)` | `#B4B1AA` |
+| `s0` | `oklch(12% 0.012 88)` | `#070602` | `oklch(96% 0.010 88)` | `#F4F2EA` |
+| `s1` | `oklch(16% 0.012 88)` | `#0F0D08` | `oklch(92% 0.010 88)` | `#E7E4DD` |
+| `s2` | `oklch(20% 0.012 88)` | `#181610` | `oklch(88% 0.010 88)` | `#DAD7D0` |
+| `s3` | `oklch(25% 0.012 88)` | `#24211B` | `oklch(84% 0.010 88)` | `#CDCAC3` |
+
+### Palette: standard
+
+| Role | Dark value | Dark hex | Light value | Light hex |
+|---|---|---|---|---|
+| `nominal` | `oklch(73% 0.22 148)` | `#00CB4C` | `oklch(42% 0.18 148)` | `#006400` |
+| `active` | `oklch(76% 0.16 204)` | `#00CDDF` | `oklch(47% 0.16 220)` | `#006B98` |
+| `target` | `oklch(65% 0.26 324)` | `#D63DE6` | `oklch(45% 0.22 324)` | `#8B0097` |
+| `caution` | `oklch(77% 0.17 73)` | `#F4A000` | `oklch(50% 0.17 73)` | `#9B4C00` |
+| `warning` | `oklch(63% 0.22 28)` | `#F13A32` | `oklch(42% 0.21 26)` | `#A10000` |
+| `data` | `oklch(93% 0.008 85)` | `#EAE7E2` | `oklch(14% 0.008 85)` | `#0B0906` |
+| `data-dim` | `oklch(38% 0.010 85)` | `#45423C` | `oklch(70% 0.008 85)` | `#A19E99` |
+| `label` | `oklch(63% 0.012 85)` | `#8C8981` | `oklch(42% 0.010 85)` | `#504D47` |
+| `muted` | `oklch(48.5% 0.010 85)` | `#625F59` | `oklch(63% 0.008 85)` | `#8B8984` |
+| `border` | `oklch(30% 0.012 85)` | `#312D27` | `oklch(82% 0.010 85)` | `#C7C4BD` |
+| `border-strong` | `oklch(40% 0.012 85)` | `#4B4740` | `oklch(74% 0.010 85)` | `#AEAAA4` |
+| `s0` | `oklch(11% 0.010 85)` | `#060402` | `oklch(97% 0.008 85)` | `#F8F5EF` |
+| `s1` | `oklch(15% 0.012 85)` | `#0D0B06` | `oklch(93% 0.010 85)` | `#EBE7E0` |
+| `s2` | `oklch(19% 0.012 85)` | `#16130E` | `oklch(89% 0.010 85)` | `#DEDAD3` |
+| `s3` | `oklch(24% 0.012 85)` | `#221F19` | `oklch(85% 0.010 85)` | `#D1CDC7` |
+
+## Core tokens
+
+### Borders
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `border.width.1` | `1px` | `var(--juno-border-width-1)` | `JunoTokens.borderWidth1` |
+| `border.width.2` | `2px` | `var(--juno-border-width-2)` | `JunoTokens.borderWidth2` |
+| `border.width.3` | `3px` | `var(--juno-border-width-3)` | `JunoTokens.borderWidth3` |
+
+### Breakpoints
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `bp.sm` | `640px` | `var(--juno-bp-sm)` | `JunoTokens.bpSm` |
+| `bp.md` | `768px` | `var(--juno-bp-md)` | `JunoTokens.bpMd` |
+| `bp.lg` | `1024px` | `var(--juno-bp-lg)` | `JunoTokens.bpLg` |
+| `bp.xl` | `1280px` | `var(--juno-bp-xl)` | `JunoTokens.bpXl` |
+| `bp.2xl` | `1536px` | `var(--juno-bp-2xl)` | `JunoTokens.bp2xl` |
+
+### Elevation
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `shadow.1` | `0 1px 2px rgb(0 0 0 / 0.30)` | `var(--juno-shadow-1)` | `JunoTokens.shadow1` |
+| `shadow.2` | `0 4px 14px rgb(0 0 0 / 0.35)` | `var(--juno-shadow-2)` | `JunoTokens.shadow2` |
+| `shadow.3` | `0 12px 32px rgb(0 0 0 / 0.50)` | `var(--juno-shadow-3)` | `JunoTokens.shadow3` |
+
+### Motion
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `motion.duration.instant` | `80ms` | `var(--juno-motion-duration-instant)` | `JunoTokens.motionDurationInstant` |
+| `motion.duration.quick` | `140ms` | `var(--juno-motion-duration-quick)` | `JunoTokens.motionDurationQuick` |
+| `motion.duration.base` | `200ms` | `var(--juno-motion-duration-base)` | `JunoTokens.motionDurationBase` |
+| `motion.duration.deliberate` | `300ms` | `var(--juno-motion-duration-deliberate)` | `JunoTokens.motionDurationDeliberate` |
+| `motion.ease.decel` | `cubic-bezier(0.2, 0.8, 0.2, 1)` | `var(--juno-motion-ease-decel)` | `JunoTokens.motionEaseDecel` |
+| `motion.ease.accel` | `cubic-bezier(0.4, 0, 1, 1)` | `var(--juno-motion-ease-accel)` | `JunoTokens.motionEaseAccel` |
+| `motion.ease.standard` | `cubic-bezier(0.2, 0.7, 0.3, 1)` | `var(--juno-motion-ease-standard)` | `JunoTokens.motionEaseStandard` |
+| `motion.ease.spring` | `cubic-bezier(0.2, 0.9, 0.3, 1.2)` | `var(--juno-motion-ease-spring)` | `JunoTokens.motionEaseSpring` |
+
+### Opacity
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `opacity.disabled` | `0.45` | `var(--juno-opacity-disabled)` | `JunoTokens.opacityDisabled` |
+| `opacity.muted` | `0.65` | `var(--juno-opacity-muted)` | `JunoTokens.opacityMuted` |
+| `opacity.scrim` | `0.62` | `var(--juno-opacity-scrim)` | `JunoTokens.opacityScrim` |
+
+### Radius
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `radius.2` | `2px` | `var(--juno-radius-2)` | `JunoTokens.radius2` |
+| `radius.3` | `3px` | `var(--juno-radius-3)` | `JunoTokens.radius3` |
+| `radius.4` | `4px` | `var(--juno-radius-4)` | `JunoTokens.radius4` |
+| `radius.5` | `5px` | `var(--juno-radius-5)` | `JunoTokens.radius5` |
+| `radius.8` | `8px` | `var(--juno-radius-8)` | `JunoTokens.radius8` |
+
+### Sizing
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `size.tap.min` | `24px` | `var(--juno-size-tap-min)` | `JunoTokens.sizeTapMin` |
+| `size.tap.comfortable` | `44px` | `var(--juno-size-tap-comfortable)` | `JunoTokens.sizeTapComfortable` |
+| `size.dot.sm` | `8px` | `var(--juno-size-dot-sm)` | `JunoTokens.sizeDotSm` |
+| `size.dot.md` | `10px` | `var(--juno-size-dot-md)` | `JunoTokens.sizeDotMd` |
+
+### Spacing
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `space.2` | `2px` | `var(--juno-space-2)` | `JunoTokens.space2` |
+| `space.4` | `4px` | `var(--juno-space-4)` | `JunoTokens.space4` |
+| `space.8` | `8px` | `var(--juno-space-8)` | `JunoTokens.space8` |
+| `space.10` | `10px` | `var(--juno-space-10)` | `JunoTokens.space10` |
+| `space.12` | `12px` | `var(--juno-space-12)` | `JunoTokens.space12` |
+| `space.16` | `16px` | `var(--juno-space-16)` | `JunoTokens.space16` |
+| `space.20` | `20px` | `var(--juno-space-20)` | `JunoTokens.space20` |
+| `space.24` | `24px` | `var(--juno-space-24)` | `JunoTokens.space24` |
+| `space.28` | `28px` | `var(--juno-space-28)` | `JunoTokens.space28` |
+| `space.32` | `32px` | `var(--juno-space-32)` | `JunoTokens.space32` |
+| `space.40` | `40px` | `var(--juno-space-40)` | `JunoTokens.space40` |
+| `space.56` | `56px` | `var(--juno-space-56)` | `JunoTokens.space56` |
+| `space.72` | `72px` | `var(--juno-space-72)` | `JunoTokens.space72` |
+| `space.96` | `96px` | `var(--juno-space-96)` | `JunoTokens.space96` |
+
+### Typography
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `font.family.sans` | `'B612', sans-serif` | `var(--juno-font-family-sans)` | `JunoTokens.fontFamilySans` |
+| `font.family.mono` | `'B612 Mono', monospace` | `var(--juno-font-family-mono)` | `JunoTokens.fontFamilyMono` |
+| `font.weight.light` | `300` | `var(--juno-font-weight-light)` | `JunoTokens.fontWeightLight` |
+| `font.weight.regular` | `400` | `var(--juno-font-weight-regular)` | `JunoTokens.fontWeightRegular` |
+| `font.weight.medium` | `500` | `var(--juno-font-weight-medium)` | `JunoTokens.fontWeightMedium` |
+| `font.weight.semibold` | `600` | `var(--juno-font-weight-semibold)` | `JunoTokens.fontWeightSemibold` |
+| `font.weight.bold` | `700` | `var(--juno-font-weight-bold)` | `JunoTokens.fontWeightBold` |
+| `font.size.10` | `10px` | `var(--juno-font-size-10)` | `JunoTokens.fontSize10` |
+| `font.size.11` | `11px` | `var(--juno-font-size-11)` | `JunoTokens.fontSize11` |
+| `font.size.12` | `12px` | `var(--juno-font-size-12)` | `JunoTokens.fontSize12` |
+| `font.size.13` | `13px` | `var(--juno-font-size-13)` | `JunoTokens.fontSize13` |
+| `font.size.14` | `14px` | `var(--juno-font-size-14)` | `JunoTokens.fontSize14` |
+| `font.size.16` | `16px` | `var(--juno-font-size-16)` | `JunoTokens.fontSize16` |
+| `font.size.18` | `18px` | `var(--juno-font-size-18)` | `JunoTokens.fontSize18` |
+| `font.size.20` | `20px` | `var(--juno-font-size-20)` | `JunoTokens.fontSize20` |
+| `font.size.28` | `28px` | `var(--juno-font-size-28)` | `JunoTokens.fontSize28` |
+| `font.size.32` | `32px` | `var(--juno-font-size-32)` | `JunoTokens.fontSize32` |
+| `font.size.36` | `36px` | `var(--juno-font-size-36)` | `JunoTokens.fontSize36` |
+| `font.size.38` | `38px` | `var(--juno-font-size-38)` | `JunoTokens.fontSize38` |
+| `font.size.48` | `48px` | `var(--juno-font-size-48)` | `JunoTokens.fontSize48` |
+| `font.size.52` | `52px` | `var(--juno-font-size-52)` | `JunoTokens.fontSize52` |
+| `font.lineHeight.none` | `1` | `var(--juno-font-lineHeight-none)` | `JunoTokens.fontLineHeightNone` |
+| `font.lineHeight.tight` | `1.1` | `var(--juno-font-lineHeight-tight)` | `JunoTokens.fontLineHeightTight` |
+| `font.lineHeight.snug` | `1.2` | `var(--juno-font-lineHeight-snug)` | `JunoTokens.fontLineHeightSnug` |
+| `font.lineHeight.normal` | `1.4` | `var(--juno-font-lineHeight-normal)` | `JunoTokens.fontLineHeightNormal` |
+| `font.lineHeight.relaxed` | `1.5` | `var(--juno-font-lineHeight-relaxed)` | `JunoTokens.fontLineHeightRelaxed` |
+| `font.lineHeight.loose` | `1.7` | `var(--juno-font-lineHeight-loose)` | `JunoTokens.fontLineHeightLoose` |
+| `font.tracking.tight` | `0.02em` | `var(--juno-font-tracking-tight)` | `JunoTokens.fontTrackingTight` |
+| `font.tracking.normal` | `0.06em` | `var(--juno-font-tracking-normal)` | `JunoTokens.fontTrackingNormal` |
+| `font.tracking.label` | `0.08em` | `var(--juno-font-tracking-label)` | `JunoTokens.fontTrackingLabel` |
+| `font.tracking.wide` | `0.12em` | `var(--juno-font-tracking-wide)` | `JunoTokens.fontTrackingWide` |
+| `font.tracking.caps` | `0.15em` | `var(--juno-font-tracking-caps)` | `JunoTokens.fontTrackingCaps` |
+| `font.tracking.wider` | `0.2em` | `var(--juno-font-tracking-wider)` | `JunoTokens.fontTrackingWider` |
+| `font.tracking.widest` | `0.3em` | `var(--juno-font-tracking-widest)` | `JunoTokens.fontTrackingWidest` |
+
+### Z-index
+
+| Token | Value | CSS variable | Flutter / iOS |
+|---|---|---|---|
+| `z.surface` | `0` | `var(--juno-z-surface)` | `JunoTokens.zSurface` |
+| `z.raised` | `100` | `var(--juno-z-raised)` | `JunoTokens.zRaised` |
+| `z.anchored` | `2000` | `var(--juno-z-anchored)` | `JunoTokens.zAnchored` |
+| `z.overlay` | `4000` | `var(--juno-z-overlay)` | `JunoTokens.zOverlay` |
+| `z.alert` | `5000` | `var(--juno-z-alert)` | `JunoTokens.zAlert` |
+

package/docs/web.md

@@ -0,0 +1,89 @@
+# Web (CSS / SCSS / JS)
+
+## CSS — the fast path
+
+Import the full stylesheet (tokens + base + utilities + components):
+
+```js
+import '@junoput01/junoui/css'; // bundler
+```
+
+```css
+@import '@junoput01/junoui/css'; /* plain CSS */
+```
+
+Set the theme with two attributes on `<html>`:
+
+```html
+<html data-juno-palette="standard" data-juno-mode="dark"></html>
+```
+
+Both are optional. **Omit `data-juno-mode` and the theme follows the OS**
+(`prefers-color-scheme`, live — no JS): dark systems get dark, light systems
+light, in whichever palette is set (default `standard`). The base layer also
+sets `color-scheme` so scrollbars and native form chrome match. An explicit
+`data-juno-mode` pins the mode and ignores the OS.
+
+Other system preferences honored out of the box: `prefers-reduced-motion`
+(animations collapse), `prefers-contrast: more` (hairlines step up to the
+strong border), `prefers-reduced-transparency` (translucent surfaces go
+solid), `forced-colors` (system palette). Language is the app's job — junoui
+ships no strings and is RTL-safe via logical properties; set `lang`/`dir` and
+the layout follows.
+
+Switch at runtime:
+
+```js
+document.documentElement.dataset.junoPalette = 'colorblind';
+document.documentElement.dataset.junoMode = 'light';
+delete document.documentElement.dataset.junoMode; // back to following the OS
+```
+
+Use semantic variables and component classes:
+
+```html
+<span class="juno-badge juno--warning">WARNING</span>
+
+<div style="color: var(--juno-nominal); padding: var(--juno-space-16);">…</div>
+```
+
+Want variables only (bring your own components)? Import `@junoput01/junoui/css/tokens`.
+
+## SCSS
+
+```scss
+@use '@junoput01/junoui/scss' as juno; // $juno-color-standard-dark-nominal, $juno-space-16, …
+```
+
+All variables are `!default`, so you can override before `@use` if you fork values.
+
+## JS / TS
+
+```ts
+import { TOKENS, CORE, getTokens } from '@junoput01/junoui';
+
+getTokens('colorblind', 'light').warning; // "#BA4300"
+TOKENS.standard.dark.nominal; // "oklch(73% 0.22 148)"
+CORE.space['16']; // "16px"
+```
+
+Types ship with the package (`JunoPalette`, `JunoMode`, `JunoRole`, `JunoTheme`).
+
+## Semantic vs explicit variables
+
+- **Semantic** `--juno-nominal` … resolve to the _current_ theme. Use these in components.
+- **Explicit** values for a specific theme live in SCSS/JS as
+  `…-standard-dark-nominal`. Use only when you need a fixed theme regardless of context.
+
+## Fonts
+
+junoui **never fetches fonts** (a cross-origin `@import` would break a strict CSP and
+phone home). `base.css` names B612 / B612 Mono via `--juno-font-family-*` but doesn't
+load them. Two options:
+
+```js
+import '@junoput01/junoui/fonts.css'; // opt-in: self-hosted B612 woff2, no network (CSP-safe)
+```
+
+…or bring your own B612 (e.g. `@fontsource/b612`). Without either, the UI falls back to
+system sans/mono. See [integration.md](./integration.md#2-fonts-opt-in-csp-safe).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoput01/junoui",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -11,7 +11,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git@github.com-junoput:junoput/junoui.git"
+    "url": "git+https://github.com/junoput/junoui.git"
   },
   "keywords": [
     "design-system",
@@ -54,6 +54,7 @@
     "src/css",
     "src/icons",
     "src/fonts",
+    "docs",
     "README.md",
     "CHANGELOG.md"
   ],

package/src/css/base.css

@@ -89,6 +89,13 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
    the contract; a phone just reads the bigger one. */
 @media (pointer: coarse) {
   :root { --juno-size-tap-min: var(--juno-size-tap-comfortable); }
+
+  /* iOS Safari zooms the page onto any focused text field whose font-size is
+     below 16px. Hold text-entry controls (.juno-input covers input, textarea
+     and the select's inner control) at a 16px floor on touch so focusing never
+     triggers that jump. max() keeps the floor even under a scaled-down
+     --juno-font-scale, and still grows when scaled up. */
+  .juno-input { font-size: max(16px, var(--juno-font-size-16)); }
 }
 
 @keyframes juno-blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }

package/src/css/components/dock.css

@@ -72,3 +72,16 @@
   outline: var(--juno-border-width-2) solid var(--juno-active);
   outline-offset: calc(-1 * var(--juno-space-2));
 }
+
+/* Fixed — same story as the pillbar: sticky only pins while the column
+   overflows, so on a short page the dock lands mid-content. Pin to the
+   viewport foot in a page-scroll shell where content height varies. Since
+   fixed leaves the flow, reserve its height at the page foot (e.g.
+   padding-block-end) so it doesn't cover the last row. In-flow
+   .juno-app-shell (main is the scroller, dock at the body foot) needs none
+   of this — prefer it. */
+.juno-dock--fixed {
+  position: fixed;
+  inset-inline: 0;
+  inset-block-end: 0;
+}

package/src/css/components/icon-loader.css

@@ -0,0 +1,53 @@
+/* ════════════════════════════════════════════════════════════════════
+ *  Component — Icon loader (nav loading ring)
+ *  A destination icon ringed by the spinning arc while that section loads —
+ *  the "this is loading" affordance for a rail / dock / pillbar item. The
+ *  icon stays static on top; the arc sizes in em around it and eats no
+ *  pointer events, so the nav item still clicks through.
+ *
+ *  The app owns the state: add .juno-arc--indeterminate to spin, drop it
+ *  when loaded (gate the blink to first-load, not every refetch). For a
+ *  determinate ring, set --juno-progress on the .juno-arc instead.
+ *  Usage:
+ *    <a class="juno-rail__item" href="…" aria-current="page">
+ *      <span class="juno-icon-loader">
+ *        <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+ *        <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+ *      </span>
+ *      <span class="juno-rail__label">Library</span>
+ *    </a>
+ *
+ *  Gotcha encoded here: the arc's rotate animation overrides `transform`, so
+ *  the ring is centred with inset:0 + margin:auto — never translate(-50%,-50%),
+ *  which the spin would clobber.
+ * ════════════════════════════════════════════════════════════════════ */
+
+.juno-icon-loader {
+  --juno-role: var(--juno-active);
+
+  /* Single-cell grid: the icon and the ring occupy the SAME cell and are
+     both centred in it, so they're guaranteed concentric — no transform (the
+     arc's rotation would clobber a translate) and no fragile margin math. The
+     ring is the larger child, so the cell sizes to it (--juno-icon-loader-ring). */
+  display: inline-grid;
+  place-items: center;
+  line-height: 0; /* drop the inline strut so the box hugs the ring */
+}
+
+.juno-icon-loader > .juno-icon,
+.juno-icon-loader > .juno-arc {
+  grid-area: 1 / 1;
+}
+
+/* icon sits above the ring */
+.juno-icon-loader > .juno-icon {
+  z-index: 1;
+}
+
+/* the ring: sized in em (relative to the icon), transparent to clicks */
+.juno-icon-loader > .juno-arc {
+  --juno-arc-size: var(--juno-icon-loader-ring, 1.9em);
+  --juno-arc-width: 0.14em;
+
+  pointer-events: none;
+}

package/src/css/components/pillbar.css

@@ -102,6 +102,21 @@
   flex-shrink: 0;
 }
 
+/* Fixed — pin to the viewport instead of flowing at the column's end.
+   Sticky only pins while the column overflows; on a short (non-scrolling)
+   page the sticky pillbar lands mid-content. Use --fixed in a page-scroll
+   shell where content height varies. Centered via inset-inline:0 + the base
+   margin-inline:auto (NOT translateX, which the app-shell model avoids
+   anyway). Leaves the viewport foot free — reserve space so it doesn't cover
+   the last row (e.g. padding-block-end on the scroll region). Prefer the
+   in-flow .juno-app-shell (main scrolls, pillbar sits at the body foot) —
+   that needs no fixed at all. */
+.juno-pillbar--fixed {
+  position: fixed;
+  inset-inline: 0;
+  z-index: var(--juno-z-anchored);
+}
+
 /* reduced-transparency preference → solid surface, no blur */
 @media (prefers-reduced-transparency: reduce) {
   .juno-pillbar {

package/src/css/components/rail.css

@@ -94,3 +94,11 @@
   justify-content: center;
   padding-inline: 0;
 }
+
+/* Responsive — the rail self-hides below md, so you pair it with a
+   .juno-dock (or .juno-pillbar) carrying .juno-hide-from-md and get the
+   rail↔dock swap without hanging a juno-hide-below-md on the rail yourself.
+   Reciprocal of the dock's md pairing; see dock.css / docs/layout.md#app-shell. */
+@media (width <= 767.98px) {
+  .juno-rail--responsive { display: none !important; }
+}

package/src/css/layout.css

@@ -92,8 +92,70 @@
 }
 .juno-reel > * { scroll-snap-align: start; flex: 0 0 auto; }
 
+/* App shell — the standard product frame, as classes instead of the
+   copy-pasted \3c style> block every consumer used to hand-roll. A rail beside
+   a body column; the body holds an optional topbar, a scrolling main region,
+   and a dock/pillbar pinned at its foot. The MAIN region is the scroller
+   (not the page), so the dock never needs sticky/fixed to stay put and the
+   mobile address bar can't clip it. Height is 100dvh (dynamic viewport) so
+   it fills the visible area under shrinking browser chrome. Pairs with the
+   viewport helpers below to swap rail↔dock across md; see docs/layout.md#app-shell.
+     <div class="juno-app-shell">
+       <nav class="juno-rail juno-rail--responsive" aria-label="Primary">…</nav>
+       <div class="juno-app-shell__body">
+         <header class="juno-app-shell__topbar">…</header>
+         <main class="juno-app-shell__main">…</main>
+         <nav class="juno-dock juno-hide-from-md" aria-label="Primary">…</nav>
+       </div>
+     </div> */
+.juno-app-shell {
+  display: flex;
+  block-size: 100dvh;
+  overflow: hidden; /* the main region scrolls, not the shell */
+  padding-inline: env(safe-area-inset-left, 0) env(safe-area-inset-right, 0);
+}
+
+.juno-app-shell__body {
+  flex: 1;
+  min-inline-size: 0;
+  display: flex;
+  flex-direction: column;
+  min-block-size: 0; /* let __main shrink and scroll instead of the shell */
+}
+
+.juno-app-shell__topbar {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--juno-space-12);
+  min-block-size: var(--juno-app-shell-topbar-size, 46px);
+  padding-inline: var(--juno-pad-surface-inline);
+  padding-block-start: env(safe-area-inset-top, 0);
+  background: var(--juno-s1);
+  border-block-end: var(--juno-border-width-1) solid var(--juno-border);
+}
+
+.juno-app-shell__main {
+  flex: 1;
+  min-block-size: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+  padding: var(--juno-pad-surface-block) var(--juno-pad-surface-inline);
+}
+
 /* Hide/show by viewport breakpoint — the rare case an intrinsic primitive
-   can't express (e.g. swap a nav for a menu button). */
-@media (width <= 767.98px) { .juno-hide-below-md { display: none !important; } }
+   can't express (e.g. swap a nav for a menu button). `hide-below-X` hides
+   under breakpoint X; `hide-from-X` hides at X and up. `show-*` are the
+   readable inverse aliases (show-from-X ≡ hide-below-X, show-below-X ≡
+   hide-from-X) — same media rule, name whichever reads clearer at the site. */
+@media (width <= 639.98px) { .juno-hide-below-sm, .juno-show-from-sm  { display: none !important; } }
+
+@media (width >= 640px)    { .juno-hide-from-sm,  .juno-show-below-sm { display: none !important; } }
+
+@media (width <= 767.98px) { .juno-hide-below-md, .juno-show-from-md  { display: none !important; } }
+
+@media (width >= 768px)    { .juno-hide-from-md,  .juno-show-below-md { display: none !important; } }
+
+@media (width <= 1023.98px) { .juno-hide-below-lg, .juno-show-from-lg  { display: none !important; } }
 
-@media (width >= 768px)    { .juno-hide-from-md  { display: none !important; } }
+@media (width >= 1024px)    { .juno-hide-from-lg,  .juno-show-below-lg { display: none !important; } }