@eifi1/ui-kit 0.48.2 → 0.50.0

package/src/admin/user-roster.tsx

@@ -38,8 +38,9 @@ import { DEFAULT_USER_ROSTER_LABELS } from "./user-roster-labels";
  *
  * The column keys ARE the server's sort keys (§3.1): `name`, `email`, `role`, `created`,
  * `last_login` — so {@link userRosterSort} turns the table's sort state into the query
- * as it is. Phone cards come from the same columns: the identity is the card's headline,
- * the role, states, last login and the actions are its fields, created is left off.
+ * as it is. Phone cards come from the same columns: the identity is the card's headline
+ * with the account's states as chips beside it, the role, last login and the actions are
+ * its three fields, created is left off.
  */
 
 /* ── Rows and states ────────────────────────────────────────────────────────── */
@@ -327,16 +328,27 @@ function StateChips({ states }: { states: readonly RosterState[] }) {
 /**
  * The roster's columns, in the contract's order (§3.3):
  *
- * | key | cell | sort | phone |
- * |---|---|---|---|
- * | `name` | {@link UserIdentityCell} | last, first | the card's headline |
- * | `email` | the address (`emailColumn` only) | address | hidden |
- * | `role` | `RoleChip`(s), or {@link RoleSelect} where `editableRole` | role | field |
- * | `state` | `AccountStateChip`s from `stateOf` | — | field |
- * | `created` | `dateColumn` | instant | hidden |
- * | `last_login` | `dateColumn`, relative, "Never" | instant | field |
- * | …`extra` | the app's | the app's | the app's |
- * | `actions` | {@link UserRowActions} | — | field |
+ * | key | cell | sort | phone | fit (0.50) |
+ * |---|---|---|---|---|
+ * | `name` | {@link UserIdentityCell} | last, first | the card's headline | `grow` |
+ * | `email` | the address (`emailColumn` only) | address | hidden | — |
+ * | `role` | `RoleChip`(s), or {@link RoleSelect} where `editableRole` | role | field | — |
+ * | `state` | `AccountStateChip`s from `stateOf` | — | chips beside the headline | — |
+ * | `created` | `dateColumn` | instant | hidden | `fitPriority: 1` |
+ * | `last_login` | `dateColumn`, relative, "Never" | instant | field | `fitPriority: 2` |
+ * | …`extra` | the app's | the app's | off the card unless marked `mobile: "secondary"` | the app's |
+ * | `actions` | {@link UserRowActions} | — | the card's actions row (`role: "actions"`) | — |
+ *
+ * The fit (0.50, kastlan K2): Name takes the rest of the row, and a table narrower than
+ * its columns leaves out Created, then Last login (DataTable's `grow` / `fitPriority`).
+ * The role and state chips still wrap in their cells (0.48), and the other cells keep one
+ * line at Normal. `{ ...col, grow: undefined, fitPriority: undefined }` restores the 0.49
+ * layout; an `extra` column takes a `fitPriority` of its own to leave too.
+ *
+ * The card holds three fields — `role`, `last_login` and one more: an `extra` column marked
+ * `mobile: "secondary"` takes that place. The actions are `role: "actions"` (0.49), drawn
+ * after the fields and never one of the three. Drop them from the card with
+ * `mobile: "hidden"`, or draw a `mobileCard`.
  *
  * Pure: hand it resolved words, or use {@link useUserRosterColumns}. The keys are stable,
  * so an app may drop or move a column (`columns.filter((c) => c.key !== "created")`).
@@ -379,6 +391,9 @@ export function userRosterColumns<T extends UserRosterRow, R extends string = st
           .filter(Boolean)
           .join(" "),
       mobilePrimary: true,
+      // Takes the rest of the row and ellipsises (0.50, kastlan K2): the roster fits its
+      // pane — a settings column, an admin page — instead of scrolling sideways.
+      grow: true,
     },
   ];
   if (emailColumn) {
@@ -437,17 +452,26 @@ export function userRosterColumns<T extends UserRosterRow, R extends string = st
         getValue: (row) => rolesOf(row, roleOf)[0] ?? "",
         options: (Object.keys(roles) as R[]).map((value) => ({ value, label: roles[value].label })),
       },
+      mobile: "secondary",
     },
     {
       key: "state",
       header: labels.state,
-      cell: (row) => <StateChips states={stateOf(row)} />,
+      // No states, no cell: the phone card then shows no chip beside the name.
+      cell: (row) => {
+        const states = stateOf(row);
+        return states.length === 0 ? null : <StateChips states={states} />;
+      },
+      // Beside the name on the phone card, so the role, last login and the actions keep
+      // the card's three fields.
+      role: "status",
     },
     dateColumn<T>({
       key: "created",
       header: labels.created,
       value: (row) => row.created_at ?? null,
-      column: { mobileHidden: true },
+      // The first to leave a narrow table (0.50, kastlan K2), then last login.
+      column: { mobileHidden: true, fitPriority: 1 },
     }),
     // How long ago rather than a date — the question is "recently?" — with the exact
     // time beside it (keksdose's last-seen column, Kurvenschmiede's; 0.32 §4: never only
@@ -458,6 +482,7 @@ export function userRosterColumns<T extends UserRosterRow, R extends string = st
       value: (row) => row.last_login_at ?? null,
       display: "relative",
       empty: labels.never,
+      column: { mobile: "secondary", fitPriority: 2 },
     }),
     ...extra,
   );
@@ -479,6 +504,8 @@ export function userRosterColumns<T extends UserRosterRow, R extends string = st
       headClassName: "w-px text-end",
       // The menu button keeps its own click: a row link must not wrap it.
       noRowLink: true,
+      // Always on the phone card, after the fields and never one of the three (0.49).
+      role: "actions",
     });
   }
   return columns;

package/src/auth/accept-invitation.tsx

@@ -147,7 +147,7 @@ export function AcceptInvitation({
           ? "accepting"
           : "signIn";
 
-  const continueButton = (variant: "brand" | "secondary") => (
+  const continueButton = (variant: "accent" | "secondary") => (
     <Button href={continueHref} replace variant={variant}>
       {labels.continue}
     </Button>
@@ -162,7 +162,7 @@ export function AcceptInvitation({
         tone="success"
         icon={<CheckCircle2 />}
         title={settled?.name ? labels.joined(settled.name) : labels.accepted}
-        action={continueButton("brand")}
+        action={continueButton("accent")}
         className={OUTCOME_CLASS}
       />
     );
@@ -174,7 +174,7 @@ export function AcceptInvitation({
         hint={labels.signInHint}
         action={
           <>
-            <Button href={signInHref} variant="brand">
+            <Button href={signInHref} variant="accent">
               {labels.signIn}
             </Button>
             {registerHref !== undefined && (

package/src/auth/not-found-page.tsx

@@ -81,7 +81,7 @@ export function NotFoundPage({
       <p className="max-w-prose text-sm text-secondary">{labels.body}</p>
       {children}
       <div className="mt-4 flex flex-wrap justify-center gap-3">
-        <Button href={homeHref} variant="brand">
+        <Button href={homeHref} variant="accent">
           {labels.home}
         </Button>
         {appHref !== undefined && (

package/src/auth/reset-password-form.tsx

@@ -232,7 +232,7 @@ export function ResetPasswordForm({
           title={token === "" ? labels.noToken : labels.invalid}
           hint={labels.invalidHint}
           action={
-            <Button href={forgotHref} variant="brand">
+            <Button href={forgotHref} variant="accent">
               {labels.requestNew}
             </Button>
           }
@@ -253,11 +253,11 @@ export function ResetPasswordForm({
         {notices}
         <p className="text-xs text-muted">{labels.sessionsEnded}</p>
         {onSignIn ? (
-          <Button type="button" variant="brand" className="w-full" onClick={() => onSignIn(email)}>
+          <Button type="button" variant="accent" className="w-full" onClick={() => onSignIn(email)}>
             {labels.signIn}
           </Button>
         ) : (
-          <Button href={email ? withQuery(signInHref, "email", email) : signInHref} variant="brand" className="w-full">
+          <Button href={email ? withQuery(signInHref, "email", email) : signInHref} variant="accent" className="w-full">
             {labels.signIn}
           </Button>
         )}

package/src/auth/verify-email.tsx

@@ -119,7 +119,7 @@ function ResendButton({
 }: {
   state: ReturnType<typeof useResend>;
   labels: VerifyEmailLabels;
-  variant: "secondary" | "brand";
+  variant: "secondary" | "accent";
 }) {
   return (
     <Button
@@ -269,7 +269,7 @@ export function VerifyEmailStatus({
   const href = continueHref ?? (signedIn ? "/" : "/login");
   // `replace`: the token is spent, so Back must not land on this page again (keksdose F1).
   const continueButton = (
-    <Button href={href} replace variant={outcome === "verified" ? "brand" : "secondary"}>
+    <Button href={href} replace variant={outcome === "verified" ? "accent" : "secondary"}>
       {labels.continue}
     </Button>
   );
@@ -304,7 +304,7 @@ export function VerifyEmailStatus({
         hint={hint}
         action={
           <>
-            {canResend && <ResendButton state={resend} labels={labels} variant="brand" />}
+            {canResend && <ResendButton state={resend} labels={labels} variant="accent" />}
             {continueButton}
           </>
         }
@@ -366,6 +366,14 @@ export interface EmailVerificationBannerProps {
    * is never hidden behind "More". Default `false`: the outcome stays in the message.
    */
   clampMobile?: boolean;
+  /**
+   * 0.50 (kastlan K1): where "Send again" goes on a phone in the `box` variant —
+   * {@link AlertBanner}'s `actionPlacement`, passed through. `"flow"` keeps it on the
+   * message's line while the message keeps 10rem, else at the end of the next line,
+   * instead of a line of its own (kastlan's ≤ 56px banner on a 390px phone, KX-5).
+   * Default `"own-line"`, as before. The `strip` variant flows like that already.
+   */
+  actionPlacement?: "own-line" | "flow";
 }
 
 /**
@@ -388,6 +396,7 @@ export function EmailVerificationBanner({
   className,
   labels: labelsProp,
   clampMobile = false,
+  actionPlacement,
 }: EmailVerificationBannerProps) {
   const labels = useKitLabels("verifyEmail", DEFAULT_VERIFY_EMAIL_LABELS, labelsProp);
   const resend = useResend(onResend, cooldown);
@@ -421,6 +430,7 @@ export function EmailVerificationBanner({
       onDismiss={onDismiss}
       dismissLabel={onDismiss ? labels.dismiss : undefined}
       clampMobile={clampMobile}
+      actionPlacement={actionPlacement}
       className={className}
     >
       {labels.banner}

package/src/billing/plan-card.tsx

@@ -471,7 +471,7 @@ export function PlanPicker({
       <div className="flex justify-end">
         <Button
           type="button"
-          variant="primary"
+          variant="default"
           className="max-sm:w-full"
           disabledReason={blocked}
           pending={pending}
@@ -538,7 +538,7 @@ export function GrantWarningConfirm({ open, onOpenChange, onConfirm, labels: lab
             {common.back}
           </Button>
           <Button
-            variant="primary"
+            variant="default"
             onClick={() => {
               onConfirm();
               onOpenChange(false);

package/src/components/amount-input.tsx

@@ -41,10 +41,11 @@ import {
 } from "./field-parts";
 import { useEndWidth, useNumericField } from "./numeric-field";
 import type { CommitScope } from "./write-lock";
+import { dataAttributes, type DataAttributes } from "../lib/data-attributes";
 
 /** {@link AmountInput}'s props — exported since 0.34 (refactor audit 2026-10, API-9): a
  *  wrapper typed itself off `ComponentProps<typeof AmountInput>` until then. */
-export interface AmountInputProps extends FieldHelpProps {
+export interface AmountInputProps extends FieldHelpProps, DataAttributes {
   value: string;
   onChange: (value: string) => void;
   currency?: string;
@@ -427,8 +428,8 @@ export function AmountInput(props: AmountInputProps) {
   const { lock, locked, off, isMobile, asDisplay, showCalc, showNumpad, setFocused, mark, draft, setDraft, derived } =
     numeric;
   const invalid = numeric.isInvalid;
-  // A locked chip is a read-out: picking a currency is a change too.
-  const editable = !!onCurrencyChange && !locked;
+  // A locked or disabled chip is a read-out: picking a currency is a change too.
+  const editable = !!onCurrencyChange && !locked && !off;
   // Room for the trailing controls — the calculator and the currency chip — once
   // measured, as NumberInput reserves its own (keksdose live #367, DUP-10): their
   // width, the track's `end-1` inset in the boxed shape, and NumberInput's 4px gap.
@@ -533,7 +534,7 @@ export function AmountInput(props: AmountInputProps) {
   const selected = getCurrency(currency);
 
   return (
-    <div className={cn("w-full", className)}>
+    <div {...dataAttributes(props)} className={cn("w-full", className)}>
       {/* Inner relative box holds the input + its absolutely-positioned
           trailing controls (calculator / currency), so those stay anchored to
           the INPUT even when the mobile math bar is rendered below (#334). It is

package/src/components/autocomplete.tsx

@@ -519,6 +519,8 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
             // Every press inside the list keeps focus in the field — rows, the status
             // line, the scrollbar — or the input's blur would close the list first.
             role="presentation"
+            // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).
+            data-kit-layer=""
             // Portalled out of the form's `dir`; the field's is put back. The list is
             // exactly the field's width, so `left` places it in either direction.
             dir={dir}

package/src/components/breadcrumbs.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useEffect, useRef, useState } from "react";
+import { Fragment, useContext, useEffect, useRef, useState } from "react";
 import type { ComponentPropsWithRef, ReactElement, ReactNode } from "react";
 import { ChevronRight, MoreHorizontal } from "lucide-react";
 import { cn } from "../lib/cn";
@@ -6,6 +6,7 @@ import { FOCUS_RING } from "./focus-ring";
 import { useKitLabels, useKitLink, type LabelOverride } from "../i18n/kit-labels";
 import { pickLinkRenderer, RenderedKitLink } from "./text-link";
 import { DEFAULT_BREADCRUMBS_LABELS } from "./breadcrumbs-labels";
+import { PageHeaderTrailContext } from "./page-header-context";
 
 export interface BreadcrumbsLabels {
   /** The `nav` landmark's name — what a screen reader lists it as. */
@@ -24,6 +25,12 @@ export interface BreadcrumbItem {
   href?: string;
   /** A stable React key, when `label` is not a string. */
   key?: string;
+  /**
+   * The app's home entry (0.49 KIT-9). Default: an entry whose `href` is `"/"`. No trail
+   * is drawn when only home entries are left — inside a `PageHeader`, or wherever the
+   * current entry is hidden (`hideCurrent`): "Home" above a page's title says nothing.
+   */
+  home?: boolean;
 }
 
 /** What {@link BreadcrumbsProps.renderLink} is handed. Spread it onto your router's
@@ -57,6 +64,18 @@ export interface BreadcrumbsProps extends Omit<ComponentPropsWithRef<"nav">, "ch
   keepEnd?: number;
   /** Overrides the {@link UiKitProvider}'s `breadcrumbs` labels. */
   labels?: LabelOverride<BreadcrumbsLabels>;
+  /**
+   * Leave out the last entry, the current page (0.49 KIT-9). The entry before it stays a
+   * link, and no entry carries `aria-current`: the page's title names where you are.
+   *
+   * Default `true` inside a `PageHeader`'s `breadcrumbs` (the title is right below, so
+   * the trail would repeat it), `false` elsewhere. With the current entry hidden — and
+   * inside a `PageHeader` either way — the trail is drawn only when at least one entry
+   * that is not home ({@link BreadcrumbItem.home}) is left, so a trail drawn by the
+   * layout above the page shows no lone "Home" link either. `false` keeps the current
+   * entry as text with `aria-current="page"`.
+   */
+  hideCurrent?: boolean;
 }
 
 /**
@@ -69,16 +88,18 @@ export interface BreadcrumbsProps extends Omit<ComponentPropsWithRef<"nav">, "ch
  * the server's first paint is already right.
  */
 export function Breadcrumbs({
-  items,
+  items: allItems,
   renderLink,
   separator,
   collapse = true,
   keepEnd = 2,
   labels: labelsProp,
+  hideCurrent,
   className,
   "aria-label": ariaLabel,
   ...rest
 }: BreadcrumbsProps) {
+  const host = useContext(PageHeaderTrailContext);
   const labels = useKitLabels("breadcrumbs", DEFAULT_BREADCRUMBS_LABELS, labelsProp);
   const kitLink = useKitLink();
   const [expanded, setExpanded] = useState(false);
@@ -92,7 +113,13 @@ export function Breadcrumbs({
     const li = revealedRef.current;
     (li?.querySelector<HTMLElement>("a[href]") ?? li)?.focus();
   }, [expanded]);
-  if (items.length === 0) return null;
+  const hides = hideCurrent ?? host?.titled ?? false;
+  const shown = hides ? allItems.slice(0, -1) : allItems;
+  if (shown.length === 0) return null;
+  // A trail of home entries alone repeats nothing worth a line: in a PageHeader, and
+  // wherever the current entry is hidden (a layout's trail above the page's title).
+  if ((host || hides) && !shown.some((item) => !(item.home ?? item.href === "/"))) return null;
+  const items = shown;
 
   const end = Math.max(1, keepEnd);
   // Crumbs [1, firstKept) are the collapsible middle. Collapsing a single crumb into a
@@ -116,7 +143,8 @@ export function Breadcrumbs({
     <nav {...rest} aria-label={ariaLabel ?? labels.label} className={cn("min-w-0 text-sm", className)}>
       <ol className="m-0 flex min-w-0 list-none flex-wrap items-center gap-x-1.5 gap-y-1 p-0 text-muted">
         {items.map((item, i) => {
-          const last = i === items.length - 1;
+          // With the current entry hidden, the last one shown is a parent: a link.
+          const last = !hides && i === items.length - 1;
           const key = item.key ?? (typeof item.label === "string" ? `${i}-${item.label}` : String(i));
           let content: ReactNode;
           if (last) {

package/src/components/button-look.ts

@@ -13,7 +13,75 @@ import type { KitLinkComponent, KitLinkProps } from "../i18n/kit-labels";
  * The other exports are the two buttons' shared parts (`@internal`).
  */
 
-export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "brand" | "link";
+/**
+ * A button's look.
+ *
+ * - `default`: the quiet action — a warm filled chip with a hairline border. What a
+ *   Button with no `variant` draws.
+ * - `accent`: the strong one, solid `--brand` with `--brand-contrast` text — the one
+ *   call to action a view leads with. "Accent" is the button's role here, painted in
+ *   `--brand`; it is not the palette's second anchor colour, also called `accent`
+ *   (theme/palette-derive.ts), which no button paints.
+ * - `secondary`: an outline. `ghost`: text or glyph only. `danger`: solid `--danger`,
+ *   for an action that destroys something. `link`: a text link that acts (a `<button>`).
+ * - `primary` and `brand` are **deprecated** aliases of `default` and `accent` (0.49,
+ *   same look; a development build warns once per name). They are removed in 0.51, and
+ *   `primary` will not come back with another meaning.
+ */
+export type ButtonVariant =
+  | "default"
+  | "accent"
+  | "secondary"
+  | "ghost"
+  | "danger"
+  | "link"
+  /** @deprecated 0.49 — use `default` (same look); removed in 0.51. */
+  | "primary"
+  /** @deprecated 0.49 — use `accent` (same look); removed in 0.51. */
+  | "brand";
+
+/** @internal A {@link ButtonVariant} without the deprecated aliases. */
+export type CanonicalButtonVariant = Exclude<ButtonVariant, "primary" | "brand">;
+
+/** The deprecated names and what they stand for — see {@link ButtonVariant}. */
+const DEPRECATED_BUTTON_VARIANTS: Readonly<Record<string, CanonicalButtonVariant>> = {
+  primary: "default",
+  brand: "accent",
+};
+
+/** The kit's dev switch, as `lib/logger.ts` reads it: a development build, never a
+ *  production one (the consumer's bundler makes `import.meta.env.DEV` false) and never
+ *  under vitest. Read per call so a test can switch it on with `vi.stubEnv`. */
+function devWarnings(): boolean {
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+}
+
+const warnedVariants = new Set<string>();
+
+/**
+ * @internal A deprecated variant name warns once (per `component` and name) in a
+ * development build, then reads as the name it stands for. `component` is the prop's
+ * owner in the message ("Button variant", "FormActions submitVariant", …).
+ */
+export function warnDeprecatedVariant(component: string, name: string, replacement: string): void {
+  if (!devWarnings()) return;
+  const key = `${component}|${name}`;
+  if (warnedVariants.has(key)) return;
+  warnedVariants.add(key);
+  console.warn(
+    `[ui-kit] ${component}="${name}" is deprecated: use "${replacement}" (same look). ` +
+      `"${name}" is removed in 0.51.`,
+  );
+}
+
+/** @internal `primary` → `default`, `brand` → `accent` (warning once in development);
+ *  every other variant as it is. Runs before every lookup keyed by the variant. */
+export function resolveButtonVariant(variant: ButtonVariant, component = "Button variant"): CanonicalButtonVariant {
+  const replacement = DEPRECATED_BUTTON_VARIANTS[variant];
+  if (replacement === undefined) return variant as CanonicalButtonVariant;
+  warnDeprecatedVariant(component, variant, replacement);
+  return replacement;
+}
 
 // Shared base ring for every button-styled element. Kept as a named const so the
 // <Button> component and the {@link buttonClasses} helper draw from one source and
@@ -83,13 +151,14 @@ const BUTTON_SIZES_LARGE: Record<ButtonSize, string> = {
 export const HOVER_INK = "hover:bg-[color-mix(in_srgb,var(--text-primary)_7%,transparent)]";
 
 // Warm, palette-token-driven so buttons blend with the fields + cards in every theme.
-// Actions default to a warm bordered look (primary = filled warm chip, secondary =
-// outline); `brand` stays the solid accent for the rare strong CTA; `danger` takes the
+// Actions default to a warm bordered look (`default` = filled warm chip, secondary =
+// outline); `accent` is the solid brand fill for the rare strong CTA; `danger` takes the
 // semantic `--danger` family (destructive semantics), so a consumer can re-point the
 // destructive hue instead of inheriting a hard-coded red. Focus rings follow each
-// variant's own accent: brand for the four neutral ones, danger for `danger`.
-export const buttonVariantClasses: Record<ButtonVariant, string> = {
-  primary:
+// variant's own accent: brand for the four neutral ones, danger for `danger`. Keyed by
+// the canonical names: {@link resolveButtonVariant} maps the deprecated ones first.
+export const buttonVariantClasses: Record<CanonicalButtonVariant, string> = {
+  default:
     // Hovers onto `--bg-active`, not `--border` (0.33, §12.9): More contrast steps the
     // border until it is a 3:1 LINE, and as a fill under the label that left 2.7:1.
     "border border-subtle bg-surface-2 text-primary hover:bg-active focus-visible:ring-brand",
@@ -97,7 +166,7 @@ export const buttonVariantClasses: Record<ButtonVariant, string> = {
   ghost: `bg-transparent text-primary ${HOVER_INK} focus-visible:ring-brand`,
   danger:
     "bg-danger text-danger-contrast hover:bg-danger-hover focus-visible:ring-danger-strong",
-  brand:
+  accent:
     "bg-brand text-brand-contrast hover:bg-brand-hover focus-visible:ring-brand",
   // A text link that is still a `<button>` — keksdose's six hand-rolled
   // `<button className="text-brand underline">` sites ("Resend code", "Show all",
@@ -132,14 +201,14 @@ export const buttonVariantClasses: Record<ButtonVariant, string> = {
  *
  * `danger` also reaches the two NEUTRAL boxed variants, where the box carries it:
  * `secondary` becomes an outlined destructive button (`--danger` text and a
- * `--danger-border` outline, the quiet danger fill on hover) and `primary` a soft one
+ * `--danger-border` outline, the quiet danger fill on hover) and `default` a soft one
  * (the quiet fill at rest, solid `--danger` on hover). kastlan's meeting-invitations-
  * tab.tsx "Remove all" is `variant="secondary" className="text-destructive"` — a
  * destructive action that must sit in a row of secondary buttons without shouting
  * like the solid `variant="danger"` would, and whose red text alone left the border
  * and hover saying "neutral". `muted` stays a text look and does nothing on a box, and
- * `danger`, `brand` and `link`'s own colours are left alone: a tone that recoloured a
- * solid danger or brand button would be a second variant under another name.
+ * `danger`, `accent` and `link`'s own colours are left alone: a tone that recoloured a
+ * solid danger or accent button would be a second variant under another name.
  */
 export type ButtonTone = "default" | "muted" | "danger";
 
@@ -154,19 +223,19 @@ const BUTTON_TONES: Record<Exclude<ButtonTone, "default">, string> = {
 };
 
 /** Only the two transparent variants take every tone; see {@link ButtonTone}. */
-const TONED_VARIANTS = new Set<ButtonVariant>(["link", "ghost"]);
+const TONED_VARIANTS = new Set<CanonicalButtonVariant>(["link", "ghost"]);
 
 // `tone="danger"` on the neutral boxed variants — see {@link ButtonTone}. Each string
 // restates every colour the variant sets (border, fill, text, hover, ring) so none of
 // the neutral ones survives the merge.
-const BUTTON_BOXED_DANGER: Partial<Record<ButtonVariant, string>> = {
+const BUTTON_BOXED_DANGER: Partial<Record<CanonicalButtonVariant, string>> = {
   // Not boxed, but its hover is a fill: the danger wash under the danger text, as
   // IconButton's danger tone (0.33). On B′'s translucent ink `--danger` fell to 4.2:1
   // over a light page.
   ghost: "hover:bg-danger-soft",
   secondary:
     "border-danger bg-transparent text-danger hover:bg-danger-soft focus-visible:ring-danger-strong",
-  primary:
+  default:
     "border-danger bg-danger-soft text-danger hover:border-[var(--danger)] hover:bg-danger hover:text-danger-contrast focus-visible:ring-danger-strong disabled:hover:border-danger disabled:hover:bg-danger-soft disabled:hover:text-danger",
 };
 
@@ -197,11 +266,12 @@ export interface ButtonClassesOptions {
  * compact toolbar links.
  */
 export function buttonClasses(
-  variant: ButtonVariant = "primary",
+  given: ButtonVariant = "default",
   classNameOrOptions?: string | ButtonClassesOptions,
 ): string {
   const { size = "md", className } =
     typeof classNameOrOptions === "object" ? classNameOrOptions : { className: classNameOrOptions };
+  const variant = resolveButtonVariant(given, "buttonClasses variant");
   return cn(
     BUTTON_BASE,
     BUTTON_SIZES[size],
@@ -221,7 +291,8 @@ export const ICON_BUTTON_PRESSED =
   "bg-brand-soft text-brand hover:bg-brand-soft-hover hover:text-brand-muted disabled:hover:bg-brand-soft disabled:hover:text-brand";
 
 /** @internal The button look shared by the `<button>` and the `<a>` form. */
-export function buttonLook(variant: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {
+export function buttonLook(given: ButtonVariant, size: ButtonSize, stretch: boolean | undefined, tone: ButtonTone) {
+  const variant = resolveButtonVariant(given);
   return cn(
     BUTTON_BASE,
     BUTTON_SIZES[size],

package/src/components/button.tsx

@@ -24,6 +24,9 @@ import type { ButtonSize, ButtonTone, ButtonVariant } from "./button-look";
  * link buttons submitting their form).
  */
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** `default` (the quiet action, what a Button without `variant` draws), `accent` (the
+   *  strong call to action, solid brand), `secondary`, `ghost`, `danger` or `link`.
+   *  `primary` / `brand` are deprecated aliases of `default` / `accent`. See {@link ButtonVariant}. */
   variant?: ButtonVariant;
   /** `md` (default) is the page's action button. `sm` is the compact one — 12px text
    *  and `px-2 py-1` — for the secondary actions in a toolbar, a card header or a
@@ -39,7 +42,7 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   ref?: Ref<HTMLButtonElement>;
   /** Text colour for `link` and `ghost`: `muted` (quiet, body colour on hover) or
    *  `danger` (quiet, `--danger` on hover). `danger` also makes `secondary` an
-   *  outlined destructive button and `primary` a soft one; ignored by the other
+   *  outlined destructive button and `default` a soft one; ignored by the other
    *  variants. See {@link ButtonTone}. */
   tone?: ButtonTone;
   /**
@@ -181,7 +184,7 @@ function ButtonLink({
   replace,
   reloadDocument,
   disabled,
-  variant = "primary",
+  variant = "default",
   size = "md",
   stretch,
   tone = "default",
@@ -257,7 +260,7 @@ function ButtonLink({
 }
 
 function ButtonElement({
-  variant = "primary",
+  variant = "default",
   size = "md",
   stretch,
   tone = "default",

package/src/components/calendar-heatmap.tsx

@@ -9,6 +9,7 @@ import { parseHex } from "../theme/color";
 import { Tooltip } from "./tooltip";
 import type { WeekDay } from "./mini-calendar";
 import { DEFAULT_CALENDAR_HEATMAP_LABELS } from "./calendar-heatmap-labels";
+import { formatWithMinus } from "../lib/minus";
 
 /**
  * Every string the heatmap speaks — the `calendarHeatmap` namespace of
@@ -248,7 +249,7 @@ export function CalendarHeatmap({
   const providerWeekStart = useKitWeekStart();
   const weekStart: WeekDay = weekStartsOn ?? providerWeekStart ?? localeWeekStart(locale);
   const numberFormat = useMemo(() => new Intl.NumberFormat(locale), [locale]);
-  const formatValue = formatValueProp ?? ((v: number) => numberFormat.format(v));
+  const formatValue = formatValueProp ?? ((v: number) => formatWithMinus(numberFormat, v));
 
   const values = useMemo(() => {
     const m = new Map<string, number>();