@junoput01/junoui 0.2.0 → 0.3.0

package/docs/design-guidelines.md

@@ -0,0 +1,147 @@
+# Design guidelines
+
+Buildable in any tool — these are rules, not code. Pair with exact values in
+[tokens-reference.md](./tokens-reference.md).
+
+## First principle: color encodes status, never decoration
+
+Every hue has one assigned role. Never reuse a status color as styling.
+
+| Role      | Meaning           | When                                                                    |
+| --------- | ----------------- | ----------------------------------------------------------------------- |
+| `nominal` | Normal / OK       | Nominal readings, confirmed-good, success.                              |
+| `active`  | Selected / active | Current selection, armed state, focus rings, live status.               |
+| `target`  | Managed / goal    | Computed set-points, automated targets. Use sparingly.                  |
+| `caution` | Non-normal, watch | Approaching limits, degraded — no immediate action.                     |
+| `warning` | Critical          | Limit exceeded, act now. Reserve strictly — overuse destroys authority. |
+
+Neutral / structural roles carry no status meaning:
+
+| Role            | Use                                                                |
+| --------------- | ------------------------------------------------------------------ |
+| `data`          | Primary numeric readouts and live values — the brightest text.     |
+| `data-dim`      | Faint metadata — timestamps, tick labels. Decorative; below muted. |
+| `label`         | Labels, units, helper and secondary text. Never for values.        |
+| `muted`         | Disabled, placeholder, decorative separators.                      |
+| `border`        | Hairline borders and dividers.                                     |
+| `border-strong` | Divider / stronger rule — heavier than the hairline border.        |
+| `s0`–`s3`       | Surface depth: base → panel → elevated card → selected/overlay.    |
+
+## More principles
+
+- **Hierarchy via contrast, not scale.** Brightness/weight separate levels before size does.
+- **Density is intentional.** Choose spacing deliberately; don't pad by accident.
+  Switch the whole UI between comfortable and compact with one attribute (below).
+- **Designed for long sessions.** The `soft` palette and dark mode reduce fatigue.
+
+## Typography
+
+- **B612 Mono** — every number, timestamp, identifier, code. Fixed-width digits
+  stop value-change jitter. Use `tabular-nums`.
+- **B612** — all non-numeric UI: headings, labels, navigation, buttons.
+- Headings are uppercase with wide tracking; values are mono and bright (`data`).
+
+## Date & time
+
+One fixed house format everywhere — no locale drift between screens. This is a
+**content convention**, not code: apps do the formatting; junoui specifies what it
+looks like.
+
+| What     | Format                    | Example              |
+| -------- | ------------------------- | -------------------- |
+| Date     | `dd.mm.yyyy`, zero-padded | `05.07.2026`         |
+| Time     | 24-hour `HH:MM`(`:SS`)    | `14:32` · `14:32:07` |
+| Combined | date first, interpunct    | `05.07.2026 · 14:32` |
+| Range    | en-dash, no spaces        | `14:00–15:30`        |
+| Open     | trailing en-dash          | `14:00–`             |
+
+Rendering rules:
+
+- Always mono + `tabular-nums` (the [Typography](#typography) value rule) — use
+  `.juno-value` or `.juno-mono`, wrapped in `<time>` with the machine-readable ISO
+  value: `<time class="juno-mono" datetime="2026-07-05T14:32">05.07.2026 · 14:32</time>`.
+- Never AM/PM, never month names in data UI (prose may spell them out).
+- Relative time ("2h ago") is app policy; when used, pair it with the absolute
+  timestamp in a `title` or adjacent text.
+
+App-side recipe (the `de-DE` locale happens to produce exactly this format):
+
+```js
+const fmt = new Intl.DateTimeFormat('de-DE', {
+  day: '2-digit',
+  month: '2-digit',
+  year: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+  hour12: false,
+});
+fmt.format(date).replace(', ', ' · '); // "05.07.2026 · 14:32"
+```
+
+This is the junoui house format. Locale-sensitive consumer products may override it
+with `Intl` defaults — deviating is a per-app decision; log it like any other
+extension (see [integration.md](./integration.md)).
+
+## Foundation tokens (motion, layering, depth, opacity)
+
+These scales exist so transitions, overlays, and surfaces stay consistent. junoui
+ships the values; stateful behavior (open/close, positioning, focus traps) lives in
+apps. Exact values: [tokens-reference.md](./tokens-reference.md).
+
+- **Motion.** Durations `--juno-motion-duration-{instant,quick,base,deliberate}`
+  (80·140·200·300ms) and easings `--juno-motion-ease-{decel,accel,standard,spring}`.
+  `instant` for state feedback, `quick` for tooltip/menu, `base` for popover/drawer,
+  `deliberate` for modal/scrim. Enter with `decel`, exit with `accel`, reposition with
+  `standard`, toggle with `spring`. Always inside a `transition`/`animation`;
+  `prefers-reduced-motion` already collapses these in `base.css`.
+- **Z-index.** `--juno-z-*` is the single layering source of truth — never invent raw
+  z-index. Layer stack: `surface` (0) < `raised` (100) < `anchored` (2000, menu ·
+  popover · tooltip) < `overlay` (4000, modal · drawer + scrim) < `alert` (5000, toast).
+  Large gaps leave room for app layers.
+- **Elevation.** Depth is **border-first** by design; elevation = z-index + shadow,
+  paired. Reach for `--juno-shadow-{1,2,3}` only when a surface lifts off the glass —
+  `1` raised card, `2` anchored (menu/popover/tooltip), `3` overlay (modal/drawer).
+- **Opacity.** `--juno-opacity-disabled` for inert controls, `--juno-opacity-muted`
+  for de-emphasised content, `--juno-opacity-scrim` for a modal/drawer backdrop.
+
+## Density
+
+One attribute on any ancestor swaps the internal padding of every component
+underneath it — no per-component class:
+
+```html
+<body data-juno-density="compact">
+  <!-- comfortable (default) needs no attribute -->
+</body>
+```
+
+Components read **semantic padding aliases** (`--juno-pad-control-*`,
+`--juno-pad-surface-*`, `--juno-gap-control`) instead of raw `--juno-space-*`;
+`data-juno-density` redefines that set. Density is deliberately **non-linear** —
+compact removes more block (vertical) than inline padding, so text never crowds its
+edges. Interactive controls keep their `min-height` (WCAG tap target); only padding
+shrinks. New components should use the aliases for internal padding to inherit
+density for free; add a new archetype only when one is genuinely needed.
+
+## Accessibility
+
+Accessibility is a core design goal, held to published standards — **WCAG 2.2** and
+**WAI-ARIA** — with the exact success criteria cited in
+[accessibility.md](./accessibility.md).
+
+- The `colorblind` palette is the IBM Carbon universal set — distinguishable across
+  deuteranopia, protanopia, tritanopia, and AAA-contrast (≥ 7:1) on dark surfaces
+  (WCAG 1.4.6).
+- **Never make color the sole signal** (WCAG 1.4.1). Always pair it with a text label,
+  icon, or shape.
+- Interactive targets: `size.tap.min` = 24px (WCAG 2.5.8, AA); `size.tap.comfortable`
+  = 44px (WCAG 2.5.5, AAA) recommended for primary mobile actions.
+- Focus is always visible — the `active` role, 2px outline (WCAG 2.4.7 / 2.4.11).
+
+## Choosing a palette
+
+| Palette      | Use                                                |
+| ------------ | -------------------------------------------------- |
+| `standard`   | Default. Vivid, high-contrast OKLCH.               |
+| `colorblind` | Accessibility-critical or universal audiences.     |
+| `soft`       | Long viewing sessions; lower chroma, less fatigue. |

package/docs/flutter.md

@@ -0,0 +1,42 @@
+# Flutter
+
+Colors are pre-converted to sRGB hex at build time (Dart has no `oklch`).
+
+## Add the file
+
+Copy the generated file into your project:
+
+```
+dist/flutter/juno_tokens.dart   →  lib/theme/juno_tokens.dart
+```
+
+## Use it
+
+```dart
+import 'theme/juno_tokens.dart';
+
+Container(
+  color: JunoTokens.standardDarkS1,
+  padding: const EdgeInsets.all(JunoTokens.space16),
+  child: Text(
+    '89.3',
+    style: TextStyle(
+      color: JunoTokens.standardDarkNominal,
+      fontSize: JunoTokens.fontSize38,
+      fontFamily: 'B612 Mono',
+    ),
+  ),
+)
+```
+
+- Colors are `Color` constants named `<palette><Mode><Role>` (camelCase),
+  fully opaque (`0xFF…`).
+- Dimensions are `double` constants (`space16`, `fontSize14`, `radius8`, …).
+
+## Theming
+
+Map the active palette/mode to a helper that returns the right constant, or build a
+`ThemeExtension` keyed on palette+mode. All constants derive from the same source,
+so they stay in lockstep with web and native.
+
+Exact values for every token: [tokens-reference.md](./tokens-reference.md).

package/docs/getting-started.md

@@ -0,0 +1,70 @@
+# Getting started
+
+junoui is a design system for **modern, futuristic, highly readable and accessible**
+UIs — usable for critical systems and everyday apps alike. Mechanically it is the
+single graphics source for your UIs: colors, spacing, typography, radii, sizing. You
+build the UI skeleton; junoui defines how it looks. Tokens are authored once in
+`tokens/` and compiled to every platform.
+
+Accessibility is a first-class goal, held to the international standards (WCAG 2.2 +
+WAI-ARIA) with the exact criteria cited per component — see
+[accessibility.md](./accessibility.md).
+
+## Install
+
+```sh
+npm install @junoput01/junoui
+```
+
+Or as a git submodule (then build once):
+
+```sh
+git submodule add git@github.com:junoput/junoui.git vendor/junoui
+cd vendor/junoui && npm install   # `prepare` builds dist/
+```
+
+`npm install` runs the `prepare` script, so `dist/` is always built for you.
+
+## The model
+
+- **Palette** — `standard` · `colorblind` · `soft`
+- **Mode** — `dark` · `light`
+- **Role** — `nominal` `active` `target` `caution` `warning` (semantic) and
+  `data` `label` `muted` `border` `s0`–`s3` (neutral/surface)
+
+A theme is one palette × one mode. Color always encodes status — see
+[design-guidelines.md](./design-guidelines.md).
+
+## Pick your platform
+
+| You're building in…                    | Read                                                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Web (CSS, SCSS, JS/TS)                 | [web.md](./web.md)                                                                                           |
+| Android / iOS                          | [native.md](./native.md)                                                                                     |
+| Flutter                                | [flutter.md](./flutter.md)                                                                                   |
+| Figma / Sketch / any tool without code | [tokens-reference.md](./tokens-reference.md) (exact values) + [design-guidelines.md](./design-guidelines.md) |
+
+Responsive behavior (how blocks adapt on resize) is its own layer:
+[layout.md](./layout.md).
+
+## What ships
+
+`npm install @junoput01/junoui` delivers `dist/` (all platform outputs), `src/css/` (authored
+stylesheet sources), `src/icons/` (SVG icon sources + license), and `src/fonts/`
+(self-hosted B612 woff2 + OFL license). The interactive demo in `showcase/` is **not**
+shipped — it lives in the repo for development only.
+
+## Build outputs
+
+| Path                                      | Platform                                                      |
+| ----------------------------------------- | ------------------------------------------------------------- |
+| `dist/css/juno.css`                       | Web — tokens + base + utilities + components                  |
+| `dist/css/juno-tokens.css`                | Web — CSS variables only                                      |
+| `dist/css/juno-fonts.css` + `dist/fonts/` | Web — opt-in self-hosted B612 (`@junoput01/junoui/fonts.css`) |
+| `dist/icons/juno-icons.svg`               | Web — icon sprite (`@junoput01/junoui/icons`)                 |
+| `dist/scss/_juno-tokens.scss`             | Web — SCSS variables                                          |
+| `dist/js/tokens.js` + `.d.ts`             | JS / TS — `TOKENS`, `CORE`, `getTokens()`                     |
+| `dist/json/tokens.json`                   | W3C DTCG — any tool                                           |
+| `dist/android/colors.xml` · `dimens.xml`  | Android                                                       |
+| `dist/ios/JunoTokens.swift`               | iOS                                                           |
+| `dist/flutter/juno_tokens.dart`           | Flutter                                                       |

package/docs/integration.md

@@ -0,0 +1,95 @@
+# Integrating junoui into an app
+
+junoui is **presentational**: tokens + a CSS component layer, zero JS. It dresses a UI
+your app builds. This is the recipe for consuming it cleanly — and the rules for
+extending it without breaking the "one design across all apps" goal.
+
+## 1. Import order (app shell)
+
+`@junoput01/junoui/css` sets a small reset + document defaults on `:root`/`body`. Load it **first**,
+your app styles **after**, so your shell wins where it must:
+
+```js
+import '@junoput01/junoui/css'; // tokens + base + components — FIRST
+import '@junoput01/junoui/fonts.css'; // optional self-hosted B612 (see §2)
+import './app.css'; // your shell + app-specific styles — AFTER
+```
+
+What junoui's base layer touches: `box-sizing`, margin/padding reset, `body`
+font/color/background, link color, focus-visible ring, and `prefers-reduced-motion` /
+`forced-colors` handling. It does **not** position or lay out your shell — that's yours.
+If a body default fights your shell, override it in your app CSS (loaded after).
+
+## 2. Fonts (opt-in, CSP-safe)
+
+junoui never fetches fonts. Either bring your own B612, or opt into the self-hosted set:
+
+```js
+import '@junoput01/junoui/fonts.css'; // local @font-face → woff2 in the package, no network
+```
+
+Safe under a strict CSP (`font-src 'self'`). Skip it and the UI falls back to system
+sans/mono until you provide the family.
+
+## 3. Theming — two attributes
+
+```html
+<html data-juno-palette="standard" data-juno-mode="dark" data-juno-density="comfortable"></html>
+```
+
+- `data-juno-palette`: `standard` · `colorblind` · `soft`
+- `data-juno-mode`: `dark` · `light`
+- `data-juno-density`: `comfortable` · `compact`
+- `data-juno-text`: `base` · `large` · `xl` (type scale)
+
+Flip these at runtime and the whole UI re-themes. Persist them if you want (localStorage);
+the value is yours to manage.
+
+## 4. Token bridge (aliasing app variables)
+
+If your app already has design aliases, redefine them in terms of `--juno-*` so one system
+drives everything:
+
+```css
+:root {
+  --bg: var(--juno-s0);
+  --ink: var(--juno-data);
+  --ink-dim: var(--juno-data-dim); /* timestamps, metadata */
+  --line: var(--juno-border);
+  --line-strong: var(--juno-border-strong); /* dividers */
+  --accent: var(--juno-active); /* see §5 — accent is semantic */
+}
+```
+
+Prefer a shipped token over `color-mix()`. junoui exposes the full neutral ramp
+(`data` · `data-dim` · `label` · `muted`) and two border tones (`border` ·
+`border-strong`), so most dense-UI needs don't require mixing.
+
+## 5. Accent is semantic — not a brand hue
+
+junoui has **no decorative brand-accent knob**, on purpose. Color encodes _status_, never
+decoration: every hue is a role (`nominal` · `active` · `target` · `caution` · `warning`).
+The "accent" is the `active` role, and it changes with the palette.
+
+If you want a different accent, **switch palette** (`soft` reads calmer) or add your own
+brand color as an app-local variable used only for non-semantic chrome (a logo, a splash).
+Do not remap junoui's roles to a brand hue — that erases the shared meaning across apps.
+
+## 6. Extending — where new things go
+
+| Need                                                     | Where                                                                                                                    |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| New **status meaning**, reusable across apps             | Propose a new role in junoui core (semver: additive = minor). Rare.                                                      |
+| A full **alternate theme** (same role names, new values) | A new **palette** (like `standard`/`colorblind`/`soft`) — the sanctioned expansion slot.                                 |
+| App-specific **decorative** color                        | App-local, **namespaced** (`--myapp-*`), layered on top; alias to `--juno-*` where you can. Never redefine junoui roles. |
+| A **component** junoui lacks (e.g. chat bubble)          | Build it locally against the token contract until junoui (or a `junoui-<domain>` layer) ships it.                        |
+
+Rule of thumb: extend **additively and namespaced**. If every app injects its own palette
+into junoui, the single-design guarantee dies.
+
+## 7. Stateful behavior stays in your app
+
+junoui ships no JS. Focus traps, list virtualization, popover positioning, data — all
+yours (or a future sibling `junoui-<framework>` package). junoui gives you the stable,
+semantic DOM (real elements, BEM classes, ARIA hooks) to wire behavior + analytics onto;
+see [accessibility.md](./accessibility.md) for the per-component ARIA contract.

package/docs/layout.md

@@ -0,0 +1,201 @@
+# Layout & responsiveness
+
+How blocks adapt — defined once, inherited by every UI. Two mechanisms:
+
+1. **Intrinsic layout primitives** — reflow by available space, no media queries.
+2. **Container queries** — a component restyles by _its own_ width, not the viewport
+   (right for a library dropped into unknown layouts).
+
+Breakpoint tokens (`--juno-bp-sm…2xl`) follow Tailwind's scale and exist for the
+rare viewport-level case.
+
+## Why container queries over viewport breakpoints
+
+junoui components live inside arbitrary app skeletons. A card doesn't know if it's
+in a 280px sidebar or full width — so it adapts to its container:
+
+```css
+.juno-card {
+  container-type: inline-size;
+} /* already set */
+```
+
+`.juno-card__row` stacks automatically when the card is < 320px wide, anywhere.
+
+## Layout primitives
+
+Wrap a region; it adapts on resize. Every knob is a custom property with a token
+default — override per instance inline.
+
+| Class                    | Does                                     | Key knob (default)                       |
+| ------------------------ | ---------------------------------------- | ---------------------------------------- |
+| `.juno-center`           | Max-measure wrapper, fluid gutters       | `--juno-measure` (`bp-xl`)               |
+| `.juno-stack`            | Vertical rhythm between children         | `--juno-stack-space` (`space-16`)        |
+| `.juno-cluster`          | Wrapping inline group (toolbars, tags)   | `--juno-cluster-space` (`space-8`)       |
+| `.juno-grid-auto`        | Cards that collapse columns themselves   | `--juno-grid-min` (`240px`)              |
+| `.juno-grid-auto--tiles` | Media wall wired to the density layer    | `--juno-tile-min` / `--juno-gap-content` |
+| `.juno-sidebar`          | Aside + fluid content, stacks when tight | `--juno-sidebar-width` (`280px`)         |
+| `.juno-switcher`         | N-up or all-stacked at a threshold       | `--juno-switcher-threshold` (`bp-sm`)    |
+| `.juno-reel`             | Horizontal scroll-snap row               | `--juno-reel-space` (`space-12`)         |
+
+### Examples
+
+```html
+<!-- responsive card grid — no breakpoints, columns just fit -->
+<div class="juno-grid-auto" style="--juno-grid-min:280px;">
+  <article class="juno-card">…</article>
+  <article class="juno-card">…</article>
+  <article class="juno-card">…</article>
+</div>
+
+<!-- toolbar that wraps -->
+<div class="juno-cluster">
+  <button class="juno-btn juno--nominal">CONFIRM</button>
+  <button class="juno-btn juno-btn--ghost">CANCEL</button>
+</div>
+
+<!-- sidebar + content; stacks when content would get too narrow -->
+<div class="juno-sidebar">
+  <aside class="juno-sidebar__aside">…</aside>
+  <main class="juno-sidebar__main">…</main>
+</div>
+
+<!-- two-up that flips to stacked under ~640px of space -->
+<div class="juno-switcher">
+  <div>A</div>
+  <div>B</div>
+</div>
+
+<!-- media wall: tile size + gap follow [data-juno-density] -->
+<div class="juno-grid-auto juno-grid-auto--tiles"><img … /><img … /><img … /></div>
+```
+
+`--tiles` reads `--juno-tile-min` / `--juno-gap-content` from the density layer
+(`150px` / `space-10` comfortable, `108px` / `space-4` compact), so one
+`data-juno-density` attribute re-densifies controls, surfaces **and** content
+grids together.
+
+## App shell
+
+Every product app assembles the same frame; `.juno-app-shell` ships it as
+classes — a collapsible [rail](./components/rail.md), a topbar, a scrolling
+content outlet, and a [dock](./components/dock.md) at the foot — so you stop
+copy-pasting the same `<style>` block into every app.
+
+```html
+<div class="juno-app-shell">
+  <nav class="juno-rail juno-rail--responsive" aria-label="Primary">
+    <div class="juno-rail__brand">JUNO</div>
+    <a class="juno-rail__item" href="/library" aria-current="page">
+      <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+      <span class="juno-rail__label">Library</span>
+    </a>
+  </nav>
+  <div class="juno-app-shell__body">
+    <header class="juno-app-shell__topbar">
+      <input class="juno-input" type="search" placeholder="SEARCH…" />
+      <span class="juno-badge juno-badge--soft juno--nominal">ONLINE</span>
+    </header>
+    <main class="juno-app-shell__main">…</main>
+    <nav class="juno-dock 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>
+    </nav>
+  </div>
+</div>
+```
+
+What the primitive encodes so you don't have to:
+
+- **`100dvh`, not `100vh`** — the shell fills the _dynamic_ viewport, so the
+  dock isn't clipped by the phone's shrinking address bar.
+- **The `__main` region is the scroller**, not the page. The dock (or
+  [pillbar](./components/pillbar.md)) is a flex sibling at the body foot, so it
+  stays pinned with zero `sticky`/`fixed` and never overlaps content — the
+  short-page pitfall of sticky nav bars (below) can't happen here.
+- **Safe-area insets** — the shell pads for landscape notches
+  (`inset-left`/`right`), the topbar for `inset-top`, the dock for
+  `inset-bottom`.
+
+Collapse the rail by toggling `.juno-rail--collapsed` (one class; the width
+transition and label hiding are built in). Trays/detail panels: the
+[slide-over](./components/drawer.md#the-slide-over-pattern) pattern in the
+drawer doc. Knobs: `--juno-app-shell-topbar-size` (topbar height).
+
+### Narrow viewports (phone)
+
+The rail↔dock swap is two classes, no JS: `.juno-rail--responsive` self-hides
+below `md`, and the dock carries `.juno-hide-from-md` so it shows only there.
+(Equivalent to hanging `.juno-hide-below-md` on the rail yourself — the
+modifier just saves you knowing to.) Keep 3–5 dock destinations; the rest go
+behind a "More" item (drawer or menu). Prefer a floating bar? Swap the dock
+for a [pillbar](./components/pillbar.md) — same contract, capsule look.
+
+**Viewport helpers.** For the cases an intrinsic primitive can't express
+(swap a nav for a menu button), hide/show by breakpoint at `sm` (640px),
+`md` (768px), `lg` (1024px):
+
+| Class                                        | Visible        |
+| -------------------------------------------- | -------------- |
+| `.juno-hide-below-md` / `.juno-show-from-md` | at `md` and up |
+| `.juno-hide-from-md` / `.juno-show-below-md` | below `md`     |
+
+`show-*` are readable aliases for the inverse `hide-*` (`show-from-md` ≡
+`hide-below-md`); pick whichever reads clearer at the call site. Same three
+cut points for `sm` and `lg`.
+
+### Page-scroll shells (dock/pillbar `--fixed`)
+
+`.juno-app-shell` is the recommended frame because its `__main` scroller keeps
+the dock in flow. If instead the **whole page** scrolls, the dock/pillbar use
+`position: sticky` — which only pins _while the column overflows_. On a short
+page that doesn't scroll, a sticky bar lands mid-content, reading as "not
+stuck." For that layout use `.juno-dock--fixed` (pins flush to the viewport
+foot) or `.juno-pillbar--fixed` (fixes to the viewport, still floating its gap
+above the foot) — then reserve the bar's footprint at the page foot (e.g.
+`padding-block-end`) so it doesn't cover the last row.
+
+### Tab + stack (phone navigation recipe)
+
+The full phone pattern is three parts: the dock or pillbar switches
+_sections_; inside a section, a [list](./components/list.md) row (or any
+link) pushes a detail view; every pushed view opens with a
+[navbar](./components/navbar.md) whose back control unwinds one level.
+junoui ships all three looks — the app owns the stack (routing/history):
+
+```html
+<div class="juno-app-shell">
+  <div class="juno-app-shell__body">
+    <!-- one section, drilled one level in -->
+    <header class="juno-navbar">
+      <a class="juno-navbar__back" href="/settings">
+        <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-caret-left" /></svg>
+        <span class="juno-navbar__back-label">Settings</span>
+      </a>
+      <h1 class="juno-navbar__title">Playback</h1>
+      <div class="juno-navbar__actions"></div>
+    </header>
+    <main class="juno-app-shell__main"><!-- .juno-list groups… --></main>
+    <nav class="juno-pillbar" aria-label="Primary"><!-- section tabs --></nav>
+  </div>
+</div>
+```
+
+## Adopting in an existing project
+
+No restructuring required — additive and incremental:
+
+1. Set `data-juno-palette` / `data-juno-mode`, swap hardcoded values → `var(--juno-*)`.
+2. Add component classes where blocks match.
+3. Wrap layout regions in a primitive (`.juno-grid-auto`, `.juno-cluster`, …) to get
+   reflow. Add `container-type: inline-size` to a wrapper for component-level queries.
+
+You opt in per region; nothing forces a markup shape.
+
+## The JS line
+
+These are all CSS. Behavior that needs state (resize observers feeding app state,
+virtualization, drag-resizable panels) belongs in your app or a sibling
+`junoui-<framework>` package — not the design system.

package/docs/native.md

@@ -0,0 +1,52 @@
+# Native mobile (Android / iOS)
+
+Native platforms can't parse `oklch()`, so colors are pre-converted to sRGB hex
+during the build. Values match the web rendering.
+
+## Android
+
+Copy or sync the generated resources into your module:
+
+```
+dist/android/colors.xml   →  res/values/colors.xml
+dist/android/dimens.xml   →  res/values/dimens.xml
+```
+
+Reference them:
+
+```xml
+<TextView
+    android:textColor="@color/standard_dark_nominal"
+    android:padding="@dimen/space_16"
+    android:textSize="@dimen/font_size_14" />
+```
+
+- Color names: `<palette>_<mode>_<role>` (e.g. `colorblind_dark_warning`).
+- Dimensions are `dp`; font sizes are `sp`.
+- Theme switching: pick the resource set for the active palette/mode, or split the
+  files into qualified `values-night/` for dark mode.
+
+## iOS (Swift)
+
+Add the generated file to your target:
+
+```
+dist/ios/JunoTokens.swift
+```
+
+```swift
+label.textColor = JunoTokens.standardDarkNominal
+let pad: CGFloat = JunoTokens.space16
+let body: CGFloat = JunoTokens.fontSize14
+```
+
+- Colors are `UIColor` constants named `<palette><Mode><Role>` (camelCase).
+- Dimensions are `CGFloat` constants.
+
+## Keeping in sync
+
+Re-run `npm run build` in junoui and re-copy the files (or script the copy in your
+CI). Because all platforms derive from the same `tokens/` source, the values can
+never drift between web and native.
+
+Exact values for every token: [tokens-reference.md](./tokens-reference.md).