@junoput01/junoui 0.2.0 → 0.3.0

package/docs/components/badge.md

@@ -0,0 +1,35 @@
+# Badge / status indicator
+
+A compact, uppercase status label.
+
+## Web
+
+```html
+<span class="juno-badge juno--nominal">NOMINAL</span>
+<span class="juno-badge juno-badge--outline juno--caution">CAUTION</span>
+```
+
+| Class                  | Effect                                         |
+| ---------------------- | ---------------------------------------------- |
+| `.juno-badge`          | Base. Filled: background = role, text = `s0`.  |
+| `.juno-badge--outline` | Transparent fill, text + border = role.        |
+| `.juno-badge--soft`    | Low-fill chip: role text on a 13% role wash.   |
+| `.juno-badge--micro`   | Data-UI atom: mono 10px, hairline role border. |
+| `.juno--<role>`        | Sets the color (required).                     |
+
+## Anatomy (any platform)
+
+- Font: B612, 700 weight, size `font.size.11`, uppercase, tracking `font.tracking.caps` (0.15em).
+- Padding: `space.4` vertical, `space.10` horizontal. Radius: `radius.3`.
+- **Filled:** fill = role color, text = `s0` (base surface).
+- **Outline:** transparent fill, text + 1px border = role color.
+
+## Usage
+
+- Use the semantic roles for status; `muted` for inactive/disabled.
+- Keep the text the literal status word — color reinforces, never replaces it.
+- `--micro` is for provenance/kind tags (`device`, `TRANSCODE`, model names) and
+  threshold values that repeat dozens of times per screen. Threshold coloring is app
+  policy — map value → role class yourself, e.g.
+  `juno-badge--micro juno--nominal` for a ≥ 90% confidence. Same recipe as the
+  [gauge](./gauge.md) thresholds.

package/docs/components/breadcrumb.md

@@ -0,0 +1,31 @@
+# Breadcrumb
+
+A horizontal trail of links to ancestor pages, ending at the current page. Built on a
+real `<nav><ol>`; the separator is a CSS chevron (no glyph font). Zero JS.
+
+## Web
+
+```html
+<nav class="juno-breadcrumb" aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/fleet">Fleet</a></li>
+    <li><a aria-current="page">api-gateway</a></li>
+  </ol>
+</nav>
+```
+
+| Part / attr             | Effect                                               |
+| ----------------------- | ---------------------------------------------------- |
+| `.juno-breadcrumb`      | `<nav>` wrapper; lay out an `<ol>` of `<li>` inside. |
+| `li + li::before`       | CSS chevron separator (rotates under RTL).           |
+| `a[href]`               | `label` link → `data` + underline on hover.          |
+| `[aria-current="page"]` | The current crumb — brightest, semibold, not a link. |
+
+## Usage
+
+- Always `aria-label="Breadcrumb"` on the `<nav>`, and `aria-current="page"` on the last
+  crumb (drop its `href` so it isn't a link).
+- Order matters: root → … → current, left to right (mirrors under `dir="rtl"`).
+- For very deep trails, collapse the middle to an ellipsis crumb the app expands — junoui
+  ships the look, the app owns the collapse.

package/docs/components/button.md

@@ -0,0 +1,32 @@
+# Button
+
+## Web
+
+```html
+<button class="juno-btn juno--nominal">CONFIRM</button>
+<button class="juno-btn juno-btn--ghost">CANCEL</button>
+<button class="juno-btn juno-btn--sm juno-btn--ghost">EDIT</button>
+<button class="juno-btn" disabled>DISABLED</button>
+```
+
+| Class              | Effect                                                                           |
+| ------------------ | -------------------------------------------------------------------------------- |
+| `.juno-btn`        | Base. Primary (filled): background = role, text = `s0`. Default role = `active`. |
+| `.juno-btn--ghost` | Transparent, `data` text, `border` outline; hover → `s2`.                        |
+| `.juno-btn--sm`    | Dense-toolbar size: `font.size.11`, `space.4` × `space.10`, `radius.3`.          |
+| `.juno--<role>`    | Sets the primary fill color.                                                     |
+| `:disabled`        | `muted` fill, `label` text, not-allowed.                                         |
+
+## Anatomy (any platform)
+
+- Font: B612, 700 weight, size `font.size.13`, uppercase, tracking `font.tracking.caps`.
+- Padding: `space.10` × `space.20`. Radius: `radius.4`. Min height: `size.tap.min` (24px; use 44px on mobile).
+- States: hover brighten ~8%, active darken ~6%, disabled = `muted`/`label`.
+
+## Usage
+
+- Primary action filled with `nominal` (confirm) or `active` (apply).
+- `warning` fill only for genuinely critical/destructive actions.
+- One primary per group; everything else is ghost.
+- `--sm` drops below the WCAG tap-minimum on purpose — it is for dense **desktop**
+  toolbars (40–46px chrome bars). Keep the default size anywhere touch is expected.

package/docs/components/card.md

@@ -0,0 +1,41 @@
+# Card / panel
+
+A surface grouping a titled header and a body.
+
+## Web
+
+```html
+<article class="juno-card juno-card--accent juno--caution">
+  <header class="juno-card__head">
+    HYD SYS B
+    <span class="juno-badge juno-badge--outline juno--caution">CAUTION</span>
+  </header>
+  <div class="juno-card__body">
+    <div class="juno-card__row">
+      <span class="juno-label">Pressure</span>
+      <span class="juno-value juno-text-caution">2,650</span>
+    </div>
+  </div>
+</article>
+```
+
+| Class                | Effect                                                 |
+| -------------------- | ------------------------------------------------------ |
+| `.juno-card`         | `s1` surface, 1px `border`, radius `radius.8`.         |
+| `.juno-card--accent` | 2px top edge in the role color (status hint).          |
+| `.juno-card--alert`  | Full border in role + tinted header — critical panels. |
+| `.juno-card__head`   | Uppercase title row; holds a status badge.             |
+| `.juno-card__body`   | Padded content column.                                 |
+| `.juno-card__row`    | Label-left / value-right baseline row.                 |
+
+## Anatomy (any platform)
+
+- Surface `s1`, border `border` 1px, radius `radius.8`.
+- Header: padding `space.12`/`space.16`, bottom 1px divider, title B612 600 uppercase tracking `wide`.
+- Body: padding `space.16`, rows gapped `space.12`.
+- Escalation: accent (2px top) → alert (full role border + `s2` header tinted in role).
+
+## Usage
+
+- One subject per card. Header carries the identifier + a status badge.
+- Match accent/alert role to the card's worst current status.

package/docs/components/checkbox.md

@@ -0,0 +1,41 @@
+# Checkbox & Radio
+
+Custom-styled native inputs (`appearance: none`) — keyboard and screen-reader support
+come for free. The checkbox is a **targeting-reticle** square whose solid core drops in
+on check; the radio is a ring with a center dot. Wrap with `.juno-choice` for a label row.
+
+## Web
+
+```html
+<label class="juno-choice"> <input class="juno-checkbox" type="checkbox" checked /> TCAS </label>
+
+<label class="juno-choice"> <input class="juno-radio" type="radio" name="mode" /> SELECTED </label>
+<label class="juno-choice">
+  <input class="juno-radio juno--target" type="radio" name="mode" checked /> MANAGED
+</label>
+
+<label class="juno-choice">
+  <input class="juno-checkbox" type="checkbox" disabled /> Restricted
+</label>
+```
+
+| Class            | Effect                                                    |
+| ---------------- | --------------------------------------------------------- |
+| `.juno-checkbox` | `space.16` reticle square; checked core + role ring-glow. |
+| `.juno-radio`    | Same as a circle with a center dot.                       |
+| `.juno-choice`   | Inline-flex label row; `gap-control`, `data` text.        |
+| `.juno--<role>`  | Recolors the core/dot (default `active`).                 |
+| `:checked`       | Border → role, 3px role glow, core scales in (spring).    |
+| `:disabled`      | `s1` + dimmed; row text → `muted`.                        |
+
+## Anatomy (any platform)
+
+- Box `space.16` on `control-surface` with a `control-edge` border; checked adds a
+  `border-width.3` ring at 22% role and a `space.8` core (spring scale-in).
+- Label row: B612 `font.size.13`, `data`, `gap-control` between box and text.
+
+## Usage
+
+- Checkbox = independent toggles; radio = one-of-many (share a `name`).
+- Keep the label inside the same `<label>` so the hit area covers both.
+- For a single on/off with an emphasized track, use the [switch](./switch.md).

package/docs/components/chip.md

@@ -0,0 +1,44 @@
+# Chip / Tag
+
+A compact pill for a discrete entity — a filter, a selected value, a removable tag.
+Where a [badge](./badge.md) is a **static** status label, a chip is **interactive**:
+selectable and/or dismissible. Reads `--juno-role` for its accent; the app owns
+selection and removal (zero JS).
+
+## Web
+
+```html
+<!-- plain tag -->
+<span class="juno-chip">us-east-1</span>
+
+<!-- role-tinted -->
+<span class="juno-chip juno--active">live</span>
+
+<!-- toggle (filter) chip -->
+<button class="juno-chip juno-chip--toggle juno--active" aria-pressed="true">Errors</button>
+
+<!-- removable -->
+<span class="juno-chip">
+  filter:prod
+  <button class="juno-chip__remove" aria-label="Remove prod filter">
+    <svg class="juno-icon juno-icon--sm" aria-hidden="true"><use href="…#juno-i-x" /></svg>
+  </button>
+</span>
+```
+
+| Class                | Effect                                                       |
+| -------------------- | ------------------------------------------------------------ |
+| `.juno-chip`         | Pill; `control-surface` fill, strong border, `data` text.    |
+| `.juno--<role>`      | Role accent (border + tinted fill + role text).              |
+| `.juno-chip--toggle` | Use on a `<button>`; `aria-pressed="true"` fills the accent. |
+| `.juno-chip__remove` | Trailing dismiss button (put an `x` icon inside; label it).  |
+| `:disabled`          | Dims + blocks pointer.                                       |
+
+## Usage
+
+- **Toggle chip:** a real `<button>`; the app flips `aria-pressed`. Use for filter sets.
+- **Removable chip:** the `__remove` button needs an `aria-label` ("Remove X"); the app
+  deletes the chip on click.
+- Chip vs badge: chip = interactive / user data; badge = read-only status. Don't make a
+  badge clickable — reach for a chip.
+- Color is never the only signal — the chip's text carries the meaning; role is accent.

package/docs/components/divider.md

@@ -0,0 +1,32 @@
+# Divider
+
+A hairline rule that separates content. Horizontal by default; vertical for a column
+separator; or labeled to break the line with a centered caption.
+
+## Web
+
+```html
+<!-- semantic horizontal break -->
+<hr class="juno-divider" />
+
+<!-- labeled -->
+<div class="juno-divider juno-divider--label">OR</div>
+
+<!-- vertical (inside a flex row) -->
+<span class="juno-divider juno-divider--vertical"></span>
+```
+
+| Class                     | Effect                                                              |
+| ------------------------- | ------------------------------------------------------------------- |
+| `.juno-divider`           | Full-width `border`-colored hairline.                               |
+| `.juno-divider--vertical` | Hairline column rule; stretches to the row (`align-self: stretch`). |
+| `.juno-divider--label`    | Caption centered between two rules (uppercase `label`).             |
+
+## Usage
+
+- Use a real `<hr>` for a **semantic** break; a `<span>` / `<div>` when it's purely
+  decorative.
+- The vertical variant needs a parent that gives it block size — a flex row works
+  (`align-self: stretch`); otherwise set a height.
+- Don't over-divide: whitespace separates most things. Reach for a rule only when groups
+  would otherwise read as one.

package/docs/components/dock.md

@@ -0,0 +1,56 @@
+# Dock
+
+The bottom navigation bar of the app shell on narrow viewports — 3–5 primary
+destinations as icon-over-label tap targets. The phone-width counterpart of the
+[rail](./rail.md); the swap recipe is in [layout.md](../layout.md#app-shell).
+
+## Web
+
+```html
+<nav class="juno-dock" aria-label="Primary">
+  <a class="juno-dock__item" href="/library" aria-current="page">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-dock__label">Library</span>
+  </a>
+  <a class="juno-dock__item" href="/nodes">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-hexagon" /></svg>
+    <span class="juno-dock__label">Nodes</span>
+  </a>
+</nav>
+```
+
+| Class / prop        | Effect                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `.juno-dock`        | Sticky bottom `s1` bar, 1px `border` seam on top, safe-area pad.                              |
+| `.juno-dock__item`  | Equal-width icon-over-label target, ≥ `size.tap.comfortable` tall.                            |
+| `.juno-dock__label` | The text — truncates with an ellipsis, never wraps.                                           |
+| `[aria-current]`    | Active item: `s2` fill + 2px role edge on top. Attribute, not class.                          |
+| `.juno-dock--fixed` | Pin to the viewport foot (`position: fixed`) — for page-scroll shells where sticky won't pin. |
+| `.juno--<role>`     | Active-edge color (default `active`).                                                         |
+
+## Anatomy (any platform)
+
+- Full-width bar on `s1`, hairline seam on the block-start edge; items split the
+  width evenly, icon above a `font.size.10` uppercase label.
+- Active = `s2` fill + `border.width.2` block-start edge in the role color —
+  the rail's active language rotated 90°.
+- Bottom padding extends into the safe area (`env(safe-area-inset-bottom)`)
+  so the home indicator never covers a target.
+
+## Usage
+
+- Keep it to 3–5 destinations; overflow belongs in a "More" item opening a
+  [drawer](./drawer.md) or [menu](./menu.md).
+- Sticky, not fixed: place it last inside the scrolling column and it pins
+  itself without overlapping content (no bottom-padding hacks). Best is the
+  [`.juno-app-shell`](../layout.md#app-shell) frame, whose `__main` region is
+  the scroller — the dock then sits at the body foot in flow.
+- **Short-page caveat:** sticky only pins while the column overflows. If the
+  _whole page_ scrolls and content is shorter than the viewport, the dock
+  lands mid-content. For that layout use `.juno-dock--fixed` (viewport-pinned)
+  and reserve its height at the page foot so it doesn't cover the last row.
+- Pair with the rail via the viewport helpers: `.juno-hide-below-md` on the
+  rail, `.juno-hide-from-md` on the dock. One nav is hidden from the
+  accessibility tree at a time, so both may share `aria-label="Primary"`.
+- The app sets `aria-current="page"` on the active item — junoui styles the
+  attribute so nav semantics stay honest.

package/docs/components/drawer.md

@@ -0,0 +1,60 @@
+# Drawer
+
+An edge-anchored `<dialog>` for secondary tasks and settings — same scrim and layer
+as the [modal](./modal.md), but it slides along one axis. Reuses `.juno-modal` for the
+surface; `.juno-drawer` re-pins and re-slides it.
+
+## Web
+
+```html
+<dialog class="juno-modal juno-drawer">
+  <!-- header / body / footer, same parts as a modal -->
+</dialog>
+
+<dialog class="juno-modal juno-drawer juno-drawer--start">…</dialog>
+<dialog class="juno-modal juno-drawer juno-drawer--bottom">…</dialog>
+```
+
+| Class                  | Effect                                                 |
+| ---------------------- | ------------------------------------------------------ |
+| `.juno-drawer`         | 380px, full height, pinned to the **inline-end** edge. |
+| `.juno-drawer--start`  | Pins to the inline-start edge.                         |
+| `.juno-drawer--bottom` | Full width, 60dvh, pinned to the bottom edge.          |
+
+## Anatomy (any platform)
+
+- Slide in from its edge, `motion.duration.base` (200ms) / `ease.decel`. Same scrim
+  (`opacity.scrim`) and shadow (`shadow.3`) as the modal.
+- Edge anchoring is logical (`margin-inline`), so start/end mirror under RTL.
+
+## The slide-over pattern
+
+The full production composition — scrim, end-anchored panel on `s1`, header row,
+scrolling body, pinned footer — assembled from existing parts. Copy-paste:
+
+```html
+<dialog class="juno-modal juno-drawer" aria-labelledby="tray-tag">
+  <div class="juno-modal__stripe"></div>
+  <div class="juno-modal__head">
+    <span class="juno-modal__tag" id="tray-tag">ACTIVE JOBS</span>
+    <button class="juno-modal__close" autofocus aria-label="Close">✕</button>
+  </div>
+  <div class="juno-modal__body"><!-- scrolls on its own --></div>
+  <div class="juno-modal__foot">
+    <button class="juno-btn juno-btn--ghost">CLEAR DONE</button>
+    <button class="juno-btn juno--warning">PAUSE ALL</button>
+  </div>
+</dialog>
+```
+
+`showModal()` provides the scrim (`::backdrop`, `opacity.scrim`) and z-order for
+free — no scrim element, no z-index bookkeeping. Head/body/foot are the modal
+parts; the drawer class only re-pins and re-slides the surface.
+
+## Usage
+
+- Settings panels, filters, detail editors that don't warrant leaving context.
+- Same `<dialog>` + `showModal()` contract as the modal.
+- **Phone widths (< `bp.sm`) are automatic:** side drawers cap at `85vw` so a
+  sliver of scrim stays visible (and tappable) for dismissal. The bottom
+  drawer always pads past the home indicator (`safe-area-inset-bottom`).

package/docs/components/field.md

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

package/docs/components/gauge.md

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

package/docs/components/icon-loader.md

@@ -0,0 +1,55 @@
+# Icon loader
+
+A nav destination's icon ringed by the spinning [arc](./loader.md#arc) while
+that section loads — the "this section is loading" affordance for a
+[rail](./rail.md), [dock](./dock.md), or [pillbar](./pillbar.md) item. The icon
+stays static on top; the arc sizes in `em` around it and takes no pointer
+events, so the item still clicks through. Zero JS in the CSS — the app toggles
+the arc's `--indeterminate` class to start/stop the spin.
+
+## Web
+
+```html
+<a class="juno-rail__item" href="/library" aria-current="page">
+  <span class="juno-icon-loader">
+    <svg class="juno-icon" aria-hidden="true"><use href="…#juno-i-squares-four" /></svg>
+    <span class="juno-arc juno-arc--indeterminate" role="status" aria-label="Loading"></span>
+  </span>
+  <span class="juno-rail__label">Library</span>
+</a>
+```
+
+When the section finishes, remove `.juno-arc--indeterminate` (or the whole
+`.juno-arc`). For a progress ring instead of an endless spin, drop
+`--indeterminate` and set `--juno-progress` (0–100) on the `.juno-arc`.
+
+| Class / prop              | Effect                                                         |
+| ------------------------- | -------------------------------------------------------------- |
+| `.juno-icon-loader`       | Positioned wrapper; sizes to the icon, centers the ring on it. |
+| `> .juno-icon`            | The static glyph, held above the ring.                         |
+| `> .juno-arc`             | The ring — `1.9em`, thin (`0.14em`), pointer-transparent.      |
+| `--juno-icon-loader-ring` | Override the ring diameter (default `1.9em`).                  |
+| `.juno--<role>`           | Ring color (default `active`).                                 |
+
+## Anatomy (any platform)
+
+- A wrapper the size of the icon; the arc is absolutely positioned and centered
+  over it, at a larger diameter so it rings the glyph.
+- The ring color is the semantic role; a `.juno--loading`/`.juno--active`
+  ancestor tints it.
+
+## Usage
+
+- **Concentric via a single-cell grid, never `translate(-50%, -50%)`** — the
+  icon and ring share one grid cell (`place-items: center`), so they're centered
+  on each other without any `transform`. The arc's rotation animation writes
+  `transform`, so a translate-based centering would be clobbered; keep the grid
+  approach if you re-roll the markup.
+- Gate the spin to first load, not every background refetch — a nav icon that
+  blinks on every poll reads as broken. Add `--indeterminate` when a section
+  has no data yet; remove it once loaded.
+- The arc carries the loading semantics (`role="status"` +
+  `aria-label="Loading"`); the icon stays `aria-hidden`. Don't also mark the
+  nav item busy — one announcement is enough.
+- Respects reduced motion via the arc's own stepped, low-key animation; see
+  [loader](./loader.md).

package/docs/components/icon.md

@@ -0,0 +1,49 @@
+# Icon
+
+A zero-JS inline-SVG glyph. Icons ship as one **SVG sprite** of `<symbol>`s; you
+reference a symbol with `<use>`. The glyph inherits the current text color and sizes
+in `em`, so it tracks `font-size` and the `[data-juno-text]` scale.
+
+Set ships [Phosphor Icons](https://phosphoricons.com) (bold weight) — MIT-licensed,
+free to redistribute and sell. The bundle carries the license in `src/icons/LICENSE`
+and a banner in the generated sprite; keep both when you ship.
+
+## Web
+
+```html
+<!-- decorative — hide from assistive tech -->
+<svg class="juno-icon" aria-hidden="true">
+  <use href="node_modules/junoui/dist/icons/juno-icons.svg#juno-i-gear" />
+</svg>
+
+<!-- meaningful — label it -->
+<svg class="juno-icon juno-icon--lg juno-icon--role juno--warning" role="img" aria-label="Warning">
+  <use href="…/juno-icons.svg#juno-i-warning" />
+</svg>
+```
+
+Import path: `@junoput01/junoui/icons` resolves to the sprite.
+
+| Class              | Effect                                                        |
+| ------------------ | ------------------------------------------------------------- |
+| `.juno-icon`       | 1.25em square, `fill: currentColor`, baseline-aligned inline. |
+| `.juno-icon--sm`   | 1em (matches surrounding text).                               |
+| `.juno-icon--lg`   | 1.75em.                                                       |
+| `.juno-icon--xl`   | 2.5em.                                                        |
+| `.juno-icon--role` | Tint with `var(--juno-role)` instead of inherited text color. |
+| `--juno-icon-size` | Override the size directly (any length).                      |
+
+## Sizing & color
+
+- **Color** is `currentColor`: an icon inside colored text matches it. Add
+  `.juno-icon--role` + a `.juno--<role>` ancestor (or set `--juno-role`) to tint by
+  status. Always pair a status color with a text label — color is never the only signal.
+- **Size** is `em`-relative, so icons grow with the type scale and stay proportional
+  inside buttons / inputs. For a fixed pixel size set `--juno-icon-size: 20px`.
+
+## Adding / changing icons
+
+Drop an SVG into `src/icons/` (must use `currentColor`, a `viewBox`), then
+`npm run build:icons` (part of `npm run build`). The file name becomes the symbol id
+`juno-i-<name>`. Swapping icon sets is a source change in `src/icons/` — keep the new
+set's license file alongside.

package/docs/components/input.md

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