@vegastack/design 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,79 @@
 import { ClassValue } from 'clsx';
 export { ClassValue } from 'clsx';
+import * as React from 'react';
+
+/**
+ * THE prose recipe — one token vocabulary for rendered rich text (audit B4-09, 2026-09-07).
+ *
+ * Two surfaces render prose the system did not author element-by-element: `MarkdownView`
+ * (react-markdown turns a markdown string into plain HTML elements) and `TextEdit` (ProseMirror
+ * owns the contenteditable DOM). Before this file each restated the same heading/paragraph/list/
+ * code/quote recipe in its own grammar — a `Components` map in one, 69 `[&_h1]:` rules in the
+ * other — and they had already drifted (`h4`–`h6`, `table`, `img` existed on one side only).
+ *
+ * ## Why descendant variants and not per-element classes
+ *
+ * A prose root cannot put a class on every element: ProseMirror generates the editor's DOM, and
+ * react-markdown's output is only reachable through an override map. Descendant variants
+ * (`[&_h1]:mt-6` → `.recipe h1 { margin-top: … }`) style both from ONE string on the root, which
+ * is what makes "MarkdownView and TextEdit render the same computed styles" true by construction
+ * rather than by review.
+ *
+ * It also settles a cascade trap the two-grammar version would have re-created: `[&_h1]:mt-6`
+ * compiles at specificity (0,1,1) and a plain `.mt-6` on the element at (0,1,0), so an
+ * element-level class silently LOSES to a root-level descendant rule. The two forms cannot
+ * coexist on one tree; the root form is the one that works for both consumers.
+ *
+ * Every value is a literal so Tailwind's scanner sees it in this file — and in the shipped `dist`,
+ * which `preset.css` scans through `@source "./dist"` (the same contract `surfaceInteractive` and
+ * `fillInteractive` rely on).
+ *
+ * Logical properties throughout (`ms`/`ps`/`border-s`/`text-start`): prose is the surface most
+ * likely to carry translated content, and the contract lane asserts RTL containment.
+ *
+ * @example
+ * // A prose root — the whole recipe:
+ * <div className={cn(proseClassName, className)} />
+ *
+ * @example
+ * // One element's rules, composed into a narrower surface:
+ * <div className={cn(prose.root, prose.p, prose.code)} />
+ */
+declare const prose: {
+    /** The root's own ink and size — every rule below is relative to this. */
+    readonly root: "text-base text-foreground";
+    readonly h1: "[&_h1]:mt-6 [&_h1]:mb-3 [&_h1]:scroll-m-20 [&_h1]:text-h1 [&_h1]:text-foreground [&_h1]:first:mt-0";
+    readonly h2: "[&_h2]:mt-6 [&_h2]:mb-3 [&_h2]:scroll-m-20 [&_h2]:text-h2 [&_h2]:text-foreground [&_h2]:first:mt-0";
+    readonly h3: "[&_h3]:mt-5 [&_h3]:mb-2 [&_h3]:scroll-m-20 [&_h3]:text-h3 [&_h3]:text-foreground [&_h3]:first:mt-0";
+    readonly h4: "[&_h4]:mt-4 [&_h4]:mb-2 [&_h4]:scroll-m-20 [&_h4]:text-h4 [&_h4]:text-foreground [&_h4]:first:mt-0";
+    readonly h5: "[&_h5]:mt-4 [&_h5]:mb-2 [&_h5]:text-label [&_h5]:text-foreground [&_h5]:first:mt-0";
+    readonly h6: "[&_h6]:mt-4 [&_h6]:mb-2 [&_h6]:text-label [&_h6]:text-muted-foreground [&_h6]:first:mt-0";
+    readonly p: "[&_p]:my-3 [&_p]:leading-relaxed [&_p]:text-foreground [&_p]:first:mt-0 [&_p]:last:mb-0";
+    readonly a: "[&_a]:font-medium [&_a]:text-info-text [&_a]:underline [&_a]:underline-offset-4 [&_a]:hover:text-info-text/(--alpha-link-hover)";
+    readonly strong: "[&_strong]:font-medium [&_strong]:text-foreground";
+    readonly em: "[&_em]:italic";
+    readonly del: "[&_del]:text-muted-foreground [&_del]:line-through [&_s]:text-muted-foreground [&_s]:line-through";
+    readonly ul: "[&_ul]:my-3 [&_ul]:ms-6 [&_ul]:list-disc [&_ul]:text-foreground [&_ul]:marker:text-muted-foreground [&_ul.contains-task-list]:list-none";
+    readonly ol: "[&_ol]:my-3 [&_ol]:ms-6 [&_ol]:list-decimal [&_ol]:text-foreground [&_ol]:marker:text-muted-foreground";
+    readonly li: "[&_li]:mt-1.5 [&_li]:leading-relaxed";
+    readonly blockquote: "[&_blockquote]:my-3 [&_blockquote]:border-s-2 [&_blockquote]:border-border [&_blockquote]:ps-4 [&_blockquote]:text-muted-foreground [&_blockquote]:italic";
+    readonly code: "[&_code]:rounded-sm [&_code]:bg-muted [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-base [&_code]:text-foreground";
+    readonly pre: "[&_pre:not([data-slot='code-block-pre'])]:my-3 [&_pre:not([data-slot='code-block-pre'])]:overflow-x-auto [&_pre:not([data-slot='code-block-pre'])]:rounded-lg [&_pre:not([data-slot='code-block-pre'])]:border [&_pre:not([data-slot='code-block-pre'])]:border-border [&_pre:not([data-slot='code-block-pre'])]:bg-muted [&_pre:not([data-slot='code-block-pre'])]:p-4 [&_pre:not([data-slot='code-block-pre'])]:text-foreground";
+    readonly preCode: "[&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_pre_code]:font-mono [&_pre_code]:text-code [&_pre_code]:text-foreground";
+    readonly hr: "[&_hr]:my-6 [&_hr]:border-border";
+    readonly table: "[&_table]:w-full [&_table]:border-collapse [&_table]:text-base [&_table]:text-foreground [&_thead]:border-b [&_thead]:border-border [&_tr]:border-b [&_tr]:border-border [&_tr]:last:border-0 [&_th]:px-3 [&_th]:py-2 [&_th]:text-start [&_th]:font-medium [&_th]:text-foreground [&_td]:px-3 [&_td]:py-2 [&_td]:text-muted-foreground";
+    readonly img: "[&_img]:my-3 [&_img]:max-w-full [&_img]:rounded-lg [&_img]:border [&_img]:border-border";
+};
+/** The element roles the prose recipe covers. */
+type ProseElement = keyof typeof prose;
+/**
+ * The whole recipe as one class string — what a prose root wears.
+ *
+ * Joined rather than merged: every entry scopes a different selector, so there is no conflict for
+ * `cn` to resolve, and a plain join keeps the composition free of a `tailwind-merge` pass on a
+ * string that never changes.
+ */
+declare const proseClassName: string;
 
 /**
  * Merges Tailwind CSS class names with intelligent conflict resolution.
@@ -16,6 +90,160 @@ export { ClassValue } from 'clsx';
  */
 declare function cn(...inputs: ClassValue[]): string;
 
+/**
+ * THE hover/pressed recipe for a control that sits on a KNOWN surface (page, card, popover, well):
+ * hover climbs one rung of the surface ladder, pressing climbs one more. Rows, menu items, ghost and
+ * outline buttons, sidebar buttons, toggles, tabs, table rows, pagination — every transparent
+ * control — spread this string instead of writing a `hover:bg-*` literal.
+ *
+ * `hover:` compiles under `@media (hover: hover)` in Tailwind v4, so touch devices keep the rest
+ * fill and still get the pressed rung through `active:`. A selected/current state is the SAME rung
+ * as pressed (`data-selected:bg-surface-3`), which is why the two are never far apart.
+ *
+ * @example
+ * <button className={cn("rounded-md px-2", surfaceInteractive)} />
+ */
+declare const surfaceInteractive = "hover:bg-surface-2 active:bg-surface-3";
+/**
+ * The GROUP-SCOPED twin of {@link surfaceInteractive}, for the one geometry where the two rungs
+ * cannot live on the interactive element itself: a wash painted by an INNER chip inset from a
+ * container hairline (`design.md` §Hover geometry — "a wash is inset ≥4px from a container hairline
+ * and inherits its inner radius"). NumberField's steppers are the case: the button is full-height and
+ * flush to the field's border, so its own background would run into that hairline; a `size-full` chip
+ * inside the button's `p-1` paints the inset wash instead, and it must react to the BUTTON's hover.
+ *
+ * The group is named `wash` rather than left unnamed so a consumer's own `group` on an ancestor of a
+ * copied-in component cannot fire it. Put `group/wash` on the interactive element, this string on the
+ * chip. Everything else spreads {@link surfaceInteractive} directly — a group indirection where the
+ * element can carry the rungs itself is noise.
+ *
+ * @example
+ * <button className="group/wash p-1">
+ *   <span className={cn("size-full rounded-sm", surfaceInteractiveGroup)} />
+ * </button>
+ */
+declare const surfaceInteractiveGroup = "group-hover/wash:bg-surface-2 group-active/wash:bg-surface-3";
+/**
+ * The inks a translucent hover/pressed wash can be composited from — the neutral ink and the five
+ * chromatic families the Button matrix and its outline/soft variants use.
+ */
+type FillTone = "foreground" | "primary" | "destructive" | "success" | "warning" | "info" | "brand";
+/**
+ * The ALPHA twin of {@link surfaceInteractive}: the same two rungs composited from an ink at
+ * `--alpha-hover` / `--alpha-pressed`, for a control whose backdrop is not a ladder surface (a kbd
+ * inside a hovered row, a chip on a well, chrome over media) or one that hovers in its OWN hue (the
+ * outline/soft status buttons). `foreground` is the neutral twin, and it is anchored to a DIFFERENT
+ * host per theme: in light it lands within 0.003 L of `surface-2`/`surface-3` over the page
+ * (measured L 0.9430 vs 0.945 and 0.9210 vs 0.922), but the dark ladder is CARD-anchored — over the
+ * dark `card` it is within 0.003 (0.2665 vs 0.269, 0.2918 vs 0.290), while over the dark
+ * `background` it is Δ0.028 / Δ0.023, a full rung off (measured 2026-09-09, LOW-7). Read that as
+ * the constraint it is: the alpha twin substitutes for the opaque rung on the surface a control of
+ * that theme actually sits on. It is AA-gated over page, card and popover in both themes.
+ *
+ * Solid fills do NOT use this: a solid already owns its darker `<tone>-hover` / `<tone>-active`
+ * steps (`bg-primary hover:bg-primary-hover active:bg-primary-active`) — an alpha over a solid
+ * would only thin it.
+ *
+ * Every value is a literal so Tailwind's scanner sees it in this file (and in the shipped `dist`,
+ * which `preset.css` scans).
+ *
+ * @example
+ * <button className={cn("bg-destructive-subtle text-destructive-text", fillInteractive.destructive)} />
+ */
+declare const fillInteractive: Record<FillTone, string>;
+/**
+ * THE field chrome — the one border/fill/hover/focus/invalid/disabled grammar every text-entry
+ * control wears (audit B1-11, 2026-09-07). Input, Textarea, NumberField's input, OTP slots, the
+ * Select trigger and the Combobox input all spread this string; before it existed the same nine
+ * declarations were copy-pasted in four files and restated a fifth time as slot overrides, so
+ * retuning the field meant finding every copy.
+ *
+ * It is CHROME only — no width, padding, height or type. Those differ per control (a square OTP
+ * slot is not `w-full`; a Textarea sizes by min-height, not `--size-*`), so each component adds its
+ * own layout and size classes after this string.
+ *
+ * The three border rungs, in ascending weight:
+ * - rest `border-input` (the derived `foreground` alpha hairline),
+ * - hover `foreground` at `--alpha-border-subtle` — neutral ink, one step darker, guarded by
+ *   `not-disabled:not-data-disabled:` because D7 keeps pointer events ON a disabled control so a
+ *   Tooltip can explain it, which would otherwise let a dead field light up under the cursor,
+ * - focus `ring` at `--alpha-tint-border`, on plain `focus` (not `focus-visible`) — a raw text field
+ *   cannot tell mouse from keyboard, so the tint is the one cue for both. Forced colours erase a
+ *   border tint outright, so the outline fallback for that case is written ONCE, unlayered, in
+ *   `@vegastack/design-tokens`' `base.css` — never per component.
+ *
+ * **FOCUS OUTRANKS INVALID, and it has to be said in the selector** (#100, 2026-09-09). The invalid
+ * tint and the focus tint are the same property at the same specificity, and Tailwind v4 emits
+ * `aria-invalid:`/`data-invalid:` AFTER `focus:`, so an invalid field simply kept its destructive
+ * border when focused. Text entry carries `outline-hidden`, so that border IS the whole affordance:
+ * a focused invalid field had NO focus indicator at all, which is a WCAG 2.2 §2.4.7 failure the
+ * geometry lane's focus assertion found on its first run. `not-focus:` makes the invalid tint stand
+ * down while the field is focused rather than fighting the cascade — the error is still carried by
+ * `aria-invalid`, by Field's message and icon, and by the tint returning on blur, whereas focus has
+ * exactly one channel. design.md § Accessibility ("focus is the neutral `ring`, never a colour")
+ * settles which one owns the border when both want it.
+ *
+ * @example
+ * <input className={cn(fieldControl, "h-(--size-md) w-full min-w-0 px-3 text-base")} />
+ */
+declare const fieldControl: string;
+/**
+ * The WRAPPER twin of {@link fieldControl}: the identical chrome on a bordered group whose state
+ * comes from a descendant — Input's prefix/suffix group, NumberField's stepper group, ChipInput and
+ * the Combobox input-group. Same three border rungs, read through `focus-within` / `has-*` /
+ * Base UI's `data-focused` instead of the control's own pseudo-classes.
+ *
+ * Every element carrying this string must also carry `data-field-group` (a bare attribute). That is
+ * the hook `base.css` uses to paint the forced-colours focus outline on the GROUP: the inner input's
+ * own outline would be clipped by the group's `overflow-hidden`, which is exactly how a High
+ * Contrast user lost the caret location on an addon field.
+ *
+ * @example
+ * <div data-field-group className={cn(fieldControlGroup, "flex h-(--size-md) items-center")} />
+ */
+declare const fieldControlGroup: string;
+/**
+ * THE selected-chip recipe — one formula for every "raised chip on a muted track" control:
+ * Tabs `pill` and `chip`, `Segmented`, `Toggle` pressed and `ToggleGroup` pressed. Before this
+ * existed the four wrote four different selected looks (`bg-background`, `bg-secondary` + hairline,
+ * `bg-foreground/10`); audit 2026-09-07 B6-02.
+ *
+ * The track is the ladder's well rung (`surface-1`); the chip is the ladder's alpha form of the
+ * pressed/selected step (§Surfaces) — `bg-foreground/(--alpha-ink-tint)`, which doctrine reaches
+ * for exactly here ("a chip on a well"). Over the `surface-1` track it composites to L 0.899 light
+ * / 0.318 dark, which is Δ0.023 / Δ0.028 PAST `surface-3` — a full extra rung, since the ladder's
+ * own step is 0.021–0.033 (measured 2026-09-09, LOW-6; the doc used to claim "within a hair of
+ * `surface-3`", which is only true of the twin composited over the PAGE, not over the track).
+ * That extra rung is deliberate and is what makes a selected chip read as raised off its own
+ * track rather than level with it. Being an alpha is also what lets the SELECTED chip keep stepping: a hovered
+ * selected chip strengthens to `--alpha-ink-tint-strong` and a pressed one drops back to the resting
+ * tint (previewing the release), so no state ever reads as dead — an opaque `surface-3` chip would
+ * have nowhere left to climb.
+ *
+ * Base UI spells "selected" differently per primitive, so the state rules ship as two literal
+ * strings rather than a selector parameter (Tailwind v4's scanner only sees literals):
+ * {@link selectedChipVariants.pressed} for Toggle/ToggleGroup/Segmented (`data-pressed`) and
+ * {@link selectedChipVariants.active} for Tabs (`data-active`). The unselected steps are guarded by
+ * the matching `not-*` variant so the two sets are mutually exclusive and never race on specificity.
+ *
+ * @example
+ * <div className={cn("rounded-md p-0.5", selectedChipVariants.track)}>
+ *   <Toggle className={cn("rounded-sm", selectedChipVariants.item, selectedChipVariants.pressed)} />
+ * </div>
+ */
+declare const selectedChipVariants: {
+    /** The muted track the chips sit in — the ladder's well rung. */
+    readonly track: "bg-surface-1";
+    /**
+     * Chrome shared by every chip: a transparent hairline reserved at rest (so selecting adds no
+     * layout shift) and the muted→ink text step.
+     */
+    readonly item: "border border-transparent hover:text-foreground";
+    /** Selected keyed on Base UI's `data-pressed` — Toggle, ToggleGroup, Segmented. */
+    readonly pressed: "not-data-pressed:hover:bg-foreground/(--alpha-hover) not-data-pressed:active:bg-foreground/(--alpha-pressed) data-pressed:border-border data-pressed:bg-foreground/(--alpha-ink-tint) data-pressed:text-foreground data-pressed:hover:bg-foreground/(--alpha-ink-tint-strong) data-pressed:active:bg-foreground/(--alpha-ink-tint)";
+    /** Selected keyed on Base UI's `data-active` — Tabs. */
+    readonly active: "not-data-[active]:hover:bg-foreground/(--alpha-hover) not-data-[active]:active:bg-foreground/(--alpha-pressed) data-[active]:border-border data-[active]:bg-foreground/(--alpha-ink-tint) data-[active]:text-foreground data-[active]:hover:bg-foreground/(--alpha-ink-tint-strong) data-[active]:active:bg-foreground/(--alpha-ink-tint)";
+};
 /**
  * @internal Registry theme-scope plumbing lives at `@vegastack/design/theme-scope`, NOT here.
  * It calls `React.createContext()` at module scope, which is `undefined` under the `react-server`
@@ -37,6 +265,20 @@ declare const TIMINGS: {
     readonly hoverOpenDelayMs: 700;
     /** Hover delay before a rich preview closes — lets the pointer travel into the card. */
     readonly hoverCloseDelayMs: 300;
+    /**
+     * Hover delay before a tooltip opens. A tooltip is a cheap label, not a preview, so it is
+     * deliberately much faster than {@link TIMINGS.hoverOpenDelayMs} — long enough that sweeping
+     * across a toolbar does not flash five tips, short enough that a deliberate hover feels
+     * instant. Base UI's `Tooltip.Provider` grouping then opens adjacent tips with no delay at
+     * all. Set once, in the app-root provider.
+     */
+    readonly tooltipOpenDelayMs: 300;
+    /**
+     * Delay before a tooltip closes. Zero: a tooltip has nothing to travel into (it is not
+     * hoverable content, unlike a HoverCard), so holding it after the pointer leaves only
+     * obscures what the user moved on to.
+     */
+    readonly tooltipCloseDelayMs: 0;
 };
 /**
  * Floating-surface positioning constants (px) — the unified sideOffset/collisionPadding
@@ -53,4 +295,34 @@ declare const FLOATING: {
     readonly collisionPadding: 8;
 };
 
-export { FLOATING, TIMINGS, cn };
+/**
+ * Fan one DOM node out to several refs — a forwarded `ref` prop plus one or more internal
+ * refs — as a single ref callback. Skips `null`/`undefined` entries, so an optional
+ * forwarded ref needs no guard at the call site. Handles both ref shapes React 19 accepts:
+ * a callback ref is invoked, an object ref has its `.current` assigned.
+ *
+ * This lives in `@vegastack/design` rather than in any one component because ref-as-prop
+ * (React 19, no `forwardRef`) makes "the component needs the node AND has to forward it"
+ * the normal case, not a special one — it was hand-inlined in nine registry files and
+ * exported from `use-animation-replay` before this. It touches no React runtime value
+ * (only ref objects the caller already holds), so it is server-safe like `cn`.
+ *
+ * **Not memoized.** Calling it produces a NEW function every time, and React detaches a
+ * changed ref callback (calls it with `null`) and reattaches it on every render. Wrap the
+ * CALL at the call site when the inputs are stable:
+ *
+ * @example
+ * const mergedRef = React.useMemo(() => mergeRefs(ref, internalRef), [ref]);
+ * return <input ref={mergedRef} />;
+ *
+ * @example
+ * // A ref callback that also does work — merge it with the forwarded ref
+ * const setRef = React.useCallback(
+ *   (node: HTMLDivElement | null) => { setContainer(node); },
+ *   [],
+ * );
+ * const mergedRef = React.useMemo(() => mergeRefs(ref, setRef), [ref, setRef]);
+ */
+declare function mergeRefs<T>(...refs: Array<React.Ref<T> | null | undefined>): React.RefCallback<T>;
+
+export { FLOATING, type FillTone, type ProseElement, TIMINGS, cn, fieldControl, fieldControlGroup, fillInteractive, mergeRefs, prose, proseClassName, selectedChipVariants, surfaceInteractive, surfaceInteractiveGroup };

package/dist/index.d.ts

@@ -1,5 +1,79 @@
 import { ClassValue } from 'clsx';
 export { ClassValue } from 'clsx';
+import * as React from 'react';
+
+/**
+ * THE prose recipe — one token vocabulary for rendered rich text (audit B4-09, 2026-09-07).
+ *
+ * Two surfaces render prose the system did not author element-by-element: `MarkdownView`
+ * (react-markdown turns a markdown string into plain HTML elements) and `TextEdit` (ProseMirror
+ * owns the contenteditable DOM). Before this file each restated the same heading/paragraph/list/
+ * code/quote recipe in its own grammar — a `Components` map in one, 69 `[&_h1]:` rules in the
+ * other — and they had already drifted (`h4`–`h6`, `table`, `img` existed on one side only).
+ *
+ * ## Why descendant variants and not per-element classes
+ *
+ * A prose root cannot put a class on every element: ProseMirror generates the editor's DOM, and
+ * react-markdown's output is only reachable through an override map. Descendant variants
+ * (`[&_h1]:mt-6` → `.recipe h1 { margin-top: … }`) style both from ONE string on the root, which
+ * is what makes "MarkdownView and TextEdit render the same computed styles" true by construction
+ * rather than by review.
+ *
+ * It also settles a cascade trap the two-grammar version would have re-created: `[&_h1]:mt-6`
+ * compiles at specificity (0,1,1) and a plain `.mt-6` on the element at (0,1,0), so an
+ * element-level class silently LOSES to a root-level descendant rule. The two forms cannot
+ * coexist on one tree; the root form is the one that works for both consumers.
+ *
+ * Every value is a literal so Tailwind's scanner sees it in this file — and in the shipped `dist`,
+ * which `preset.css` scans through `@source "./dist"` (the same contract `surfaceInteractive` and
+ * `fillInteractive` rely on).
+ *
+ * Logical properties throughout (`ms`/`ps`/`border-s`/`text-start`): prose is the surface most
+ * likely to carry translated content, and the contract lane asserts RTL containment.
+ *
+ * @example
+ * // A prose root — the whole recipe:
+ * <div className={cn(proseClassName, className)} />
+ *
+ * @example
+ * // One element's rules, composed into a narrower surface:
+ * <div className={cn(prose.root, prose.p, prose.code)} />
+ */
+declare const prose: {
+    /** The root's own ink and size — every rule below is relative to this. */
+    readonly root: "text-base text-foreground";
+    readonly h1: "[&_h1]:mt-6 [&_h1]:mb-3 [&_h1]:scroll-m-20 [&_h1]:text-h1 [&_h1]:text-foreground [&_h1]:first:mt-0";
+    readonly h2: "[&_h2]:mt-6 [&_h2]:mb-3 [&_h2]:scroll-m-20 [&_h2]:text-h2 [&_h2]:text-foreground [&_h2]:first:mt-0";
+    readonly h3: "[&_h3]:mt-5 [&_h3]:mb-2 [&_h3]:scroll-m-20 [&_h3]:text-h3 [&_h3]:text-foreground [&_h3]:first:mt-0";
+    readonly h4: "[&_h4]:mt-4 [&_h4]:mb-2 [&_h4]:scroll-m-20 [&_h4]:text-h4 [&_h4]:text-foreground [&_h4]:first:mt-0";
+    readonly h5: "[&_h5]:mt-4 [&_h5]:mb-2 [&_h5]:text-label [&_h5]:text-foreground [&_h5]:first:mt-0";
+    readonly h6: "[&_h6]:mt-4 [&_h6]:mb-2 [&_h6]:text-label [&_h6]:text-muted-foreground [&_h6]:first:mt-0";
+    readonly p: "[&_p]:my-3 [&_p]:leading-relaxed [&_p]:text-foreground [&_p]:first:mt-0 [&_p]:last:mb-0";
+    readonly a: "[&_a]:font-medium [&_a]:text-info-text [&_a]:underline [&_a]:underline-offset-4 [&_a]:hover:text-info-text/(--alpha-link-hover)";
+    readonly strong: "[&_strong]:font-medium [&_strong]:text-foreground";
+    readonly em: "[&_em]:italic";
+    readonly del: "[&_del]:text-muted-foreground [&_del]:line-through [&_s]:text-muted-foreground [&_s]:line-through";
+    readonly ul: "[&_ul]:my-3 [&_ul]:ms-6 [&_ul]:list-disc [&_ul]:text-foreground [&_ul]:marker:text-muted-foreground [&_ul.contains-task-list]:list-none";
+    readonly ol: "[&_ol]:my-3 [&_ol]:ms-6 [&_ol]:list-decimal [&_ol]:text-foreground [&_ol]:marker:text-muted-foreground";
+    readonly li: "[&_li]:mt-1.5 [&_li]:leading-relaxed";
+    readonly blockquote: "[&_blockquote]:my-3 [&_blockquote]:border-s-2 [&_blockquote]:border-border [&_blockquote]:ps-4 [&_blockquote]:text-muted-foreground [&_blockquote]:italic";
+    readonly code: "[&_code]:rounded-sm [&_code]:bg-muted [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-base [&_code]:text-foreground";
+    readonly pre: "[&_pre:not([data-slot='code-block-pre'])]:my-3 [&_pre:not([data-slot='code-block-pre'])]:overflow-x-auto [&_pre:not([data-slot='code-block-pre'])]:rounded-lg [&_pre:not([data-slot='code-block-pre'])]:border [&_pre:not([data-slot='code-block-pre'])]:border-border [&_pre:not([data-slot='code-block-pre'])]:bg-muted [&_pre:not([data-slot='code-block-pre'])]:p-4 [&_pre:not([data-slot='code-block-pre'])]:text-foreground";
+    readonly preCode: "[&_pre_code]:bg-transparent [&_pre_code]:p-0 [&_pre_code]:font-mono [&_pre_code]:text-code [&_pre_code]:text-foreground";
+    readonly hr: "[&_hr]:my-6 [&_hr]:border-border";
+    readonly table: "[&_table]:w-full [&_table]:border-collapse [&_table]:text-base [&_table]:text-foreground [&_thead]:border-b [&_thead]:border-border [&_tr]:border-b [&_tr]:border-border [&_tr]:last:border-0 [&_th]:px-3 [&_th]:py-2 [&_th]:text-start [&_th]:font-medium [&_th]:text-foreground [&_td]:px-3 [&_td]:py-2 [&_td]:text-muted-foreground";
+    readonly img: "[&_img]:my-3 [&_img]:max-w-full [&_img]:rounded-lg [&_img]:border [&_img]:border-border";
+};
+/** The element roles the prose recipe covers. */
+type ProseElement = keyof typeof prose;
+/**
+ * The whole recipe as one class string — what a prose root wears.
+ *
+ * Joined rather than merged: every entry scopes a different selector, so there is no conflict for
+ * `cn` to resolve, and a plain join keeps the composition free of a `tailwind-merge` pass on a
+ * string that never changes.
+ */
+declare const proseClassName: string;
 
 /**
  * Merges Tailwind CSS class names with intelligent conflict resolution.
@@ -16,6 +90,160 @@ export { ClassValue } from 'clsx';
  */
 declare function cn(...inputs: ClassValue[]): string;
 
+/**
+ * THE hover/pressed recipe for a control that sits on a KNOWN surface (page, card, popover, well):
+ * hover climbs one rung of the surface ladder, pressing climbs one more. Rows, menu items, ghost and
+ * outline buttons, sidebar buttons, toggles, tabs, table rows, pagination — every transparent
+ * control — spread this string instead of writing a `hover:bg-*` literal.
+ *
+ * `hover:` compiles under `@media (hover: hover)` in Tailwind v4, so touch devices keep the rest
+ * fill and still get the pressed rung through `active:`. A selected/current state is the SAME rung
+ * as pressed (`data-selected:bg-surface-3`), which is why the two are never far apart.
+ *
+ * @example
+ * <button className={cn("rounded-md px-2", surfaceInteractive)} />
+ */
+declare const surfaceInteractive = "hover:bg-surface-2 active:bg-surface-3";
+/**
+ * The GROUP-SCOPED twin of {@link surfaceInteractive}, for the one geometry where the two rungs
+ * cannot live on the interactive element itself: a wash painted by an INNER chip inset from a
+ * container hairline (`design.md` §Hover geometry — "a wash is inset ≥4px from a container hairline
+ * and inherits its inner radius"). NumberField's steppers are the case: the button is full-height and
+ * flush to the field's border, so its own background would run into that hairline; a `size-full` chip
+ * inside the button's `p-1` paints the inset wash instead, and it must react to the BUTTON's hover.
+ *
+ * The group is named `wash` rather than left unnamed so a consumer's own `group` on an ancestor of a
+ * copied-in component cannot fire it. Put `group/wash` on the interactive element, this string on the
+ * chip. Everything else spreads {@link surfaceInteractive} directly — a group indirection where the
+ * element can carry the rungs itself is noise.
+ *
+ * @example
+ * <button className="group/wash p-1">
+ *   <span className={cn("size-full rounded-sm", surfaceInteractiveGroup)} />
+ * </button>
+ */
+declare const surfaceInteractiveGroup = "group-hover/wash:bg-surface-2 group-active/wash:bg-surface-3";
+/**
+ * The inks a translucent hover/pressed wash can be composited from — the neutral ink and the five
+ * chromatic families the Button matrix and its outline/soft variants use.
+ */
+type FillTone = "foreground" | "primary" | "destructive" | "success" | "warning" | "info" | "brand";
+/**
+ * The ALPHA twin of {@link surfaceInteractive}: the same two rungs composited from an ink at
+ * `--alpha-hover` / `--alpha-pressed`, for a control whose backdrop is not a ladder surface (a kbd
+ * inside a hovered row, a chip on a well, chrome over media) or one that hovers in its OWN hue (the
+ * outline/soft status buttons). `foreground` is the neutral twin, and it is anchored to a DIFFERENT
+ * host per theme: in light it lands within 0.003 L of `surface-2`/`surface-3` over the page
+ * (measured L 0.9430 vs 0.945 and 0.9210 vs 0.922), but the dark ladder is CARD-anchored — over the
+ * dark `card` it is within 0.003 (0.2665 vs 0.269, 0.2918 vs 0.290), while over the dark
+ * `background` it is Δ0.028 / Δ0.023, a full rung off (measured 2026-09-09, LOW-7). Read that as
+ * the constraint it is: the alpha twin substitutes for the opaque rung on the surface a control of
+ * that theme actually sits on. It is AA-gated over page, card and popover in both themes.
+ *
+ * Solid fills do NOT use this: a solid already owns its darker `<tone>-hover` / `<tone>-active`
+ * steps (`bg-primary hover:bg-primary-hover active:bg-primary-active`) — an alpha over a solid
+ * would only thin it.
+ *
+ * Every value is a literal so Tailwind's scanner sees it in this file (and in the shipped `dist`,
+ * which `preset.css` scans).
+ *
+ * @example
+ * <button className={cn("bg-destructive-subtle text-destructive-text", fillInteractive.destructive)} />
+ */
+declare const fillInteractive: Record<FillTone, string>;
+/**
+ * THE field chrome — the one border/fill/hover/focus/invalid/disabled grammar every text-entry
+ * control wears (audit B1-11, 2026-09-07). Input, Textarea, NumberField's input, OTP slots, the
+ * Select trigger and the Combobox input all spread this string; before it existed the same nine
+ * declarations were copy-pasted in four files and restated a fifth time as slot overrides, so
+ * retuning the field meant finding every copy.
+ *
+ * It is CHROME only — no width, padding, height or type. Those differ per control (a square OTP
+ * slot is not `w-full`; a Textarea sizes by min-height, not `--size-*`), so each component adds its
+ * own layout and size classes after this string.
+ *
+ * The three border rungs, in ascending weight:
+ * - rest `border-input` (the derived `foreground` alpha hairline),
+ * - hover `foreground` at `--alpha-border-subtle` — neutral ink, one step darker, guarded by
+ *   `not-disabled:not-data-disabled:` because D7 keeps pointer events ON a disabled control so a
+ *   Tooltip can explain it, which would otherwise let a dead field light up under the cursor,
+ * - focus `ring` at `--alpha-tint-border`, on plain `focus` (not `focus-visible`) — a raw text field
+ *   cannot tell mouse from keyboard, so the tint is the one cue for both. Forced colours erase a
+ *   border tint outright, so the outline fallback for that case is written ONCE, unlayered, in
+ *   `@vegastack/design-tokens`' `base.css` — never per component.
+ *
+ * **FOCUS OUTRANKS INVALID, and it has to be said in the selector** (#100, 2026-09-09). The invalid
+ * tint and the focus tint are the same property at the same specificity, and Tailwind v4 emits
+ * `aria-invalid:`/`data-invalid:` AFTER `focus:`, so an invalid field simply kept its destructive
+ * border when focused. Text entry carries `outline-hidden`, so that border IS the whole affordance:
+ * a focused invalid field had NO focus indicator at all, which is a WCAG 2.2 §2.4.7 failure the
+ * geometry lane's focus assertion found on its first run. `not-focus:` makes the invalid tint stand
+ * down while the field is focused rather than fighting the cascade — the error is still carried by
+ * `aria-invalid`, by Field's message and icon, and by the tint returning on blur, whereas focus has
+ * exactly one channel. design.md § Accessibility ("focus is the neutral `ring`, never a colour")
+ * settles which one owns the border when both want it.
+ *
+ * @example
+ * <input className={cn(fieldControl, "h-(--size-md) w-full min-w-0 px-3 text-base")} />
+ */
+declare const fieldControl: string;
+/**
+ * The WRAPPER twin of {@link fieldControl}: the identical chrome on a bordered group whose state
+ * comes from a descendant — Input's prefix/suffix group, NumberField's stepper group, ChipInput and
+ * the Combobox input-group. Same three border rungs, read through `focus-within` / `has-*` /
+ * Base UI's `data-focused` instead of the control's own pseudo-classes.
+ *
+ * Every element carrying this string must also carry `data-field-group` (a bare attribute). That is
+ * the hook `base.css` uses to paint the forced-colours focus outline on the GROUP: the inner input's
+ * own outline would be clipped by the group's `overflow-hidden`, which is exactly how a High
+ * Contrast user lost the caret location on an addon field.
+ *
+ * @example
+ * <div data-field-group className={cn(fieldControlGroup, "flex h-(--size-md) items-center")} />
+ */
+declare const fieldControlGroup: string;
+/**
+ * THE selected-chip recipe — one formula for every "raised chip on a muted track" control:
+ * Tabs `pill` and `chip`, `Segmented`, `Toggle` pressed and `ToggleGroup` pressed. Before this
+ * existed the four wrote four different selected looks (`bg-background`, `bg-secondary` + hairline,
+ * `bg-foreground/10`); audit 2026-09-07 B6-02.
+ *
+ * The track is the ladder's well rung (`surface-1`); the chip is the ladder's alpha form of the
+ * pressed/selected step (§Surfaces) — `bg-foreground/(--alpha-ink-tint)`, which doctrine reaches
+ * for exactly here ("a chip on a well"). Over the `surface-1` track it composites to L 0.899 light
+ * / 0.318 dark, which is Δ0.023 / Δ0.028 PAST `surface-3` — a full extra rung, since the ladder's
+ * own step is 0.021–0.033 (measured 2026-09-09, LOW-6; the doc used to claim "within a hair of
+ * `surface-3`", which is only true of the twin composited over the PAGE, not over the track).
+ * That extra rung is deliberate and is what makes a selected chip read as raised off its own
+ * track rather than level with it. Being an alpha is also what lets the SELECTED chip keep stepping: a hovered
+ * selected chip strengthens to `--alpha-ink-tint-strong` and a pressed one drops back to the resting
+ * tint (previewing the release), so no state ever reads as dead — an opaque `surface-3` chip would
+ * have nowhere left to climb.
+ *
+ * Base UI spells "selected" differently per primitive, so the state rules ship as two literal
+ * strings rather than a selector parameter (Tailwind v4's scanner only sees literals):
+ * {@link selectedChipVariants.pressed} for Toggle/ToggleGroup/Segmented (`data-pressed`) and
+ * {@link selectedChipVariants.active} for Tabs (`data-active`). The unselected steps are guarded by
+ * the matching `not-*` variant so the two sets are mutually exclusive and never race on specificity.
+ *
+ * @example
+ * <div className={cn("rounded-md p-0.5", selectedChipVariants.track)}>
+ *   <Toggle className={cn("rounded-sm", selectedChipVariants.item, selectedChipVariants.pressed)} />
+ * </div>
+ */
+declare const selectedChipVariants: {
+    /** The muted track the chips sit in — the ladder's well rung. */
+    readonly track: "bg-surface-1";
+    /**
+     * Chrome shared by every chip: a transparent hairline reserved at rest (so selecting adds no
+     * layout shift) and the muted→ink text step.
+     */
+    readonly item: "border border-transparent hover:text-foreground";
+    /** Selected keyed on Base UI's `data-pressed` — Toggle, ToggleGroup, Segmented. */
+    readonly pressed: "not-data-pressed:hover:bg-foreground/(--alpha-hover) not-data-pressed:active:bg-foreground/(--alpha-pressed) data-pressed:border-border data-pressed:bg-foreground/(--alpha-ink-tint) data-pressed:text-foreground data-pressed:hover:bg-foreground/(--alpha-ink-tint-strong) data-pressed:active:bg-foreground/(--alpha-ink-tint)";
+    /** Selected keyed on Base UI's `data-active` — Tabs. */
+    readonly active: "not-data-[active]:hover:bg-foreground/(--alpha-hover) not-data-[active]:active:bg-foreground/(--alpha-pressed) data-[active]:border-border data-[active]:bg-foreground/(--alpha-ink-tint) data-[active]:text-foreground data-[active]:hover:bg-foreground/(--alpha-ink-tint-strong) data-[active]:active:bg-foreground/(--alpha-ink-tint)";
+};
 /**
  * @internal Registry theme-scope plumbing lives at `@vegastack/design/theme-scope`, NOT here.
  * It calls `React.createContext()` at module scope, which is `undefined` under the `react-server`
@@ -37,6 +265,20 @@ declare const TIMINGS: {
     readonly hoverOpenDelayMs: 700;
     /** Hover delay before a rich preview closes — lets the pointer travel into the card. */
     readonly hoverCloseDelayMs: 300;
+    /**
+     * Hover delay before a tooltip opens. A tooltip is a cheap label, not a preview, so it is
+     * deliberately much faster than {@link TIMINGS.hoverOpenDelayMs} — long enough that sweeping
+     * across a toolbar does not flash five tips, short enough that a deliberate hover feels
+     * instant. Base UI's `Tooltip.Provider` grouping then opens adjacent tips with no delay at
+     * all. Set once, in the app-root provider.
+     */
+    readonly tooltipOpenDelayMs: 300;
+    /**
+     * Delay before a tooltip closes. Zero: a tooltip has nothing to travel into (it is not
+     * hoverable content, unlike a HoverCard), so holding it after the pointer leaves only
+     * obscures what the user moved on to.
+     */
+    readonly tooltipCloseDelayMs: 0;
 };
 /**
  * Floating-surface positioning constants (px) — the unified sideOffset/collisionPadding
@@ -53,4 +295,34 @@ declare const FLOATING: {
     readonly collisionPadding: 8;
 };
 
-export { FLOATING, TIMINGS, cn };
+/**
+ * Fan one DOM node out to several refs — a forwarded `ref` prop plus one or more internal
+ * refs — as a single ref callback. Skips `null`/`undefined` entries, so an optional
+ * forwarded ref needs no guard at the call site. Handles both ref shapes React 19 accepts:
+ * a callback ref is invoked, an object ref has its `.current` assigned.
+ *
+ * This lives in `@vegastack/design` rather than in any one component because ref-as-prop
+ * (React 19, no `forwardRef`) makes "the component needs the node AND has to forward it"
+ * the normal case, not a special one — it was hand-inlined in nine registry files and
+ * exported from `use-animation-replay` before this. It touches no React runtime value
+ * (only ref objects the caller already holds), so it is server-safe like `cn`.
+ *
+ * **Not memoized.** Calling it produces a NEW function every time, and React detaches a
+ * changed ref callback (calls it with `null`) and reattaches it on every render. Wrap the
+ * CALL at the call site when the inputs are stable:
+ *
+ * @example
+ * const mergedRef = React.useMemo(() => mergeRefs(ref, internalRef), [ref]);
+ * return <input ref={mergedRef} />;
+ *
+ * @example
+ * // A ref callback that also does work — merge it with the forwarded ref
+ * const setRef = React.useCallback(
+ *   (node: HTMLDivElement | null) => { setContainer(node); },
+ *   [],
+ * );
+ * const mergedRef = React.useMemo(() => mergeRefs(ref, setRef), [ref, setRef]);
+ */
+declare function mergeRefs<T>(...refs: Array<React.Ref<T> | null | undefined>): React.RefCallback<T>;
+
+export { FLOATING, type FillTone, type ProseElement, TIMINGS, cn, fieldControl, fieldControlGroup, fillInteractive, mergeRefs, prose, proseClassName, selectedChipVariants, surfaceInteractive, surfaceInteractiveGroup };

package/dist/index.js

@@ -1,10 +1,28 @@
 import {
   FLOATING,
   TIMINGS,
-  cn
-} from "./chunk-FBU37ITM.js";
+  cn,
+  fieldControl,
+  fieldControlGroup,
+  fillInteractive,
+  mergeRefs,
+  prose,
+  proseClassName,
+  selectedChipVariants,
+  surfaceInteractive,
+  surfaceInteractiveGroup
+} from "./chunk-LRQSVCP6.js";
 export {
   FLOATING,
   TIMINGS,
-  cn
+  cn,
+  fieldControl,
+  fieldControlGroup,
+  fillInteractive,
+  mergeRefs,
+  prose,
+  proseClassName,
+  selectedChipVariants,
+  surfaceInteractive,
+  surfaceInteractiveGroup
 };