@junoput01/junoui 0.2.0 → 0.4.0

package/docs/components/pillbar.md

@@ -0,0 +1,211 @@
+# Pillbar
+
+A floating pill-shaped bar hovering above the content's bottom edge — the
+iOS-style alternative to the full-width [dock](./dock.md). Holds 2–5 icon
+actions or destinations; mix nav links and toggle buttons, separated by an
+optional divider. Zero JS.
+
+## Web
+
+```html
+<nav class="juno-pillbar" aria-label="Primary">
+  <a class="juno-pillbar__item" href="/library" aria-current="page" aria-label="Library">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-pillbar__label">Library</span>
+  </a>
+  <a class="juno-pillbar__item" href="/albums" aria-label="Albums">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-images" /></svg>
+  </a>
+  <span class="juno-pillbar__sep"></span>
+  <button class="juno-pillbar__item" aria-label="Sync">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-arrows-clockwise" /></svg>
+  </button>
+</nav>
+```
+
+| Class / prop                                                                   | Effect                                                                                                                                             |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.juno-pillbar`                                                                | Sticky floating pill: blurred translucent `s1`, hairline, `shadow.2`.                                                                              |
+| `.juno-pillbar__item`                                                          | Round tap target ≥ `size.tap.comfortable`; icon with optional label.                                                                               |
+| `.juno-pillbar__label`                                                         | Inline text next to the icon — truncates at 12ch.                                                                                                  |
+| `.juno-pillbar__sep`                                                           | Vertical hairline between item groups (e.g. destinations vs. actions).                                                                             |
+| `[aria-current]`                                                               | Active destination: `s3` pill fill + role color. Attribute, not class.                                                                             |
+| `[aria-pressed]`                                                               | Same active look for toggle buttons.                                                                                                               |
+| `.juno-pillbar--fixed`                                                         | Fix to the viewport (`position: fixed`), floating its usual `space.16` + safe-area above the foot — for page-scroll shells where sticky won't pin. |
+| `.juno-pillbar--top-right` / `--top-left` / `--bottom-right` / `--bottom-left` | Fix as a floating cluster in one viewport corner (safe-area-clamped), instead of the centered bottom bar.                                          |
+| `.juno-pillbar__input`                                                         | Borderless search field inside the pill (`min(52vw, 240px)`, 16px font floor).                                                                     |
+| `.juno-pillbar__overflow`                                                      | "More" trigger for items that don't fit — anchors a [menu](./menu.md) via `popovertarget`.                                                         |
+| `.juno-pillbar--collapsible`                                                   | The pill folds into a single circle (`__toggle`) and animates back to full width — see [Collapsible](#collapsible).                                |
+| `.juno-pillbar__toggle`                                                        | The collapsible pill's circular expand/collapse control; state on `aria-expanded`, same chrome as `__overflow`.                                    |
+| `.juno-pillbar__tray`                                                          | Wrapper whose width animates shut — holds one child wrapping the usual `__item` markup.                                                            |
+| `.juno--<role>`                                                                | Active color (default `active`).                                                                                                                   |
+
+### Geometry custom props
+
+Read from `.juno-pillbar` (or its computed style) instead of hardcoding these
+in an app-side capacity planner — they're the single source of truth for how
+many `__item` fit before the rest should route to `__overflow`.
+
+| Prop                  | Default                | Meaning                                                                                                                                               |
+| --------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--juno-pillbar-item` | `size.tap.comfortable` | Item tap-target side (square).                                                                                                                        |
+| `--juno-pillbar-gap`  | `space.2`              | Gap between items.                                                                                                                                    |
+| `--juno-pillbar-pad`  | `space.4`              | Pill's own inner padding.                                                                                                                             |
+| `--juno-pillbar-edge` | `space.16`             | Base (bottom-center) placement's offset from the viewport edge. Not used by the corner modifiers, which keep their own distinct block/inline offsets. |
+
+## Corner placement
+
+The base pillbar is a centered bottom bar. The corner modifiers pin it as a
+floating cluster in one viewport corner instead — e.g. a top-right
+search/filter cluster over a full-bleed grid. Each flips to `position: fixed`
+and clamps the corner with `env(safe-area-inset-*)` so it never lands under a
+notch or the home indicator; the base blur/border/shadow carries over. For the
+bottom corners, reserve scroll clearance with
+`padding-block-end: var(--juno-pillbar-clearance)` if the pill overlaps
+content.
+
+## Input slot
+
+`.juno-pillbar__input` is an expandable search field that lives inside the
+pill, reading as part of it rather than a boxed control.
+
+```html
+<div class="juno-pillbar juno-pillbar--top-right">
+  <input
+    class="juno-pillbar__input"
+    type="search"
+    aria-label="Search library"
+    placeholder="Search…"
+  />
+  <button class="juno-pillbar__item" aria-label="Search" aria-pressed="true">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-magnifying-glass" /></svg>
+  </button>
+</div>
+```
+
+- The field is borderless/transparent; its font-size is held at
+  `max(16px, …)` because iOS Safari zooms the whole page onto any focused text
+  field under 16px (the same floor the base [input](./input.md) applies on
+  touch).
+- **A placeholder is not a label** — give the input an `aria-label` or a
+  visually-hidden `<label>`.
+
+## Overflow slot
+
+`.juno-pillbar__overflow` is a "more" trigger, styled like `__item`, for
+pills with variable membership (e.g. a top-right action pill whose item count
+depends on the current view). It opens a [`.juno-menu`](./menu.md) holding
+whatever didn't fit — zero JS, via the native Popover API:
+
+```html
+<div class="juno-pillbar juno-pillbar--top-right">
+  <button class="juno-pillbar__item" aria-label="Search" aria-pressed="true">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-magnifying-glass" /></svg>
+  </button>
+  <button class="juno-pillbar__item" aria-label="Filter">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-funnel" /></svg>
+  </button>
+  <button
+    class="juno-pillbar__overflow"
+    popovertarget="pillbar-more"
+    aria-haspopup="menu"
+    aria-expanded="false"
+    aria-label="More"
+  >
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-dots-three" /></svg>
+  </button>
+</div>
+<ul class="juno-menu" id="pillbar-more" popover role="menu">
+  <li>
+    <button
+      class="juno-menu__item"
+      role="menuitem"
+      popovertarget="pillbar-more"
+      popovertargetaction="hide"
+    >
+      <span class="juno-menu__icon">⤓</span>Export
+    </button>
+  </li>
+</ul>
+```
+
+- **junoui ships the docking point, not the collapse policy.** Deciding
+  _which_ items overflow and _when_ is the app's job — read the
+  [geometry custom props](#geometry-custom-props) to do the capacity math,
+  then conditionally render `.juno-pillbar__overflow` and move the spilled
+  `__item`s into the menu. This keeps one source of truth for the pixel
+  constants instead of an app re-declaring them in JS.
+- The invoker (`popovertarget`) is the menu's implicit anchor, so
+  `.juno-menu`'s own `position-try-fallbacks` handles flipping it clear of the
+  viewport edge — no extra positioning needed in the pill.
+- `aria-expanded` mirrors the menu's open state like `[aria-pressed]` does for
+  toggle items; toggle it from the app or a stateless enhancer (junoui itself
+  ships no JS).
+
+## Collapsible
+
+`.juno-pillbar--collapsible` lets the whole pill fold into a single circular
+button and expand back to full width on demand — for toolbars that should get
+out of the content's way (e.g. a media viewer's action bar). State lives on
+the toggle's `aria-expanded`; junoui ships no JS, the app flips the attribute.
+
+```html
+<nav class="juno-pillbar juno-pillbar--collapsible" aria-label="Tools">
+  <button class="juno-pillbar__toggle" aria-expanded="false" aria-label="Show toolbar">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-dots-three" /></svg>
+  </button>
+  <div class="juno-pillbar__tray">
+    <div>
+      <button class="juno-pillbar__item" aria-label="Share">…</button>
+      <span class="juno-pillbar__sep"></span>
+      <button class="juno-pillbar__item" aria-label="Delete">…</button>
+    </div>
+  </div>
+</nav>
+```
+
+- **The tray needs exactly one child wrapper** (any element). The expansion is
+  a `grid-template-columns: 0fr ↔ 1fr` transition — the only widely-supported
+  way to animate to an intrinsic width (Safari 16+) — and the track needs a
+  single shrinkable child to collapse.
+- DOM order is free: toggle-first reads naturally for a left-anchored pill,
+  toggle-last for a right-anchored corner (`--bottom-right`), so the circle
+  stays put and the tray grows out of it.
+- Collapsed, the tray goes `visibility: hidden` at the end of the slide, which
+  also removes its items from the tab order. **Collapsing while focus is
+  inside the tray is the app's edge:** move focus to the toggle first.
+- The toggle's glyph rotates a quarter-turn while expanded; swap the icon from
+  the app instead if you want e.g. dots → ×.
+- `prefers-reduced-motion` is handled by the base layer (every transition
+  collapses to ~0ms) — the states still apply, just without the slide.
+
+## Anatomy (any platform)
+
+- Fully-rounded capsule floating `space.16` off the bottom edge (plus the safe
+  area), centered inline; translucent `s1` with a background blur, hairline
+  `border`, `shadow.2` lift.
+- Items are capsule targets at least `size.tap.comfortable` square; the active
+  one fills `s3` and takes the role color.
+- A separator is a `border`-colored vertical hairline, `space.20` tall.
+
+## Usage
+
+- Same rules as the dock: 3–5 destinations, overflow goes behind a "More" item.
+  Pick **one** bottom pattern per screen — dock _or_ pillbar, never both.
+- Variable-membership action pills (not fixed destinations) use the
+  [overflow slot](#overflow-slot) instead of hand-rolling a "more" menu.
+- Sticky, not fixed: place it last inside the scrolling column; it floats over
+  content while staying in flow. Best inside the
+  [`.juno-app-shell`](../layout.md#app-shell) frame, whose `__main` is the
+  scroller.
+- **Short-page caveat:** sticky only pins while the column overflows, so on a
+  short page that doesn't scroll the pillbar lands mid-content. If the _whole
+  page_ scrolls, use `.juno-pillbar--fixed` to fix it to the viewport (it keeps
+  floating its usual gap above the foot) and reserve its footprint at the page
+  foot.
+- Icon-only items need `aria-label`. Show the label on the active item (or all
+  items) when space allows.
+- Nav destinations are `<a>` with `aria-current="page"`; momentary or toggle
+  actions are `<button>` (toggles flip `aria-pressed`).
+- Works inside a [navbar](./navbar.md) + tab-stack shell — the recipe is in
+  [layout.md](../layout.md#app-shell).

package/docs/components/popover.md

@@ -0,0 +1,43 @@
+# Popover
+
+An anchored, click-triggered surface for rich, interactive content — filters,
+quick-edits, detail cards. Unlike a [tooltip](./tooltip.md) it holds focusable controls
+and persists until dismissed.
+
+Built on the **native Popover API**: the panel lives in the browser **top layer**, so
+it is _never_ clipped by an ancestor's `overflow`/`transform` and never fights
+`z-index`. A `popovertarget` button is its **implicit anchor**; CSS anchor positioning
+pins the panel below, inline-end aligned. Open/close, light-dismiss (outside click),
+and ESC are all the platform's job — **zero JS**.
+
+## Web
+
+```html
+<button popovertarget="pf" aria-haspopup="dialog">RANGE FILTER ▾</button>
+<div class="juno-popover" id="pf" popover role="dialog" aria-label="Range filter">
+  <!-- any controls -->
+  <span class="juno-popover__arrow"></span>
+</div>
+```
+
+| Class                  | Effect                                                              |
+| ---------------------- | ------------------------------------------------------------------- |
+| `.juno-popover`        | 280px `s2` panel, radius `5`, shadow `2`. Top-layer, anchor-pinned. |
+| `.juno-popover__arrow` | Pointer back to the anchor (top-end corner).                        |
+| `.juno-popover-anchor` | Optional inline wrapper to group trigger + panel (layout only).     |
+
+## Anatomy (any platform)
+
+- Top-layer surface `s2` + `shadow.2`, surface-padding. Pinned below the invoker
+  (`position-area: block-end span-inline-start`) with a `space.12` gap; flips to stay
+  on-screen via `position-try-fallbacks`.
+- Enter: rise + fade, `motion.duration.quick` / `ease.decel`, animated open↔closed with
+  `@starting-style` + `transition-behavior: allow-discrete`.
+
+## Usage
+
+- Reach for a popover when the content is interactive; a tooltip when it's just text.
+- `popovertarget` makes the `<button>` toggle the panel and exposes `aria-expanded` /
+  `aria-details` implicitly — no script needed. Keep `aria-haspopup` for intent.
+- Default anchoring is block-end / inline-end. Override with `position-area` (or set
+  `inset` on the panel's `toggle` event) for other placements or older engines.

package/docs/components/rail.md

@@ -0,0 +1,54 @@
+# Rail
+
+The side navigation column of the standard app shell — brand block on top, then
+icon + label items. Collapsible to icons-only. The full shell composition
+(rail + topbar + content + slide-over) is in [layout.md](../layout.md#app-shell).
+On phone widths the shell swaps the rail for a [dock](./dock.md) (bottom nav).
+
+## Web
+
+```html
+<nav class="juno-rail" aria-label="Primary">
+  <div class="juno-rail__brand">JUNO</div>
+  <a class="juno-rail__item" href="/library" aria-current="page">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-rail__label">Library</span>
+  </a>
+  <a class="juno-rail__item" href="/nodes">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    <span class="juno-rail__label">Nodes</span>
+  </a>
+</nav>
+```
+
+| Class / prop             | Effect                                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------------------ |
+| `.juno-rail`             | `s1` column, 180px, 1px `border` seam on the inline-end edge.                                    |
+| `.juno-rail__brand`      | Mono uppercase brand block.                                                                      |
+| `.juno-rail__item`       | Icon + label row; hover `s2`.                                                                    |
+| `.juno-rail__label`      | The text — hidden when collapsed.                                                                |
+| `[aria-current]`         | Active item: `s3` fill + 2px role edge. Attribute, not a class.                                  |
+| `.juno-rail--collapsed`  | Icons-only, `space.56` wide; width transition.                                                   |
+| `.juno-rail--responsive` | Self-hides below `md`; pair with a `.juno-dock` / `.juno-pillbar` carrying `.juno-hide-from-md`. |
+| `--juno-rail-width`      | Override the expanded width.                                                                     |
+| `.juno--<role>`          | Active-edge color (default `active`).                                                            |
+
+## Anatomy (any platform)
+
+- Column on `s1`, hairline seam, items `space.8` × `space.16`, `font.size.12`
+  uppercase `label` → `data` on hover/active.
+- Active = `s3` fill + `border.width.2` inline-start edge in the role color.
+- Edges are logical: the rail mirrors under RTL.
+
+## Usage
+
+- The app owns the collapse state (a class toggle) and sets `aria-current="page"`
+  on the active item — junoui styles the attribute so nav semantics stay honest.
+- When collapsed, labels leave the accessibility tree: give each item an
+  `aria-label` (or `title`) so icons-only mode stays navigable.
+- Pair with [tooltip](./tooltip.md) for collapsed-item labels.
+- Adaptive shell: add `.juno-rail--responsive` so the rail self-hides below
+  `md` and a paired [dock](./dock.md)/[pillbar](./pillbar.md) takes over — no
+  need to hang `.juno-hide-below-md` on the rail yourself.
+- Show a section is loading by wrapping an item's icon in an
+  [icon-loader](./icon-loader.md) ring.

package/docs/components/readout.md

@@ -0,0 +1,39 @@
+# Data readout
+
+A tile showing one live value: small label, large mono value, unit.
+
+## Web
+
+```html
+<div class="juno-readout juno--nominal">
+  <span class="juno-readout__label">N1</span>
+  <span class="juno-readout__value">89.3</span>
+  <span class="juno-readout__unit">%</span>
+</div>
+
+<div class="juno-readout juno-readout--alert juno--warning">
+  <span class="juno-readout__label">OIL PSI</span>
+  <span class="juno-readout__value">12</span>
+  <span class="juno-readout__unit juno-text-warning">↓ LOW</span>
+</div>
+```
+
+| Class                            | Effect                                                     |
+| -------------------------------- | ---------------------------------------------------------- |
+| `.juno-readout`                  | `s2` tile, radius `radius.5`. Value default role = `data`. |
+| `.juno--<role>`                  | Colors the value (status).                                 |
+| `.juno-readout--alert`           | Adds a 1px role border for critical tiles.                 |
+| `__label` / `__value` / `__unit` | Parts.                                                     |
+
+## Anatomy (any platform)
+
+- Tile `s2`, padding `space.20`/`space.16`, radius `radius.5`.
+- Label: `font.size.10`, uppercase, tracking `wider`, color `label`.
+- Value: **B612 Mono 700**, `font.size.38`, `tabular-nums`, color = role (default `data`).
+- Unit: `font.size.11`, color `label`.
+
+## Usage
+
+- Value stays `data` (neutral) when nominal; switch to a status role only when the
+  reading itself is non-normal.
+- Always B612 Mono with tabular figures so digits don't shift as values update.

package/docs/components/reload.md

@@ -0,0 +1,41 @@
+# Reload
+
+The non-blocking counterpart to the [skeleton](./skeleton.md). A skeleton
+stands in for content that isn't there yet (first paint); the reload indicator
+signals a refresh happening _over_ content that's already on screen — the stale
+data stays readable and interactive while fresh data lands.
+
+It's a small pulsing dot with a soft halo, centered as a fixed overlay that
+eats no pointer events, so the page underneath stays fully usable.
+
+## Web
+
+```html
+<div class="juno-reload" role="status" aria-label="Reloading">
+  <span class="juno-reload__dot"></span>
+</div>
+```
+
+| Class / prop        | Effect                                                              |
+| ------------------- | ------------------------------------------------------------------- |
+| `.juno-reload`      | Fixed, centered, `pointer-events: none` overlay.                    |
+| `.juno-reload__dot` | `space.16` role-colored dot with a soft halo, gentle opacity pulse. |
+| `.juno--<role>`     | Dot color (default `active`).                                       |
+
+## Usage
+
+- Render it while a **background refetch is in flight over existing content**;
+  drop it when the request settles. For first-paint (no content yet) use the
+  [skeleton](./skeleton.md) instead.
+- The app owns the state (zero JS in the component) — mount/unmount it, or
+  toggle a `hidden` attribute.
+- The pulse uses the shared `juno-pulse` keyframe — a soft dim, not a full
+  blink. `prefers-reduced-motion` stops the pulse (via the base layer); the
+  dot stays visible so the "refreshing" state is still conveyed.
+
+## Accessibility
+
+- `role="status"` + `aria-label` announces the refresh **politely**, without
+  stealing focus — it's a status, not an alert. Don't use `role="alert"`.
+- Keep it non-blocking: `pointer-events: none` ensures it never traps clicks on
+  the content it floats over.

package/docs/components/segmented.md

@@ -0,0 +1,46 @@
+# Segmented control
+
+An exclusive-choice pill row — filters (`ALL / PHOTOS / VIDEO`), mode switchers,
+sort pickers. Native radios carry the state; zero JS.
+
+## Web
+
+```html
+<fieldset class="juno-seg juno--active">
+  <label class="juno-seg__opt"><input type="radio" name="kind" checked /><span>ALL</span></label>
+  <label class="juno-seg__opt"><input type="radio" name="kind" /><span>PHOTOS</span></label>
+  <label class="juno-seg__opt"><input type="radio" name="kind" /><span>VIDEO</span></label>
+</fieldset>
+```
+
+JS-driven apps may use buttons instead — the app flips `aria-pressed`:
+
+```html
+<div class="juno-seg" role="group" aria-label="Kind">
+  <button class="juno-seg__opt" aria-pressed="true">ALL</button>
+  <button class="juno-seg__opt" aria-pressed="false">PHOTOS</button>
+</div>
+```
+
+| Class            | Effect                                                                  |
+| ---------------- | ----------------------------------------------------------------------- |
+| `.juno-seg`      | The row (a `<fieldset>` or `role="group"`); wraps, `space.4` gap.       |
+| `.juno-seg__opt` | One pill: label + hidden radio + `<span>`, or an `aria-pressed` button. |
+| `.juno-seg--sm`  | Dense-toolbar size (`font.size.10`), matches `.juno-btn--sm`.           |
+| `.juno--<role>`  | Color of the checked pill (default `data`-neutral).                     |
+
+## Anatomy (any platform)
+
+- Pill: B612, 700 weight, `font.size.11`, uppercase, tracking `font.tracking.label`,
+  `space.4` × `space.10` padding, `radius.3`, 1px `border` outline.
+- Checked: background `s3`, border + text take the role color.
+- Hover (unchecked): background `s2`. Focus ring on the pill via `:focus-visible`.
+
+## Usage
+
+- Exclusive choice among 2–5 short options that should all stay visible; more than
+  that, use a [select](./select.md).
+- The radio flavor is a working form control with arrow-key group navigation for
+  free — prefer it; reach for `aria-pressed` buttons only when state lives in JS.
+- Wrap the radio flavor in a `<fieldset>` with a `<legend>` (may be visually hidden)
+  so the group is announced.

package/docs/components/select.md

@@ -0,0 +1,33 @@
+# Select
+
+A native `<select>` styled as an input, with a token-colored chevron.
+
+## Web
+
+```html
+<div class="juno-select">
+  <select class="juno-input">
+    <option>NOMINAL</option>
+    <option>CAUTION</option>
+    <option>WARNING</option>
+  </select>
+</div>
+```
+
+| Class                        | Effect                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------- |
+| `.juno-select`               | Wrapper; draws the chevron and positions it (inline-end).                                     |
+| `.juno-select > .juno-input` | The native `<select>` reuses the input box; `appearance:none`, room reserved for the chevron. |
+
+## Anatomy (any platform)
+
+- Box is identical to [input](./input.md): `s0` bg, neutral border, radius `4`,
+  density-aware padding.
+- Chevron: a CSS triangle in `label` color at `space.12` from the inline-end edge —
+  inherits a token, no SVG, mirrors under RTL.
+
+## Usage
+
+- Always a real `<select>` — keyboard and screen-reader behavior come for free.
+- Role classes (`.juno--<role>`) and `aria-invalid` tint the border exactly as on input.
+- Wrap in [`.juno-field`](./field.md) for a label.

package/docs/components/skeleton.md

@@ -0,0 +1,45 @@
+# Skeleton
+
+A shimmering placeholder that stands in for content not yet loaded — same shimmer as
+the [table](./table.md) row skeleton, generalized to text lines, blocks, circles, and
+aspect-ratio tiles. Zero JS; honors `prefers-reduced-motion` (shimmer → static) via the
+global motion contract.
+
+## Web
+
+```html
+<div aria-busy="true" aria-live="polite">
+  <span class="juno-skeleton juno-skeleton--circle" style="--juno-skeleton-h: 48px"></span>
+  <span class="juno-skeleton juno-skeleton--text" style="inline-size: 60%"></span>
+  <span class="juno-skeleton juno-skeleton--text"></span>
+  <span class="juno-skeleton juno-skeleton--block"></span>
+  <span class="juno-skeleton juno-skeleton--tile"></span>
+</div>
+```
+
+| Class                    | Effect                                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-skeleton`         | Shimmering bar; height `--juno-skeleton-h` (default `space.16`).                                                                                       |
+| `.juno-skeleton--text`   | One text line (`1em` tall, soft radius).                                                                                                               |
+| `.juno-skeleton--circle` | Round avatar / icon placeholder (square via the height).                                                                                               |
+| `.juno-skeleton--block`  | Larger surface (card / media), `space.56` tall.                                                                                                        |
+| `.juno-skeleton--tile`   | Content-box mode: sized by `--juno-skeleton-ratio` instead of a fixed height — the media-grid case (a tile matching a real image/card's aspect ratio). |
+| `--juno-skeleton-h`      | Override the height (any length).                                                                                                                      |
+| `--juno-skeleton-ratio`  | `.juno-skeleton--tile` only — the aspect ratio (default `1`, e.g. `16 / 9`).                                                                           |
+
+## Usage
+
+- Wrap the loading region in `aria-busy="true"` (and `aria-live="polite"`) so assistive
+  tech announces the pending state; swap in the real content when it arrives.
+- Mirror the **shape** of the content it replaces — line widths, an avatar circle, a
+  tile's aspect ratio — so the layout doesn't jump on load.
+- Width is layout-driven: set `inline-size` (e.g. `60%`) per line; height via the variant,
+  `--juno-skeleton-h`, or (for `--tile`) `--juno-skeleton-ratio`.
+
+## Anatomy (any platform)
+
+- Solid `s2` fill; the shimmer is a separate overlay layer sliding across on `transform`
+  only (never `background-position`), so it animates on the compositor instead of
+  repainting the gradient every frame — cheap even with hundreds of skeletons on screen.
+  Highlight band `s3` at 70% opacity, 1.2s ease-in-out loop. Radius `3` (block/tile `4`,
+  text `2`). Static fill under reduced motion.

package/docs/components/slider.md

@@ -0,0 +1,48 @@
+# Slider
+
+A track slider: a recessed channel with detent notches, an accent fill, and
+a gripped lever. **Value-driven** — junoui ships the look; the app sets the value % and
+owns drag / keyboard / ARIA (the same split as the overlays). Two sizes: standard (lever
+always full) and `--compact` (lever recedes to a slim marker until hover / focus / drag).
+
+## Web
+
+```html
+<div
+  class="juno-slider"
+  style="--juno-slider-pct: 72"
+  role="slider"
+  tabindex="0"
+  aria-valuenow="72"
+  aria-valuemin="0"
+  aria-valuemax="100"
+>
+  <span class="juno-slider__channel"></span>
+  <span class="juno-slider__lever"></span>
+</div>
+
+<!-- compact, managed accent -->
+<div class="juno-slider juno-slider--compact juno--target" style="--juno-slider-pct: 50">…</div>
+```
+
+| Property / class         | Effect                                                          |
+| ------------------------ | --------------------------------------------------------------- |
+| `--juno-slider-pct`      | 0–100; the app sets it. Drives the fill width + lever position. |
+| `.juno-slider__channel`  | `s0` channel, `control-edge` border, inset shadow, 10% detents. |
+| `.juno-slider__lever`    | Gripped lever (`space.26`×`space.40`) at the value.             |
+| `.juno-slider--compact`  | Lever shrinks to a marker until hover / focus / drag.           |
+| `.juno--<role>`          | Tints the fill (default `active`).                              |
+| `[aria-disabled="true"]` | Dimmed, not-allowed.                                            |
+
+## Anatomy (any platform)
+
+- Channel `space.20`, inset; faint detents every 10%; accent fill (8%→34%) to the value.
+- Lever 26×40 (standard), gradient `s3`→`s2`, three grips; compact shrinks to 10×22.
+- Lever/size transitions use `motion.duration.base` / `ease`.
+
+## Usage
+
+- The app owns the value: set `--juno-slider-pct` and keep `aria-valuenow` in sync; wire
+  pointer-drag and arrow/Page keys, plus `aria-valuetext` when the number needs units.
+  (`showcase/app.js` has a reference driver.)
+- Pair with a mono readout (`.juno-value`) of the current value.

package/docs/components/spark.md

@@ -0,0 +1,51 @@
+# Spark
+
+A sparkline **contract**, not a chart library. junoui deliberately ships no
+charting: your app computes the `<polyline>` points; `.juno-spark` supplies the
+size / stroke / role-color so every sparkline in a product matches.
+
+## Web
+
+```html
+<svg
+  class="juno-spark juno--nominal"
+  viewBox="0 0 120 24"
+  preserveAspectRatio="none"
+  aria-hidden="true"
+>
+  <polyline points="0,20 8,14 16,17 24,10 32,12 40,6 48,9" />
+</svg>
+```
+
+| Class / part    | Effect                                            |
+| --------------- | ------------------------------------------------- |
+| `.juno-spark`   | Block, full width, `space.24` tall.               |
+| `polyline`      | No fill, role stroke, 1.5 wide, round joins/caps. |
+| `.juno--<role>` | Line color (default `active`).                    |
+
+## Generating points
+
+16 samples into a `0 0 120 24` viewBox, y inverted (SVG y grows downward),
+with 2px headroom so the round cap never clips:
+
+```js
+const W = 120,
+  H = 24,
+  PAD = 2;
+const points = (samples) => {
+  const max = Math.max(...samples, 1);
+  const step = W / (samples.length - 1);
+  return samples
+    .map((v, i) => `${(i * step).toFixed(1)},${(H - PAD - (v / max) * (H - 2 * PAD)).toFixed(1)}`)
+    .join(' ');
+};
+```
+
+## Usage
+
+- Trend-at-a-glance in cards and table rows; pair with a [readout](./readout.md)
+  or [gauge](./gauge.md) for the current value.
+- A sparkline has no axes and is decorative — `aria-hidden="true"`, and put the
+  actual number in text next to it.
+- Needs axes, tooltips, more than one series? That's a chart — use a charting
+  library in the app, not this.

package/docs/components/status.md

@@ -0,0 +1,30 @@
+# Status dot
+
+A colored dot plus a text label — the most compact status signal.
+
+## Web
+
+```html
+<span class="juno-status juno--nominal"><span class="juno-status__dot"></span>NOMINAL</span>
+<span class="juno-status juno--active juno-status--live"
+  ><span class="juno-status__dot"></span>ACTIVE</span
+>
+```
+
+| Class                | Effect                                                                |
+| -------------------- | --------------------------------------------------------------------- |
+| `.juno-status`       | Inline dot + label, both in the role color. Default role = `nominal`. |
+| `.juno-status__dot`  | The dot (`size.dot.sm` = 8px).                                        |
+| `.juno-status--lg`   | Larger dot (`size.dot.md` = 10px) for legends.                        |
+| `.juno-status--live` | Blink animation (respects `prefers-reduced-motion`).                  |
+
+## Anatomy (any platform)
+
+- Dot: circle, `size.dot.sm` (8px), fill = role; legend variant `size.dot.md` (10px).
+- Label: `font.size.12`, tracking `font.tracking.label`, color = role.
+- Gap dot↔label: `space.8`.
+
+## Usage
+
+- Always show the text label; the dot color reinforces it, never replaces it.
+- `--live` pulse only for genuinely live/armed signals — not decoration.