@junoput01/junoui 0.2.0 → 0.3.0

package/docs/components/list.md

@@ -0,0 +1,76 @@
+# List
+
+Grouped rows for vertical data organization — the settings-screen pattern.
+Labeled groups of full-width rows; each row carries a leading icon, a label
+(with optional support line), and a trailing value, control, or drill-in
+chevron. The phone-first sibling of the [table](./table.md): use a list when
+each record is a _destination or setting_, a table when you compare columns.
+
+## Web
+
+```html
+<section class="juno-list">
+  <h3 class="juno-list__header">Playback</h3>
+  <ul class="juno-list__group">
+    <li>
+      <a class="juno-list__row" href="/settings/quality">
+        <svg class="juno-icon juno-list__icon" aria-hidden="true">
+          <use href="…#juno-i-sliders" />
+        </svg>
+        <span class="juno-list__main">
+          <span class="juno-list__label">Quality</span>
+          <span class="juno-list__support">Streaming resolution</span>
+        </span>
+        <span class="juno-list__value">1080p</span>
+        <svg class="juno-icon juno-list__chevron" aria-hidden="true">
+          <use href="…#juno-i-caret-right" />
+        </svg>
+      </a>
+    </li>
+    <li>
+      <div class="juno-list__row">
+        <span class="juno-list__main"><span class="juno-list__label">Autoplay</span></span>
+        <label class="juno-switch juno-switch--sm"
+          ><input class="juno-switch__input" type="checkbox" role="switch" checked /><span
+            class="juno-switch__track"
+          ></span
+        ></label>
+      </div>
+    </li>
+  </ul>
+</section>
+```
+
+| Class                 | Effect                                                              |
+| --------------------- | ------------------------------------------------------------------- |
+| `.juno-list`          | Stack of header + group(s).                                         |
+| `.juno-list__header`  | Uppercase group label above the group.                              |
+| `.juno-list__group`   | `s1` card frame; rows divided by hairlines, corners rounded.        |
+| `.juno-list__row`     | Row ≥ `size.tap.comfortable`; `<a>`/`<button>` rows get hover.      |
+| `.juno-list__icon`    | Leading glyph, label-toned.                                         |
+| `.juno-list__main`    | Label + optional support line; truncates, takes the flexible space. |
+| `.juno-list__label`   | Primary text.                                                       |
+| `.juno-list__support` | Secondary line under the label.                                     |
+| `.juno-list__value`   | Trailing mono value.                                                |
+| `.juno-list__chevron` | Drill-in caret (`caret-right`), muted.                              |
+
+## Anatomy (any platform)
+
+- Group = `s1` surface, hairline `border`, `radius.8`; rows split by hairlines
+  drawn between rows only (no doubled edges).
+- Row ≥ `size.tap.comfortable` tall, `space.16` inline padding, `space.12`
+  gap between slots. Label `font.size.13` data-toned; support `font.size.11`
+  label-toned; value mono `font.size.12`.
+- Only interactive rows respond: hover/press fills `s2`.
+
+## Usage
+
+- Trailing slot takes whatever fits the row's job: a mono value, a
+  [badge](./badge.md), a [switch](./switch.md), or the chevron when the row
+  drills into a detail view (pair the pushed view with a
+  [navbar](./navbar.md) back control).
+- A chevron row must be an `<a>` (or `<button>`) — the whole row is the tap
+  target, never just the caret.
+- Static key→value screens can skip `<ul>`/`<li>` and stack `div.juno-list__row`
+  directly inside `.juno-list__group`; keep list semantics when rows navigate.
+- Don't put two controls in one row — a row is one target. Split it.

package/docs/components/loader.md

@@ -0,0 +1,80 @@
+# Loaders (arc · beacon · linear)
+
+Three progress indicators, each in an **indeterminate** form (loops on its own,
+CSS only) and a **determinate** form (tracks real progress).
+
+## Progress API
+
+Determinate variants read `--juno-progress` (0–100). Set it inline or from JS:
+
+```js
+el.style.setProperty('--juno-progress', 63);
+```
+
+Color comes from `--juno-role` (default `active`); add a `.juno--<role>` class to recolor.
+
+## Arc — circular ring
+
+```html
+<!-- indeterminate -->
+<div class="juno-arc juno-arc--indeterminate"></div>
+
+<!-- determinate (label as a sibling so the ring mask doesn't clip it) -->
+<div style="position:relative;width:76px;height:76px;">
+  <div class="juno-arc" style="--juno-progress:63;"></div>
+  <span class="juno-arc__label">63%</span>
+</div>
+```
+
+| Class / var                                         | Effect                                                           |
+| --------------------------------------------------- | ---------------------------------------------------------------- |
+| `.juno-arc`                                         | Ring; determinate sweep = progress (conic gradient + ring mask). |
+| `.juno-arc--indeterminate`                          | 12-step mechanical rotation.                                     |
+| `--juno-arc-size` (76px) · `--juno-arc-width` (4px) | Diameter / stroke.                                               |
+
+> The ring uses a CSS mask, which clips children. Put `.juno-arc__label` as a
+> **sibling** over a positioned wrapper, not inside `.juno-arc`.
+
+## Beacon — radiating pulse
+
+```html
+<!-- indeterminate -->
+<div class="juno-beacon"><span class="juno-beacon__core"></span></div>
+
+<!-- determinate: fill grows centre → rim -->
+<div class="juno-beacon juno-beacon--determinate" style="--juno-progress:63;">
+  <span class="juno-beacon__track"></span>
+  <span class="juno-beacon__fill"></span>
+  <span class="juno-beacon__hub"></span>
+  <span class="juno-beacon__label">63%</span>
+</div>
+```
+
+| Part                                       | Role                                            |
+| ------------------------------------------ | ----------------------------------------------- |
+| `.juno-beacon`                             | Container; emits two staggered pulse rings.     |
+| `.juno-beacon__core`                       | Centre dot (indeterminate).                     |
+| `.juno-beacon--determinate`                | Switches to a centre→rim fill mask by progress. |
+| `__track` / `__fill` / `__hub` / `__label` | Ring track, growing fill, centre hub, readout.  |
+
+## Linear — bar
+
+```html
+<!-- indeterminate -->
+<div class="juno-bar juno-bar--indeterminate"><span class="juno-bar__fill"></span></div>
+
+<!-- determinate -->
+<div class="juno-bar" style="--juno-progress:63;"><span class="juno-bar__fill"></span></div>
+```
+
+| Class                      | Effect                                |
+| -------------------------- | ------------------------------------- |
+| `.juno-bar`                | Track (`s2`, 6px, radius `radius.3`). |
+| `.juno-bar__fill`          | Fill; width = progress, color = role. |
+| `.juno-bar--indeterminate` | A 40% segment slides across.          |
+
+## Notes
+
+- Indeterminate forms need no JS. All animations respect `prefers-reduced-motion`
+  (slowed to near-static by the base layer).
+- Use determinate whenever real progress is known — it reads as more trustworthy.

package/docs/components/menu.md

@@ -0,0 +1,54 @@
+# Menu / Dropdown
+
+A list of immediate actions anchored to its trigger — with section dividers, keyboard
+shortcuts, and a destructive item set apart by `warning`. Built on the **native Popover
+API** (top layer — never clipped, never z-index-trapped): open/close, light-dismiss, and
+ESC are free. junoui ships the look; **the app owns** roving focus (arrow keys).
+
+## Web
+
+```html
+<button popovertarget="acts" aria-haspopup="menu">ACTIONS ▾</button>
+<ul class="juno-menu" id="acts" popover role="menu">
+  <li>
+    <button class="juno-menu__item" role="menuitem" popovertarget="acts" popovertargetaction="hide">
+      <span class="juno-menu__icon">⤓</span>Import data
+      <span class="juno-menu__kbd">⌘O</span>
+    </button>
+  </li>
+  <li class="juno-menu__sep" role="separator"></li>
+  <li>
+    <button
+      class="juno-menu__item juno--warning"
+      role="menuitem"
+      popovertarget="acts"
+      popovertargetaction="hide"
+    >
+      <span class="juno-menu__icon">⨯</span>Delete project
+    </button>
+  </li>
+</ul>
+```
+
+| Class                            | Effect                                                       |
+| -------------------------------- | ------------------------------------------------------------ |
+| `.juno-menu`                     | 256px `s2` panel, radius `5`, shadow `2`. Top-layer, pinned. |
+| `.juno-menu__item`               | Action row; hover/focus → `s3`. Icon + label + shortcut.     |
+| `.juno-menu__item.juno--warning` | Destructive item; text + icon `warning`, hover tinted.       |
+| `.juno-menu__icon` / `__kbd`     | Leading glyph (`label`) / trailing shortcut (`muted`).       |
+| `.juno-menu__sep`                | Section divider.                                             |
+
+## Anatomy (any platform)
+
+- Top-layer surface `s2` + `shadow.2`, pinned below the invoker with a `space.8` gap;
+  flips to stay on-screen. Rise + fade, `motion.duration.quick` (140ms) / `ease.decel`,
+  animated with `@starting-style` + `allow-discrete`.
+
+## Usage
+
+- Real `<button>` items inside `role="menu"` / `role="menuitem"`. Each item carries
+  `popovertarget="<id>" popovertargetaction="hide"` so activating it closes the menu with
+  no JS; the app still wires arrow-key roving focus + Enter.
+- `popovertarget` on the trigger handles open / ESC / outside-click and exposes
+  `aria-expanded` implicitly. Keep `aria-haspopup="menu"` for intent.
+- One destructive item max, separated by a divider and marked `.juno--warning`.

package/docs/components/modal.md

@@ -0,0 +1,52 @@
+# Modal / Dialog
+
+A centered, scrim-backed `<dialog>` for decisions that must block the deck. junoui
+ships the look + entry motion; **the app owns** `showModal()`/`close()`, focus-trapping,
+and ESC/scrim-click dismiss (native `<dialog>` gives you most of this free).
+
+## Web
+
+```html
+<dialog class="juno-modal">
+  <div class="juno-modal__stripe"></div>
+  <div class="juno-modal__head">
+    <span class="juno-modal__tag">DEPLOYMENT</span>
+    <button class="juno-modal__close" aria-label="Close">✕</button>
+  </div>
+  <div class="juno-modal__body">
+    <h2 class="juno-modal__title">Promote build to production?</h2>
+    <p class="juno-modal__text">This routes production traffic to the new version…</p>
+    <div class="juno-modal__foot">
+      <button class="juno-btn juno-btn--ghost">CANCEL</button>
+      <button class="juno-btn">PROMOTE BUILD</button>
+    </div>
+  </div>
+</dialog>
+
+<!-- destructive -->
+<dialog class="juno-modal juno--warning">…</dialog>
+```
+
+| Class                                      | Effect                                                              |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| `.juno-modal`                              | 440px panel, `s1`, radius `8`, shadow `3` (e3), `z.overlay` (4000). |
+| `.juno-modal__stripe`                      | Top accent bar in `--juno-role`.                                    |
+| `.juno-modal__head` / `__tag` / `__close`  | Tag row + close button (`size.tap.min`).                            |
+| `.juno-modal__title` / `__text` / `__foot` | Title (20px light), body, right-aligned actions.                    |
+| `.juno--warning`                           | Destructive: stripe + tag turn `warning`.                           |
+| `::backdrop`                               | Dark scrim at `opacity.scrim` + 1.5px blur.                         |
+
+## Anatomy (any platform)
+
+- Enter: scrim fades, panel scales 0.97→1 + rises, `motion.duration.deliberate`
+  (300ms) / `ease.decel`. Exit accelerates. `prefers-reduced-motion` collapses it.
+- Elevation = `z.overlay` + `shadow.3`, paired. One scrim at a time — never stack modals.
+
+## Usage
+
+- Use a real `<dialog>` + `showModal()` so focus-trap, ESC, and inert background come free.
+- Destructive actions: `.juno--warning` + a deliberate confirm (`.juno-btn juno--warning`).
+- For edge-anchored panels that don't block, use the [drawer](./drawer.md).
+- **Phone widths (< `bp.sm`) are automatic:** the centered dialog becomes a
+  bottom sheet — full-width, top corners rounded, sliding up, footer buttons
+  stretched, content padded past the home indicator. No extra class.

package/docs/components/navbar.md

@@ -0,0 +1,53 @@
+# Navbar
+
+The top bar of a pushed view on phones: a back control on the start edge —
+**always present**, so any screen can unwind — a centered truncating title,
+and trailing actions. junoui ships the look; the app owns the navigation
+stack (what "back" does and where it goes).
+
+## Web
+
+```html
+<header class="juno-navbar">
+  <a class="juno-navbar__back" href="/library">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-caret-left" /></svg>
+    <span class="juno-navbar__back-label">Library</span>
+  </a>
+  <h1 class="juno-navbar__title">Album</h1>
+  <div class="juno-navbar__actions">
+    <button class="juno-btn juno-btn--sm juno-btn--ghost">EDIT</button>
+  </div>
+</header>
+```
+
+| Class                      | Effect                                                             |
+| -------------------------- | ------------------------------------------------------------------ |
+| `.juno-navbar`             | Sticky top `s1` bar, hairline seam below, safe-area padded on top. |
+| `.juno-navbar__back`       | Start-edge back control, active-toned; ≥ `size.tap.comfortable`.   |
+| `.juno-navbar__back-label` | Parent-view name next to the caret — truncates at 14ch.            |
+| `.juno-navbar__title`      | Centered `font.size.14` title; truncates, never wraps.             |
+| `.juno-navbar__actions`    | Trailing cluster for small buttons / icons.                        |
+
+## Anatomy (any platform)
+
+- Three-column grid: equal flexible sides keep the title optically centered;
+  when space runs out the title truncates first, never sliding under the back
+  control (back/actions keep their own truncated width).
+- Back = `caret.left` + the **parent view's name** in the active color; the
+  caret flips under RTL. Title `font.size.14` semibold, data-toned.
+- Bar ≥ `size.tap.comfortable` tall; top padding extends into
+  `env(safe-area-inset-top)` so the notch never covers it.
+
+## Usage
+
+- **Tab + stack recipe:** the [dock](./dock.md)/[pillbar](./pillbar.md)
+  switches sections; inside a section, drilling into a
+  [list](./list.md) row pushes a view whose navbar backs out one level.
+  Full shell recipe: [layout.md](../layout.md#app-shell).
+- The back control is a real `<a>` to the parent route (deep-linkable), or a
+  `<button>` when the app drives history. Label it with the parent view's
+  name; keep `aria-label="Back"` when only the caret fits.
+- Root views (tab landing screens) have no parent — there, swap the back slot
+  for a brand/title block or leave it empty; every _pushed_ view keeps it.
+- One `<h1>` per document — pushed views' navbar titles are usually the
+  screen's `<h1>`.

package/docs/components/pagination.md

@@ -0,0 +1,42 @@
+# Pagination
+
+A row of page controls — prev / next plus numbered pages, with the current page marked
+`aria-current="page"`. Built on a real `<nav>`; the app owns which page is active and
+renders the list. Zero JS.
+
+## Web
+
+```html
+<nav class="juno-pagination" aria-label="Pagination">
+  <button class="juno-pagination__item" aria-label="Previous page" disabled>
+    <svg class="juno-icon juno-icon--sm" aria-hidden="true"><use href="…#juno-i-caret-left" /></svg>
+  </button>
+  <button class="juno-pagination__item" aria-current="page">1</button>
+  <button class="juno-pagination__item">2</button>
+  <button class="juno-pagination__item">3</button>
+  <span class="juno-pagination__gap">…</span>
+  <button class="juno-pagination__item">9</button>
+  <button class="juno-pagination__item" aria-label="Next page">
+    <svg class="juno-icon juno-icon--sm" aria-hidden="true">
+      <use href="…#juno-i-caret-right" />
+    </svg>
+  </button>
+</nav>
+```
+
+| Part / attr              | Effect                                                 |
+| ------------------------ | ------------------------------------------------------ |
+| `.juno-pagination`       | `<nav>` flex row; wraps on narrow widths.              |
+| `.juno-pagination__item` | Page / prev / next button (44px tap target, mono).     |
+| `[aria-current="page"]`  | Current page — filled `active` accent, non-actionable. |
+| `:disabled`              | Dim prev / next at the ends.                           |
+| `.juno-pagination__gap`  | The `…` between page ranges (not a button).            |
+
+## Usage
+
+- `aria-label="Pagination"` on the `<nav>`; `aria-current="page"` on the active page;
+  `aria-label` on the icon-only prev / next ("Previous page").
+- The app computes the window of page numbers + where `…` falls, and disables prev / next
+  at the ends.
+- For a simple "‹ Prev / Next ›" pair (as in the [table](./table.md) footer), use two
+  `__item` buttons without the numbered list.

package/docs/components/pillbar.md

@@ -0,0 +1,64 @@
+# 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--<role>`        | Active color (default `active`).                                                                                                                   |
+
+## 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.
+- 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/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.