@junoput01/junoui 0.2.0 → 0.4.0

package/docs/components/input.md

@@ -0,0 +1,45 @@
+# Input / textarea
+
+Text entry — inputs are precise. **Mono by default** (codes, IDs, tokens, values);
+add `.juno-input--sans` for free text. One class for `<input>` and `<textarea>`.
+
+## Web
+
+```html
+<input class="juno-input" type="text" value="UAL 519" />
+<!-- mono code -->
+<input class="juno-input juno-input--sans" placeholder="Type to edit…" />
+<!-- free text -->
+<input class="juno-input juno--target" value="38000" />
+<!-- managed -->
+<input class="juno-input" aria-invalid="true" value="7700" />
+<!-- error -->
+<input class="juno-input" disabled value="LOCKED" />
+<textarea class="juno-input juno-input--sans" rows="4"></textarea>
+```
+
+| Class / attr        | Effect                                                                               |
+| ------------------- | ------------------------------------------------------------------------------------ |
+| `.juno-input`       | Box: `control-surface` bg, `control-edge` border, radius `4`, density padding. Mono. |
+| `.juno-input--sans` | Sans font for free-text fields.                                                      |
+| `.juno--<role>`     | Re-colors the border (e.g. `target` for managed values).                             |
+| `[aria-invalid]`    | `warning` border + text, tied to the a11y attribute.                                 |
+| `:disabled`         | `s1` bg, `muted` text, not-allowed.                                                  |
+
+`--juno-role` defaults to `control-edge`, so the resting border is quiet; a role class
+or `aria-invalid` overrides it. **Focus** = `active` border + a 1px ring (replaces the
+base outline on inputs).
+
+## Anatomy (any platform)
+
+- **Control surface:** on dark panels the hairline border vanishes, so the edge lifts
+  to `muted` on an `s2` field; light mode keeps the true `border` on `s0`
+  (`--juno-control-surface` / `--juno-control-edge`).
+- Padding `--juno-pad-control-block` × `space.12` (density-aware). Radius `4`. Min
+  height `size.tap.min`. Font `font.size.14`, `data`; placeholder `muted`.
+
+## Usage
+
+- Mono is the default because most technical entry is codes/values; opt into `--sans`
+  for names and remarks. Textarea is usually `--sans`.
+- Wrap in [`.juno-field`](./field.md) for label + help/error.

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/load-state.md

@@ -0,0 +1,131 @@
+# Load state
+
+A vocabulary for every way a load can go, so nothing spins forever. junoui already had
+"resolving" (arc/beacon/bar, both indeterminate and determinate) and "layout known, not
+loaded yet" ([skeleton](./skeleton.md)). This adds the two treatments those don't cover —
+**working with no ETA** and **failed** — plus a table-agnostic **empty** state and an
+optional CSS-only switch to show exactly one at a time. Zero JS: junoui ships the look and
+the ARIA contract per state; deciding _when_ a load becomes a fault or an empty result is
+the app's job.
+
+## The decision table
+
+| State                           | Treatment                 | Why                                                          |
+| ------------------------------- | ------------------------- | ------------------------------------------------------------ |
+| No data yet, about to fetch     | `.juno-beacon`            | "no bytes yet" — a pulse, not a promise of progress.         |
+| Fetching, will resolve          | `.juno-arc` / `.juno-bar` | Real progress or a bounded wait — see [loader](./loader.md). |
+| Layout known, content pending   | `.juno-skeleton`          | Placeholder mirrors the shape of what's coming.              |
+| Server working, **no ETA**      | `.juno-shimmer`           | Motion _without_ a completion promise.                       |
+| Failed — **terminal**           | `.juno-fault`             | Static. A spinner on a 404 spins forever.                    |
+| Legitimately nothing — terminal | `.juno-empty`             | Static. Not a failure — don't tint it like one.              |
+
+`.juno-shimmer` and `.juno-fault` are the two treatments this ticket adds; `.juno-empty` is
+the generalized, table-agnostic form of the existing `.juno-table__empty` (same anatomy,
+usable outside a table).
+
+## Web
+
+### Shimmer — work in progress, no completion promise
+
+```html
+<div class="juno-shimmer" style="block-size: 120px;" aria-busy="true" aria-live="polite"></div>
+```
+
+Shares `.juno-skeleton`'s compositor-only band (same `@keyframes juno-skeleton-shimmer`,
+defined once in `skeleton.css`) — one shimmer implementation, applied to a solid fill
+instead of a placeholder shape. Override cadence with `--juno-shimmer-dur` (default
+`1.4s`).
+
+### Fault — terminal, never animates
+
+```html
+<div class="juno-fault" role="status">
+  <span class="juno-fault__icon" aria-hidden="true">!</span>
+  <p>Couldn't load this image.</p>
+</div>
+```
+
+Role defaults to `caution`; add a `.juno--<role>` class to recolor (`.juno--warning` for a
+harder failure) — never hardcode a color. `role="status"` on the fault itself is a
+per-region, polite announcement (this fired once, doesn't need to interrupt); for a
+page-level urgent message use [`.juno-alert`](./alert.md) with `role="alert"` instead.
+
+### Empty — legitimately nothing, terminal
+
+```html
+<div class="juno-empty">
+  <span class="juno-empty__icon" aria-hidden="true">∅</span>
+  <p>Nothing here yet.</p>
+</div>
+```
+
+### The switch (optional)
+
+CSS-only, one visible child at a time. The app sets `data-juno-state` on the parent as
+its fetch/rendition state changes; junoui does no state inference.
+
+```html
+<div class="juno-state" data-juno-state="processing">
+  <div data-juno-when="loading">
+    <div class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></div>
+  </div>
+  <div data-juno-when="processing" aria-busy="true" aria-live="polite">
+    <div class="juno-shimmer" style="block-size: 120px;"></div>
+  </div>
+  <div data-juno-when="error">
+    <div class="juno-fault" role="status">
+      <span class="juno-fault__icon" aria-hidden="true">!</span>
+      <p>Couldn't load this.</p>
+    </div>
+  </div>
+  <div data-juno-when="empty">
+    <div class="juno-empty">
+      <span class="juno-empty__icon" aria-hidden="true">∅</span>
+      <p>Nothing here yet.</p>
+    </div>
+  </div>
+</div>
+```
+
+| Class / attribute                   | Effect                                                                                                        |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `.juno-state`                       | Switch container.                                                                                             |
+| `[data-juno-when]`                  | A wrapper hidden by default; shown when its (space-separated) token list contains the parent's current state. |
+| `.juno-state[data-juno-state='…']`  | Set by the app: `loading` \| `processing` \| `error` \| `empty`.                                              |
+| `.juno-shimmer`                     | Compositor-only shimmer band on a solid fill (shares skeleton's `@keyframes`).                                |
+| `--juno-shimmer-dur`                | Shimmer cycle length (default `1.4s`).                                                                        |
+| `.juno-fault` / `.juno-fault__icon` | Terminal failure card. Role `caution` by default.                                                             |
+| `.juno-empty` / `.juno-empty__icon` | Terminal empty-result card. Neutral (`label`/`muted`), same anatomy as `.juno-table__empty`.                  |
+
+## Anatomy (any platform)
+
+- Shimmer: solid `s2` fill, `s3` highlight band at 70% opacity sliding on `transform`
+  only, 1.4s ease-in-out loop — identical mechanism to skeleton, different semantic use.
+- Fault: column, centered, `space.8` gap, `space.24` padding, role-colored text and icon
+  outline (`radius.8` box, `border.width.1`). Never animates.
+- Empty: column, centered, `space.12` gap, `space.56`/`space.24` padding, `label`/`muted`
+  text and icon outline (`radius.8` box). Never animates.
+
+## Usage
+
+- **Shimmer vs. skeleton:** skeleton implies a known layout waiting for content (first
+  paint); shimmer implies ongoing server-side work with no bound on when it finishes
+  (transcoding, indexing, re-encoding). Don't use skeleton for the latter — the moment a
+  skeleton is on screen, the layout it promises should be about to land.
+  Reference: `web/src/media/loadview.ts` (nexora) — spinner only while nothing has
+  started, shimmer for `processing`, static fault for `error`; "a spinner on a 404 spins
+  forever."
+- **Fault vs. alert:** a fault is a _region_ replacing content that failed to load
+  (an image tile, a card). An [alert](./alert.md) is a page-level message. Don't reach for
+  `.juno-alert` inside a grid cell.
+- **Empty is not a failure:** legitimately-zero-results (an empty search, a fresh account)
+  is a distinct terminal state from an error — keep it neutral, offer a next action
+  (a button/link) rather than an apology.
+- **The switch is optional.** Nothing stops rendering `.juno-shimmer` / `.juno-fault` /
+  `.juno-empty` directly and swapping them with app-side conditional rendering; `.juno-state`
+  exists for markup that's easier to keep all-present (e.g. server-rendered) and toggle
+  by attribute.
+- **a11y, per state:** `loading`/`processing` → `aria-busy="true"` (+ `aria-live="polite"`
+  if the region isn't otherwise announced); `.juno-fault` → `role="status"` on itself;
+  `.juno-empty` → no extra role, it's static content. See
+  [accessibility.md](../accessibility.md) for the full per-component ARIA contract.

package/docs/components/loader.md

@@ -0,0 +1,88 @@
+# 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--smooth`                                 | With `--indeterminate`: continuous (linear) rotation instead of the 12-step sweep — use under ~24px, where the steps read as jitter. |
+| `--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`.
+
+> To ring an _arbitrary control_ (a button, a badge, an avatar) without
+> changing its own box, don't reposition `.juno-arc` by hand — compose
+> [`.juno-icon-loader`](./icon-loader.md), junoui's one ring-a-thing
+> primitive. It stacks the arc and the control on a single grid cell sized
+> off two custom props, so nothing you wrap ever resizes when the ring
+> appears.
+
+## 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.