@junoput01/junoui 0.2.0 → 0.4.0

package/docs/components/dock.md

@@ -0,0 +1,215 @@
+# Dock
+
+The bottom navigation bar of the app shell on narrow viewports — 3–5 primary
+destinations as icon-over-label tap targets. The phone-width counterpart of the
+[rail](./rail.md); the swap recipe is in [layout.md](../layout.md#app-shell).
+
+## Web
+
+```html
+<nav class="juno-dock" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-dock__label">Library</span>
+  </a>
+  <a class="juno-dock__item" href="/nodes">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    <span class="juno-dock__label">Nodes</span>
+  </a>
+</nav>
+```
+
+| Class / prop              | Effect                                                                                                                                                                                     |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-dock`              | Sticky bottom `s1` bar, 1px `border` seam on top, safe-area pad.                                                                                                                           |
+| `.juno-dock__item`        | Equal-width icon-over-label target, ≥ `size.tap.comfortable` tall.                                                                                                                         |
+| `.juno-dock__label`       | The text — truncates with an ellipsis, never wraps.                                                                                                                                        |
+| `[aria-current]`          | Active item: `s2` fill + 2px role edge on top. Attribute, not class.                                                                                                                       |
+| `.juno-dock--fixed`       | Pin to the viewport foot (`position: fixed`) — for page-scroll shells where sticky won't pin.                                                                                              |
+| `.juno-dock--pill`        | Floating rounded pill: big glyphs in circular bubbles, labels hidden, active = bubble fill.                                                                                                |
+| `.juno-dock--float`       | Pillbar-style floating capsule chrome (fixed, rounded, blurred, shadowed) — keeps icon+label items and the full-item active fill. Combine with `--icon` for the `--pill` look, decomposed. |
+| `.juno-dock--icon`        | Labels hidden, glyphs grow, active = bubble fill — standalone (no floating chrome required).                                                                                               |
+| `.juno-dock__bubble`      | Circular icon holder (`--pill`/`--icon`); pair with `.juno-icon-loader` to host the loading ring.                                                                                          |
+| `.juno-dock--collapsible` | Fold-to-a-circle variant driven by `--juno-dock-fold` — see [Collapsible](#collapsible-fold-driven).                                                                                       |
+| `.juno-dock__tray`        | The collapsible bar's item row — fades out as the fold closes.                                                                                                                             |
+| `.juno-dock__knob`        | The collapsed circle's face (a button); shown only under `data-juno-collapsed`.                                                                                                            |
+| `.juno--<role>`           | Active-edge color (default `active`).                                                                                                                                                      |
+| `--juno-dock-scale`       | Consumer-set scale factor (default `1`) applied to the whole bar — e.g. shrink on scroll.                                                                                                  |
+
+## Pill variant
+
+`.juno-dock--pill` turns the full-width bar into a floating rounded pill: big
+glyphs sit in circular `.juno-dock__bubble`s, the labels drop, and only the
+active tab's bubble fills. It floats out of flow (fixed), so the page scrolls
+_under_ it — reserve room on the scroller with
+`padding-block-end: var(--juno-dock-clearance)` (a published token that folds
+in the pill height + safe area, so it stays correct if the geometry changes).
+
+```html
+<nav class="juno-dock juno-dock--pill juno-hide-from-md" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page" aria-label="Library">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    </span>
+  </a>
+  <button class="juno-dock__item" aria-label="Nodes">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    </span>
+  </button>
+</nav>
+```
+
+- **Labels are hidden — every item MUST carry an `aria-label`** (on the
+  `<a>`/`<button>`). The glyph alone is not an accessible name.
+- Focus lands on the bubble, so the ring hugs the round target.
+- Pair every bubble with [`.juno-icon-loader`](./icon-loader.md) — it's the
+  concentric-stack contract, and having it on from the start means a loading
+  arc can appear later without touching the class list.
+
+### Section-loading ring
+
+The bubble doesn't invent its own ring: it is an
+[icon-loader](./icon-loader.md) host that overrides the ring's two dimensions
+(`--juno-icon-loader-ring` = the bubble diameter, `--juno-icon-loader-ring-width`
+= 2px), so the arc rings the bubble's **edge** rather than the glyph. Drop an
+indeterminate [arc](./loader.md) inside while the section loads; it eats no
+clicks, so the item still activates, and because the bubble's box is definite
+the arc appearing never resizes it. The app owns the state — add/remove
+`.juno-arc--indeterminate`; give the arc `role="status"` + `aria-label`.
+
+```html
+<span class="juno-dock__bubble juno-icon-loader">
+  <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-gear" /></svg>
+  <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+</span>
+```
+
+## Float variant
+
+`.juno-dock--float` lifts the pillbar's floating capsule chrome (fixed
+position, rounded shell, blur, shadow, off-edge margin) onto the dock's own
+item model — icon+label items stay, and the active item still fills (`s2` +
+role edge), just clipped to the capsule's rounded corners. It's `--pill`'s
+exterior without `--pill`'s interior; combine with `--icon` below to
+reproduce the original `--pill` look from two composable pieces. Out of flow
+(fixed), so reserve room on the scroller with
+`padding-block-end: var(--juno-dock-clearance)`.
+
+```html
+<nav class="juno-dock juno-dock--float juno-hide-from-md" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-dock__label">Library</span>
+  </a>
+  <a class="juno-dock__item" href="/nodes">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    <span class="juno-dock__label">Nodes</span>
+  </a>
+</nav>
+```
+
+## Icon variant
+
+`.juno-dock--icon` hides labels, grows the glyph, and moves the active state
+onto a circular `.juno-dock__bubble` — usable standalone on a plain
+sticky/`--fixed` bar for a compact, icon-only dock that stays in flow. Follows
+the same bubble contract as `--pill` (pair with
+[`.juno-icon-loader`](./icon-loader.md); see the pill section above for the
+section-loading ring).
+
+```html
+<nav class="juno-dock juno-dock--icon" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page" aria-label="Library">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    </span>
+  </a>
+  <button class="juno-dock__item" aria-label="Nodes">
+    <span class="juno-dock__bubble juno-icon-loader">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    </span>
+  </button>
+</nav>
+```
+
+- **Labels are hidden — every item MUST carry an `aria-label`.**
+- Combine with `.juno-dock--float` for a floating icon-only capsule (the
+  original `--pill` treatment, built from the two composable variants).
+
+## Shrink on scroll
+
+`--juno-dock-scale` (default `1`) drives a `transform: scale()` on the whole
+bar, anchored `bottom center`, so a consumer can compact the dock as the page
+scrolls without junoui shipping any scroll-listener JS:
+
+```js
+dockEl.style.setProperty('--juno-dock-scale', shrink ? '0.92' : '1');
+```
+
+The transition duration is authored through the motion scale, so
+`prefers-reduced-motion` collapses it to an instant snap with no
+component-specific media query.
+
+## Collapsible (fold-driven)
+
+`.juno-dock--collapsible` folds the whole bar into a single circular
+`.juno-dock__knob` at the inline-end edge, driven by one inherited custom prop
+the app writes — `--juno-dock-fold` (`0` open … `1` the circle). Write it per
+scroll frame for a gesture-tracked fold, or flip it `0`/`1` for a toggle.
+Compose with a fixed placement (`--pill`, `--float`, or `--fixed`).
+
+```html
+<nav class="juno-dock juno-dock--pill juno-dock--collapsible" aria-label="Primary">
+  <div class="juno-dock__tray">…the usual __item children…</div>
+  <button class="juno-dock__knob" aria-label="Show navigation">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-dots-three" /></svg>
+  </button>
+</nav>
+```
+
+Two phases, split at `--juno-dock-fold-split` (default `0.35`): first the bar
+**shrinks** in place to `--juno-dock-fold-scale` (default `0.78`, transform
+only — no relayout), then it **slides** shut to `--juno-dock-collapsed-size`.
+The width interpolates between two definite lengths (a transition cannot run
+to an intrinsic size); `--juno-dock-fold-smoothing` (default `90ms`) smooths
+over scroll-event discretization — anything longer visibly lags the finger.
+
+- `data-juno-collapsed` is the **end state**, set by the app only at fold = 1:
+  it hides the tray (`visibility` — the items leave the tab order) and reveals
+  the knob. Remove it the moment the fold reopens.
+- The knob **must** carry an `aria-label`. Collapsing while focus is inside
+  the tray is the app's edge — move focus to the knob first.
+- The fold's scale **replaces** the base `--juno-dock-scale` hook (one
+  transform slot). Transform-origin is the physical bottom right; RTL
+  consumers flip the origin and inset overrides together.
+- Knobs: `--juno-dock-collapsed-size` (default: one tap-comfortable bubble
+  plus the pill's padding and border), `--juno-dock-edge-gap` (what the
+  floating margins take from `100%` — default `2 × space.12`).
+
+## Anatomy (any platform)
+
+- Full-width bar on `s1`, hairline seam on the block-start edge; items split the
+  width evenly, icon above a `font.size.10` uppercase label.
+- Active = `s2` fill + `border.width.2` block-start edge in the role color —
+  the rail's active language rotated 90°.
+- Bottom padding extends into the safe area (`env(safe-area-inset-bottom)`)
+  so the home indicator never covers a target.
+
+## Usage
+
+- Keep it to 3–5 destinations; overflow belongs in a "More" item opening a
+  [drawer](./drawer.md) or [menu](./menu.md).
+- Sticky, not fixed: place it last inside the scrolling column and it pins
+  itself without overlapping content (no bottom-padding hacks). Best is the
+  [`.juno-app-shell`](../layout.md#app-shell) frame, whose `__main` region is
+  the scroller — the dock then sits at the body foot in flow.
+- **Short-page caveat:** sticky only pins while the column overflows. If the
+  _whole page_ scrolls and content is shorter than the viewport, the dock
+  lands mid-content. For that layout use `.juno-dock--fixed` (viewport-pinned)
+  and reserve its height at the page foot so it doesn't cover the last row.
+- Pair with the rail via the viewport helpers: `.juno-hide-below-md` on the
+  rail, `.juno-hide-from-md` on the dock. One nav is hidden from the
+  accessibility tree at a time, so both may share `aria-label="Primary"`.
+- The app sets `aria-current="page"` on the active item — junoui styles the
+  attribute so nav semantics stay honest.

package/docs/components/drawer.md

@@ -0,0 +1,100 @@
+# Drawer
+
+An edge-anchored `<dialog>` for secondary tasks and settings — same scrim and layer
+as the [modal](./modal.md), but it slides along one axis. Reuses `.juno-modal` for the
+surface; `.juno-drawer` re-pins and re-slides it.
+
+## Web
+
+```html
+<dialog class="juno-modal juno-drawer">
+  <!-- header / body / footer, same parts as a modal -->
+</dialog>
+
+<dialog class="juno-modal juno-drawer juno-drawer--start">…</dialog>
+<dialog class="juno-modal juno-drawer juno-drawer--bottom">…</dialog>
+```
+
+| Class                  | Effect                                                                                                                                     |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `.juno-drawer`         | 380px, full height, pinned to the **inline-end** edge.                                                                                     |
+| `.juno-drawer--start`  | Pins to the inline-start edge.                                                                                                             |
+| `.juno-drawer--bottom` | Full width, real bottom sheet: height via `--juno-sheet-h` (default `60dvh`), grab handle, rounded top corners, pinned to the bottom edge. |
+
+## Anatomy (any platform)
+
+- Slide in from its edge, `motion.duration.base` (200ms) / `ease.decel`. Same scrim
+  (`opacity.scrim`) and shadow (`shadow.3`) as the modal.
+- Edge anchoring is logical (`margin-inline`), so start/end mirror under RTL.
+
+## Bottom sheet (`.juno-drawer--bottom`)
+
+```html
+<dialog class="juno-modal juno-drawer juno-drawer--bottom" aria-labelledby="sheet-tag">
+  <div class="juno-sheet__handle" aria-hidden="true"></div>
+  <div class="juno-modal__stripe"></div>
+  <div class="juno-modal__head">
+    <span class="juno-modal__tag" id="sheet-tag">FILTERS</span>
+    <button class="juno-modal__close" autofocus aria-label="Close">✕</button>
+  </div>
+  <div class="juno-modal__body"><!-- scrolls on its own, pads past the home indicator --></div>
+</dialog>
+```
+
+- **Height knob:** `--juno-sheet-h` (default `60dvh`) sets the sheet's block-size;
+  `--juno-sheet-max` (default `92dvh`) caps it. Both are plain custom properties an
+  app can swap per open (or per breakpoint) for peek/half/full snap points — this is
+  CSS only. junoui does **not** ship the drag gesture that would let a user pull
+  between those points; that's stateful interaction and belongs to the app (or a
+  sibling `junoui-<framework>` package).
+- **Grab handle:** `.juno-sheet__handle` is a decorative bar the app renders as the
+  first child. Mark it `aria-hidden="true"` — the dialog's own `aria-labelledby`
+  (pointing at the title) remains the accessible name. It is not a button and has no
+  built-in drag behavior.
+- **Safe area lives on the body, not the sheet.** `.juno-drawer--bottom` itself has
+  `padding-block-end: 0`; `.juno-modal__body` carries
+  `calc(var(--juno-pad-surface-inline) + env(safe-area-inset-bottom, 0px))` so a
+  scrolling sheet never hides its last row under the home indicator (a sheet that
+  doesn't scroll still gets the clearance, since the padding sits on the body box
+  either way).
+- **`<dialog>` is the only supported sheet root.** `showModal()` gives you the
+  top-layer stacking, `::backdrop` scrim, ESC handling, scroll lock, and — critically —
+  focus trap **and** `inert` background for free: the rest of the page becomes
+  unfocusable and unclickable the moment the sheet opens, with no extra markup.
+  Hand-rolling a bottom sheet from a positioned `<div>` + a manual scrim `<button>`
+  reproduces the visual but silently drops all of that: no focus trap, no `inert`,
+  ESC and outside-dismiss have to be wired by hand and are easy to get wrong. Don't
+  do it — use `<dialog class="juno-modal juno-drawer juno-drawer--bottom">`.
+
+## The slide-over pattern
+
+The full production composition — scrim, end-anchored panel on `s1`, header row,
+scrolling body, pinned footer — assembled from existing parts. Copy-paste:
+
+```html
+<dialog class="juno-modal juno-drawer" aria-labelledby="tray-tag">
+  <div class="juno-modal__stripe"></div>
+  <div class="juno-modal__head">
+    <span class="juno-modal__tag" id="tray-tag">ACTIVE JOBS</span>
+    <button class="juno-modal__close" autofocus aria-label="Close">✕</button>
+  </div>
+  <div class="juno-modal__body"><!-- scrolls on its own --></div>
+  <div class="juno-modal__foot">
+    <button class="juno-btn juno-btn--ghost">CLEAR DONE</button>
+    <button class="juno-btn juno--warning">PAUSE ALL</button>
+  </div>
+</dialog>
+```
+
+`showModal()` provides the scrim (`::backdrop`, `opacity.scrim`) and z-order for
+free — no scrim element, no z-index bookkeeping. Head/body/foot are the modal
+parts; the drawer class only re-pins and re-slides the surface.
+
+## Usage
+
+- Settings panels, filters, detail editors that don't warrant leaving context.
+- Same `<dialog>` + `showModal()` contract as the modal.
+- **Phone widths (< `bp.sm`) are automatic:** side drawers cap at `85vw` so a
+  sliver of scrim stays visible (and tappable) for dismissal. The bottom drawer's
+  body always pads past the home indicator (`safe-area-inset-bottom`) — see
+  [Bottom sheet](#bottom-sheet-juno-drawer--bottom) above.

package/docs/components/field.md

@@ -0,0 +1,44 @@
+# Field
+
+Wraps any control with a label, optional help text, and an error message. Pure
+layout + the validation/required cue — it owns no state.
+
+## Web
+
+```html
+<div class="juno-field">
+  <label class="juno-field__label" for="cs">
+    Order ID <span class="juno-field__req" aria-hidden="true">*</span>
+  </label>
+  <input id="cs" class="juno-input juno-mono" type="text" aria-required="true" />
+  <span class="juno-field__help">Prefix + number</span>
+</div>
+
+<!-- error -->
+<div class="juno-field">
+  <label class="juno-field__label" for="sq">Error code</label>
+  <input id="sq" class="juno-input juno-mono" aria-invalid="true" aria-describedby="sq-e" />
+  <span class="juno-field__error" id="sq-e">Service unavailable</span>
+</div>
+```
+
+| Class                | Effect                                                                  |
+| -------------------- | ----------------------------------------------------------------------- |
+| `.juno-field`        | Vertical stack (label · control · help/error), `space.4` gap.           |
+| `.juno-field__label` | 10px uppercase, tracking `wider`, `label` color.                        |
+| `.juno-field__req`   | Required asterisk in `warning`. Decorative — pair with `aria-required`. |
+| `.juno-field__help`  | 11px `label` helper text.                                               |
+| `.juno-field__error` | 11px `warning` error text.                                              |
+
+## Anatomy (any platform)
+
+- Stack label → control → message; gap `space.4`.
+- Label: B612, `font.size.10`, uppercase, tracking `font.tracking.wider`, `label` color.
+- Help `font.size.11` `label`; error `font.size.11` `warning`.
+
+## Usage
+
+- One control per field. Tie `for`/`id`, and `aria-describedby` to the help/error id.
+- For errors, set `aria-invalid="true"` on the control (it re-colors its own border)
+  **and** show `.juno-field__error`. The asterisk is visual; required-ness is
+  `aria-required` on the control.

package/docs/components/fold-slot.md

@@ -0,0 +1,31 @@
+# Fold slot
+
+Animated presence for a member of any flex/grid row: instead of popping in and
+out of the DOM, the slot's width folds to zero, it fades, and at the end of the
+fold it leaves the tab order (`visibility`, discretely transitioned — instant
+coming in, end-of-fade going out). Keep the element mounted; flip
+`data-juno-in`. Zero JS.
+
+## Web
+
+```html
+<div class="juno-pillbar">
+  <button class="juno-fold" data-juno-in aria-label="Scroll to top">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-arrow-up" /></svg>
+  </button>
+  …other members…
+</div>
+```
+
+| Class / prop       | Effect                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `.juno-fold`       | The slot: definite width (`--juno-fold-size`), folds shut when `data-juno-in` is absent.                                        |
+| `[data-juno-in]`   | Present state — app-set. Absent = folded away, invisible, out of the tab order.                                                 |
+| `--juno-fold-size` | The slot's open width (default `size.tap.comfortable`) — must be definite, transitions cannot run to an intrinsic size.         |
+| `--juno-fold-gap`  | The row's flex/grid gap (default `0px`) — the folded slot swallows one gap with a negative margin so the row closes completely. |
+
+- The row's own width follows the slot, so the whole row slides open/closed.
+- `prefers-reduced-motion`: handled by the base layer (states still apply,
+  transition durations collapse).
+- Canonical use: transient toolbar actions — a scroll-to-top arrow, a
+  contextual button — whose arrival should slide the row rather than jump it.

package/docs/components/gauge.md

@@ -0,0 +1,48 @@
+# Gauge
+
+A determinate metric ring — CPU / RAM / DISK readouts with the value centered.
+The metric cousin of the [arc loader](./loader.md): the arc shows _progress of a
+task_; the gauge shows _the current level of a quantity_. Pure CSS
+(`conic-gradient`), no SVG in the markup.
+
+## Web
+
+```html
+<div
+  class="juno-gauge juno-gauge--sm juno--nominal"
+  style="--juno-gauge-value: 67"
+  role="meter"
+  aria-valuenow="67"
+  aria-valuemin="0"
+  aria-valuemax="100"
+  aria-label="Disk"
+>
+  <span class="juno-gauge__value">67</span>
+</div>
+<span class="juno-gauge__label">DISK</span>
+```
+
+| Class / prop         | Effect                                                                        |
+| -------------------- | ----------------------------------------------------------------------------- |
+| `.juno-gauge`        | 64px ring; sweep = `--juno-gauge-value` (0–100).                              |
+| `.juno-gauge--sm`    | 44px — dense card grids.                                                      |
+| `.juno-gauge--lg`    | 96px — hero metrics.                                                          |
+| `.juno-gauge__value` | Centered mono readout, role-colored.                                          |
+| `.juno-gauge__label` | Caption (a sibling — place it under or beside the ring).                      |
+| `.juno--<role>`      | Ring + value color (default `active`).                                        |
+| `--juno-gauge-value` | The value, set inline or from JS. Registered (`@property`) so it transitions. |
+
+## Anatomy (any platform)
+
+- Ring: track = `border` color, fill sweep = role, round the ring `size / 16`
+  stroke (4px at 64). Value: mono, bold, same color as the sweep.
+- Sweep starts at 12 o'clock, clockwise.
+
+## Usage
+
+- **Thresholds are app policy.** junoui ships no value → color rule; map it
+  yourself. The field-tested recipe: `v ≥ 90 → warning`, `≥ 75 → caution`,
+  `else nominal`.
+- Add `role="meter"` + `aria-valuenow/min/max` + a label; the ring alone is
+  invisible to assistive tech.
+- For task progress (this will finish), use a [loader](./loader.md) instead.

package/docs/components/icon-loader.md

@@ -0,0 +1,122 @@
+# Icon loader
+
+A control ringed by the spinning [arc](./loader.md#arc) while its section
+loads — the "this section is loading" affordance for a [rail](./rail.md),
+[dock](./dock.md), or [pillbar](./pillbar.md) item. What it wraps stays static
+on top; the arc rings it and takes no pointer events, so the item still clicks
+through. Zero JS in the CSS — the app toggles the arc's `--indeterminate` class
+to start/stop the spin.
+
+This is junoui's **only** concentric-ring mechanism. Anything that wants an arc
+around it composes `.juno-icon-loader` rather than re-rolling the geometry — the
+[dock](./dock.md#section-loading-ring)'s `__bubble` is the same wrapper with the
+ring resized to the bubble.
+
+## Web
+
+```html
+<a class="juno-rail__item" href="/library" aria-current="page">
+  <span class="juno-icon-loader">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+  </span>
+  <span class="juno-rail__label">Library</span>
+</a>
+```
+
+When the section finishes, remove `.juno-arc--indeterminate` (or the whole
+`.juno-arc`). For a progress ring instead of an endless spin, drop
+`--indeterminate` and set `--juno-progress` (0–100) on the `.juno-arc`.
+
+| Class / prop                    | Effect                                                              |
+| ------------------------------- | ------------------------------------------------------------------- |
+| `.juno-icon-loader`             | Single-cell grid wrapper — every child is centred on the same cell. |
+| `> *`                           | The ringed content, held above the ring.                            |
+| `> .juno-arc`                   | The ring — pointer-transparent, painted under the content.          |
+| `--juno-icon-loader-ring`       | Ring diameter (default `1.9em`, i.e. relative to the glyph).        |
+| `--juno-icon-loader-ring-width` | Ring stroke (default `0.14em`).                                     |
+| `.juno--<role>`                 | Ring color (default `active`).                                      |
+
+### Ringing something bigger than a glyph
+
+Both dimensions are custom props, so the same wrapper rings a 14px glyph and a
+44px bubble. Give the host a **definite** box and set the diameter to it — then
+the ring hugs the edge and the box does not resize when the arc appears:
+
+```css
+.my-avatar-loader {
+  --juno-icon-loader-ring: var(--juno-size-tap-comfortable);
+  --juno-icon-loader-ring-width: 2px;
+
+  inline-size: var(--juno-size-tap-comfortable);
+  block-size: var(--juno-size-tap-comfortable);
+}
+```
+
+That is exactly how `.juno-dock__bubble` gets its section-loading ring.
+
+### Ringing an arbitrary control (button, badge, avatar)
+
+The wrapper doesn't care what it wraps — swap the icon for any interactive
+control and the ring still hugs it without resizing its box. Set the ring
+diameter to the control's own size (its `--juno-size-*` or `em` value) and
+the control keeps its own footprint; the wrapper is the only thing that
+grows to fit the ring:
+
+```html
+<!-- 40px circular icon button -->
+<span
+  class="juno-icon-loader"
+  style="--juno-icon-loader-ring:40px;--juno-icon-loader-ring-width:2px"
+>
+  <button class="juno-btn juno-btn--icon" aria-label="More">&#8943;</button>
+  <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+</span>
+
+<!-- 14px inline badge — small ring, use --smooth to avoid stepped jitter -->
+<span
+  class="juno-icon-loader"
+  style="--juno-icon-loader-ring:14px;--juno-icon-loader-ring-width:2px"
+>
+  <span class="juno-badge juno-badge--micro">3</span>
+  <span
+    class="juno-arc juno-arc--indeterminate juno-arc--smooth"
+    role="status"
+    aria-label="Loading"
+  ></span>
+</span>
+```
+
+The ring is `pointer-events: none` and sits under the content (`z-index: 0`
+vs. `1`), so a wrapped `<button>` stays fully clickable.
+
+## Anatomy (any platform)
+
+- A wrapper that stacks the ring and what it rings on one centred cell; with no
+  explicit size the wrapper sizes to the larger of the two (normally the ring).
+- The ring color is the semantic role; a `.juno--loading`/`.juno--active`
+  ancestor tints it.
+
+## Usage
+
+- **Concentric via a single-cell grid, never `translate(-50%, -50%)`** — every
+  child shares one grid cell (`place-items: center`), so they're centered on
+  each other without any `transform`. The arc's rotation animation writes
+  `transform`, so a translate-based centering would be clobbered; keep the grid
+  approach if you re-roll the markup.
+- **Don't hand-roll a second ring.** If a component needs an arc around it,
+  compose this class and override the two ring props — one primitive keeps the
+  centring gotcha, the pointer-events rule, and the paint order in one place.
+  That includes bespoke overlay CSS elsewhere for a "this control is loading"
+  ring — delete it and wrap the control in `.juno-icon-loader` instead.
+- Below ~24px, add `.juno-arc--smooth` next to `--indeterminate` — the
+  default 12-step sweep (see [loader](./loader.md)) reads as jitter at that
+  size; `--smooth` makes it a continuous rotation.
+- Gate the spin to first load, not every background refetch — a nav icon that
+  blinks on every poll reads as broken. Add `--indeterminate` when a section
+  has no data yet; remove it once loaded.
+- The arc carries the loading semantics (`role="status"` +
+  `aria-label="Loading"`); the icon stays `aria-hidden`. Don't also mark the
+  nav item busy — one announcement is enough.
+- Respects reduced motion via the arc's own stepped, low-key animation; see
+  [loader](./loader.md).

package/docs/components/icon.md

@@ -0,0 +1,70 @@
+# Icon
+
+A zero-JS inline-SVG glyph. Icons ship as one **SVG sprite** of `<symbol>`s; you
+reference a symbol with `<use>`. The glyph inherits the current text color and sizes
+in `em`, so it tracks `font-size` and the `[data-juno-text]` scale.
+
+Set ships [Phosphor Icons](https://phosphoricons.com) (bold weight) — MIT-licensed,
+free to redistribute and sell. The bundle carries the license in `src/icons/LICENSE`
+and a banner in the generated sprite; keep both when you ship.
+
+## Web
+
+```html
+<!-- decorative — hide from assistive tech -->
+<svg class="juno-icon" aria-hidden="true">
+  <use href="node_modules/junoui/dist/icons/juno-icons.svg#juno-i-gear" />
+</svg>
+
+<!-- meaningful — label it -->
+<svg class="juno-icon juno-icon--lg juno-icon--role juno--warning" role="img" aria-label="Warning">
+  <use href="…/juno-icons.svg#juno-i-warning" />
+</svg>
+```
+
+Import path: `@junoput01/junoui/icons` resolves to the sprite.
+
+## Same-document refs (Safari fix)
+
+An **external** sprite reference (`<use href="…file.svg#id">`) intermittently
+fails to render in Safari — icons randomly vanish and reappear. The reliable
+path is a **same-document** reference (`<use href="#juno-i-gear">`), which needs
+the sprite living in the current document. Rather than hand-roll that injection
+in every app, import the shipped helper once:
+
+```js
+import '@junoput01/junoui/icons/inline'; // injects the sprite into the document once
+```
+
+```html
+<svg class="juno-icon" aria-hidden="true"><use href="#juno-i-gear" /></svg>
+```
+
+The module auto-installs on import in a browser (no-op server-side / before
+hydration) and is id-guarded, so importing it from many modules injects only
+once. It also exports `installJunoIcons(doc)` (default + named) for manual or
+multi-document (iframe) control. No bundler `?raw` loader needed.
+
+| Class              | Effect                                                        |
+| ------------------ | ------------------------------------------------------------- |
+| `.juno-icon`       | 1.25em square, `fill: currentColor`, baseline-aligned inline. |
+| `.juno-icon--sm`   | 1em (matches surrounding text).                               |
+| `.juno-icon--lg`   | 1.75em.                                                       |
+| `.juno-icon--xl`   | 2.5em.                                                        |
+| `.juno-icon--role` | Tint with `var(--juno-role)` instead of inherited text color. |
+| `--juno-icon-size` | Override the size directly (any length).                      |
+
+## Sizing & color
+
+- **Color** is `currentColor`: an icon inside colored text matches it. Add
+  `.juno-icon--role` + a `.juno--<role>` ancestor (or set `--juno-role`) to tint by
+  status. Always pair a status color with a text label — color is never the only signal.
+- **Size** is `em`-relative, so icons grow with the type scale and stay proportional
+  inside buttons / inputs. For a fixed pixel size set `--juno-icon-size: 20px`.
+
+## Adding / changing icons
+
+Drop an SVG into `src/icons/` (must use `currentColor`, a `viewBox`), then
+`npm run build:icons` (part of `npm run build`). The file name becomes the symbol id
+`juno-i-<name>`. Swapping icon sets is a source change in `src/icons/` — keep the new
+set's license file alongside.