@justanarthur/modo-ui 0.6.0-canary.8 → 0.6.0

package/DESIGN.md

@@ -1,623 +0,0 @@
----
-version: alpha
-name: UI — Fluid Functionalism for modo
-description: >-
-  A quiet, neutral, dense interface where motion carries the meaning: springs instead of durations,
-  one hover highlight that glides between rows, labels that get heavier without moving, eight nesting
-  surface levels, and overlays that melt out of whatever opened them through a liquid neck. Light values
-  are the plain token names; `-dark` twins are the dark scheme (every color is one light-dark() token in
-  tokens/colors.css and primitives/surface/surface.css).
-colors:
-  primary: "oklch(0.205 0 0)"
-  on-primary: "oklch(0.985 0 0)"
-  background: "oklch(0.985 0 0)"
-  background-dark: "oklch(0.205 0 0)"
-  foreground: "oklch(0.205 0 0)"
-  foreground-dark: "oklch(0.97 0 0)"
-  card: "oklch(1 0 0)"
-  card-dark: "oklch(0.264 0 0)"
-  muted: "oklch(0.967 0.001 286.375)"
-  muted-dark: "oklch(0.235 0 0)"
-  muted-foreground: "oklch(0.556 0 0)"
-  muted-foreground-dark: "oklch(0.7155 0 0)"
-  accent: "oklch(0.922 0 0)"
-  accent-dark: "oklch(0.439 0 0)"
-  selected: "oklch(0.87 0 0)"
-  selected-dark: "oklch(0.439 0 0)"
-  border: "color-mix(in srgb, oklch(0.205 0 0) 12%, transparent)"
-  border-dark: "color-mix(in srgb, oklch(0.97 0 0) 12%, transparent)"
-  input: "oklch(0.922 0 0)"
-  input-dark: "oklch(0.371 0 0)"
-  control-border: "oklch(0.708 0 0)"
-  control-border-dark: "oklch(0.556 0 0)"
-  hover: "rgb(0 0 0 / 0.04)"
-  hover-dark: "rgb(255 255 255 / 0.06)"
-  active: "rgb(0 0 0 / 0.07)"
-  active-dark: "rgb(255 255 255 / 0.1)"
-  scrim: "oklch(0 0 0 / 0.4)"
-  scrim-dark: "oklch(0 0 0 / 0.8)"
-  brand: "oklch(0.693 0.16 265)"
-  brand-hover: "oklch(0.649 0.164 264.76)"
-  focus-ring: "oklch(0.693 0.16 265)"
-  thumb: "oklch(1 0 0)"
-  destructive: "oklch(0.6368 0.2078 25.33)"
-  destructive-dark: "oklch(0.7106 0.1661 22.22)"
-  destructive-light: "oklch(0.971 0.013 17.38)"
-  destructive-light-dark: "oklch(0.2575 0.0886 26.04)"
-  destructive-strong: "oklch(0.47 0.175 27)"
-  destructive-strong-dark: "oklch(0.81 0.105 22)"
-  destructive-wash: "color-mix(in oklab, oklch(0.6368 0.2078 25.33) 16%, transparent)"
-  destructive-wash-dark: "color-mix(in oklab, oklch(0.7106 0.1661 22.22) 16%, transparent)"
-  destructive-wash-hover: "color-mix(in oklab, oklch(0.6368 0.2078 25.33) 20%, transparent)"
-  destructive-wash-hover-dark: "color-mix(in oklab, oklch(0.7106 0.1661 22.22) 20%, transparent)"
-  destructive-wash-active: "color-mix(in oklab, oklch(0.6368 0.2078 25.33) 24%, transparent)"
-  destructive-wash-active-dark: "color-mix(in oklab, oklch(0.7106 0.1661 22.22) 24%, transparent)"
-  success-strong: "oklch(0.46 0.12 151)"
-  success-strong-dark: "oklch(0.83 0.15 152)"
-  success-wash: "color-mix(in oklab, oklch(0.723 0.192 149.58) 16%, transparent)"
-  success-wash-hover: "color-mix(in oklab, oklch(0.723 0.192 149.58) 20%, transparent)"
-  success-wash-active: "color-mix(in oklab, oklch(0.723 0.192 149.58) 24%, transparent)"
-  status-success: "oklch(0.723 0.192 149.58)"
-  status-loading: "oklch(0.715 0 0)"
-  status-warning: "oklch(0.7686 0.1647 70.08)"
-  status-info: "oklch(0.623 0.188 259.81)"
-  skeleton: "color-mix(in oklab, oklch(0.205 0 0) 8%, transparent)"
-  skeleton-dark: "color-mix(in oklab, oklch(0.97 0 0) 8%, transparent)"
-  image-edge: "rgb(0 0 0 / 0.1)"
-  image-edge-dark: "rgb(255 255 255 / 0.1)"
-  progress-track: "color-mix(in oklab, oklch(0.205 0 0) 10%, transparent)"
-  progress-track-dark: "color-mix(in oklab, oklch(0.97 0 0) 10%, transparent)"
-  well: "oklch(0.967 0.001 286.375)"
-  well-dark: "oklch(0 0 0 / 0.25)"
-  surface-1: "oklch(0.985 0 0)"
-  surface-2: "oklch(0.991 0 0)"
-  surface-3: "oklch(1 0 0)"
-  surface-4: "oklch(1 0 0)"
-  surface-5: "oklch(1 0 0)"
-  surface-6: "oklch(1 0 0)"
-  surface-7: "oklch(1 0 0)"
-  surface-8: "oklch(1 0 0)"
-  surface-1-dark: "oklch(0.205 0 0)"
-  surface-2-dark: "oklch(0.235 0 0)"
-  surface-3-dark: "oklch(0.264 0 0)"
-  surface-4-dark: "oklch(0.293 0 0)"
-  surface-5-dark: "oklch(0.321 0 0)"
-  surface-6-dark: "oklch(0.349 0 0)"
-  surface-7-dark: "oklch(0.375 0 0)"
-  surface-8-dark: "oklch(0.402 0 0)"
-typography:
-  display:
-    fontFamily: Inter Variable
-    fontSize: 28px
-    fontWeight: 700
-    lineHeight: 34px
-    fontVariation: "'wght' 700, 'opsz' 25"
-  title:
-    fontFamily: Inter Variable
-    fontSize: 16px
-    fontWeight: 550
-    lineHeight: 22px
-    fontVariation: "'wght' 550, 'opsz' 18"
-  subtitle:
-    fontFamily: Inter Variable
-    fontSize: 14px
-    fontWeight: 550
-    lineHeight: 20px
-    fontVariation: "'wght' 550, 'opsz' 18"
-  body:
-    fontFamily: Inter Variable
-    fontSize: 13px
-    fontWeight: 400
-    lineHeight: 20px
-    fontVariation: "'wght' 400, 'opsz' 14"
-  body-selected:
-    fontFamily: Inter Variable
-    fontSize: 13px
-    fontWeight: 550
-    lineHeight: 20px
-    fontVariation: "'wght' 550, 'opsz' 18"
-  caption:
-    fontFamily: Inter Variable
-    fontSize: 12px
-    fontWeight: 400
-    lineHeight: 16px
-    fontVariation: "'wght' 400, 'opsz' 14"
-  caption-medium:
-    fontFamily: Inter Variable
-    fontSize: 12px
-    fontWeight: 450
-    lineHeight: 16px
-    fontVariation: "'wght' 450, 'opsz' 15"
-  micro:
-    fontFamily: Inter Variable
-    fontSize: 11px
-    fontWeight: 400
-    lineHeight: 14px
-    fontVariation: "'wght' 400, 'opsz' 14"
-  display-compact:
-    fontFamily: Inter Variable
-    fontSize: 24px
-    fontWeight: 700
-    lineHeight: 34px
-    fontVariation: "'wght' 700, 'opsz' 25"
-  title-compact:
-    fontFamily: Inter Variable
-    fontSize: 15px
-    fontWeight: 550
-    lineHeight: 22px
-    fontVariation: "'wght' 550, 'opsz' 18"
-  subtitle-compact:
-    fontFamily: Inter Variable
-    fontSize: 13px
-    fontWeight: 550
-    lineHeight: 20px
-    fontVariation: "'wght' 550, 'opsz' 18"
-  body-compact:
-    fontFamily: Inter Variable
-    fontSize: 12px
-    fontWeight: 400
-    lineHeight: 20px
-    fontVariation: "'wght' 400, 'opsz' 14"
-  caption-compact:
-    fontFamily: Inter Variable
-    fontSize: 11px
-    fontWeight: 400
-    lineHeight: 16px
-    fontVariation: "'wght' 400, 'opsz' 14"
-  micro-compact:
-    fontFamily: Inter Variable
-    fontSize: 10px
-    fontWeight: 400
-    lineHeight: 14px
-    fontVariation: "'wght' 400, 'opsz' 14"
-  code:
-    fontFamily: ui-monospace
-    fontSize: 12px
-    fontWeight: 400
-    lineHeight: 16px
-rounded:
-  glyph: 3px
-  box: 5px
-  md: 6px
-  lg: 8px
-  focus-ring: 10px
-  xl: 12px
-  2xl: 16px
-  pill: 20px
-  pill-focus-ring: 22px
-  3xl: 24px
-  full: 9999px
-spacing:
-  space-1: 4px
-  space-2: 8px
-  space-3: 12px
-  space-4: 16px
-  space-5: 24px
-  space-6: 32px
-  control: 36px
-  control-compact: 28px
-  segment-item: 28px
-  segment-item-compact: 24px
-  control-px: 12px
-  control-px-compact: 10px
-  row-px: 8px
-  row-px-compact: 6px
-  gap: 8px
-  gap-compact: 4px
-  icon: 16px
-  icon-compact: 14px
-  goo-neck: 12px
-  measure: 45rem
-motion:
-  fast: 80ms
-  fast-exit: 60ms
-  moderate: 160ms
-  moderate-exit: 120ms
-  slow: 240ms
-  slow-exit: 160ms
-  goo: 250ms
-  goo-exit: 200ms
-  loop: 2s
-components:
-  button-primary:
-    backgroundColor: "{colors.foreground}"
-    textColor: "{colors.background}"
-    typography: "{typography.body}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.control}"
-    padding: 0 16px
-  button-primary-hover:
-    backgroundColor: "color-mix(in srgb, oklch(0.205 0 0) 90%, oklch(0.985 0 0))"
-  button-primary-active:
-    backgroundColor: "color-mix(in srgb, oklch(0.205 0 0) 80%, oklch(0.985 0 0))"
-  button-secondary:
-    backgroundColor: "{colors.accent}"
-    textColor: "{colors.foreground}"
-    typography: "{typography.body}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.control}"
-    padding: 0 16px
-  button-secondary-hover:
-    backgroundColor: "color-mix(in srgb, oklch(0.922 0 0) 80%, oklch(0.985 0 0))"
-  button-tertiary:
-    textColor: "{colors.foreground}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.control}"
-    padding: 0 16px
-  button-tertiary-hover:
-    backgroundColor: "{colors.hover}"
-  button-ghost:
-    textColor: "{colors.muted-foreground}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.control}"
-  button-ghost-hover:
-    backgroundColor: "{colors.hover}"
-  button-compact:
-    typography: "{typography.body-compact}"
-    height: "{spacing.control-compact}"
-    padding: 0 12px
-  input-field:
-    textColor: "{colors.foreground}"
-    typography: "{typography.body}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.control}"
-    padding: 0 10px
-  input-field-focus:
-    backgroundColor: "{colors.card}"
-  menu-popup:
-    backgroundColor: "{colors.surface-3}"
-    rounded: "{rounded.xl}"
-  menu-row:
-    textColor: "{colors.foreground}"
-    typography: "{typography.body}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.control}"
-    padding: 0 8px
-  hover-highlight:
-    backgroundColor: "{colors.hover}"
-    rounded: "{rounded.lg}"
-  popover:
-    backgroundColor: "{colors.surface-3}"
-    rounded: "{rounded.xl}"
-    padding: 16px
-  dialog:
-    backgroundColor: "{colors.surface-5}"
-    rounded: "{rounded.xl}"
-    padding: 24px
-    width: 400px
-  tabs-list:
-    backgroundColor: "{colors.well}"
-    rounded: "{rounded.xl}"
-    height: "{spacing.control}"
-    padding: 4px
-  tabs-indicator:
-    backgroundColor: "{colors.surface-4}"
-    rounded: "{rounded.lg}"
-    height: "{spacing.segment-item}"
-  tooltip:
-    backgroundColor: "{colors.foreground}"
-    textColor: "{colors.background}"
-    typography: "{typography.caption-medium}"
-    rounded: "{rounded.lg}"
-    padding: 4px 8px
-  badge:
-    typography: "{typography.caption-medium}"
-    rounded: "{rounded.lg}"
-    height: 24px
-    padding: 0 10px
-  switch-track-on:
-    backgroundColor: "{colors.brand}"
-  switch-thumb:
-    backgroundColor: "{colors.thumb}"
-    rounded: "{rounded.full}"
-  code-block:
-    backgroundColor: "{colors.surface-2}"
-    textColor: "{colors.foreground}"
-    typography: "{typography.code}"
-    rounded: "{rounded.xl}"
-    padding: 16px
----
-
-# UI — Fluid Functionalism for modo
-
-The `ui` design system: Fluid Functionalism (Base UI flavor, MIT © 2026 Micka Touillaud) on UnoCSS and
-`cn`, plus a local morph layer that makes overlays and indicators liquid. The front matter holds the
-normative values; the CSS custom properties in `tokens/*.css` and `primitives/surface/surface.css` are
-the source they are copied from, and they win if the two ever disagree. Component code never writes
-these values: it reads the utility that maps to each token (the class in backticks below).
-
-## Overview
-
-Functional first, then fluid. The interface is neutral, compact and quiet at rest, and almost every
-pixel of personality is spent on *how things change*: a state change is always legible, never abrupt,
-and never decorative.
-
-- **Neutral, ink on paper.** Greyscale everywhere. The one chromatic accent, a cool blue (`brand`), is
-  reserved for focus, "on" (switch track), drop targets and the selected swatch. Status hues appear only
-  in toasts, badges and errors.
-- **Dense, desktop-grade.** 13px body text, 36px controls, a 28px compact step for toolbars, tables and
-  sidebars. Density is chosen per region (`SizeProvider`), never per control.
-- **Hierarchy from size, weight and elevation**, not from color, borders, capitals or letter-spacing.
-- **Motion is the signature.** Springs, not durations. One hover highlight per list that glides to the
-  nearest row. Selection backgrounds that melt from item to item like a drop of liquid. Overlays that
-  grow out of the control that opened them through a goo neck, then let go.
-- **Calm under reduced motion.** Every effect degrades to a fade: fewer and gentler, never none.
-
-The feeling to aim for: a precise instrument that happens to be made of liquid. Nothing bounces for
-fun; the only overshoot in the system is the slow tier's 0.12 and the goo's 0.15.
-
-## Colors
-
-Two text colors, a greyscale ground, one blue.
-
-- **Foreground (`text-foreground`)** — near-black ink in light, near-white in dark. Headings, labels,
-  values, selected items, the primary button's fill (until `--primary` is re-pointed).
-- **Muted foreground (`text-muted-foreground`)** — the only secondary text color: descriptions, captions,
-  placeholders, idle icons, idle tab labels. Never an opacity step of foreground (`text-foreground/60`
-  is wrong); a third text tone does not exist.
-- **Background (`bg-background`)** — the page, equal to surface 1. Also the text color on the primary
-  button (until `--primary-foreground` is re-pointed) and the tooltip (`text-background`).
-- **Surfaces (`bg-surface-1` … `bg-surface-8`)** — the elevation ladder (see Elevation & Depth). Prefer a
-  surface level over `card`/`background` for anything that floats or nests.
-- **Muted (`bg-muted`)** — a sunken fill: a field's hover wash, a queued row. In dark it is surface 2, so
-  it never carries a track: it would vanish on a card or the inset.
-- **Well (`bg-well`)** — the recessed track under a segmented control's indicator (the tabs list). Light is
-  muted; dark is black at 25%, which darkens whatever it sits on, so the track reads on the page, a card
-  and the inset alike.
-- **Accent (`bg-accent`)** — the secondary button and the switch's off track. `selected` is a firmer
-  grey for persistent selection fills.
-- **Hover / Active (`bg-hover`, `bg-active`)** — translucent overlays (black 4% / 7% in light, white 6% /
-  10% in dark) so they read on any surface level. Every hover and press fill uses them; never an ad-hoc
-  grey. The raw tint direction is `--overlay` (`bg-overlay/8` → `rgb(var(--overlay) / 0.08)`).
-- **Border (`border-border`, `ring-border`)** — 12% of foreground, so it tracks the scheme and nested
-  forced scopes. Hairlines only, 1px.
-- **Brand (`bg-brand`, `ring-focus-ring`)** — `focus-ring` is `brand`: every keyboard ring is a 1px blue
-  ring 2px outside the element. The single theming point for focus.
-- **Primary (`bg-primary`, `text-primary-foreground`)** — the primary Button's theme hooks, so a host can
-  recolour it without forking the component: `--primary` (the fill, default `foreground`), `--primary-hover`
-  and `--primary-active` (default: `--primary` mixed 10% / 20% toward `background`), `--primary-foreground`
-  (the label, default `background`) and `--shadow-button-primary` (an extra shadow list drawn on the fill
-  layer, after its press ring: a lit edge, an outline, a drop; default the invisible `0 0 #0000`). All
-  five default to the ink look, so nothing moves until one is overridden. Re-point them on
-  `:root, .light, .dark` (zero-specificity defaults, so any stylesheet order wins), and set the hover and
-  active steps with the fill, since their defaults mix from the `--primary` they are declared with.
-  Other ink fills (checkbox, switch, progress, …) still read `foreground`.
-- **Destructive (`text-destructive`, `bg-destructive-light`)** — errors and destructive confirms only.
-- **Tinted actions (`text-destructive-strong` on `bg-destructive-wash`, `text-success-strong` on
-  `bg-success-wash`)** — the destructive and success buttons: the hue as text, dark enough for AA on its
-  wash, over a translucent wash of it that deepens on hover and press (`-hover`, `-active`). Never a
-  solid fill.
-- **Skeleton (`bg-skeleton`)** — 8% of foreground: the loading placeholder, quieter than any border.
-- **Image edge (`outline-image-edge`)** — a 1px inset edge (black or white at 10%) on images and
-  avatars, so a picture keeps its outline on any substrate.
-- **Progress track (`bg-progress-track`)** — 10% of foreground under the ink (`bg-foreground`) fill of
-  a progress bar.
-- **Status (`text-status-*`, `bg-status-*/16`)** — success, loading, error, warning, info, action. A
-  status shows as tinted text on a 16% wash of itself, never as a solid fill behind text.
-- **Scrim (`bg-scrim`)** — behind a modal dialog; it fades with the morph's progress.
-- **Syntax (`text-syntax-*`)** — low-chroma hues for code, so code reads as text first.
-
-Every color is one `light-dark(light, dark)` token; the scheme comes from `color-scheme` on `<html>`
-(`.light` / `.dark` pin it, also on any subtree). Shadows cannot ride `light-dark()`, so `--shadow-N` is
-re-pointed per scheme in `surface.css`.
-
-## Typography
-
-**Inter Variable** with its optical-size axis (`@fontsource-variable/inter/opsz.css`). The opsz axis is
-not optional: every weight is paired with an optical size so a label keeps its width when it gets
-heavier.
-
-Six roles, each a size and a whole-pixel line height, as utilities `text-<role>` (and
-`text-<role>-compact` for the compact step, which keeps the role's leading):
-
-| Role | Default | Compact | Use |
-|---|---|---|---|
-| `text-display` | 28/34 | 24 | The page title. The only bold text. |
-| `text-title` | 16/22 | 15 | Section headings, dialog titles. |
-| `text-subtitle` | 14/20 | 13 | Card and popover titles, emphasized rows. |
-| `text-body` | 13/20 | 12 | Control labels, rows, body copy. The default. |
-| `text-caption` | 12/16 | 11 | Descriptions, meta, errors, group labels, tooltips, badges. |
-| `text-micro` | 11/14 | 10 | Keycaps, counters, tiny chips. Single line only. |
-
-Body's 20px leading is what puts a padded row on the ladder: 8 + 20 + 8 = 36px.
-
-Weights come from `font-variation-settings`, through the `weight-*` utilities, never `font-*`:
-
-- `weight-normal` (400, opsz 14) — all running text and idle labels.
-- `weight-medium` (450, opsz 15) — small labels that need to hold on a fill: tooltips, badges, errors.
-- `weight-semibold` (550, opsz 18) — headings and anything selected, active or open.
-- `weight-bold` (700, opsz 25) — the display role only.
-
-A label that changes weight with state (a tab, a selected card title, an open accordion row) renders
-twice in one grid cell: an invisible `weight-semibold` copy reserves the width, the visible copy tweens
-`transition-[color,font-variation-settings] duration-fast`. Neighbours never move.
-
-No uppercase, no letter-spacing, no eyebrows above titles in new UI (`Card.Eyebrow` is the one vendored
-exception). Sentence case everywhere; the docs chrome capitalizes in content, not with CSS. Fixed-height
-labels trim their box (`[text-box:trim-both_cap_alphabetic]`) so the cap height sits optically centered.
-`h1–h3` balance, `p` wraps pretty. Code is `font-mono` at caption size.
-
-## Layout
-
-A 4px grid. Spacing tokens `--space-1…6` = 4, 8, 12, 16, 24, 32px (the docs chrome reads them);
-component code uses the matching utilities (`gap-1`, `p-4`, …), which sit on the same 4px grid.
-
-**The size ladder** is the layout system. Two steps only, and everything steps down together:
-
-| Token (`useSize()`) | Default | Compact |
-|---|---|---|
-| `control` (buttons, inputs, select triggers, **and** list/menu rows) | 36px `h-9` | 28px `h-7` |
-| `segmentItem` + `segmentPad` (segmented tabs) | 28 + 4 | 24 + 2 |
-| `text` | `text-body` | `text-body-compact` |
-| `px` (bounded controls) | 12px | 10px |
-| `itemPx` (rows inside a padded popup) | 8px | 6px |
-| `gap` (icon ↔ label, control ↔ control) | 8px | 4px |
-| `icon` (glyphs, checkbox squares) | 16px | 14px |
-
-A popup row is exactly as tall as the trigger that opened it. Density is a region decision: wrap the
-region in one `SizeProvider size="compact"` and every control in it (menus it opens included) follows.
-A component's own `size` prop wins over the provider.
-
-Other fixed measures: popovers cap at `min(92vw, 20rem)`; dialogs are 400 / 540 / 880px wide (`sm`,
-`lg`, `xl`), one notch narrower in compact regions; popup lists cap at `min(300px,
-var(--available-height))` and scroll inside `ScrollArea` with a scroll-aware `scroll-fade`; reading
-columns cap at `--modo-measure` (45rem). Native scrollbars are thin and low-contrast (overlay 8% → 12% on
-hover → 16% while dragging), matching the `ScrollArea` thumb.
-
-## Elevation & Depth
-
-Eight surface levels that nest. Each `bg-surface-N` pairs 1:1 with a `shadow-surface-N`.
-
-- **Light:** only two color steps (floor 0.985, sunken 0.991), then flat white from surface 3 up.
-  Elevation is carried by shadow alone: a 1px `--shadow-color` hairline (black 6%) plus stacked drops
-  whose offsets double per level (1, 3, 6, 12, 24, 48, 96px).
-- **Dark:** an additive ladder from 0.205 to 0.402 in even steps, each with an inset top highlight, an
-  inset ring and black drops.
-
-Substrate flows through React context (`useSurface()`, 1 = the page). A floating surface computes
-`min(substrate + offset, 8)`, paints that level and re-provides it, so a popover inside a dialog lands
-above the dialog without any prop:
-
-| Surface | Offset | Shadow |
-|---|---|---|
-| Code block | +1 | none |
-| Popover, dropdown, select, combobox, context menu, preview card, toast, search suggestions | +2 | fixed `shadow-surface-3` |
-| Tabs' active indicator | +3 | matches level |
-| Dialog, alert dialog, sheet | +4 | matches level |
-| Tooltip | inverted: `bg-foreground`, no shadow | — |
-
-Menus keep a fixed `shadow-surface-3` whatever their depth, so a menu still reads as a menu three layers
-down. Hover and pressed states are overlays (`bg-hover`, `bg-active`), not levels, so they work at any
-elevation. Use `Elevated offset={n}` (or `surfaceClasses(level)` / `SURFACE_BG[level]`) for anything new
-that floats; never hard-code a surface.
-
-## Shapes
-
-Rounded, concentric, never mixed. Two shape modes from `useShape()`; **rounded** is the default and what
-everything renders without a provider:
-
-| Slot | Rounded | Pill |
-|---|---|---|
-| `item`, `bg`, `button`, `input` | 8px `rounded-lg` | 20px |
-| `focusRing` (2px outside the element) | 10px | 22px |
-| `container` (popups, cards, dialogs, segmented tracks) | 12px `rounded-xl` | 24px |
-| `mergedBg` (merged selection runs) | 8px | 16px |
-
-A rounded surface nested close inside another uses concentric corners: inner = outer − inset − border.
-The shipped pair (12 → 8) assumes a 4px inset. Small boxes use `rounded-box` (5px: checkbox squares,
-keycaps) and `rounded-glyph` (3px). Thumbs, dots and the loading button are circles (`rounded-full`).
-Never write a radius: read `shape.*` so the pill mode follows.
-
-## Motion
-
-Springs, tiered by the size of what moves. The bigger the thing, the slower the spring. Never a
-hand-written duration; never a fourth speed.
-
-| Tier | Enter | Exit (tween, one tier quicker) | Use |
-|---|---|---|---|
-| `spring.fast` | 80ms spring, bounce 0 | 60ms | Hover highlight, focus ring, fades, icon stroke, weight changes |
-| `spring.moderate` | 160ms spring, bounce 0 | 120ms | Indicators, thumbs, small panels, width changes, the loading fold |
-| `spring.slow` | 240ms spring, bounce 0.12 | 160ms | Large surfaces: plain morphs, the search field's growth, shared parts |
-| `spring.goo` | 250ms visual, bounce 0.15 | 200ms spring back | Every goo morph, so the liquid neck is on screen long enough to read |
-
-CSS consumers use `duration-fast|moderate|slow[-exit]` and `delay-*`. `--duration-loop` (2s) is the
-period of pending-state loops (the indeterminate progress sweep, the spinner, the skeleton pulse); it is
-not a spring tier, and under reduced motion a loop pulses opacity in place. Animate `transform` and `opacity`;
-a measured geometry engine (the morph layer, `GooIndicator`) is the only thing that writes boxes.
-
-The signature behaviors:
-
-- **Fluid hover.** One `bg-hover` highlight per list, on the item nearest the cursor (inside wins, else
-  nearest center), so it never blinks off in a gap. It travels on `spring.fast` and melts between rows.
-  A fresh pointer entry fades in where it is instead of sliding across. A click in a gap goes to the lit
-  row: what is lit is what a click hits.
-- **Liquid indicators.** Anything that travels between items (the active tab, a switch thumb, selection
-  runs, the hover pill) leaves a blob behind that lingers a third of the spring and follows, melted
-  through a goo filter. At rest nothing is filtered.
-- **Morphing overlays.** Popover, dropdown, select, combobox, context menu, tooltip, preview card,
-  dialog, sheet, command, search suggestions and toasts grow from their source (`from`: the trigger,
-  the press point, the center, a window edge, or any element) with an `effect`: `goo` (default, a
-  liquid neck that pinches off), `morph` (the box grows), `slide` or `fade`. They close back into where
-  they came from. With `hideSource` the trigger *becomes* the panel.
-- **Press geometry.** A pressed button's fill shrinks exactly 1px per side at any width (spread shadow
-  collapse, not a scale), releasing slower than it presses.
-- **Icons thicken, labels don't move.** Hovered/active icons step stroke 1.5 → 2 on the fast tier.
-- **Loading folds.** A loading button folds its surface into a circle around the spinner while its box
-  stays put.
-- **Exits are crisp.** A dismissal never replays the entrance backwards.
-- **Reduced motion.** Every morph becomes a fade; travel snaps; opacity and color fades stay.
-
-## Components
-
-Each item lives at `<tier>/[<group>/]<name>/index.tsx` and composes from Base UI (behavior) plus the
-shared systems above (look and motion). Ready-made patterns to reach for before writing anything:
-
-- **Buttons** — `primary` (ink fill by default, the `--primary` theme hooks), `secondary` (accent fill), `tertiary` (transparent, a 1px
-  `border` ring that moves inward on press), `ghost` (transparent, muted text that turns foreground over
-  the hover overlay). A component token with no `backgroundColor` is transparent over its substrate.
-  Sizes `default` 36 / `compact` 28 / `icon` / `icon-compact`. Icons sit 4px closer to their edge than
-  text. `active` holds the pressed look while a menu it opened is showing. One primary per view.
-  `outline` is `tertiary` under its shadcn name. `destructive` and `success` are their hue as text on a
-  wash of it (Tinted actions), never a solid fill; `link` is underlined foreground text on the control
-  height, no padding. `xs` and `sm` resolve to `compact`: the ladder has two steps.
-- **Inputs** — transparent and ringless at rest, a `bg-muted/50` wash plus a `ring-border` ring on
-  hover, `bg-card` plus the ring on focus; read-only keeps the ring but never lifts the fill. The label
-  sits above in muted body text (an asterisk when required), help text below in muted caption, both
-  inset to the text. Errors: destructive caption at `weight-medium`, a `destructive-light` wash.
-  Adornments are muted and light with the field; field actions are 4px inside the ring. File
-  dropzones: a dashed hairline on the container radius, a muted fill while files hover over it,
-  destructive for files it won't take; a drag it can partly take keeps the neutral fill and says that
-  some will be skipped.
-- **Lists and menus** — rows on the control height, `itemPx` inset, one fluid hover highlight, rows
-  without their own `:hover` fill. Disabled rows stay registered but are skipped. Keyboard focus earns a
-  1px brand ring that springs between rows; pointer focus never shows it.
-- **Selection** — checkbox and radio rows melt their selected backgrounds into one run; tabs and
-  subtle tabs carry an elevated (+3) or translucent indicator that melts between items; the selected
-  label goes `weight-semibold`. Checkbox, radio and switch also come bare (no label): just the box,
-  circle or track, with a 1px focus ring offset 2px, for tables and hand-laid forms. An indeterminate
-  checkbox shows a dash that blurs into the check. A loading control keeps its box: the combobox
-  chevron blurs into a spinner in the same slot.
-- **Overlays** — popup surfaces at +2 with `shadow-surface-3`, dialogs at +4, `rounded-xl` containers,
-  12px goo neck between trigger and panel, content padding 16px (popover) or 24px (dialog). A confirm
-  that runs a task folds its button into the loading circle and holds the dialog until it settles.
-- **Tooltips** — inverted (`bg-foreground` / `text-background`), caption at `weight-medium`, morph from
-  the trigger, a hand-off between grouped tooltips is instant; the same label whether written flat or
-  as Trigger + Content parts.
-- **Badges** — 24px (20px compact), caption medium, a 15% wash of the color into the background with
-  foreground text; dot variant keeps a neutral outline; `outline` is that frame without the dot, and
-  no color.
-- **Toasts** — a status pill that melts into a body; status color as text on a 16% wash. Shown from
-  anywhere through the global `toast()`; a custom icon sits in the same status disc.
-- **Cards** — transparent and borderless, inheriting the substrate; hairline dividers and the fluid
-  hover do the framing; only clickable cards join the hover. `border="outlined"` gives a standalone
-  card the outlined group's hairline frame; `Card.Divider` is a full-bleed hairline between its parts.
-- **Pagination** — the current page is a liquid `bg-accent` indicator on the fluid-hover strip; dense
-  tables use the jump-to-page field.
-- **Avatar** — one control tall (36px, 28px compact), a circle, or a square on the item radius,
-  with the image edge; initials or an icon on `bg-accent` until the image loads, which then fades in.
-- **Progress** — a 4px pill: the ink fill slides to its value on `spring.moderate`; with no value a
-  segment sweeps the track on the loop period. The spinner is the loading button's figure-eight.
-- **Skeleton** — `bg-skeleton` blocks on the item radius pulsing in opacity, rows on the control
-  height; hidden from assistive tech (mark the loading region busy instead).
-- **Separator** — the one 1px `border` hairline, horizontal or vertical; no ornament.
-
-## Do's and Don'ts
-
-- Do compose from an existing item before writing a new one; wrap rather than fork vendored code.
-- Do read every visual from a token utility: `text-<role>`, `weight-*`, `bg-surface-N`,
-  `shadow-surface-N`, `bg-hover`, `shape.*`, `duration-<tier>`, `spring.*`.
-- Do lift floating surfaces relative to the substrate (`useSurface()` + offset) and re-provide the level.
-- Do size controls from `useSize()` and let regions choose density with `SizeProvider`.
-- Do give every list exactly one fluid hover highlight, and every traveling indicator a `GooIndicator`.
-- Do grow every new overlay out of its source through `useMorph` + `MorphSurface`.
-- Do test light, dark, compact, keyboard and reduced motion.
-- Don't write an arbitrary value for color, type, radius, shadow or motion (`text-[13px]`, `bg-[#…]`,
-  `rounded-[10px]`, `duration-[200ms]`); add the token instead. Layout geometry may be arbitrary.
-- Don't use a third text color, an opacity step of a text color, uppercase, letter-spacing, or `font-*`
-  weights.
-- Don't add a per-row `:hover` background next to a fluid hover list.
-- Don't hand-write a `duration`, an easing curve or a fourth spring; don't animate `top`/`left`/`width`/
-  `height` outside the morph engine.
-- Don't use the brand blue for anything but focus, "on", drop targets and selected swatches.
-- Don't hard-code a surface background or a radius: a menu inside a dialog must still lift.
-- Don't stack two measured-height animations: the outer one snaps when a child changed its size.

package/blocks/sidebar-app/examples.mdx

@@ -1,33 +0,0 @@
-import SidebarApp from './index'
-
-# Preset
-
-The preset as it ships: collapsed. Press the trigger (or `[`) and the sidebar slides in; pick a thread and the active row melts over to it.
-
-<div className="h-[560px] w-full overflow-hidden rounded-xl border border-border bg-background">
-  <SidebarApp contained />
-</div>
-
-# Open
-
-`defaultOpen` starts it expanded. Open the workspace switcher, a thread's "More options" or the user row: each menu grows out of its row.
-
-<div className="h-[560px] w-full overflow-hidden rounded-xl border border-border bg-background">
-  <SidebarApp contained defaultOpen />
-</div>
-
-# Open on hover
-
-`openOnHover`: move to the left edge or onto the topbar's trigger and the collapsed sidebar opens; leave it and it closes. Press the trigger to keep it open, again to go back to on hover.
-
-<div className="h-[560px] w-full overflow-hidden rounded-xl border border-border bg-background">
-  <SidebarApp contained openOnHover />
-</div>
-
-# Floating on the right
-
-The same shell with `variant="floating"` and `side="right"`; the shortcut becomes `]`.
-
-<div className="h-[560px] w-full overflow-hidden rounded-xl border border-border bg-background">
-  <SidebarApp contained defaultOpen variant="floating" side="right" />
-</div>