@lovett/ui 0.0.9 → 0.0.10

package/src/v2/README.md

@@ -1,208 +0,0 @@
-# `@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.