@junoput01/junoui 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- a7fb0b8: App-shell composition primitive + nav ergonomics — all CSS, all additive:
+
+  - `.juno-app-shell` — the standard product frame as classes instead of a
+    copy-pasted `<style>` block: `__body` column, `__topbar`, and a `__main`
+    scroller with a dock/pillbar pinned at its foot. Encodes `100dvh` (dock isn't
+    clipped by mobile browser chrome), main-as-scroller (dock stays put with no
+    `sticky`/`fixed`), and safe-area insets. Knob: `--juno-app-shell-topbar-size`.
+  - `.juno-rail--responsive` — the rail self-hides below `md`, so the rail↔dock
+    swap is one modifier instead of hanging `.juno-hide-below-md` yourself. rail.css
+    now cross-references the dock pairing.
+  - Viewport helpers extended to `sm` (640px) and `lg` (1024px), each with
+    `hide-below-*` / `hide-from-*`, plus readable `show-from-*` / `show-below-*`
+    inverse aliases.
+  - `.juno-dock--fixed` (pins flush to the foot) / `.juno-pillbar--fixed` (fixes
+    to the viewport, still floating its gap above the foot) — for
+    page-scroll shells, where `position: sticky` won't pin on a non-overflowing
+    column and the bar would land mid-content. Prefer `.juno-app-shell`, which
+    avoids the problem entirely.
+  - `.juno-icon-loader` — a nav destination's icon ringed by the spinning
+    [arc](../docs/components/loader.md) while its section loads. Icon static on
+    top; ring sized in `em`, pointer-transparent, kept concentric with a
+    single-cell grid (never `translate`, which the arc's rotation would clobber).
+  - Touch inputs hold a 16px font floor on coarse pointers, so iOS Safari no
+    longer zooms the page when a text field is focused.
+  - `docs/` now ships in the npm tarball, so the paths README and the CSS
+    comments point at (e.g. `docs/layout.md#app-shell`) resolve inside
+    `node_modules` for consumers.
+
 ## 0.2.0
 
 ### Minor Changes

package/dist/css/juno.css

@@ -440,6 +440,13 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
    the contract; a phone just reads the bigger one. */
 @media (pointer: coarse) {
   :root { --juno-size-tap-min: var(--juno-size-tap-comfortable); }
+
+  /* iOS Safari zooms the page onto any focused text field whose font-size is
+     below 16px. Hold text-entry controls (.juno-input covers input, textarea
+     and the select's inner control) at a 16px floor on touch so focusing never
+     triggers that jump. max() keeps the floor even under a scaled-down
+     --juno-font-scale, and still grows when scaled up. */
+  .juno-input { font-size: max(16px, var(--juno-font-size-16)); }
 }
 
 @keyframes juno-blink { 0%, 100% { opacity: 1; } 50% { opacity: 0; } }
@@ -564,11 +571,73 @@ code, kbd, samp, pre { font-family: var(--juno-font-family-mono); }
 }
 .juno-reel > * { scroll-snap-align: start; flex: 0 0 auto; }
 
+/* App shell — the standard product frame, as classes instead of the
+   copy-pasted \3c style> block every consumer used to hand-roll. A rail beside
+   a body column; the body holds an optional topbar, a scrolling main region,
+   and a dock/pillbar pinned at its foot. The MAIN region is the scroller
+   (not the page), so the dock never needs sticky/fixed to stay put and the
+   mobile address bar can't clip it. Height is 100dvh (dynamic viewport) so
+   it fills the visible area under shrinking browser chrome. Pairs with the
+   viewport helpers below to swap rail↔dock across md; see docs/layout.md#app-shell.
+     <div class="juno-app-shell">
+       <nav class="juno-rail juno-rail--responsive" aria-label="Primary">…</nav>
+       <div class="juno-app-shell__body">
+         <header class="juno-app-shell__topbar">…</header>
+         <main class="juno-app-shell__main">…</main>
+         <nav class="juno-dock juno-hide-from-md" aria-label="Primary">…</nav>
+       </div>
+     </div> */
+.juno-app-shell {
+  display: flex;
+  block-size: 100dvh;
+  overflow: hidden; /* the main region scrolls, not the shell */
+  padding-inline: env(safe-area-inset-left, 0) env(safe-area-inset-right, 0);
+}
+
+.juno-app-shell__body {
+  flex: 1;
+  min-inline-size: 0;
+  display: flex;
+  flex-direction: column;
+  min-block-size: 0; /* let __main shrink and scroll instead of the shell */
+}
+
+.juno-app-shell__topbar {
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--juno-space-12);
+  min-block-size: var(--juno-app-shell-topbar-size, 46px);
+  padding-inline: var(--juno-pad-surface-inline);
+  padding-block-start: env(safe-area-inset-top, 0);
+  background: var(--juno-s1);
+  border-block-end: var(--juno-border-width-1) solid var(--juno-border);
+}
+
+.juno-app-shell__main {
+  flex: 1;
+  min-block-size: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+  padding: var(--juno-pad-surface-block) var(--juno-pad-surface-inline);
+}
+
 /* Hide/show by viewport breakpoint — the rare case an intrinsic primitive
-   can't express (e.g. swap a nav for a menu button). */
-@media (width <= 767.98px) { .juno-hide-below-md { display: none !important; } }
+   can't express (e.g. swap a nav for a menu button). `hide-below-X` hides
+   under breakpoint X; `hide-from-X` hides at X and up. `show-*` are the
+   readable inverse aliases (show-from-X ≡ hide-below-X, show-below-X ≡
+   hide-from-X) — same media rule, name whichever reads clearer at the site. */
+@media (width <= 639.98px) { .juno-hide-below-sm, .juno-show-from-sm  { display: none !important; } }
+
+@media (width >= 640px)    { .juno-hide-from-sm,  .juno-show-below-sm { display: none !important; } }
+
+@media (width <= 767.98px) { .juno-hide-below-md, .juno-show-from-md  { display: none !important; } }
+
+@media (width >= 768px)    { .juno-hide-from-md,  .juno-show-below-md { display: none !important; } }
 
-@media (width >= 768px)    { .juno-hide-from-md  { display: none !important; } }
+@media (width <= 1023.98px) { .juno-hide-below-lg, .juno-show-from-lg  { display: none !important; } }
+
+@media (width >= 1024px)    { .juno-hide-from-lg,  .juno-show-below-lg { display: none !important; } }
 
 /* ════════════════════════════════════════════════════════════════════
  *  junoui — density layer
@@ -1453,6 +1522,19 @@ button.juno-chip {
   outline-offset: calc(-1 * var(--juno-space-2));
 }
 
+/* Fixed — same story as the pillbar: sticky only pins while the column
+   overflows, so on a short page the dock lands mid-content. Pin to the
+   viewport foot in a page-scroll shell where content height varies. Since
+   fixed leaves the flow, reserve its height at the page foot (e.g.
+   padding-block-end) so it doesn't cover the last row. In-flow
+   .juno-app-shell (main is the scroller, dock at the body foot) needs none
+   of this — prefer it. */
+.juno-dock--fixed {
+  position: fixed;
+  inset-inline: 0;
+  inset-block-end: 0;
+}
+
 /* ════════════════════════════════════════════════════════════════════
  *  Component — Status dot + label
  *  Usage:
@@ -1687,6 +1769,60 @@ button.juno-chip {
 }
 .juno-gauge--lg .juno-gauge__value { font-size: var(--juno-font-size-20); }
 
+/* ════════════════════════════════════════════════════════════════════
+ *  Component — Icon loader (nav loading ring)
+ *  A destination icon ringed by the spinning arc while that section loads —
+ *  the "this is loading" affordance for a rail / dock / pillbar item. The
+ *  icon stays static on top; the arc sizes in em around it and eats no
+ *  pointer events, so the nav item still clicks through.
+ *
+ *  The app owns the state: add .juno-arc--indeterminate to spin, drop it
+ *  when loaded (gate the blink to first-load, not every refetch). For a
+ *  determinate ring, set --juno-progress on the .juno-arc instead.
+ *  Usage:
+ *    <a class="juno-rail__item" href="…" 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>
+ *
+ *  Gotcha encoded here: the arc's rotate animation overrides `transform`, so
+ *  the ring is centred with inset:0 + margin:auto — never translate(-50%,-50%),
+ *  which the spin would clobber.
+ * ════════════════════════════════════════════════════════════════════ */
+
+.juno-icon-loader {
+  --juno-role: var(--juno-active);
+
+  /* Single-cell grid: the icon and the ring occupy the SAME cell and are
+     both centred in it, so they're guaranteed concentric — no transform (the
+     arc's rotation would clobber a translate) and no fragile margin math. The
+     ring is the larger child, so the cell sizes to it (--juno-icon-loader-ring). */
+  display: inline-grid;
+  place-items: center;
+  line-height: 0; /* drop the inline strut so the box hugs the ring */
+}
+
+.juno-icon-loader > .juno-icon,
+.juno-icon-loader > .juno-arc {
+  grid-area: 1 / 1;
+}
+
+/* icon sits above the ring */
+.juno-icon-loader > .juno-icon {
+  z-index: 1;
+}
+
+/* the ring: sized in em (relative to the icon), transparent to clicks */
+.juno-icon-loader > .juno-arc {
+  --juno-arc-size: var(--juno-icon-loader-ring, 1.9em);
+  --juno-arc-width: 0.14em;
+
+  pointer-events: none;
+}
+
 /* ════════════════════════════════════════════════════════════════════
  *  Component — Icon  ·  inline SVG glyph
  *  A zero-JS icon primitive. Reference a symbol from the sprite; the glyph
@@ -2638,6 +2774,21 @@ button.juno-list__row:disabled {
   flex-shrink: 0;
 }
 
+/* Fixed — pin to the viewport instead of flowing at the column's end.
+   Sticky only pins while the column overflows; on a short (non-scrolling)
+   page the sticky pillbar lands mid-content. Use --fixed in a page-scroll
+   shell where content height varies. Centered via inset-inline:0 + the base
+   margin-inline:auto (NOT translateX, which the app-shell model avoids
+   anyway). Leaves the viewport foot free — reserve space so it doesn't cover
+   the last row (e.g. padding-block-end on the scroll region). Prefer the
+   in-flow .juno-app-shell (main scrolls, pillbar sits at the body foot) —
+   that needs no fixed at all. */
+.juno-pillbar--fixed {
+  position: fixed;
+  inset-inline: 0;
+  z-index: var(--juno-z-anchored);
+}
+
 /* reduced-transparency preference → solid surface, no blur */
 @media (prefers-reduced-transparency: reduce) {
   .juno-pillbar {
@@ -2817,6 +2968,14 @@ button.juno-list__row:disabled {
   padding-inline: 0;
 }
 
+/* Responsive — the rail self-hides below md, so you pair it with a
+   .juno-dock (or .juno-pillbar) carrying .juno-hide-from-md and get the
+   rail↔dock swap without hanging a juno-hide-below-md on the rail yourself.
+   Reciprocal of the dock's md pairing; see dock.css / docs/layout.md#app-shell. */
+@media (width <= 767.98px) {
+  .juno-rail--responsive { display: none !important; }
+}
+
 /* ════════════════════════════════════════════════════════════════════
  *  Component — Data readout tile
  *  Usage:

package/docs/accessibility.md

@@ -0,0 +1,167 @@
+# Accessibility
+
+Accessibility is a primary goal of junoui, not an afterthought. The design system
+ships the **look and the accessibility contract**; the _interaction behavior_ (focus
+trapping, ARIA state updates, keyboard handlers) lives in your app or a sibling
+`junoui-<framework>` package — but this page states exactly what junoui guarantees, to
+which published standard, and what you must wire up.
+
+## Standards we build to
+
+junoui targets the international web accessibility standards and references the
+specific criteria it meets — so a claim can be checked, not just trusted:
+
+- **[WCAG 2.2](https://www.w3.org/TR/WCAG22/)** (W3C Recommendation) — **AA across the
+  board, AAA where it matters** (see the specific success criteria cited below).
+- **[WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/)** roles/states/properties, and
+  the **[ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/)**
+  for the keyboard/interaction patterns in [the contract table](#the-aria-contract-per-component).
+
+Criteria referenced on this page, by number:
+
+| SC         | Name                        | Level | Where                             |
+| ---------- | --------------------------- | ----- | --------------------------------- |
+| **1.4.1**  | Use of Color                | A     | [Color](#color)                   |
+| **1.4.3**  | Contrast (Minimum)          | AA    | [Color](#color)                   |
+| **1.4.6**  | Contrast (Enhanced)         | AAA   | [Color](#color)                   |
+| **1.4.11** | Non-text Contrast           | AA    | [Focus](#focus)                   |
+| **2.4.7**  | Focus Visible               | AA    | [Focus](#focus)                   |
+| **2.4.11** | Focus Appearance            | AA    | [Focus](#focus)                   |
+| **2.2.2**  | Pause, Stop, Hide           | A     | [Motion](#motion)                 |
+| **2.3.3**  | Animation from Interactions | AAA   | [Motion](#motion)                 |
+| **2.5.8**  | Target Size (Minimum)       | AA    | [Targets](#targets)               |
+| **2.5.5**  | Target Size (Enhanced)      | AAA   | [Targets](#targets)               |
+| **1.4.12** | Text Spacing                | AA    | [Density](#density--text-spacing) |
+
+This coverage is expected to grow: junoui adds standards references as components and
+tokens land, and never removes a guarantee without a semver-major note.
+
+## Color
+
+- **Never make color the only signal** (WCAG **1.4.1** Use of Color, A). Every status
+  pairs color with a text label, icon, or shape. A badge says `WARNING`; a dot sits
+  beside its word.
+- The **colorblind** palette (IBM Carbon universal set) is distinguishable across
+  deuteranopia, protanopia, and tritanopia. On the dark base–card surfaces (`s0`–`s2`)
+  every status role passes WCAG **1.4.6** Contrast (Enhanced), AAA (≥ 7:1); on the
+  selected/overlay surface (`s3`) it holds AA (≈ 7:1, ≥ 4.5:1). Use it for
+  accessibility-critical or universal audiences.
+- Contrast (measured — regenerate with `node scripts/audit-contrast.mjs`):
+  - `data` (values) meets **1.4.6** (AAA, ≥ 7:1) on **every** surface `s0`–`s3`, both
+    themes and all three palettes (dark ≈ 13–17:1).
+  - `label` (secondary text) meets **1.4.3** Contrast (Minimum), AA (≥ 4.5:1) on **every**
+    surface `s0`–`s3` (dark ≈ 4.6–5.9:1). Never use it for values.
+  - Status roles (`nominal`/`active`/`caution`/`warning`/`target`) meet **1.4.3** AA on
+    `s0`–`s3`; most reach AAA on `s0`–`s2`.
+  - `muted` and `data-dim` are **decorative / WCAG-exempt roles** — disabled controls,
+    placeholders, faint tick labels. They intentionally sit below 4.5:1; never carry
+    meaningful text in them (a real timestamp or value uses `label`/`data`, not `data-dim`).
+    Exact values: [tokens-reference.md](./tokens-reference.md).
+- **Surfaces & borders (dark).** Adjacent surface fills differ by only ~1.05:1, so a
+  block reads against its background through its **border**, not its fill. The dark
+  `border` / `border-strong` tokens are lifted (≈ 1.5:1 / 2.2:1 vs the base surface) so
+  cards, panels and dividers stay perceptible. Container boundaries are decorative and
+  exempt from **1.4.11** Non-text Contrast. Component-_identifying_ edges use the
+  `--juno-control-edge` family instead: input / checkbox / slider / avatar edges
+  (`-strong`, = `label`) clear ≥ 3:1 (dark ≈ 5.3:1) as **1.4.11** requires; table
+  gridlines (`--juno-control-edge`, = `muted`, ≈ 2.9:1) are supplementary rules — table
+  structure is carried by `<th>`/alignment, not the line — so they fall under the
+  decorative exemption.
+
+## Focus
+
+- A visible focus ring is defined in the base layer for links, buttons, inputs, and
+  anything with `[tabindex]`: 2px solid `--juno-active`, 2px offset. It tracks the
+  theme and is never removed (WCAG **2.4.7** Focus Visible, AA).
+- The ring's size, offset and `active`-role contrast satisfy **2.4.11** Focus
+  Appearance (AA, WCAG 2.2) and **1.4.11** Non-text Contrast (AA) against adjacent
+  surfaces.
+- Don't suppress `:focus-visible`. If you build a custom control, give it a tabstop
+  and let the ring apply.
+- Text inputs / select / textarea swap the outline for an equivalent visible signal:
+  an `active` border + 1px ring. Never remove focus indication outright.
+
+## Motion
+
+- All animations respect `prefers-reduced-motion: reduce` (base layer slows them to
+  near-static). Loader pulses and the `--live` dot honor it automatically — covering
+  WCAG **2.2.2** Pause, Stop, Hide (A) and **2.3.3** Animation from Interactions (AAA).
+- Use the `determinate` loaders when progress is known — less motion, more trust.
+
+## Targets
+
+- `--juno-size-tap-min` = 24px — WCAG **2.5.8** Target Size (Minimum), AA (WCAG 2.2).
+- `--juno-size-tap-comfortable` = 44px — WCAG **2.5.5** Target Size (Enhanced), AAA;
+  recommended for primary actions on touch.
+- `.juno-btn` already sets `min-height: var(--juno-size-tap-min)`.
+- **On coarse pointers this is automatic:** under `@media (pointer: coarse)` the
+  base layer raises `--juno-size-tap-min` to the comfortable 44px, so every
+  control sized off the tap minimum grows on touch devices. A cascade override —
+  the token values themselves don't change.
+- Hover-revealed affordances get a touch fallback: table row actions stay
+  visible under `@media (hover: none)`.
+
+## Forced colors / high contrast
+
+- The base layer opts components into the system palette under
+  `@media (forced-colors: active)`: borders fall back to `CanvasText`, focus to
+  `Highlight`. Badges keep their fill (`forced-color-adjust: none`) so status stays
+  legible.
+
+## Writing direction (RTL)
+
+- Components use **CSS logical properties** (`margin-inline`, `padding-inline`,
+  `inset`, `min-inline-size`) so they mirror correctly under `dir="rtl"` with no
+  extra CSS. Avoid reintroducing physical `left`/`right` in consuming code.
+
+## Density & text spacing
+
+- Type tokens set line-height and spacing with enough headroom that user or
+  browser-imposed **text spacing** (line-height 1.5×, paragraph/letter/word spacing)
+  doesn't clip or overlap content — WCAG **1.4.12** Text Spacing (AA).
+- Compact density shrinks padding, never a control's `min-height` (the tap target
+  under [Targets](#targets)) and never the type scale — readability holds at every
+  density.
+
+## The ARIA contract (per component)
+
+junoui gives structure + style; you add roles/state:
+
+| Component                 | You must add                                                                                                                                                                                                                             |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Badge / status dot        | Text label in the DOM (not color alone). For live values, `aria-live="polite"`.                                                                                                                                                          |
+| Button                    | Use a real `<button>`; `disabled` for disabled (not just the class).                                                                                                                                                                     |
+| Card                      | Heading semantics (`<h2>`…) in `__head` if it titles a region.                                                                                                                                                                           |
+| Loader (indeterminate)    | `role="status"` + `aria-label="Loading"`.                                                                                                                                                                                                |
+| Loader (determinate)      | `role="progressbar"` + `aria-valuenow/min/max`.                                                                                                                                                                                          |
+| Input / select / textarea | A `<label>` tied by `for`/`id`. Errors: `aria-invalid="true"` + `aria-describedby` → the error text. Required: `aria-required`.                                                                                                          |
+| Checkbox / radio          | Real `<input>` inside its `<label>`; radios share a `name`. State is native `checked`.                                                                                                                                                   |
+| Switch                    | `role="switch"` on the input; app keeps `checked` + `aria-checked` in sync.                                                                                                                                                              |
+| Toggle button             | Real `<button>` with `aria-pressed`; app flips it. Legend text is in the DOM, not color alone.                                                                                                                                           |
+| Slider                    | Value-driven `div`: add `role="slider"`, `tabindex`, `aria-valuenow/min/max` (+ `aria-valuetext` for units); app wires drag + arrow/Page keys and keeps `--juno-slider-pct` in sync.                                                     |
+| Modal / drawer            | Native `<dialog>` + `showModal()` (focus-trap, ESC, inert background, scrim-click come free). Name it via `aria-labelledby` → the title.                                                                                                 |
+| Tooltip                   | Trigger needs a tabstop; bubble `role="tooltip"` + `aria-describedby` so it reveals on focus, not only hover. Promote to `popover="hint"` to escape ancestor clipping (top layer).                                                       |
+| Popover                   | Native `popover` + `popovertarget` button (top layer; ESC + outside-click dismiss + `aria-expanded` come free). Keep `aria-haspopup`; move focus in on open, restore on close.                                                           |
+| Menu / dropdown           | `role="menu"` + `role="menuitem"`; native `popover` + `popovertarget` (free dismiss/ESC/`aria-expanded`), items `popovertargetaction="hide"`. App wires arrow-key roving focus + Enter.                                                  |
+| Table / data grid         | Real `<table>`/`<th>`/`<td>` (use `scope`). Sortable headers: `aria-sort` per column, kept in sync as you reorder. Selected rows: `aria-selected="true"`. Truncated cells: a `title` (or tooltip) with the full value.                   |
+| Alert                     | `role="alert"` for urgent (assertive), `role="status"` for passive. Icon is `aria-hidden`; the message text carries the meaning. Dismiss is a real `<button>` with `aria-label`.                                                         |
+| Toast                     | Stack is a live region: `aria-live="polite"` (`assertive` for errors). Each toast `role="status"`; keep it short. Dismiss `<button>` + `aria-label`; don't rely on the auto-timeout alone for critical info.                             |
+| Tabs                      | `role="tablist"` + `role="tab"` (each `aria-controls` its `role="tabpanel"`, which is `aria-labelledby` the tab). App keeps one `aria-selected="true"`, hides the rest, moves roving `tabindex`, and wires ← / → / Home / End.           |
+| Accordion                 | Native `<details>`/`<summary>` — open state, focus, and Enter/Space are built in. For one-open-at-a-time, give the `<details>` a shared `name`. No ARIA to add.                                                                          |
+| Icon                      | Decorative: `aria-hidden="true"`. Meaningful (icon-only control): `role="img"` + `aria-label`, or label the surrounding control. Never the only signal for status.                                                                       |
+| Skeleton                  | Wrap the loading region in `aria-busy="true"` (+ `aria-live="polite"`); swap in real content when loaded. The shimmer itself is decorative.                                                                                              |
+| Avatar                    | `<img>` needs a meaningful `alt`. The status ring is decorative — pair it with a `title` / visible label so status isn't color-only.                                                                                                     |
+| Divider                   | Semantic break: use `<hr>`. Purely decorative: a `<span>`/`<div>` (no role needed).                                                                                                                                                      |
+| Chip / tag                | Toggle chip: real `<button>` + `aria-pressed`. Removable: the `__remove` `<button>` needs an `aria-label` ("Remove X"). Meaning is in the text, not color.                                                                               |
+| Breadcrumb                | `<nav aria-label="Breadcrumb">` around an `<ol>`; mark the last crumb `aria-current="page"` and drop its `href`.                                                                                                                         |
+| Pagination                | `<nav aria-label="Pagination">`; current page `aria-current="page"`; icon-only prev/next need `aria-label`; disable the ends with `disabled`.                                                                                            |
+| Stepper                   | Real `<ol>`; set `data-state` per step and `aria-current="step"` on the active one. State drives the color — don't rely on color alone.                                                                                                  |
+| Rail / dock               | `<nav aria-label="Primary">` of real links; active item `aria-current="page"`. Collapsed rail items (icons-only) need `aria-label`/`title`. When both navs render (rail + dock swap), the hidden one leaves the tree via `display:none`. |
+| Pillbar                   | `<nav aria-label>` when it navigates; links get `aria-current="page"`, toggle buttons `aria-pressed`. Icon-only items need `aria-label`. Never render both a dock and a pillbar on one screen.                                           |
+| Navbar                    | Back is a real `<a>` (parent route) or `<button>` (history); `aria-label="Back"` when the caret has no text. Title is usually the screen's `<h1>`. The bar itself needs no role — it's a `<header>`.                                     |
+| List                      | Rows that navigate are `<a>` (or `<button>`) wrapping the whole row — never a bare chevron target. Keep `<ul>`/`<li>` when rows form a set. A trailing switch/checkbox is its own labeled control; don't nest it inside a link row.      |
+
+These are interaction concerns — junoui can't enforce them in CSS, so they're your
+responsibility (or the widget package's). Each row follows the matching
+[WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/patterns/) pattern;
+when in doubt, implement the APG keyboard model for that role.

package/docs/components/README.md

@@ -0,0 +1,68 @@
+# Components
+
+Framework-agnostic elements built from tokens. On the web they're CSS classes in
+`@junoput01/junoui/css`; on other platforms, build the same anatomy from
+[tokens-reference.md](../tokens-reference.md).
+
+## The role mechanism (web)
+
+A component reads a single custom property, `--juno-role`. A role class sets it, so
+**one class re-colors any component**:
+
+```html
+<span class="juno-badge juno--warning">…</span>
+<!-- role = warning -->
+<button class="juno-btn juno--nominal">…</button>
+<!-- role = nominal -->
+```
+
+Role classes: `.juno--nominal` `.juno--active` `.juno--target` `.juno--caution`
+`.juno--warning` `.juno--muted`.
+
+## Catalogue
+
+| Component                      | Class                                  | Spec                                   |
+| ------------------------------ | -------------------------------------- | -------------------------------------- |
+| Badge / status indicator       | `.juno-badge`                          | [badge.md](./badge.md)                 |
+| Button                         | `.juno-btn`                            | [button.md](./button.md)               |
+| Card / panel                   | `.juno-card`                           | [card.md](./card.md)                   |
+| Data readout                   | `.juno-readout`                        | [readout.md](./readout.md)             |
+| Status dot                     | `.juno-status`                         | [status.md](./status.md)               |
+| Loaders (arc · beacon · bar)   | `.juno-arc` `.juno-beacon` `.juno-bar` | [loader.md](./loader.md)               |
+| Gauge (metric ring)            | `.juno-gauge`                          | [gauge.md](./gauge.md)                 |
+| Spark (sparkline contract)     | `.juno-spark`                          | [spark.md](./spark.md)                 |
+| Field wrapper                  | `.juno-field`                          | [field.md](./field.md)                 |
+| Input / textarea               | `.juno-input`                          | [input.md](./input.md)                 |
+| Select                         | `.juno-select`                         | [select.md](./select.md)               |
+| Checkbox / radio               | `.juno-checkbox` `.juno-radio`         | [checkbox.md](./checkbox.md)           |
+| Switch                         | `.juno-switch`                         | [switch.md](./switch.md)               |
+| Segmented control              | `.juno-seg`                            | [segmented.md](./segmented.md)         |
+| Toggle button                  | `.juno-toggle-btn`                     | [toggle-button.md](./toggle-button.md) |
+| Slider                         | `.juno-slider`                         | [slider.md](./slider.md)               |
+| Modal / dialog                 | `.juno-modal`                          | [modal.md](./modal.md)                 |
+| Drawer                         | `.juno-drawer`                         | [drawer.md](./drawer.md)               |
+| Tooltip                        | `.juno-tooltip`                        | [tooltip.md](./tooltip.md)             |
+| Popover                        | `.juno-popover`                        | [popover.md](./popover.md)             |
+| Menu / dropdown                | `.juno-menu`                           | [menu.md](./menu.md)                   |
+| Table / data grid              | `.juno-table`                          | [table.md](./table.md)                 |
+| Alert / inline notification    | `.juno-alert`                          | [alert.md](./alert.md)                 |
+| Toast / snackbar               | `.juno-toast`                          | [toast.md](./toast.md)                 |
+| Tabs                           | `.juno-tabs`                           | [tabs.md](./tabs.md)                   |
+| Accordion / disclosure         | `.juno-accordion`                      | [accordion.md](./accordion.md)         |
+| Icon                           | `.juno-icon`                           | [icon.md](./icon.md)                   |
+| Skeleton / loading placeholder | `.juno-skeleton`                       | [skeleton.md](./skeleton.md)           |
+| Thumb / media placeholder      | `.juno-thumb`                          | [thumb.md](./thumb.md)                 |
+| Avatar                         | `.juno-avatar`                         | [avatar.md](./avatar.md)               |
+| Divider / separator            | `.juno-divider`                        | [divider.md](./divider.md)             |
+| Chip / tag                     | `.juno-chip`                           | [chip.md](./chip.md)                   |
+| Breadcrumb                     | `.juno-breadcrumb`                     | [breadcrumb.md](./breadcrumb.md)       |
+| Pagination                     | `.juno-pagination`                     | [pagination.md](./pagination.md)       |
+| Stepper                        | `.juno-stepper`                        | [stepper.md](./stepper.md)             |
+| Rail (app-shell nav)           | `.juno-rail`                           | [rail.md](./rail.md)                   |
+| Dock (bottom nav, narrow)      | `.juno-dock`                           | [dock.md](./dock.md)                   |
+| Pillbar (floating pill bar)    | `.juno-pillbar`                        | [pillbar.md](./pillbar.md)             |
+| Icon loader (nav loading ring) | `.juno-icon-loader`                    | [icon-loader.md](./icon-loader.md)     |
+| Navbar (stack top bar)         | `.juno-navbar`                         | [navbar.md](./navbar.md)               |
+| List (grouped rows)            | `.juno-list`                           | [list.md](./list.md)                   |
+
+Always pair a status color with a text label — color is never the only signal.

package/docs/components/accordion.md

@@ -0,0 +1,49 @@
+# Accordion / disclosure
+
+Stacked, expandable sections built on the native `<details>` / `<summary>` — keyboard and
+screen-reader native, **zero JS**. A chevron rotates on open. Use a lone `<details>` for a
+single disclosure, or group them in `.juno-accordion` for a bordered set.
+
+## Web
+
+```html
+<div class="juno-accordion">
+  <details class="juno-accordion__item" open>
+    <summary class="juno-accordion__summary">Region · us-east-1</summary>
+    <div class="juno-accordion__body">Primary region. 3 replicas, auto-scaling on.</div>
+  </details>
+  <details class="juno-accordion__item">
+    <summary class="juno-accordion__summary">Region · eu-west-1</summary>
+    <div class="juno-accordion__body">Failover armed. 1 of 3 replicas reporting.</div>
+  </details>
+</div>
+
+<!-- lone disclosure (frames itself) -->
+<details class="juno-accordion__item">
+  <summary class="juno-accordion__summary">Advanced options</summary>
+  <div class="juno-accordion__body">…</div>
+</details>
+```
+
+| Class                      | Effect                                                         |
+| -------------------------- | -------------------------------------------------------------- |
+| `.juno-accordion`          | Bordered group; clips its items' corners.                      |
+| `.juno-accordion__item`    | A `<details>`; row rule between items. `[open]` to start open. |
+| `.juno-accordion__summary` | The `<summary>` header; native marker hidden, chevron added.   |
+| `.juno-accordion__body`    | The revealed content (`s0`, `label` text).                     |
+
+## Anatomy (any platform)
+
+- Summary: `s1` row, `data` label, control-padding; hover → `s2`. A chevron (a rotated
+  corner) flips from ▸ to ▾ via `[open]`, `motion.duration.quick`.
+- Body: `s0` panel under a 1px rule. Native open/close (no height animation by default).
+- A lone `details.juno-accordion__item:only-child` draws its own border + radius.
+
+## Usage
+
+- **Zero JS** — `<details>` toggles itself; `<summary>` is focusable and Enter/Space work.
+  For "only one open at a time", give the `<details>` a shared `name` attribute (native
+  exclusive accordion) — no script needed.
+- Keep the summary a short label; put detail in the body.
+- To animate open/close, progressively enhance with `::details-content` +
+  `interpolate-size` where supported; the component stays correct without it.

package/docs/components/alert.md

@@ -0,0 +1,46 @@
+# Alert / inline notification
+
+A role-tinted banner for in-context messages — validation summaries, system status,
+callouts. Soft-fill with a role accent rail; icon + title + text + optional actions and
+dismiss. Color comes from `var(--juno-role)` (set by a `.juno--<role>` class).
+
+## Web
+
+```html
+<div class="juno-alert juno--warning" role="alert">
+  <span class="juno-alert__icon" aria-hidden="true">⚠</span>
+  <div class="juno-alert__body">
+    <span class="juno-alert__title">Deploy blocked</span>
+    <span class="juno-alert__text">Two required checks are still failing.</span>
+    <div class="juno-alert__actions">
+      <button class="juno-btn juno--warning">RE-RUN</button>
+      <button class="juno-btn juno-btn--ghost">VIEW LOG</button>
+    </div>
+  </div>
+  <button class="juno-alert__close" aria-label="Dismiss">✕</button>
+</div>
+```
+
+| Class                  | Effect                                                                      |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `.juno-alert`          | Soft role wash + role border + start accent rail. Default `active`.         |
+| `.juno-alert__icon`    | Leading glyph, role-colored. Mark it `aria-hidden`.                         |
+| `.juno-alert__body`    | `__title` (data, semibold) + `__text` (label) column.                       |
+| `.juno-alert__actions` | Row of buttons under the text.                                              |
+| `.juno-alert__close`   | Ghost dismiss button (app removes the alert).                               |
+| `.juno-alert--solid`   | High-emphasis: full role fill, text on `s0`.                                |
+| `.juno--<role>`        | Sets the color (`active` info · `nominal` success · `caution` · `warning`). |
+
+## Anatomy (any platform)
+
+- Surface: `color-mix(role 10%)` wash, `color-mix(role 30%)` border, `border.width.3`
+  role rail on the inline-start edge, `radius.5`, surface padding.
+- Icon + title (`data`, semibold) + text (`label`); `--solid` swaps to a full role fill.
+
+## Usage
+
+- **Inline, not floating** — alerts sit in the layout. For transient confirmations use a
+  [toast](./toast.md).
+- `role="alert"` for urgent (assertive announce); `role="status"` for passive.
+- Pair the role color with the icon **and** a word — never color alone.
+- Dismiss is the app's job: remove the node (`showcase/app.js` wires `.juno-alert__close`).

package/docs/components/avatar.md

@@ -0,0 +1,45 @@
+# Avatar
+
+A round (or squared) portrait holding an `<img>`, **initials**, or an
+[icon](./icon.md) fallback. One custom property drives the size; an optional role ring
+marks status. Zero JS. Pairs with a [`.juno-skeleton--circle`](./skeleton.md) while the
+image loads.
+
+## Web
+
+```html
+<!-- image -->
+<span class="juno-avatar"><img src="ada.jpg" alt="Ada Lovelace" /></span>
+
+<!-- initials -->
+<span class="juno-avatar juno-avatar--lg">AL</span>
+
+<!-- icon fallback + status ring -->
+<span class="juno-avatar juno-avatar--ring juno--nominal" title="Online">
+  <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-user" /></svg>
+</span>
+
+<!-- overlapping cluster -->
+<span class="juno-avatar-group">
+  <span class="juno-avatar"><img src="a.jpg" alt="Ada" /></span>
+  <span class="juno-avatar"><img src="g.jpg" alt="Grace" /></span>
+  <span class="juno-avatar">+3</span>
+</span>
+```
+
+| Class                    | Effect                                                      |
+| ------------------------ | ----------------------------------------------------------- |
+| `.juno-avatar`           | Circle portrait; `--juno-avatar-size` (default `space.32`). |
+| `.juno-avatar--sm/lg/xl` | `space.24` / `space.40` / `space.56`.                       |
+| `.juno-avatar--square`   | Rounded-rect instead of circle.                             |
+| `.juno-avatar--ring`     | Status ring in `var(--juno-role)` (+ soft halo).            |
+| `.juno-avatar-group`     | Overlapping row; each tucks under the previous.             |
+| `--juno-avatar-size`     | Override the size (initials scale to ~40% of it).           |
+
+## Usage
+
+- An `<img>` fills the box (`object-fit: cover`); always set a meaningful `alt`.
+- Initials / `+N` overflow are plain text content — center-aligned, uppercase.
+- The **ring is decorative**: pair it with a `title` / visible label so status isn't
+  color-only.
+- In a group, set `alt` per avatar; the trailing `+N` chip is just another avatar.