@junoput01/junoui 0.2.0 → 0.3.0

package/docs/components/skeleton.md

@@ -0,0 +1,38 @@
+# Skeleton
+
+A shimmering placeholder that stands in for content not yet loaded — same shimmer as
+the [table](./table.md) row skeleton, generalized to text lines, blocks, and circles.
+Zero JS; honors `prefers-reduced-motion` (shimmer → static).
+
+## Web
+
+```html
+<div aria-busy="true" aria-live="polite">
+  <span class="juno-skeleton juno-skeleton--circle" style="--juno-skeleton-h: 48px"></span>
+  <span class="juno-skeleton juno-skeleton--text" style="inline-size: 60%"></span>
+  <span class="juno-skeleton juno-skeleton--text"></span>
+  <span class="juno-skeleton juno-skeleton--block"></span>
+</div>
+```
+
+| Class                    | Effect                                                           |
+| ------------------------ | ---------------------------------------------------------------- |
+| `.juno-skeleton`         | Shimmering bar; height `--juno-skeleton-h` (default `space.16`). |
+| `.juno-skeleton--text`   | One text line (`1em` tall, soft radius).                         |
+| `.juno-skeleton--circle` | Round avatar / icon placeholder (square via the height).         |
+| `.juno-skeleton--block`  | Larger surface (card / media), `space.56` tall.                  |
+| `--juno-skeleton-h`      | Override the height (any length).                                |
+
+## Usage
+
+- Wrap the loading region in `aria-busy="true"` (and `aria-live="polite"`) so assistive
+  tech announces the pending state; swap in the real content when it arrives.
+- Mirror the **shape** of the content it replaces — line widths, an avatar circle — so
+  the layout doesn't jump on load.
+- Width is layout-driven: set `inline-size` (e.g. `60%`) per line; height via the variant
+  or `--juno-skeleton-h`.
+
+## Anatomy (any platform)
+
+- `s2`→`s3`→`s2` horizontal gradient, `background-size: 200%`, animated 1.2s ease-in-out
+  loop. Radius `3` (block `4`, text `2`). Static fill under reduced-motion.

package/docs/components/slider.md

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

package/docs/components/spark.md

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

package/docs/components/status.md

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

package/docs/components/stepper.md

@@ -0,0 +1,46 @@
+# Stepper
+
+A sequence of steps with numbered markers and connectors that shows progress through a
+multi-step flow. Each step carries `data-state` — `complete` · `current` · `upcoming`;
+the active one gets `aria-current="step"`. Built on a real `<ol>`; the app sets the
+states. Zero JS. Reads `--juno-role` (default `active`) for the accent.
+
+## Web
+
+```html
+<ol class="juno-stepper">
+  <li class="juno-stepper__step" data-state="complete">
+    <span class="juno-stepper__marker">
+      <svg class="juno-icon juno-icon--sm" aria-hidden="true"><use href="…#juno-i-check" /></svg>
+    </span>
+    <span class="juno-stepper__label">Plan</span>
+  </li>
+  <li class="juno-stepper__step" data-state="current" aria-current="step">
+    <span class="juno-stepper__marker">2</span>
+    <span class="juno-stepper__label">Build</span>
+  </li>
+  <li class="juno-stepper__step" data-state="upcoming">
+    <span class="juno-stepper__marker">3</span>
+    <span class="juno-stepper__label">Ship</span>
+  </li>
+</ol>
+```
+
+| Part / attr               | Effect                                                      |
+| ------------------------- | ----------------------------------------------------------- |
+| `.juno-stepper`           | `<ol>` row; `--juno-stepper-marker` sizes the circle.       |
+| `.juno-stepper__step`     | One step; set `data-state` + connector lights when reached. |
+| `.juno-stepper__marker`   | Numbered circle (or a `check` icon when complete).          |
+| `.juno-stepper__label`    | Step caption.                                               |
+| `data-state="complete"`   | Filled accent marker + lit connector.                       |
+| `data-state="current"`    | Ringed accent marker; pair with `aria-current="step"`.      |
+| `data-state="upcoming"`   | Muted marker + connector.                                   |
+| `.juno-stepper--vertical` | Stack steps; connector runs down the marker column.         |
+
+## Usage
+
+- Set `aria-current="step"` on the current step so assistive tech announces position.
+- The **state drives the color**, not vice-versa — `complete` and `current` both light
+  the accent + their incoming connector; `upcoming` stays muted.
+- Use a `check` icon for completed markers, the number for current / upcoming.
+- Change the accent with a role class on `.juno-stepper` (e.g. `.juno--nominal`).

package/docs/components/switch.md

@@ -0,0 +1,38 @@
+# Switch
+
+A labeled rocker: a squared track that lights green (`nominal`) when ON, with an
+**ON / OFF legend** and a sliding knob. A real checkbox drives it; the app owns state.
+
+## Web
+
+```html
+<label class="juno-switch">
+  <input class="juno-switch__input" type="checkbox" role="switch" checked />
+  <span class="juno-switch__track"></span>
+  <span>AUTO-SCALING</span>
+</label>
+```
+
+| Class                    | Effect                                                                             |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| `.juno-switch`           | Inline-flex label row; `gap-control`, `data` text.                                 |
+| `.juno-switch__input`    | The checkbox — visually hidden, still focusable / tab-ordered.                     |
+| `.juno-switch__track`    | 70 × `space.28` track; OFF = `control-edge`, ON = role (`nominal`). Legend + knob. |
+| `.juno-switch--sm`       | Quiet 40 × `space.20` track: no printed legend, smaller knob. For per-row toggles. |
+| `.juno--<role>`          | On-color of the track (put on `__track`).                                          |
+| `:checked` / `:disabled` | Slides the knob to inline-end + legend ON / dims.                                  |
+
+## Anatomy (any platform)
+
+- Track 70 × `space.28`, radius `4`, inset shadow. Knob 26 × 22, radius `4`, gradient
+  `s3`→`s2`, three grip lines; printed ON / OFF legend (mono 10px, `muted` → role).
+- Knob travels via `inset-inline-start` (mirrors under RTL), `motion.duration.quick`;
+  honors `prefers-reduced-motion`.
+
+## Usage
+
+- Switch = immediate state change (a setting that takes effect now). For form values
+  submitted later, prefer a [checkbox](./checkbox.md).
+- The default rocker is for settings panels; `--sm` for columns of row toggles
+  (plugin lists, table rows) where five rockers would shout.
+- Add `role="switch"`; the app toggles `checked` + `aria-checked`.

package/docs/components/table.md

@@ -0,0 +1,126 @@
+# Table / data grid
+
+Dense, scannable rows that read like instrument readouts — numbers in mono and
+right-aligned, semantic color reserved for status, and the active-cyan rail marking the
+row in focus. junoui dresses a **real `<table>`** and ships the **look + the ARIA
+contract**; the app owns sort, selection, inline-edit, pagination, and filtering.
+
+## Web
+
+```html
+<div class="juno-table-scroll">
+  <table class="juno-table juno-table--zebra juno-table--sticky">
+    <thead>
+      <tr>
+        <th aria-sort="ascending">SERVICE</th>
+        <th class="juno-table__num" aria-sort="none">CPU</th>
+        <th>STATUS</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr aria-selected="true">
+        <td class="juno-table__id">api-gateway</td>
+        <td class="juno-table__num">62</td>
+        <td><span class="juno-badge juno-badge--soft juno--nominal">HEALTHY</span></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+| Class                      | Effect                                                                  |
+| -------------------------- | ----------------------------------------------------------------------- |
+| `.juno-table-scroll`       | Overflow-scrolling viewport (`max-block-size: 480px`) + thin scrollbar. |
+| `.juno-table`              | The `<table>`: header `s2`, mono numerics, `border` row rules.          |
+| `.juno-table--sticky`      | Header holds (`position: sticky`) while the body scrolls.               |
+| `.juno-table--zebra`       | Stripes even body rows (`s2` dark / `s1` light).                        |
+| `.juno-table--compact`     | Tighter row padding (per-table; independent of global density).         |
+| `.juno-table--stack`       | Phone mode: rows become label/value cards below 480px (see below).      |
+| `th[aria-sort]`            | Marks a sortable column; `ascending` / `descending` draw the arrow.     |
+| `tr[aria-selected="true"]` | Active rail (left) + cyan row wash.                                     |
+
+### Cell flavors
+
+| Class                   | Use                                                                                                                        |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `.juno-table__id`       | Identifier — mono, bold (codes, hostnames, IDs).                                                                           |
+| `.juno-table__num`      | Numeric — mono, bold, end-aligned (measured values).                                                                       |
+| `.juno-table__mono`     | Secondary mono (routes, sub-codes) — quieter `label` color.                                                                |
+| `.juno-table__time`     | Timestamp — mono, end-aligned, muted.                                                                                      |
+| `.juno-table__trend`    | Role-colored mono delta; author supplies the `▲` / `▼` + sign.                                                             |
+| `.juno-table__meter`    | Inline track + role fill + value; set `--juno-table-fill` (0–100).                                                         |
+| `.juno-table__actions`  | Icon buttons (`__action`), revealed on row hover / focus.                                                                  |
+| `.juno-badge--soft`     | Status as a low-fill role chip (see [badge](./badge.md)).                                                                  |
+| `.juno-table__check`    | Selection-column cell (44px, centered). Holds a `.juno-checkbox`.                                                          |
+| `.juno-table__editable` | Editable cell: dashed `__mark` underline + hover ring. App swaps `__mark` for a `.juno-table__edit-input` on double-click. |
+
+### Overflow (set on a cell)
+
+| Class                   | Behavior                                                              |
+| ----------------------- | --------------------------------------------------------------------- |
+| `.juno-table__truncate` | Single line + ellipsis (default). Pair with a `title` / tooltip.      |
+| `.juno-table__clamp`    | Two lines, then ellipsis. Wrap the text in `.juno-table__clamp-text`. |
+| `.juno-table__wrap`     | Full value; row grows. Reserve for one descriptive column.            |
+
+All three cap at `--juno-cell-max` (default 240px).
+
+### Stacked mode (phone widths)
+
+Wide tables don't shrink — they either scroll (the default: `.juno-table-scroll`
+scrolls sideways too) or **stack**. Opt in with `.juno-table--stack`, give every
+`td` a `data-label` echoing its column header, and make the wrapper a container:
+
+```html
+<div class="juno-table-scroll" style="container-type: inline-size">
+  <table class="juno-table juno-table--stack">
+    <tbody>
+      <tr>
+        <td data-label="FLIGHT" class="juno-table__id">JU-204</td>
+        <td data-label="ALT" class="juno-table__num">37,000</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+Below a 480px container the header row hides, each row becomes a bordered card,
+and each cell renders as a label/value pair (the `data-label` becomes the label).
+The selection rail moves to the card's edge, and row actions stay visible (no
+hover on touch). Semantics stay a real `<table>` — only the display flips.
+
+### Framing rows
+
+`.juno-table__toolbar` (top), `.juno-table__foot` (bottom), and `.juno-table__bulk`
+(the selection bar — role `active`, with `.juno-table__bulk-count`) are flex rows you
+stack around the scroll viewport. Frame the whole thing in a [`.juno-card`](./card.md)
+for the border + radius + clipped corners.
+
+### States
+
+- `.juno-table__skeleton` — shimmer bar for loading rows (honors `prefers-reduced-motion`).
+- `.juno-table__empty` + `.juno-table__empty-icon` — the no-data block.
+
+## Anatomy (any platform)
+
+- Header: `s2`, `font.size.10` uppercase `label`, `control-edge` underline, sticky.
+- Body cell: `space.12`/`space.16` padding (`space.8` block when compact), `border` rule,
+  `data` text. Numerics mono + bold + end-aligned.
+- Selected row: `active` left rail (`border.width.3`) + `color-mix(active 11%)` wash.
+- Status is a soft badge per row; caution / warning tint **only the note**, never the
+  whole row, so the grid stays calm.
+
+## Usage (the app's half)
+
+junoui can't sort or select in CSS — wire these and keep the ARIA in sync:
+
+- **Sort:** click a `th`; set its `aria-sort` to `ascending` / `descending` (others to
+  `none`) and reorder the rows.
+- **Select:** a `.juno-checkbox` per row (in a `.juno-table__check` cell) toggles
+  `aria-selected` on the `<tr>`; reflect the count in a `.juno-table__bulk` bar. The
+  header "select all" checkbox drives every visible row (use `indeterminate` for a
+  partial set).
+- **Inline edit:** swap the cell's text for an [`.juno-input`](./input.md) on
+  double-click; Enter commits, Esc cancels.
+- **Paginate / filter:** owned by the app; `.juno-table__foot` is just the frame.
+
+`showcase/app.js` (`initTables`) is a reference driver for sort + selection.

package/docs/components/tabs.md

@@ -0,0 +1,61 @@
+# Tabs
+
+A horizontal tablist with an active-cyan underline; the selected tab shows its panel.
+junoui ships the look + the ARIA contract; the app owns switching, panel visibility, and
+arrow-key roving focus.
+
+## Web
+
+```html
+<div class="juno-tabs">
+  <div class="juno-tabs__list" role="tablist" aria-label="Service detail">
+    <button class="juno-tabs__tab" role="tab" id="t1" aria-controls="p1" aria-selected="true">
+      OVERVIEW
+    </button>
+    <button class="juno-tabs__tab" role="tab" id="t2" aria-controls="p2" aria-selected="false">
+      METRICS
+    </button>
+    <button
+      class="juno-tabs__tab"
+      role="tab"
+      id="t3"
+      aria-controls="p3"
+      aria-selected="false"
+      disabled
+    >
+      CONFIG
+    </button>
+  </div>
+  <div class="juno-tabs__panel" role="tabpanel" id="p1" aria-labelledby="t1">…</div>
+  <div class="juno-tabs__panel" role="tabpanel" id="p2" aria-labelledby="t2" hidden>…</div>
+  <div class="juno-tabs__panel" role="tabpanel" id="p3" aria-labelledby="t3" hidden>…</div>
+</div>
+```
+
+| Class                            | Effect                                                         |
+| -------------------------------- | -------------------------------------------------------------- |
+| `.juno-tabs__list`               | The `role="tablist"` row; bottom rule the tabs sit on.         |
+| `.juno-tabs__tab`                | A tab button. `label` at rest → `data` on hover.               |
+| `.juno-tabs__tab[aria-selected]` | Selected: `active` text + `active` underline indicator.        |
+| `.juno-tabs__tab:disabled`       | Dimmed, not selectable.                                        |
+| `.juno-tabs__panel`              | The `role="tabpanel"`; `[hidden]` when its tab isn't selected. |
+
+## Anatomy (any platform)
+
+- Tabs sit on a 1px `border` rule; the selected tab paints a `border.width.2` `active`
+  underline that overlaps the rule. Text `label` → `active` when selected.
+- Panel gets `space.20` of leading space above its content.
+
+## Usage (the app's half)
+
+junoui can't switch panels in CSS — wire it and keep the ARIA in sync:
+
+- On tab activation: set its `aria-selected="true"` (others `false`), unhide its panel
+  (`[hidden]` on the rest), and move the roving `tabindex` (selected = `0`, rest = `-1`).
+- **Keyboard:** `←` / `→` move between tabs (wrapping), `Home` / `End` jump to the ends;
+  activation follows focus. `showcase/app.js` (`initTabs`) is a reference driver.
+- For a stable layout, give panels equal-ish height or let content flow; don't animate
+  height unless you measure it.
+- Tabs never wrap: when the strip runs out of room (phone widths) it scrolls
+  sideways, so every tab stays reachable. Keep labels short anyway — a scrolled
+  tab is a hidden tab until swiped to.

package/docs/components/thumb.md

@@ -0,0 +1,61 @@
+# Thumb
+
+A media frame that never shows the browser's broken-image glyph. A muted
+placeholder (icon on `s2`) sits under the media; the image covers it while
+present. **Loading** is [skeleton](./skeleton.md)'s job — thumb handles media
+that is **missing or failed**.
+
+## Web
+
+```html
+<!-- normal: image covers the placeholder -->
+<figure class="juno-thumb" style="aspect-ratio: 1">
+  <img src="…" alt="Sunset clip" onerror="this.remove()" />
+</figure>
+
+<!-- known-missing: ship no <img>; the placeholder just shows -->
+<figure
+  class="juno-thumb juno-thumb--video"
+  style="aspect-ratio: 16/9"
+  role="img"
+  aria-label="Preview unavailable"
+>
+  <figcaption class="juno-thumb__label">Unavailable</figcaption>
+</figure>
+```
+
+| Class / attr              | Effect                                                         |
+| ------------------------- | -------------------------------------------------------------- |
+| `.juno-thumb`             | Frame: `s2` fill, hairline border, `radius.3`, centered glyph. |
+| `.juno-thumb--video`      | Play glyph instead of the image glyph.                         |
+| `.juno-thumb__label`      | Optional uppercase micro-caption under the glyph.              |
+| `> img` / `> video`       | Covers the frame (`object-fit: cover`).                        |
+| `onerror="this.remove()"` | The whole JS contract — optional, stateless, one attribute.    |
+
+## Anatomy (any platform)
+
+- Frame: surface `s2`, 1px `border`, radius `3`; size from the app
+  (`aspect-ratio` inline or the [tiles grid](../layout.md)).
+- Glyph: 28% of the frame (capped `space.32`), `muted` color — a missing thumb
+  is **not** a warning state; the placeholder stays neutral.
+- Media covers the full frame, center-cropped.
+
+## Failure contract
+
+There is no portable CSS-only way to detect a broken image, so the contract is
+explicit:
+
+- **Failed to load** → `onerror="this.remove()"`: the broken element removes
+  itself, the placeholder underneath shows.
+- **Known missing** (offline node, purged cache, no permission) → render no
+  media element at all.
+- When no media renders, the alt text is gone too — put the accessible name on
+  the figure (`role="img"` + `aria-label`) or show a `__label`.
+
+## Usage
+
+- Media walls (pairs with `.juno-grid-auto--tiles`), avatars' big cousin,
+  video poster slots, attachment previews.
+- Keep the placeholder neutral; if failure _matters_ (broken pipeline), say it
+  with a [badge](./badge.md) or [alert](./alert.md) next to the thumb.
+- Retry, lazy-load, LQIP/blur-up: app or `junoui-<framework>` territory.

package/docs/components/toast.md

@@ -0,0 +1,48 @@
+# Toast / snackbar
+
+A transient, floating notification. Same role-rail language as the [alert](./alert.md),
+but elevated and stacked in a fixed corner on the reserved **alert layer**
+(`--juno-z-alert`, above modals). junoui ships the look + enter/exit motion; the app owns
+creation, auto-dismiss timing, and the live-region announcement.
+
+## Web
+
+```html
+<!-- one stack per corner; the app appends toasts into it -->
+<div class="juno-toast-stack" id="toasts" aria-live="polite"></div>
+
+<!-- a toast (app-created) -->
+<div class="juno-toast juno--nominal" role="status">
+  <span class="juno-toast__icon" aria-hidden="true">✓</span>
+  <span class="juno-toast__text">Build promoted.</span>
+  <button class="juno-toast__close" aria-label="Dismiss">✕</button>
+</div>
+```
+
+| Class                                      | Effect                                                              |
+| ------------------------------------------ | ------------------------------------------------------------------- |
+| `.juno-toast-stack`                        | Fixed container on `z.alert`; bottom-end, stacks its toasts.        |
+| `.juno-toast-stack--top` / `--start`       | Move the stack to the top / inline-start.                           |
+| `.juno-toast`                              | `s2` surface, `shadow.2`, role start-rail. Default `active`.        |
+| `.juno-toast--leaving`                     | Exit state (app adds it, then removes the node on `transitionend`). |
+| `.juno-toast__icon` / `__text` / `__close` | Glyph · message · dismiss.                                          |
+| `.juno--<role>`                            | Sets the rail + icon color.                                         |
+
+## Anatomy (any platform)
+
+- Stack: `position: fixed`, `z.alert` (5000), `inline-size: min(360px, …)`, `pointer-events:
+none` so only the toasts catch clicks.
+- Toast: solid `s2` + `shadow.2` + role rail. Enters via `@starting-style` (fade + slide),
+  exits on `.juno-toast--leaving`; both honor `prefers-reduced-motion`.
+
+## Usage
+
+- The app creates and destroys toasts: append to the stack, start a timer (~4s), then add
+  `.juno-toast--leaving` and remove on `transitionend`. `showcase/app.js` (`showToast`) is a
+  reference driver.
+- Put `aria-live="polite"` on the stack (`assertive` for errors) so new toasts announce.
+- Keep messages short and self-contained; one line. For anything needing a decision, use a
+  [modal](./modal.md) or inline [alert](./alert.md).
+- **Phone widths (< `bp.sm`) are automatic:** the stack goes full-width along the
+  bottom edge (thumb reach), clear of the home indicator, and toasts slide up
+  instead of sideways. No extra class.

package/docs/components/toggle-button.md

@@ -0,0 +1,40 @@
+# Toggle button
+
+An Airbus-style illuminated-legend pushbutton: the body stays dark; a top strip lights
+(`nominal`) and the surround glows when engaged. A real `<button aria-pressed>`; the app
+flips `aria-pressed`. Use for panel-style on/off controls where the lit legend matters.
+
+## Web
+
+```html
+<button class="juno-toggle-btn" aria-pressed="true">
+  <span class="juno-toggle-btn__strip"></span>
+  <span class="juno-toggle-btn__row">
+    <span class="juno-toggle-btn__text">
+      <span class="juno-toggle-btn__legend">AUTO-SCALING</span>
+      <span class="juno-toggle-btn__desc">Scale workers with load</span>
+    </span>
+    <span class="juno-toggle-btn__status">ON</span>
+  </span>
+</button>
+```
+
+| Class                                              | Effect                                              |
+| -------------------------------------------------- | --------------------------------------------------- |
+| `.juno-toggle-btn`                                 | Pushbutton tile on `control-surface`.               |
+| `[aria-pressed="true"]`                            | Border → role, surround glow, strip + status light. |
+| `.juno-toggle-btn__strip`                          | Top legend strip; `s3` (off) → role (on) with glow. |
+| `.juno-toggle-btn__legend` / `__desc` / `__status` | Mono legend, sub-label, ON/OFF status.              |
+| `.juno--<role>`                                    | Lit color (default `nominal`).                      |
+| `:disabled`                                        | Dimmed, not-allowed.                                |
+
+## Anatomy (any platform)
+
+- Tile border `control-edge` → role when pressed, plus a 20% role outer glow. Strip
+  `space.4` tall lights to role with an 8px glow. `motion.duration.quick` transitions.
+
+## Usage
+
+- A latching control whose engaged state must read at a glance (system arm/enable).
+- Use a real `<button>` and keep `aria-pressed` in sync; for inline on/off in a form,
+  prefer the [switch](./switch.md).

package/docs/components/tooltip.md

@@ -0,0 +1,63 @@
+# Tooltip
+
+A transient hover/focus label. Pure CSS reveal — no JS. Four placements with an arrow.
+
+## Web
+
+```html
+<span class="juno-tooltip">
+  <button tabindex="0">SPD</button>
+  <span class="juno-tooltip__bubble" role="tooltip">
+    Requests / sec · 248
+    <span class="juno-tooltip__arrow"></span>
+  </span>
+</span>
+
+<!-- placements -->
+<span class="juno-tooltip__bubble juno-tooltip__bubble--right">…</span>
+<span class="juno-tooltip__bubble juno-tooltip__bubble--bottom">…</span>
+<span class="juno-tooltip__bubble juno-tooltip__bubble--left">…</span>
+```
+
+| Class                                           | Effect                                                   |
+| ----------------------------------------------- | -------------------------------------------------------- |
+| `.juno-tooltip`                                 | Relative wrapper around the trigger.                     |
+| `.juno-tooltip__bubble`                         | `s3` bubble, mono 11px, shadow `2`, `z.anchored` (2000). |
+| `--top` (default) `--right` `--bottom` `--left` | Placement of the bubble + arrow.                         |
+| `.juno-tooltip__arrow`                          | Rotated-square pointer back to the trigger.              |
+
+Shows on `:hover` or `:focus-within` of the wrapper; `motion.duration.quick` (140ms)
+/ `ease.decel` rise.
+
+## Top-layer mode (escaping clipping)
+
+The pure-CSS reveal is clipped if an ancestor sets `overflow`/`clip` (cards, scroll
+areas). To lift it above everything, promote the bubble to a `popover="hint"` — it then
+renders in the browser **top layer**, immune to ancestor clipping. The bubble already
+carries `:popover-open` + anchor-positioning styles; a tiny stateless enhancer toggles it
+and points `position-anchor` at the trigger:
+
+```js
+const name = `--juno-tip-${i}`;
+trigger.style.anchorName = name;
+bubble.style.positionAnchor = name;
+bubble.popover = 'hint';
+trigger.addEventListener('pointerenter', () => bubble.showPopover());
+trigger.addEventListener('pointerleave', () => bubble.hidePopover());
+trigger.addEventListener('focus', () => bubble.showPopover());
+trigger.addEventListener('blur', () => bubble.hidePopover());
+```
+
+(`showcase/app.js` ships this as `initTooltips()`.) With no enhancer the component still
+works as the CSS-only hover tooltip — just clippable by its container.
+
+## Anatomy (any platform)
+
+- Bubble offset `space.8` from the trigger edge; small rise on reveal.
+- Content is mono (codes/values); single line (`white-space: nowrap`).
+
+## Usage
+
+- Reference text only — never put focusable controls in a tooltip (use a [popover](./popover.md)).
+- Give the trigger a tabstop and the bubble `role="tooltip"` + `aria-describedby` so it
+  reveals on keyboard focus, not just hover.