themelia-ui 2.0.0 → 3.0.0

package/dist/styles/FACTORS.md

@@ -32,9 +32,5 @@ Every length scaled by `--density-scale` is wrapped in `round(…, 1px)`, so a p
 lands a control or a gap between two pixels: the ladder is 34, 30 and 24px at the default and
 32, 28 and 23px under `compact`.
 
-Per-family factors (`--button-scale` and 44 more) were removed: each needed a named token for
-every measurement it scaled. Scale one region with a scope instead.
-
-`verify factors` (`scripts/verify-css.mjs`) fails when a per-family factor reappears, when a
-length multiplies two factors (the effect squares), when a type token reaches the density
-factor, or when a density-scaled length is not rounded.
+There is no per-component factor: scale one region with a scope instead. Multiply a length by
+one factor only, or the effect squares.

package/dist/styles/SCOPES.md

@@ -54,15 +54,33 @@ nested under a dark ancestor, or the light value would win one level down:
 }
 ```
 
-The `prefers-color-scheme: dark` block does the same with
-`[data-ui-scope]:not([data-theme="light"])`. A dark override you write for a derived token
-needs the same selectors.
-
-**The one nesting a descendant selector cannot see.** An explicit light island inside a dark
-tree keeps its own boundary light, but a bare boundary nested inside that island matches
-`.dark …` again and re-derives dark. CSS has no "nearest theme ancestor". Give each boundary
-inside the island its own `data-theme`, or use `UIScope`, which writes the resolved scheme on
-every boundary it renders.
+The `prefers-color-scheme: dark` block (`colorScheme: "system"`) does the same, and honours an
+explicit light choice however it is spelled: the `.light` class (next-themes' class strategy)
+or `data-theme="light"`, on the boundary itself or on any ancestor:
+
+```css
+@media (prefers-color-scheme: dark) {
+  :root:not(.light, [data-theme="light"]),
+  [data-ui-scope]:not(.light, [data-theme="light"], :where(.light, [data-theme="light"]) *),
+  [data-density]:not(.light, [data-theme="light"], :where(.light, [data-theme="light"]) *) {
+    --background: var(--neutral-900);
+  }
+}
+```
+
+A dark override of your own needs both blocks, with exactly these selectors.
+
+**The one nesting a descendant selector cannot see.** An explicit light island inside a
+`.dark` tree keeps its own boundary light, but a bare boundary nested inside that island
+matches `.dark …` again and re-derives dark. CSS has no "nearest theme ancestor". Give each
+boundary inside the island its own `data-theme`, or use `UIScope`, which writes the resolved
+scheme on every boundary it renders. (Under the OS preference alone the island holds: the
+media block skips every descendant of a light scope.)
+
+**A surface's ground is reset at a colour island.** `--surface-ground` carries the colour a
+surface painted, resolved where that surface set it. A `[data-theme]`, `.light` or `.dark`
+element resets it to `initial`, so a reader inside the island falls back to its own
+`--background` instead of a ground from the other mode.
 
 **In a CSS Module the theme classes are hashed.** `.light` and `.dark` in a boundary list
 become local classes and match nothing. Write `:global(.light)` and `:global(.dark)`.

package/dist/styles/TOKENS.md

@@ -10,10 +10,8 @@ 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 dead token, a PASS-THROUGH (a second name for another
-token that does no arithmetic and is never re-pointed), an override nothing reads, a runtime
-token no stylesheet declares, a colour literal outside `tokens/`, and a length off the 2px
-grid.
+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
 
@@ -26,15 +24,13 @@ One of three things, and a name that does none of them is noise:
 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 **family with a member re-declared in another file** is an extension
-point: inlining `--text-role-main` breaks the auth panel that re-points it for its own
-subtree. A token **named in TSX or a test** has a reader a `var()` scan cannot see.
+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. In the repository it is
-generated from `scripts/theme-manifest.mjs` by `npm run tokens:theme`; edit the manifest,
-not the file.
+`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.
@@ -58,13 +54,28 @@ because they are one decision:
 `--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:
+difference (`--space-md` at the defaults), so outer = inner + inset. There is no third
+radius token:
 
 | token | used by |
 |---|---|
-| `--radius` | cards, dialogs, sheets, popovers, menus, listboxes |
-| `--radius-sm` | buttons, inputs, tabs, badges, rows, chips, tooltips, calendar cells, nested subpanels |
-| `--radius-pill` | switches, avatars, pills — a shape rather than a radius |
+| `--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
 
@@ -108,12 +119,153 @@ There is no per-component scale factor. See [FACTORS.md](./FACTORS.md) for the t
 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, framed ContentBlocks
-and overlay bodies share these insets. Overlay headers and footers use 0.75 of the vertical
-inset and the body's horizontal inset; the header adds one `--space-2xs` above its title.
-Compact collection shells use half the inset.
+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.
 
 Title/description pairs in CardHeader, ContentBlock and OverlayHeader use the same
 `Stack gap="xs"`. CardFooter and OverlayFooter use a wrapping horizontal Stack with
@@ -122,7 +274,7 @@ with custom before/after values. Specialized timelines and ledgers keep their ow
 
 `--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 family-specific padding variable for
+sets both axes for that surface. Do not add another component-specific padding variable for
 the same job.
 
 Set fonts at the theme root or an explicit scope. Dark regions inherit the font family;

package/dist/styles/index.css

@@ -43,7 +43,6 @@
 @import "./theming/field.css" layer(theming);
 @import "./theming/feedback.css" layer(theming);
 @import "./theming/text.css" layer(theming);
-@import "./theming/mentions.css" layer(theming);
 
 /* ── base: element reset (declares its own @layer base) ───────────────────────── */
 @import "./base.css";

package/dist/styles/map.css

@@ -29,11 +29,10 @@
 /* ── The panes Leaflet paints itself ──────────────────────────────────────────── */
 
 .map--component .leaflet-popup-content-wrapper {
-	border: var(--border-width) solid var(--border);
 	border-radius: var(--radius);
 	background-color: var(--popover);
 	color: var(--popover-foreground);
-	box-shadow: var(--shadow-md);
+	box-shadow: var(--popover-shadow);
 }
 
 .map--component .leaflet-popup-content {
@@ -92,12 +91,14 @@
 	display: none;
 }
 
-/* The on-map instruction tooltip stays, in the kit's surface. */
+/* The on-map instruction tooltip stays, drawn as the kit's inverse Tooltip. */
 .map--component .leaflet-draw-tooltip {
-	border: var(--border-width) solid var(--border);
-	border-radius: var(--radius);
-	background-color: var(--popover);
-	color: var(--popover-foreground);
+	border: var(--border-width) solid var(--foreground);
+	border-radius: var(--radius-sm);
+	padding-block: var(--space-sm);
+	padding-inline: var(--control-px);
+	background-color: var(--foreground);
+	color: var(--background);
 	font-family: var(--font-sans);
 	font-size: var(--text-xs);
 	line-height: var(--text-xs--line-height);
@@ -105,7 +106,12 @@
 
 /* Physical on purpose: Leaflet positions this arrow in physical terms. */
 .map--component .leaflet-draw-tooltip::before {
-	border-right-color: var(--border);
+	border-right-color: var(--foreground);
+}
+
+/* leaflet-draw's second line: the tooltip's ink, receded. */
+.map--component .leaflet-draw-tooltip-subtext {
+	color: var(--background-70);
 }
 
 /* ── Marker clusters ──────────────────────────────────────────────────────────── */

package/dist/styles/mentions.css

@@ -29,8 +29,9 @@
 		-webkit-user-select: all;
 	}
 
-	:is(span, a)[data-ref-id]:hover {
-		background-color: color-mix(in oklab, var(--foreground) 15%, transparent);
+	/* Only a chip with a destination answers the pointer, as a linked soft Badge: its hue at 20%. */
+	a[data-ref-id]:hover {
+		background-color: color-mix(in oklab, var(--foreground) 20%, transparent);
 	}
 
 	/* A chip with no destination is a label, so it does not pretend to be clickable. */
@@ -42,66 +43,58 @@
 		cursor: pointer;
 	}
 
+	/*
+	 * Each hued tone re-points one hue and one ink; the recipe below is Badge soft's
+	 * arithmetic on it: a 10% wash, a 30% edge, a 20% hover. An unknown tone matches none of
+	 * these and keeps the untoned chip.
+	 */
 	:is(span, a)[data-ref-id][data-ref-tone="primary"] {
-		background-color: var(--primary-12);
-		color: var(--primary);
-		box-shadow: inset 0 0 0 var(--border-width) var(--primary-25);
-	}
-
-	:is(span, a)[data-ref-id][data-ref-tone="primary"]:hover {
-		background-color: var(--primary-20);
-	}
-
-	:is(span, a)[data-ref-id][data-ref-tone="secondary"] {
-		background-color: var(--muted);
-		color: var(--muted-foreground);
-		box-shadow: inset 0 0 0 var(--border-width) var(--foreground-10);
-	}
-
-	/* A lift, like every neutral hover. */
-	:is(span, a)[data-ref-id][data-ref-tone="secondary"]:hover {
-		background-color: var(--accent);
+		--ref-hue: var(--primary);
+		--ref-ink: var(--primary-accent);
 	}
 
 	:is(span, a)[data-ref-id][data-ref-tone="info"] {
-		background-color: var(--info-15);
-		color: var(--info);
-		box-shadow: inset 0 0 0 var(--border-width) var(--info-30);
+		--ref-hue: var(--info);
+		--ref-ink: var(--info);
 	}
 
-	:is(span, a)[data-ref-id][data-ref-tone="info"]:hover {
-		background-color: color-mix(in oklab, var(--info) 20%, transparent);
+	:is(span, a)[data-ref-id][data-ref-tone="success"] {
+		--ref-hue: var(--success);
+		--ref-ink: var(--success);
 	}
 
-	:is(span, a)[data-ref-id][data-ref-tone="success"] {
-		background-color: color-mix(in oklab, var(--success) 20%, transparent);
-		color: var(--success);
-		box-shadow: inset 0 0 0 var(--border-width) var(--success-30);
+	/* Warning ink is the accent step, and its edge the warning line step (40%), as on Badge. */
+	:is(span, a)[data-ref-id][data-ref-tone="warning"] {
+		--ref-hue: var(--warning);
+		--ref-ink: var(--warning-accent);
+		--ref-line: 40%;
 	}
 
-	:is(span, a)[data-ref-id][data-ref-tone="success"]:hover {
-		background-color: var(--success-30);
+	:is(span, a)[data-ref-id][data-ref-tone="destructive"] {
+		--ref-hue: var(--destructive);
+		--ref-ink: var(--destructive-accent);
 	}
 
-	/* Warning ink is the paired foreground: the warning hue on its own wash fails contrast. */
-	:is(span, a)[data-ref-id][data-ref-tone="warning"] {
-		background-color: var(--warning-50);
-		color: var(--warning-foreground);
-		box-shadow: inset 0 0 0 var(--border-width) var(--warning-50);
+	:is(span, a)[data-ref-id]:is([data-ref-tone="primary"], [data-ref-tone="info"], [data-ref-tone="success"], [data-ref-tone="warning"], [data-ref-tone="destructive"]) {
+		background-color: color-mix(in oklab, var(--ref-hue) 10%, transparent);
+		color: var(--ref-ink);
+		box-shadow: inset 0 0 0 var(--border-width) color-mix(in oklab, var(--ref-hue) var(--ref-line, 30%), transparent);
 	}
 
-	:is(span, a)[data-ref-id][data-ref-tone="warning"]:hover {
-		background-color: color-mix(in oklab, var(--warning) 70%, transparent);
+	a[data-ref-id]:is([data-ref-tone="primary"], [data-ref-tone="info"], [data-ref-tone="success"], [data-ref-tone="warning"], [data-ref-tone="destructive"]):hover {
+		background-color: color-mix(in oklab, var(--ref-hue) 20%, transparent);
 	}
 
-	:is(span, a)[data-ref-id][data-ref-tone="destructive"] {
-		background-color: color-mix(in oklab, var(--destructive) 12%, transparent);
-		color: var(--mention-destructive-fg);
-		box-shadow: inset 0 0 0 var(--border-width) var(--destructive-30);
+	/* Secondary is neutral: the untoned fill with supporting ink. */
+	:is(span, a)[data-ref-id][data-ref-tone="secondary"] {
+		background-color: var(--foreground-8);
+		color: var(--muted-foreground);
+		box-shadow: inset 0 0 0 var(--border-width) var(--foreground-10);
 	}
 
-	:is(span, a)[data-ref-id][data-ref-tone="destructive"]:hover {
-		background-color: var(--destructive-20);
+	/* Badge secondary's hover: its supporting ink at 20%. */
+	a[data-ref-id][data-ref-tone="secondary"]:hover {
+		background-color: color-mix(in oklab, var(--muted-foreground) 20%, transparent);
 	}
 
 	/*

package/dist/styles/tailwind.css

@@ -19,7 +19,7 @@
  * names the two projects share — both descend from shadcn, so 41 names collide and 23 of them
  * are silently re-pointed without this file. The kit's small radius, six type steps and three
  * font stacks quietly become Tailwind's, and `--text-sm` loses its type-factor fallback so
- * scoped type scaling stops working. The 38 restated names below are the fix.
+ * scoped type scaling stops working. The 39 restated names below are the fix.
  *
  * `inline` is load-bearing, not a style choice. Without it every key resolves once at
  * `:root`, and `bg-primary` inside a `.dark` subtree paints the light colour. The second
@@ -144,6 +144,7 @@
 	--leading-snug:           1.375;
 	--leading-normal:         1.5;
 	--leading-relaxed:        1.625;
+	--tracking-tight:         -0.025em;
 	--tracking-widest:        0.1em;
 	--ease-out:               cubic-bezier(0.23, 1, 0.32, 1);
 	--ease-in-out:            cubic-bezier(0.4, 0, 0.2, 1);

package/dist/styles/themes/default.css

@@ -20,7 +20,7 @@
 	--radius-sm: 0.5rem; /* Everything inside a container or smaller than one — controls, rows, chips, badges, tooltips. */
 	--border-width: 1px; /* Default hairline weight for dividers, outlines, and control borders. */
 	--border-width-strong: 2px; /* Emphasized rail weight for quote bars and active navigation indicators. */
-	--radius-pill: 999px; /* Fully rounded ends for pills, switches, and avatars. */
+	--radius-pill: 999px; /* Fully rounded ends for pills, switches, tracks, and status dots. True circles (avatars, radios) use 50%. */
 }
 
 :root,
@@ -61,16 +61,16 @@
 	--sidebar-accent: var(--neutral-75); /* Sidebar hover and selected-row neutral fill. */
 	--sidebar-accent-foreground: var(--neutral-900); /* Text and icons on sidebar accent fills. */
 	--sidebar-border: var(--neutral-200); /* Sidebar dividers and shell border. */
-	--sidebar-ring: var(--neutral-400); /* Focus-visible ring inside the sidebar. */
+	--sidebar-ring: var(--neutral-400); /* The sidebar's focus-ring seed, as --ring is the page's: sidebar surfaces mix it 70/30 toward --sidebar-foreground in light, read it unmixed in dark, and compose --focus-ring, --focus-ring-inset and --field-focus-ring from it. */
 	--shadow-ink: var(--pure-black); /* Ink every elevation tier tints with. */
-	--shadow-2xs: 0 1px 2px 0px color-mix(in oklab, var(--shadow-ink) 4%, transparent); /* Minimal elevation for compact controls. */
-	--shadow-xs: 0 1px 2px 0px color-mix(in oklab, var(--shadow-ink) 6%, transparent), 0 1px 1px -1px color-mix(in oklab, var(--shadow-ink) 6%, transparent); /* Extra-small elevation for controls and rows. */
-	--shadow-sm: 0 1px 2px 0px color-mix(in oklab, var(--shadow-ink) 6%, transparent), 0 2px 4px -2px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Small elevation for raised controls and cards. */
-	--shadow: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 8%, transparent), 0 4px 8px -4px color-mix(in oklab, var(--shadow-ink) 12%, transparent); /* Default elevation for framed content. */
-	--shadow-md: 0 2px 4px -1px color-mix(in oklab, var(--shadow-ink) 8%, transparent), 0 8px 16px -8px color-mix(in oklab, var(--shadow-ink) 16%, transparent); /* Medium elevation for floating surfaces. */
-	--shadow-lg: 0 4px 8px -2px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 12px 24px -12px color-mix(in oklab, var(--shadow-ink) 18%, transparent); /* Large elevation for menus, dialogs, and popovers. */
-	--shadow-xl: 0 8px 16px -4px color-mix(in oklab, var(--shadow-ink) 12%, transparent), 0 20px 40px -20px color-mix(in oklab, var(--shadow-ink) 22%, transparent); /* Extra-large elevation for prominent overlays. */
-	--shadow-2xl: 0 16px 32px -8px color-mix(in oklab, var(--shadow-ink) 18%, transparent), 0 32px 64px -28px color-mix(in oklab, var(--shadow-ink) 28%, transparent); /* Maximum elevation for exceptional floating surfaces. */
+	--shadow-2xs: 0 1px 2px 0px color-mix(in oklab, var(--shadow-ink) 4%, transparent); /* shadcn compatibility only; no kit surface reads it. Resting lift is --shadow-xs. */
+	--shadow-xs: 0 1px 2px 0px color-mix(in oklab, var(--shadow-ink) 6%, transparent), 0 1px 1px -1px color-mix(in oklab, var(--shadow-ink) 6%, transparent); /* Resting lift: a framed card's bezel, a raised chip, a slider thumb, a floating sidebar. */
+	--shadow-sm: 0 1px 2px 0px color-mix(in oklab, var(--shadow-ink) 6%, transparent), 0 2px 4px -2px color-mix(in oklab, var(--shadow-ink) 10%, transparent); /* Hover lift for every clickable card and tile, and controls over artwork. */
+	--shadow: 0 1px 3px 0px color-mix(in oklab, var(--shadow-ink) 8%, transparent), 0 4px 8px -4px color-mix(in oklab, var(--shadow-ink) 12%, transparent); /* shadcn compatibility only; no kit surface reads it. Hover lift is --shadow-sm. */
+	--shadow-md: 0 2px 4px -1px color-mix(in oklab, var(--shadow-ink) 8%, transparent), 0 8px 16px -8px color-mix(in oklab, var(--shadow-ink) 16%, transparent); /* The lift inside --popover-shadow; anchored popups read that, with its hairline ring. */
+	--shadow-lg: 0 4px 8px -2px color-mix(in oklab, var(--shadow-ink) 10%, transparent), 0 12px 24px -12px color-mix(in oklab, var(--shadow-ink) 18%, transparent); /* Free-floating transient surfaces: toast, drag ghost, floating batch bar, submenu. */
+	--shadow-xl: 0 8px 16px -4px color-mix(in oklab, var(--shadow-ink) 12%, transparent), 0 20px 40px -20px color-mix(in oklab, var(--shadow-ink) 22%, transparent); /* Modals and command palettes. */
+	--shadow-2xl: 0 16px 32px -8px color-mix(in oklab, var(--shadow-ink) 18%, transparent), 0 32px 64px -28px color-mix(in oklab, var(--shadow-ink) 28%, transparent); /* shadcn compatibility only; no kit surface reads it. Modals and palettes use --shadow-xl. */
 }
 
 /*
@@ -110,7 +110,8 @@
 	--chart-5: var(--series-5-dark);
 	--sidebar: var(--neutral-950);
 	--sidebar-foreground: var(--neutral-50);
-	--sidebar-primary: var(--violet-500);
+	--sidebar-primary: var(--neutral-50);
+	--sidebar-primary-foreground: var(--neutral-900);
 	--sidebar-accent: var(--neutral-800);
 	--sidebar-accent-foreground: var(--neutral-50);
 	--sidebar-border: var(--white-a10);
@@ -123,9 +124,9 @@
  * Emitted rather than hand-written so it cannot drift from the block above.
  */
 @media (prefers-color-scheme: dark) {
-	:root:not([data-theme="light"]),
-	[data-ui-scope]:not([data-theme="light"]),
-	[data-density]:not([data-theme="light"]) {
+	:root:not(.light, [data-theme="light"]),
+	[data-ui-scope]:not(.light, [data-theme="light"], :where(.light, [data-theme="light"]) *),
+	[data-density]:not(.light, [data-theme="light"], :where(.light, [data-theme="light"]) *) {
 		color-scheme: dark;
 		--background: var(--neutral-900);
 		--foreground: var(--neutral-50);
@@ -153,7 +154,8 @@
 		--chart-5: var(--series-5-dark);
 		--sidebar: var(--neutral-950);
 		--sidebar-foreground: var(--neutral-50);
-		--sidebar-primary: var(--violet-500);
+		--sidebar-primary: var(--neutral-50);
+		--sidebar-primary-foreground: var(--neutral-900);
 		--sidebar-accent: var(--neutral-800);
 		--sidebar-accent-foreground: var(--neutral-50);
 		--sidebar-border: var(--white-a10);