themelia-ui 3.0.0 → 3.2.0

package/dist/styles/TOKENS.md

@@ -1,281 +1,122 @@
-# The token contract
-
-The theme is `themes/default.css` plus `tokens/*.css`: the global contract. The rest is
-cross-cutting wiring and component-owned measurements a theme author does not need to touch.
-
-**The theme surface is the global contract, not every token.** Only the contract is a theme
-surface: a theme author sets it and every component follows, because a component token is
-either derived from it or a measurement a rebrand has no opinion about.
-
-**A component's variables live with the component**: in its own module when one component
-reads them, in `styles/theming/` only when many do.
-
-The package's token checks fail on a `var()` nothing defines, a token JavaScript reads but no
-stylesheet declares, and a literal colour, radius, spacing or hairline in a component module.
-
-## What earns a component token
-
-One of three things, and a name that does none of them is noise:
-
-* **arithmetic** — `--heatmap-pitch: calc(var(--heatmap-cell) + var(--space-2xs))`
-* **a variant or scope re-points it** — `--badge-hue`, declared once per tone
-* **JS writes it** — `style={{ "--micro-bar": "62%" }}`, the interface a chart arrives through
-
-A name like `--sidebar-p: var(--space-md)` does none: however often it is read, it is one
-name in front of one step, and every reader can say `--space-md`.
-
-Two exemptions. A **token family with a member re-declared in another file** is an
-extension point: inlining `--text-role-main` breaks the inverse Alert that re-points it for
-its own subtree. A token **named in TSX or a test** has a reader a `var()` scan cannot see.
-
-## What a theme owns
-
-`themes/default.css` is shadcn-shaped, so a shadcn theme drops in.
-
-**Colour** resolves through the ramp in `tokens/palette.css`. The theme file holds no
-literals, so a rebrand moves the ramp rather than forty separate values.
-
-```css
---background --foreground --card --popover --primary --secondary
---muted --accent --destructive --border --input --ring
---chart-1…5 --sidebar-*
-```
-
-**Edge** — the three properties that describe every border in the kit, kept together
-because they are one decision:
-
-```css
---border: var(--neutral-200);   /* colour */
---border-width: 1px;            /* weight */
---radius: 1rem;                 /* corner  */
-```
-
-**Shape** is two values. `--radius` rounds whatever holds other rounded things;
-`--radius-sm` rounds everything inside one or smaller than one. Both are plain values
-declared once at `:root`, and nothing derives one from the other, so a theme that changes
-one usually sets both. A container holding `--radius-sm` items insets them by the
-difference (`--space-md` at the defaults), so outer = inner + inset. There is no third
-radius token:
-
-| token | used by |
-|---|---|
-| `--radius` | wrappers: cards, dialogs, sheets, popovers, menus, listboxes, panels, columns, dropzones, framed media and maps, choice cards |
-| `--radius-sm` | items: buttons at every size, fields, checkboxes, glyph buttons, tabs, badges, chips and tags, rows, menu items, tooltips, calendar cells, thumbnails, icon tiles, bubbles, gallery tiles, and every wrapper nested inside a Card |
-| `--radius-pill` | shapes rather than corners: switches, tracks, skeleton bars, status dots, series swatches, a count overlaid on an icon |
-| `50%` | true circles only: avatars, radios, spinners, a circular IconBadge |
-
-Every other corner is arithmetic on the two radii:
-
-* an edge-to-edge child of a bordered wrapper: `calc(var(--radius) - var(--border-width))`
-* an item inset inside an item frame: `calc(var(--radius-sm) - <inset>)`
-* an item parked in a wrapper's corner at `--space-md`: plain `--radius-sm`, concentric by construction
-* data marks and arrow tips, which are not controls: `calc(var(--radius-sm) / 4)`
-
-A control is never smaller than its corner: an 18px checkbox and a 16px clear glyph take
-`--radius-sm` like a button, so a theme's item radius reaches every control.
-
-A state never sets a radius: hover, focus, open, active and invalid keep the resting corner.
-`--button-radius` is a hook that only ever takes one of the expressions above.
-
-## What the ramps own
-
-`tokens/` holds the ladders the theme resolves against: the colour ramp, the type scale
-(`--text-xs` … `--text-2xl` and its paired line heights), the spacing scale, the content
-widths, and the raw tunables — `--height-control`, `--control-x`, `--row-x/y`,
-`--surface-x/y`, `--icon`, `--avatar`, `--scale`.
-
-**Spacing sits on a 2px grid.** Every length under `4rem` is a multiple of `0.125rem`, so
-neighbouring insets cannot land a pixel apart.
-
-**Type is exempt from the grid**, because a type ramp is geometric — `0.75`, `0.8125`,
-`0.875`, `1`, `1.125` — and lands off a 2px grid by construction. `0.8125rem` is the
-`--text-pxs` step, not a stray 13px.
+# The theme contract
+
+The theme is `src/styles/theme/*.css`: about eighty variables, declared once at `:root`. Every
+colour is `light-dark(light, dark)`, and the element's `color-scheme` (set by `.light`,
+`.dark`, `data-theme` or the operating system) picks the half. Component styles inherit
+theme defaults rather than redeclaring them. Explicit scope overrides and density presets
+replace the corresponding inherited values on their regions. A dark region inside a light
+page needs no second set of colour declarations.
+
+Components read the theme and compute the rest in the rule that uses it. The package's checks
+fail on a `var()` nothing defines, a literal colour, radius, spacing or hairline in a
+component module, and a rule keyed on `.dark` or `prefers-color-scheme`.
+
+## What the theme owns
+
+| File | Variables |
+| --- | --- |
+| `colour.css` | `--background`, `--foreground`, `--card`, `--popover`, `--muted`, `--accent`, `--border`, `--input`, `--ring`, the tones and their foregrounds, `--link`, `--chart-1`…`5`, the `--sidebar-*` set, `--overlay-backdrop`, and the tint strengths `--tint` and `--tint-strong` |
+| `shape.css` | `--radius`, `--radius-sm`, `--radius-pill`, `--border-width` |
+| `spacing.css` | `--padding`, `--padding-sm`, `--gap`, `--gap-sm` |
+| `size.css` | `--control-height`, `--control-height-sm`, `--icon-size`, `--icon-size-sm` |
+| `typography.css` | the font stacks, the type steps `--text-xs`…`--text-2xl`, and the type factor `--text-scale` |
+| `elevation.css` | `--shadow`, `--shadow-lg` |
+| `motion.css` | `--duration-fast`, `--duration`, `--ease`, `--disabled-opacity` |
+| `layout.css` | the z tiers, `--sidebar-width`, `--header-height`, `--content-width`, `--overlay-backdrop-filter` |
+| `density.css` | the `compact`, `default` and `comfortable` presets, keyed on `data-density` |
+
+The colour names are shadcn's, so a shadcn theme drops in.
+
+## Two of each
+
+Every length, shadow, tint and duration comes as a pair. A value between or beyond them is
+arithmetic on the pair in the rule that needs it, never a third variable.
+
+| Pair | The first | The second |
+| --- | --- | --- |
+| `--radius`, `--radius-sm` | containers: cards, dialogs, popovers, menus, panels | anything inside one, or smaller: controls, rows, chips, badges, tooltips |
+| `--padding`, `--padding-sm` | container insets | item insets: rows, cells, chips, fields |
+| `--gap`, `--gap-sm` | between groups: fields, cards, sections | inside a group: icon and label, title and description |
+| `--control-height`, `-sm` | every button, field, select and trigger | the dense step |
+| `--icon-size`, `-sm` | icons beside text and in controls | icons in dense rows and chips |
+| `--shadow`, `--shadow-lg` | raised: a framed card, a raised chip, a thumb, a hover lift | floating: popovers, menus, dialogs, toasts |
+| `--tint`, `--tint-strong` | a soft fill: a selected row, a soft badge, a wash | a tinted line or edge |
+| `--duration-fast`, `--duration` | state changes: hover, press, colour | entrances: popups, dialogs, panels |
+
+**Corners.** `--radius-pill` is a shape, not a corner: switches, tracks, status dots. True
+circles are `50%`. Every other corner is arithmetic: a nested corner is its container's
+radius less the inset (`calc(var(--radius) - var(--padding-sm))`), an edge-to-edge child of a
+bordered container is `calc(var(--radius) - var(--border-width))`, and a data mark or an
+arrow tip is `calc(var(--radius-sm) / 4)`. A control is never smaller than its corner, and a
+state (hover, focus, open, invalid) never sets a radius.
+
+**Hairlines.** Every edge is `--border-width`; a mark (a quote bar, a drop line) and the
+focus outline are twice it.
+
+## Colour roles
+
+**Grounds.** `--background` is the page, the app shell and content dialogs; `--card` every
+in-flow framed region; `--popover` anchored popups and palettes; `--sidebar` the shell
+sidebar. A surface that paints a ground sets `--surface-ground` to it, and a sticky cell or a
+fade reads `var(--surface-ground, var(--background))` to match what it sits on.
+
+**Fills.** `--muted` is a well or a placeholder. A strip (a card footer, a zebra stripe) is
+`--muted` at `--tint-strong`; a track or a skeleton is `--foreground` at `--tint`, which lifts
+off any ground.
+
+**State.** `--accent` is the one hover and current fill: control hover, the menu cursor, an
+open trigger, the current navigation item, row hover. Selected is `--primary` at `--tint`
+(a large surface adds a `--primary` edge), and a checked mark is solid `--primary`. Selection
+outranks hover. Current navigation is neutral; the brand colour is for a value the user chose.
+
+**Tones.** A component with a `tone` renders `data-tone`, and the tone rule
+(`src/styles/tone.css`) gives it three variables instead of a colour name: `--tone` (the
+hue: a solid fill, a tint, a line), `--tone-foreground` (text on the solid fill) and
+`--tone-ink` (the hue as text or a glyph, on the page or on its own tint). The ink is the hue
+itself in dark mode; in light mode it mixes toward the text colour as far as the hue needs to
+hold 4.5:1.
+
+**Edges.** `--border` is every divider and frame; `--input` the frame of a control, and a
+control's hover edge mixes it toward `--foreground`. An invalid control's edge and outline
+are `--destructive`.
+
+**Focus.** One rule (`src/styles/focus.css`) outlines every focused element in `--ring` at
+twice the hairline, offset by the same. A component that clips its content draws the outline
+inside (`outline-offset: calc(var(--border-width) * -2)`); one that shows focus another way (a
+menu's highlight) removes the outline only beside that equivalent.
+
+**Contrast.** `src/lib/theming/theme-contrast.test.ts` measures the theme's text and focus
+pairs in both modes and fails below WCAG AA.
+
+## Type
+
+Type goes through `Text` and `Heading`. A module sets no `font-size`, `font-weight`,
+`line-height`, `letter-spacing` or `font-family`; an element `Text` cannot wrap (a native
+control, a button's label, a table cell) takes `textClassName({ size, weight, … })`. Each step
+is `calc(var(--text-X) * var(--text-scale))` with its own line box, and colour reaches a
+`Text` through its `type` prop, never a class.
+
+## Density and scale
+
+A `data-density` preset sets the four lengths and the two control heights on its element, so
+a region is denser or roomier and type keeps its size. The provider's `scale` computes the
+same lengths, the icon sizes and the type factor in JavaScript and writes them, rounded to
+whole pixels; CSS multiplies one factor, `--text-scale`, inside Text.
 
 ## What components own
 
-**A component reads the theme directly**: `background-color: var(--foreground)` in the
-module, not `--tooltip-bg: var(--foreground)` somewhere else and `var(--tooltip-bg)` here.
-A name with one reader is indirection. Where a component adjusts a theme value, it does the
-arithmetic in its own rule — `calc(var(--space-lg) * 2)` — rather than minting a name.
-
-A token earns a NAME only when one of these is true:
-
-| | |
-|---|---|
-| **arithmetic read by two or more rules** | a `calc()` whose readers must stay equal; a bare `var(--step)` is a pass-through however often it is read |
-| **an extension point** | another file re-declares it, so inlining kills the override |
-| **read from TS/TSX** | a runtime hook; the indirection is the API |
-| **an `--animate-*`** | CSS Modules scope keyframe names; inlined, the animation dies |
-| **a bare length a module may not hold** | a module may not hold raw px or rem spacing |
-
-Everything else belongs in the rule that uses it, and still may not hold a colour literal:
-colour always resolves through the palette.
-
-**An extension point is anything another file re-declares**, including a one-line rule:
-`.columns4 { --choice-card-min: 9rem; }` is how a variant re-points a token, and inlining
-the default silently kills all three column variants.
-
-There is no per-component scale factor. See [FACTORS.md](./FACTORS.md) for the three global
-factors, and [SCOPES.md](./SCOPES.md) for why derived values are declared at every scope
-boundary rather than once at `:root`.
-
-## One token per role
-
-Every visual role has one token or one recipe. Reach for the role, not for a value that
-happens to look right, and never spell an ad hoc `color-mix()` step in a module: a pair the
-kit uses is declared once in `theming/colors.css`.
-
-**Grounds.** What a surface is painted with.
-
-| token | role |
-|---|---|
-| `--background` | the page, the app shell, and content dialogs, sheets and drawers |
-| `--card` | every in-flow framed region: Card, DataTable and DataView frames, the EventCalendar grid, panels |
-| `--popover` | anchored popups, command palettes (CommandDialog, GlobalSearchDialog), a raised segmented chip |
-| `--sidebar` | the shell sidebar |
-| `--field-bg` | the resting fill of every field and box control (transparent by default) |
-
-The **modal ground** is deliberate: a content dialog is the page brought forward and sits on
-`--background`; a palette is a popup that happens to be modal and sits on `--popover`. A
-dark lift for cards belongs in the theme's `--card`, never in one module.
-
-`--surface-ground` is "the surface I sit on". A surface that paints a ground (Card, popups,
-the sidebar, table and data-view frames) sets it; a sticky cell, a cut-out ring, an opaque
-halo or a fade reads `var(--surface-ground, var(--background))`, so it matches whatever it
-lands on. It is unset by default and reset at every colour island (SCOPES.md).
-
-**Neutral fills.**
-
-| token | role |
-|---|---|
-| `--muted` | a solid placeholder: media and thumbnail fallback, map canvas, QR fallback |
-| `--muted-50` | a recessed well: muted ContentBlock and Item, summary and diff panels, code, table head and foot cells, segmented and enclosed-tab tracks, unread rows, the secondary Alert |
-| `--muted-20` | a strip: Card, Overlay and GlobalSearch footers, zebra stripes, column-group bands, optional sections |
-| `--muted-40` `-60` `-80` | the empty-state illustration ramp, nothing else |
-| `--foreground-8` | a small neutral fill that must lift on any ground: avatar fallback, neutral IconBadge, tile or medallion, neutral chip, tag or mention, read-only plate |
-| `--foreground-10` | skeletons |
-| `--foreground-20` | every track or unfilled segment: Progress, Slider, Upload, metric and chip progress |
-
-There is no muted step between these: a well is `-50`, a strip `-20`.
-
-**State fills.** `--muted-*` and `--foreground-*` are never state fills.
-
-| token | role |
-|---|---|
-| `--accent` | control hover (Toggle and clear or remove glyphs included), the popup cursor, a pressed toggle, an open popup trigger, the current navigation item |
-| `--accent-50` | row and large-surface hover, add-slot hover, an open accordion item |
-| `--sidebar-accent` `--sidebar-accent-50` | the same two roles inside the sidebar |
-| `--primary-5` with a `--primary` edge | a selected large surface: choice card, switch card, locale tile, drop target |
-| `--primary-10` | a selected row |
-| `--primary` | a checked mark and solid selection |
-| `--primary-accent` | state ink: check and busy icons, today, the radio ring |
-
-Selection outranks hover: a selected item does not change on hover. Current navigation is
-neutral (`--accent`, foreground ink, medium weight); the brand ladder is for a value the user
-chose.
-
-**Tone ladder.** For T in primary, info, success, warning and destructive:
-
-| role | step | readers |
-|---|---|---|
-| solid fill | `--T` with `--T-foreground` | solid Button, Badge and IconBadge |
-| ink | `--primary-accent`, `--info`, `--success`, `--warning-accent`, `--destructive-accent` | text, glyphs, dots, sparklines and bars on the page or on a tint |
-| wash | `T-5`, warning `-10` | large panels: Alert, AI confirmation, a failed row, an applied coupon |
-| soft | `T-10` | chips and tiles: Badge soft, mentions, IconBadge, trend and diff chips, calendar chips, timeline discs, ghost and outline hover |
-| soft hover, halo | `T-20` | a linked soft chip's hover, the current-step and status halos |
-| line | `T-30`, warning `-40` | callouts, soft chips, outline Buttons and Badges, metric panels, applied filters |
-
-Warning's steps sit one higher because amber is light: a 10% amber wash lands where the
-other hues land at 5%. `--primary-15`, `--primary-25` and `--primary-40` are not tone steps:
-they belong to the range band, the analytics ruler and the media-tile selection ring.
-There is no other soft or wash step in any hue. Badge and mention
-chips do the arithmetic on one re-pointed hue (`--badge-hue`, `--ref-hue`) with the same
-percentages.
-
-**Edges.**
-
-| token | role |
-|---|---|
-| `--border-width` | every hairline, rail and connector |
-| `--border-width-strong` | marks only: a quote bar, the active-nav bar, a dot ring, a drop line |
-| `--focus-ring-width` | focus only |
-| `--border` | an outer edge: frames on the page, overlays, page-chrome bars, the Separator, rails, thumbnails |
-| `--border-60` | an inner edge: header, footer and toolbar bands, section rules, nested frames, row rules, menu separators |
-| `--control-border` `--control-border-hover` | the frame of a control in a row with fields: outline toggles and ToggleGroup, pill groups, filter pills, interactive chips, dashed add slots. Mixed separately for dark. A divider inside a control (a ButtonGroup separator, a filter pill's segments) is an inner rule, `--border-60` |
-| `--foreground-20` | the hover edge of a clickable surface |
-| `--invalid-ring-border` with `--invalid-ring` | every invalid edge. Focus adds the ring, invalid keeps its border, and hover never repaints it |
-
-There is no edge colour between the two. No literal `1.5px` or `3px` edge.
-
-**Elevation.**
-
-| token | role |
-|---|---|
-| none | bordered or flat surfaces, field shells, sticky bars |
-| `--shadow-xs` | resting lift: a framed Card's bezel, a raised chip, a thumb, a floating sidebar |
-| `--shadow-sm` | hover lift for every clickable card and tile; controls over artwork |
-| `--popover-shadow` | every anchored popup (select, combobox, mention panel, chart tooltip, map popup), never with a real border |
-| `--shadow-lg` | free-floating transients: toast, drag ghost, floating batch bar, submenu |
-| `--shadow-xl` | modals and palettes |
-
-`--shadow-2xs`, `--shadow` and `--shadow-2xl` are kept for shadcn compatibility; no kit
-surface reads them. A frosted sticky bar is opaque `--background`, then `--background-70`
-with `blur(12px)` under `@supports`.
-
-**Focus.** Controls take `--focus-ring`, or `--focus-ring-inset` under a clip. Fields and
-field shells take `--field-focus-ring` with a `--focus-ring-color` border, keyed on the
-control's `:focus-visible`; the rich-text editor and the AI composer are the multi-control
-exception and light on `:focus-within`. Never read `--ring` directly. Every Sidebar
-surface re-points `--focus-ring-color` to the theme's `--sidebar-ring` through the same
-recipe (mixed toward `--sidebar-foreground` in light, unmixed in dark) and composes
-`--focus-ring`, `--focus-ring-inset` and `--field-focus-ring` again from it. It also sets
-`--surface-ground: var(--sidebar)`.
-
-**Type.** Sizes come with their paired leading. `--leading-none` for fixed-height controls
-and glyphs, `--leading-tight` for titles at base size and up, `--leading-relaxed` for prose;
-`--leading-snug` never on `xs` or `sm`. Weight: normal for body; medium for labels, headers,
-controls, badges, row and accordion titles; semibold for surface titles, Heading, card
-titles and headline figures; bold for strong text and grand totals. `--tracking-widest` is
-for uppercase and shortcuts, `--tracking-tight` for Heading `xl` and `2xl` only. Colour
-reaches a `Text` through its `type` prop, never a module rule. Links read `--link-color` and
-`--link-underline-offset`.
-
-**Size.** Control heights and paddings go in matching pairs from the control ladder; a 24px
-glyph button is `--control-h-2xs`. A chevron inside a control is `--size-icon`, a caret after
-text `--size-icon-sm`. A head-of-row thumbnail is `--size-medallion`; a nav or menu row icon
-is `--size-icon`; a status dot is `--space-md`. Gaps: control icon to label `--space-sm`, chip
-icon to label `--space-xs`, sibling actions `--space-md`. Every derived multiple is rounded
-to a whole pixel and lands on the 2px grid.
-
-**Dark and inverse.** Small inverse chips flip with the theme (Tooltip, solid neutral
-controls). Large inverse slabs stay dark in both modes: the inverse Alert and the toast read
-`--inverse-*`, and the auth showcase panel is a `data-theme="dark"` scope. A QR code always
-renders dark modules on light through `--inverse-background` and `--inverse-foreground`.
-
-**Menus in dark.** `overlay.darkMenus` (default `true`) renders dropdown and context menus in
-the dark scheme on a light page. It applies to command menus only: listboxes, selects,
-comboboxes and pickers belong to the field that opened them and follow the page, like every
-other popup.
-
-## Shared surface and content rhythm
-
-Retheme surface padding with `--surface-x` and `--surface-y`. Cards, choice cards, framed
-ContentBlocks, popovers, hover cards, the form actions bar and overlay bodies share these
-insets. Overlay headers and footers, and CardFooter, use 0.75 of the vertical inset
-(`round(calc(var(--surface-py) * 0.75), 1px)`) and the body's horizontal inset; the overlay
-header adds one `--space-2xs` above its title. Bands (a toolbar or header row inside a frame)
-are `--row-py` by `--surface-px`; edge-to-edge rows, table cells included, take `--surface-px`
-inline; list rows are `--row-py` by `--row-px`. Compact collection shells use half the inset.
+A component's own variables are private and named `--_x`, declared on its root class or
+inlined where used. A private name earns its place with one of:
 
-Title/description pairs in CardHeader, ContentBlock and OverlayHeader use the same
-`Stack gap="xs"`. CardFooter and OverlayFooter use a wrapping horizontal Stack with
-`gap="md"`. Ordinary label/value rows belong to MetadataList, including activity changes
-with custom before/after values. Specialized timelines and ledgers keep their own geometry.
+- **arithmetic** read by two or more rules that must stay equal;
+- **a variant** that re-points it (`.columns4 { --_min: 9rem; }`);
+- **JavaScript** that writes it (`style={{ "--_progress-fill": … }}`);
+- **another module** that sets it: `--_button-height`, `--_button-radius`, `--_card-px` and
+  `--_card-py`, `--_icon-badge-size`, `--_content-block-gap`, `--_overlay-max-width`.
 
-`--content-block-p` and `--overlay-region-p` are optional local overrides. They are unset
-(`initial`) by default, so each axis follows the shared surface controls; setting either
-sets both axes for that surface. Do not add another component-specific padding variable for
-the same job.
+A bare `var(--gap)` behind another name is none of these; read the theme directly.
 
-Set fonts at the theme root or an explicit scope. Dark regions inherit the font family;
-switching colour mode does not restore the package's default font.
+Animations name global keyframes through `--keyframes-*` (CSS Modules would rename a bare
+name) and state their own timing: `animation: var(--keyframes-spin) 1s linear infinite`. The
+keyframes are named `themelia-*`, so Tailwind's and tw-animate-css's `spin` or `enter` never
+replace them.

package/dist/styles/animation.css

@@ -0,0 +1,114 @@
+/*
+ * Animation. CSS Modules rename a keyframes name written in a module, so a module names these
+ * global keyframes through a variable and states the timing itself, where it resolves against
+ * the element's own durations (a scope with `motion.reduced` included):
+ *
+ *   .content {
+ *     animation: var(--keyframes-exit) var(--duration-fast) var(--ease);
+ *     --_enter-opacity: 0;
+ *     --_enter-scale: 0.95;
+ *   }
+ *   .content[data-open] { animation: var(--keyframes-enter) var(--duration-fast) var(--ease); }
+ *
+ * The enter and exit keyframes read private parameters with neutral fallbacks, so a surface
+ * sets only the axes it animates. The variables are `--keyframes-*` because Tailwind's
+ * `--animate-*` hold whole shorthands. The keyframes are `themelia-*` because Tailwind and
+ * tw-animate-css define a `spin`, `pulse`, `enter` and `exit` of their own, and keyframes of
+ * one name replace each other: whichever loads last would run for both.
+ */
+@layer tokens {
+	:root {
+		--keyframes-enter: themelia-enter;
+		--keyframes-exit: themelia-exit;
+		--keyframes-spin: themelia-spin;
+		--keyframes-pulse: themelia-pulse;
+		--keyframes-ping: themelia-ping;
+		--keyframes-progress: themelia-progress;
+		--keyframes-shimmer: themelia-shimmer;
+	}
+}
+
+@keyframes themelia-enter {
+	from {
+		opacity: var(--_enter-opacity, 1);
+		transform: translate3d(var(--_enter-x, 0), var(--_enter-y, 0), 0) scale(var(--_enter-scale, 1));
+	}
+}
+
+@keyframes themelia-exit {
+	to {
+		opacity: var(--_exit-opacity, 1);
+		transform: translate3d(var(--_exit-x, 0), var(--_exit-y, 0), 0) scale(var(--_exit-scale, 1));
+	}
+}
+
+/* Indeterminate progress: spinners and loader buttons. */
+@keyframes themelia-spin {
+	to {
+		transform: rotate(360deg);
+	}
+}
+
+/* An expanding, fading halo, paired with a solid dot that stays put. */
+@keyframes themelia-ping {
+	75%,
+	100% {
+		transform: scale(2);
+		opacity: 0;
+	}
+}
+
+/* Skeleton placeholders. */
+@keyframes themelia-pulse {
+	50% {
+		opacity: 0.5;
+	}
+}
+
+/*
+ * The indeterminate bar's band. Translate percentages are of the band (40% of the track),
+ * so 250% carries it fully off the far edge. Keep in step with the band width.
+ */
+@keyframes themelia-progress {
+	from {
+		transform: translateX(-100%);
+	}
+	to {
+		transform: translateX(250%);
+	}
+}
+
+/* Right to left across a background twice the element's size: one pass per cycle. */
+@keyframes themelia-shimmer {
+	from {
+		background-position: 200% 0;
+	}
+
+	to {
+		background-position: -200% 0;
+	}
+}
+
+/*
+ * Native top-layer surfaces (dialog, alert dialog, sheet, drawer) use transitions plus
+ * `@starting-style`, not the keyframes above: the element leaves the top layer the moment
+ * `close()` runs, so only transitioning `overlay` and `display` (allow-discrete) keeps it
+ * there to animate out. Unsupported browsers show and hide it instantly.
+ */
+
+/* Motion here is decorative, so reduced motion removes it. */
+@media (prefers-reduced-motion: reduce) {
+	/*
+	 * Catches motion not written against the duration variables (spinners, skeletons, the
+	 * progress crawl, third-party CSS). `0s` animations still fire their end events; `0s`
+	 * transitions fire no `transitionend`, hence 0.01ms. A non-zero animation duration would
+	 * make Base UI see both and warn on every Collapsible and Accordion.
+	 */
+	*,
+	*::before,
+	*::after {
+		animation-duration: 0s !important;
+		animation-iteration-count: 1 !important;
+		transition-duration: 0.01ms !important;
+	}
+}

package/dist/styles/base.css

@@ -18,7 +18,7 @@
 
 	html {
 		font-family: var(--font-sans);
-		line-height: var(--text-sm--line-height);
+		line-height: calc(1.25 / 0.875);
 		-webkit-text-size-adjust: 100%;
 		tab-size: 4;
 	}
@@ -26,8 +26,9 @@
 	body {
 		background-color: var(--background);
 		color: var(--foreground);
-		font-size: var(--text-sm);
-		line-height: var(--text-sm--line-height);
+		/* Text's `sm` step: the size of anything the kit's own type does not reach. */
+		font-size: calc(var(--text-sm) * var(--text-scale));
+		line-height: calc(1.25 / 0.875);
 		-webkit-font-smoothing: antialiased;
 		-moz-osx-font-smoothing: grayscale;
 	}
@@ -39,7 +40,7 @@
 	}
 
 	:is(input, textarea, [contenteditable="true"]) {
-		caret-color: var(--primary-accent);
+		caret-color: var(--primary);
 	}
 
 	code,
@@ -75,8 +76,8 @@
 	mark {
 		margin-inline: -0.125em;
 		padding-inline: 0.125em;
-		/* 30, not 20: 20 turns faint on a dark card. */
-		background-color: var(--warning-30);
+		/* The strong tint: a light one turns faint on a dark card. */
+		background-color: color-mix(in oklab, var(--warning) var(--tint-strong), transparent);
 		color: var(--foreground);
 		-webkit-box-decoration-break: clone;
 		box-decoration-break: clone;