@lovett/ui 0.0.4 → 0.0.6

package/src/tokens.css

@@ -30,7 +30,7 @@
  *     • Text:      --foreground, --text-secondary, --text-tertiary,
  *                  --text-muted, --muted-foreground
  *     • Semantic:  --success(-bg), --warning(-bg), --info(-bg),
- *                  --destructive(-foreground)
+ *                  --destructive(-bg, -foreground)
  *     • Folder:    --folder-red/amber/emerald/teal/blue/violet/pink/
  *                  slate/ink (categorical palette for folder accents)
  *     • Spacing:   --space-1…12 (4 / 8 / 12 / 16 / 20 / 24 / 32 / 40 / 48)
@@ -125,32 +125,23 @@
   /* ============================================================
      DARK THEME SURFACES  — INTERNAL (primitives only)
      ============================================================ */
-  --background: 9 9 11;
   --foreground: 244 244 245;
-  --bg-surface: 17 17 19;
-  --bg-elevated: 24 24 27;
-  --bg-card: 20 20 22;
-  --bg-card-hover: 26 26 29;
-  --bg-input: 15 15 17;
-
-  --card: 20 20 22;
+  /* PUBLIC (ADR-063 D1): opaque elevated surface for bespoke lens/app
+     floating chrome (pills, capsules, one-off raised panels) that can't be a
+     primitive. Same values as the INTERNAL --bg-elevated by design. */
   --card-foreground: 244 244 245;
-  --popover: 24 24 27;
   --popover-foreground: 244 244 245;
-
-  --muted: 39 39 42;
   --muted-foreground: 161 161 170;
   --text-secondary: 161 161 170;
-  --text-tertiary: 113 113 122;
-  --text-muted: 82 82 91;
-
-  --secondary: 39 39 42;
+  /* Lifted 113->132 / 82->106: at the old values --text-tertiary measured
+     3.56:1 and --text-muted 2.22:1 on --bg-card, i.e. both under the 3:1
+     floor on the surface they are most often used on. */
+  --text-tertiary: 132 132 141;
+  --text-muted: 106 106 115;
   --secondary-foreground: 244 244 245;
 
   --border: 255 255 255 / 0.08;
   --border-strong: 255 255 255 / 0.14;
-  --input: 39 39 42;
-
   /* Semantic — PUBLIC */
   --success: 16 185 129;
   --success-bg: 16 185 129 / 0.12;
@@ -159,6 +150,7 @@
   --info: 59 130 246;
   --info-bg: 59 130 246 / 0.12;
   --destructive: 239 68 68;
+  --destructive-bg: 239 68 68 / 0.12;
   --destructive-foreground: 255 255 255;
 
   /* Folder palette — PUBLIC. Categorical accents for Asset folders
@@ -211,8 +203,6 @@
   --bullet-offset-y: 7px;
 
   /* Recessed card footer strip — INTERNAL (<Card.Foot>) */
-  --card-foot-bg: 255 255 255 / 0.025;
-
   /* Card surface — INTERNAL (<Card>) */
   --border-card: 255 255 255 / 0.08;
   --card-shadow-rest:
@@ -221,13 +211,10 @@
     0 4px 12px rgb(0 0 0 / 0.28);
 
   /* Card-tray — INTERNAL (<Card.Tray>) */
-  --tray-bg: 24 24 27;
-  --tray-inset: 10px;
+  --tray-inset: 4px;
   --radius-tray: var(--radius-md);
 
   /* Card frame — INTERNAL (outer .ds-card-surface bg in framed mode) */
-  --card-frame-bg: 20 20 22;
-
   /* ============================================================
      CALCULATOR SHELL v2 — INTERNAL (ADR-076 D7). Consumed only by
      the v2 primitives (CalculatorShellV2 header, StatRow tiles) and
@@ -250,7 +237,6 @@
   /* ============================================================
      MAIN CONTENT AREA — INTERNAL (layout primitives only)
      ============================================================ */
-  --main-content-bg: 10 10 11;
   --main-content-border: 255 255 255 / 0.08;
 
   /* ============================================================
@@ -294,9 +280,6 @@
   --surface-overlay: 255 255 255 / 0.06;
   --surface-overlay-strong: 255 255 255 / 0.10;
   --surface-overlay-stronger: 255 255 255 / 0.16;
-
-  --page-bg: 5 5 6;
-  --bg-input-hover: 19 19 22;
   --modal-overlay: 0 0 0 / 0.65;
 
   /* `--surface-on-accent` — PUBLIC (Phase Sidebar-E MIN-1, ADR-049).
@@ -349,7 +332,43 @@
   --toast-border: 255 255 255 / 0.10;
 
   /* Canvas placement bg — INTERNAL (placement primitive) */
-  --canvas-placement-bg: 17 17 19;
+
+  /* Surface ladder — dark. Same five roles, same hue family. */
+  --surface-page: 11 11 12;
+  --surface-frame: 21 21 23;
+  --surface-card: 27 27 30;
+  --surface-inset: 45 45 48;
+  --surface-hover: 55 55 59;
+  /* A control you can act on — input, select, option tile, chip-button.
+     Sits at CARD level on purpose: in light that is white against the
+     frame behind it, which reads "type here"; in dark it is raised above
+     the frame. --muted/--surface-inset is the RECESSED role (wells, zebra,
+     table headers) and reads as disabled when a control borrows it. The
+     lenses were borrowing it because --bg-input is internal and this
+     public role did not exist. */
+  --surface-control: var(--surface-card);
+  --surface-elevated: 37 37 40;
+
+  --page-bg: var(--surface-page);
+  --background: var(--surface-page);
+  --main-content-bg: var(--surface-page);
+  --bg-surface: var(--surface-frame);
+  --bg-card: var(--surface-card);
+  --card: var(--surface-card);
+  --tray-bg: var(--surface-card);
+  --card-frame-bg: var(--surface-frame);
+  --card-foot-bg: var(--surface-frame);
+  --bg-elevated: var(--surface-elevated);
+  --surface-raised: var(--surface-elevated);
+  --popover: var(--surface-elevated);
+  --bg-input: var(--surface-frame);
+  --muted: var(--surface-inset);
+  --input: var(--surface-inset);
+  --secondary: var(--surface-inset);
+  --canvas-placement-bg: var(--surface-frame);
+  --bg-card-hover: var(--surface-hover);
+  --bg-input-hover: var(--surface-inset);
+
 }
 
 /* ============================================================
@@ -382,27 +401,15 @@
    * almost entirely on --border-card (0.07). If cards visually
    * disappear, bump --border-card. Hover/muted/input-hover stay
    * darker on purpose so state changes remain visible. */
-  --background: 254 254 254;
   --foreground: 17 17 19;
-  --bg-surface: 254 254 254;
-  --bg-elevated: 255 255 255;
-  --bg-card: 255 255 255;
-  --bg-card-hover: 244 244 244;
-  --bg-input: 255 255 255;
-  --bg-input-hover: 253 253 253;
-
-  --card: 255 255 255;
+  /* PUBLIC (ADR-063 D1) — see the dark block note. */
   --card-foreground: 17 17 19;
-  --popover: 255 255 255;
   --popover-foreground: 17 17 19;
-
-  --muted: 245 245 245;
   --muted-foreground: 82 82 91;
   --text-secondary: 82 82 91;
   /* --text-tertiary stays from :root */
-  --text-muted: 161 161 170;
-
-  --secondary: 244 244 245;
+  /* Lifted 161->137 — was 2.56:1 on a white card. */
+  --text-muted: 137 137 146;
   --secondary-foreground: 17 17 19;
 
   --border: 0 0 0 / 0.12;
@@ -412,8 +419,6 @@
    * to delineate. The 0.16 value worked when --bg-input was slate-tinted; on
    * white-on-white the prior border was too subtle. */
   --border-input: 0 0 0 / 0.22;
-  --input: 244 244 245;
-
   --success: 5 150 105;
   --success-bg: 5 150 105 / 0.10;
   /* `--warning` and the folder palette are intentionally split out
@@ -423,13 +428,12 @@
   --info: 37 99 235;
   --info-bg: 37 99 235 / 0.10;
   --destructive: 220 38 38;
+  --destructive-bg: 220 38 38 / 0.10;
 
   --surface-overlay-soft: 0 0 0 / 0.03;
   --surface-overlay: 0 0 0 / 0.05;
   --surface-overlay-strong: 0 0 0 / 0.08;
   --surface-overlay-stronger: 0 0 0 / 0.12;
-
-  --page-bg: 254 254 254;
   --modal-overlay: 0 0 0 / 0.40;
   /* `--surface-on-accent` stays white in light mode too — see :root
    * comment. Declared here for symmetry / future-proofing. */
@@ -449,17 +453,7 @@
    * what was actually painting "the steely background" the owner
    * flagged; --page-bg is the body, but MainLayout's content area
    * paints with this token. Both must move together. */
-  --main-content-bg: 254 254 254;
   --main-content-border: 0 0 0 / 0.10;
-
-  --canvas-placement-bg: 241 245 249;
-
-  --card-foot-bg: 248 250 252;
-
-  --tray-bg: 255 255 255;
-
-  --card-frame-bg: 248 250 252;
-
   /* Calculator Shell v2 — light overrides (ADR-076 D7). */
   --brand-ink: 20 20 23;
   --shell-shadow:
@@ -483,6 +477,68 @@
     0 2px 4px rgb(0 0 0 / 0.07),
     0 8px 24px rgb(0 0 0 / 0.09);
 
+  /* ============================================================
+     SURFACE LADDER — the canonical set (2026-08-04)
+     ------------------------------------------------------------
+     Before this, 19 surface tokens carried 4 distinct values, in
+     THREE different grey families: --card-frame-bg / --card-foot-bg
+     at hue 248 (slate), --muted / --bg-card-hover at 90
+     (achromatic), --input / --secondary at 286 (zinc). Mixing grey
+     families is what reads as "inconsistent" long before anyone can
+     say which value is wrong.
+
+     Everything now sits on hue 286 — the family the TEXT ramp
+     already uses (--foreground and every --text-* measure 285.8-286.4),
+     so greys and type finally agree.
+
+     FIVE roles. Every legacy name below is an alias onto one of them,
+     so no component changes and nothing is orphaned:
+
+       page    the document. PURE WHITE — no grey backdrop.
+       card    cards, trays, inputs, popovers. Also white; separation
+               is border + shadow, not a fill step.
+       frame   the CONTAINED BACKGROUND for a group of sections —
+               <FrameStack> wrapping several <SectionCard>. The only
+               place a grey surface is correct.
+       inset   recessed wells, table header strips, zebra rows.
+       hover   the deepest step; hover on an inset.
+     ============================================================ */
+  --surface-page: 255 255 255;
+  --surface-card: 255 255 255;
+  --surface-frame: 247 247 249;
+  --surface-inset: 242 242 244;
+  --surface-hover: 238 238 240;
+  /* A control you can act on — input, select, option tile, chip-button.
+     Sits at CARD level on purpose: in light that is white against the
+     frame behind it, which reads "type here"; in dark it is raised above
+     the frame. --muted/--surface-inset is the RECESSED role (wells, zebra,
+     table headers) and reads as disabled when a control borrows it. The
+     lenses were borrowing it because --bg-input is internal and this
+     public role did not exist. */
+  --surface-control: var(--surface-card);
+
+  /* Legacy names — aliases onto the five above. Kept so the ~1,300
+     existing call sites keep working; prefer the canonical names. */
+  --page-bg: var(--surface-page);
+  --background: var(--surface-page);
+  --bg-surface: var(--surface-page);
+  --main-content-bg: var(--surface-page);
+  --bg-card: var(--surface-card);
+  --card: var(--surface-card);
+  --tray-bg: var(--surface-card);
+  --bg-elevated: var(--surface-card);
+  --surface-raised: var(--surface-card);
+  --popover: var(--surface-card);
+  --bg-input: var(--surface-card);
+  --card-frame-bg: var(--surface-frame);
+  --card-foot-bg: var(--surface-frame);
+  --muted: var(--surface-inset);
+  --input: var(--surface-inset);
+  --secondary: var(--surface-inset);
+  --canvas-placement-bg: var(--surface-inset);
+  --bg-card-hover: var(--surface-hover);
+  --bg-input-hover: var(--surface-frame);
+
 }
 
 /* ============================================================
@@ -510,7 +566,12 @@
    dark even though the rest of the shell is light.
    ============================================================ */
 [data-theme="light"] {
-  --sidebar-bg: 244 244 248;
+  /* Flat white — this token is the app FRAME (main-layout.tsx paints the
+     whole shell with it), so a grey here tints every light page behind the
+     floating content card. The card's border + shadow carry the separation.
+     Matches meta-ads-audit-dashboard, which consumes the same tokens and
+     sets its rail to --page-bg. */
+  --sidebar-bg: 255 255 255;
   --sidebar-surface: 0 0 0 / 0.04;
   --sidebar-surface-hover: 0 0 0 / 0.08;
   --sidebar-surface-active: 207 14 15 / 0.10;
@@ -571,9 +632,69 @@
    so the hex literals are permitted here and nowhere in apps/.
    ============================================================ */
 :root {
-  --color-meta-blue: #1877f2;
+  --color-meta-blue: rgb(var(--platform-facebook));
   --color-meta-ink: #050505;
   --color-surface-50: #fafafa;
   --color-surface-100: #f4f4f5;
   --color-surface-200: #e4e4e7;
 }
+
+/* ============================================================
+   PLATFORM BRAND + MEDIA-OVERLAY TOKENS (theme-INDEPENDENT)
+   ------------------------------------------------------------
+   Third-party brand colours. Facebook is #1877F2 whether the
+   workspace is light or dark, so these deliberately sit OUTSIDE
+   the theme blocks — putting them in the theme would make a
+   platform badge change colour with the app, which is wrong.
+
+   This block exists because `swipes.css` and `collections.css`
+   each said, in their own header: "when a second consumer of
+   these exact tokens lands, promote to packages/ui/src/tokens.css".
+   Three landed (collections, ad-intel, the social previews), and
+   the same Facebook blue ended up defined in seven places under
+   seven names — plus an eighth, `--adstage-fb-like`, at a DIFFERENT
+   and wrong value (#2078f4). This is that promotion.
+
+   BARE TRIPLES, not complete colours: the same brand colour is
+   used at different opacities per surface (swipes/collections
+   badges at 0.78, ad-intel at 0.85), so the alpha belongs at the
+   call site — `rgb(var(--platform-facebook) / 0.78)`. Baking an
+   alpha into the token is what makes it un-shareable.
+
+   The `--media-*` overlays DO carry their alpha, because there the
+   opacity ramp IS the shared definition: swipes and collections
+   used byte-identical values.
+
+   Platform-chrome and exempt substrate (packages/ui), so the
+   literals are permitted here and nowhere in apps/.
+   ============================================================ */
+:root {
+  /* Platform brand colours. */
+  --platform-facebook: 24 119 242;
+  --platform-instagram: 225 48 108;
+  --platform-linkedin: 10 102 194;
+  --platform-google: 66 133 244;
+  /* Google's logo green — the discovery report's tiles use it where the
+   * badge surfaces use the logo blue above. Both are real, both are used. */
+  --platform-google-green: 52 168 83;
+  --platform-youtube: 255 0 0;
+  /* TikTok's brand is black, which only works as a BADGE FILL (white text
+   * on it). As an icon colour on a dark card it measures 1.22:1, so the
+   * discovery tiles use theme-aware --folder-slate instead. Same reason
+   * there is no --platform-x: X is brand-black too, and its one consumer
+   * uses --folder-ink, which is byte-identical in light mode. */
+  --platform-tiktok: 0 0 0;
+  --platform-yelp: 211 35 35;
+  --platform-email: 245 158 11;
+  --platform-website: 255 255 255;
+  /* Near-white reads on every brand fill above. */
+  --platform-on-color: 255 255 255;
+
+  /* Overlays on creative media. Theme-independent because the thing
+   * underneath is an image, not a themed surface. */
+  --media-scrim-strong: 0 0 0 / 0.78;
+  --media-scrim-mid: 0 0 0 / 0.2;
+  --media-scrim-label: 0 0 0 / 0.55;
+  --media-on-scrim: 255 255 255 / 0.88;
+  --media-overlay-btn: 255 255 255 / 0.14;
+}

package/src/v2/README.md

@@ -0,0 +1,208 @@
+# `@lovett/ui` v2
+
+The document layer. Built for dense, text-heavy surfaces — briefs, checklists,
+dossiers, report pages — where the job is to make a lot of information legible
+rather than to entertain anyone.
+
+```tsx
+import '@lovett/ui/src/v2/theme.css'
+import { DocumentShell, DocumentSection, FieldRow } from '@lovett/ui/v2'
+```
+
+v2 is **additive**. Every token is namespaced `--lv-*`, every class `.lv-*`.
+`theme.css` loads alongside v1's `tokens.css` and `styles.css` without changing
+a single v1 pixel, so a page migrates one section at a time. Nothing in v1 was
+touched.
+
+---
+
+## The surface ladder
+
+This is the spine. Everything else is detail.
+
+```
+page  →  shell  →  section  →  card  →  [inset]
+─────────────── brighter ──────────────►  ◄─ recessed
+```
+
+| Tier | Token | What sits here |
+| --- | --- | --- |
+| page | `--lv-surface-page` | the viewport floor |
+| shell | `--lv-surface-shell` | `DocumentShell` — the document's own field |
+| section | `--lv-surface-section` | `Section` — a titled region |
+| card | `--lv-surface-card` | `StatTile`, a tray |
+| inset | `--lv-surface-inset` | `Panel` — **the recessed panel** |
+
+Each tier is one notch brighter than the one behind it. `inset` deliberately
+goes the other way, because a recessed panel *inside* a card is the single most
+premium move in the system and recession is the only thing that makes it read
+as recessed. Use `Panel` for the thing inside a card the reader actually came
+for: the extracted quote, the computed figure, the diff, the raw payload.
+
+**Depth is shadow plus a top-edge inner highlight, never a border.** A 1px
+hairline used for elevation reads as a form field. Hairlines here are strictly
+structural — dividers, table rules, field outlines, the `Timeline` rail.
+
+Elevation runs `--lv-elev-0` → `-4` for lifting and `--lv-elev-inset` for
+digging. In dark mode the layered soft shadows collapse to a single ring plus
+one drop, because stacked low-alpha shadows are invisible on a dark surface.
+
+---
+
+## The colour formula
+
+Authored in OKLCH. Ramps are **constant-hue**; chroma at each step is a
+percentage of that hue's sRGB maximum *at that lightness*, so nothing clips and
+no hue accidentally outranks another.
+
+**Neutral** — hue 255, chroma capped at 0.023. Navy-tinted, not black. A pure
+grey ramp goes dead next to a warm accent; this one stays alive without ever
+reading as "blue".
+
+**Accent** — hue 27.5, the house red. `--lv-accent` is the AA-safe action step
+(L 0.554); `--lv-accent-mark` is the brighter step used for dots, rails, and
+fills that carry no text on them.
+
+> **The accent earns its impact from scarcity.** Exactly one filled accent
+> surface per view. `Action variant="primary"` is that one thing; everything
+> else is `secondary`, `ghost`, or `danger`. Three red buttons on a screen means
+> there is no primary action on that screen.
+
+**Semantic hues, held far apart:**
+
+| Role | Hue | Marker shape |
+| --- | --- | --- |
+| success | 150° green | filled dot |
+| warning | 95° gold | triangle |
+| danger | 48° burnt orange | square / octagon |
+| info | 290° violet | circle |
+
+**Danger is not red, and that is on purpose.** The brand *is* red. A red brand
+plus a red danger state cannot be told apart on a page that shows both, and no
+credible danger red sits far enough from the brand hue to fix it. Moving the
+meaning is the only thing that works. The cost is real — orange is a weaker
+danger signal than red — so every component that carries a tone also carries an
+**icon with a distinct silhouette** and a **screen-reader word**. Colour is
+never the only signal. Destructive actions must additionally use an explicit
+verb ("Delete brief", not "Confirm").
+
+Each tone exposes four tokens: `-text` (the AA-safe reading colour), `-mark`
+(dots/icons/tracks, which may be brighter because they are larger), `-soft` (the
+tinted fill), and `-rule` (the leading rule).
+
+**Both appearances, both directions.** Light is the default; dark comes from
+`prefers-color-scheme` *and* from `[data-theme="dark"]`, and `[data-theme="light"]`
+forces light back under a dark OS. Dark is not an inversion — the ladder is
+rebuilt from different steps of the same ramps and every foreground/background
+pair was re-checked. Accents gain chroma in dark, because a light-mode accent
+goes muddy once its surround darkens.
+
+---
+
+## The spacing scale
+
+One 4px grid: `0 1 2 3 4 5 6 7 8 10 12 14 16 20 24` → `0px … 96px`.
+
+`SpaceStep` is a union type, so `gap={13}` does not compile. That single
+constraint removes the most common reason a nice interface feels subtly off.
+
+Grouping goes **space first, background shape second, line last**. The gap
+between groups is at least 2× the gap within one. There is deliberately no
+`Divider` primitive — reaching for a divider is almost always a failure of
+spacing.
+
+**Radius is sharp and concentric.** `xs 3 · sm 4 · md 6 · lg 10 · xl 14`.
+A card at `lg` (10px) with a 4px frame gives its tray `md` (6px):
+`outer = inner + padding`, both directions.
+
+---
+
+## Type
+
+Named by role, never by size: `2xs xs sm base md lg xl 2xl 3xl stat`, plus
+`--lv-prose-*` for long-form.
+
+- UI chrome sits at 13–14px; long-form prose at 16px / 1.62, capped at `68ch`.
+- Large type gets negative tracking, small uppercase labels get positive.
+- **`tabular-nums` on every comparable number**, by default, not opt-in —
+  `StatTile`, `ProgressTrack`, `FieldRow numeric`, `StatusPill`, `Timeline meta`
+  all set it themselves.
+- Type carries hierarchy before colour does. There are only four ink steps on
+  purpose; a fifth would mean weight and size had stopped doing their job.
+
+---
+
+## Layout stability
+
+A premium UI is mechanically solid: surfaces hold still and only contents
+change. Every v2 component reserves its space.
+
+- **`StatTile`** — `slots` sizes a `min-width` in `ch` for the largest plausible
+  value. Set it to your worst case *including separators* (`1,284,930` → `9`).
+  The delta row is always in the box; when there is no delta it is
+  `visibility: hidden`, never `display: none`.
+- **`ProgressTrack`** — the percentage lives in a 4ch slot, so 9% → 100% cannot
+  nudge the label.
+- **`EmptyState` / `LoadingSkeleton` / `ErrorState`** — all three take the same
+  `reserve` prop feeding one `min-height`. Give all three the loaded content's
+  typical height and the region stops jumping through the whole lifecycle.
+  `LoadingSkeleton`'s `variant` mirrors the real primitives (`stat`, `fields`,
+  `document`) so the skeleton is the same shape, not just the same area.
+- **`Action`** — loading keeps the label in the DOM holding the width and hides
+  it behind the spinner. Disabled changes paint only. The button never resizes
+  under the pointer.
+- **`DocumentShell`** — the nav's active indicator is a 2px leading rule that is
+  always rendered and transparent when inactive. Adding it on activation would
+  shove every label sideways as you scroll.
+
+---
+
+## Motion
+
+Spring on small, ease on large. `--lv-ease-spring` is for buttons, toggles, and
+badges only — never a panel, and never a data value, because overshoot on a
+number reads as imprecise. Press scale is `0.96` exactly; below `0.95` feels
+exaggerated. Never `transition: all`.
+
+`prefers-reduced-motion` collapses every duration token to 1ms and kills the
+skeleton sheen and the indeterminate travel outright — reduced motion shows the
+*final* state, not a frozen animation.
+
+---
+
+## When to reach for which
+
+| You have | Use |
+| --- | --- |
+| a long document with sections | `DocumentShell` + `DocumentSection` |
+| body copy inside one | `Prose` (capped measure, `text-wrap: pretty`) |
+| label/value pairs | `DefinitionList` + `FieldRow` — one shared label column |
+| a number someone will compare | `StatTile` (set `slots`) |
+| a state the reader must not miss | `Callout` (icon + word + rule) |
+| a state in a row or a header | `StatusPill` (shape carries it) |
+| a measured quantity 0–100 | `ProgressTrack` |
+| an ordered sequence of events | `Timeline` |
+| the thing inside the card that matters | `Panel` (the recess) |
+| vertical / horizontal flow | `Stack` / `Inline` |
+| a responsive tile field | `Grid minColumnWidth` — breaks where content stops fitting, not at a device preset |
+| controls above content | `Toolbar` (`Toolbar.Spacer` before `Toolbar.Divider`) |
+| nothing yet / loading / broken | `EmptyState` / `LoadingSkeleton` / `ErrorState` — same `reserve` |
+
+---
+
+## Reviewing it
+
+`__demo__/showcase.tsx` exports `<V2Showcase />`, which renders every primitive
+in every state — default, hover, focus, disabled, loading, empty, error,
+overflow — on one page, with a light/dark toggle. That page is the review
+surface; if a change is not visible there, it is not reviewable.
+
+## Rules for adding to v2
+
+1. New tokens are `--lv-*`. New classes are `.lv-*`. No exceptions — the
+   namespace is what keeps v1 safe.
+2. Spacing props take a `SpaceStep`. Never a raw number, never a string.
+3. Every state a component can be in must occupy the same box as every other.
+4. Any tone must be carried by an icon or a shape as well as a hue.
+5. When in doubt, remove. Fewer borders, fills, colours, and font sizes.
+   Premium reads as confident and quiet; busy reads as cheap.