@instruments/materia-ui 0.1.0

package/dist/styles/theme.css

@@ -0,0 +1,26 @@
+/**
+ * Granular `@source`-only entry (`@instruments/materia-ui/styles/theme.css`).
+ *
+ * Most consumers do NOT need this file - the canonical external entry is the
+ * self-contained `@instruments/materia-ui/styles` (index.css), which bundles the
+ * design tokens, `@theme`, `@layer` rules, the responsive safelist, AND this
+ * same component `@source` scanning:
+ *
+ *   @import "tailwindcss";
+ *   @import "@instruments/materia-ui/styles"; // tokens + theme + component scanning
+ *
+ * This file exposes ONLY the `@source` directives (no tokens/theme), for the
+ * rare consumer who supplies their own theme layer but still needs Tailwind v4
+ * to scan the package's compiled components (v4 excludes node_modules, so
+ * without an explicit `@source` every `bg-primary`, `glass-scrim`, … tree-shakes
+ * to nothing and components render unstyled). The paths resolve relative to THIS
+ * file; in the published package it lives at `dist/styles/theme.css` and scans
+ * the compiled `dist/components`, … where the class-string literals are
+ * preserved. In-monorepo the shim already scans `../ui/src`, so this is a no-op
+ * for workspace apps and exists purely for external consumers.
+ */
+@source "../components";
+@source "../compositions";
+@source "../tokens";
+@source "../hooks";
+@source "../utils";

package/dist/tokens/alignment.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Flexbox cross-axis alignment types.
+ * Used by `Flex`, `Stack`, `HStack`, `VStack`, and `Grid` via the `align` prop.
+ */
+export type FlexAlign = "stretch" | "flex-start" | "flex-end" | "center" | "baseline";
+/**
+ * Inline-axis text alignment. Logical values, so `"end"` flips under RTL.
+ * Used by `DescriptionDetails` via the `align` prop.
+ */
+export type TextAlign = "start" | "center" | "end";
+/** Class per {@link TextAlign}. */
+export declare const TEXT_ALIGN_CLASS: Record<TextAlign, string>;

package/dist/tokens/alignment.js

@@ -0,0 +1,6 @@
+/** Class per {@link TextAlign}. */
+export const TEXT_ALIGN_CLASS = {
+    center: "text-center",
+    end: "text-end",
+    start: "text-start",
+};

package/dist/tokens/anatomy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Component anatomy type for documenting compound component structure.
+ * Used to generate hierarchical documentation in Storybook.
+ */
+export interface ComponentAnatomy {
+    /** Nested child components */
+    children?: ComponentAnatomy[];
+    /** Optional description of this part's purpose */
+    description?: string;
+    /** Display name for this component part */
+    label: string;
+    /** The data-slot value for this component part */
+    slot: string;
+}
+/**
+ * Helper function to define component anatomy with type safety.
+ *
+ * @example
+ * ```ts
+ * export const cardAnatomy = defineAnatomy({
+ *   slot: "card",
+ *   label: "Card",
+ *   children: [
+ *     { slot: "card-header", label: "CardHeader" },
+ *     { slot: "card-content", label: "CardContent" },
+ *   ],
+ * });
+ * ```
+ */
+export declare const defineAnatomy: (anatomy: ComponentAnatomy) => ComponentAnatomy;

package/dist/tokens/anatomy.js

@@ -0,0 +1,16 @@
+/**
+ * Helper function to define component anatomy with type safety.
+ *
+ * @example
+ * ```ts
+ * export const cardAnatomy = defineAnatomy({
+ *   slot: "card",
+ *   label: "Card",
+ *   children: [
+ *     { slot: "card-header", label: "CardHeader" },
+ *     { slot: "card-content", label: "CardContent" },
+ *   ],
+ * });
+ * ```
+ */
+export const defineAnatomy = (anatomy) => anatomy;

package/dist/tokens/border.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared border style vocabulary. Used by container-like components (Card,
+ * DataGrid) that expose a `border` prop with the same three options.
+ */
+export type BorderStyle = "none" | "solid" | "dashed";
+/**
+ * Resolves a `BorderStyle` to its Tailwind class string.
+ */
+export declare const borderStyleClasses: (border: BorderStyle) => string;

package/dist/tokens/border.js

@@ -0,0 +1,12 @@
+/**
+ * Resolves a `BorderStyle` to its Tailwind class string.
+ */
+export const borderStyleClasses = (border) => {
+    if (border === "none") {
+        return "border-0";
+    }
+    if (border === "dashed") {
+        return "border border-dashed border-muted-foreground/25";
+    }
+    return "border border-border";
+};

package/dist/tokens/breakpoint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tailwind v4 breakpoint pixel values.
+ * Includes extended breakpoints for small mobile (2xs) and ultrawide (3xl).
+ */
+export declare const BREAKPOINT_VALUES: {
+    readonly "2xl": 1536;
+    readonly "2xs": 320;
+    readonly "3xl": 1920;
+    readonly lg: 1024;
+    readonly md: 768;
+    readonly sm: 640;
+    readonly xl: 1280;
+    readonly xs: 480;
+};
+/** Breakpoint name type */
+export type Breakpoint = keyof typeof BREAKPOINT_VALUES | "base";
+/** Ordered list of breakpoints from smallest to largest (excluding base) */
+export declare const BREAKPOINTS: readonly ["2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl"];
+/** Semantic viewport categories */
+export type Viewport = "mobile" | "tablet" | "desktop";

package/dist/tokens/breakpoint.js

@@ -0,0 +1,25 @@
+/**
+ * Tailwind v4 breakpoint pixel values.
+ * Includes extended breakpoints for small mobile (2xs) and ultrawide (3xl).
+ */
+export const BREAKPOINT_VALUES = {
+    "2xl": 1536,
+    "2xs": 320,
+    "3xl": 1920,
+    lg: 1024,
+    md: 768,
+    sm: 640,
+    xl: 1280,
+    xs: 480,
+};
+/** Ordered list of breakpoints from smallest to largest (excluding base) */
+export const BREAKPOINTS = [
+    "2xs",
+    "xs",
+    "sm",
+    "md",
+    "lg",
+    "xl",
+    "2xl",
+    "3xl",
+];

package/dist/tokens/color.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Deterministic colour utilities inspired by the Midday project.
+ *
+ * Provides a stable mapping from an input string to a colour from a
+ * predefined palette. Useful for avatars, category labels, etc.
+ */
+/**
+ * DETERMINISTIC_COLORS utility.
+ * Import from "@instruments/materia-ui/tokens/color".
+ */
+export declare const DETERMINISTIC_COLORS: readonly string[];
+/**
+ * Produces a deterministic positive integer hash for a given string.
+ */
+export declare const customHash: (value: string) => number;
+/**
+ * Returns a stable index for `value` within a given array length.
+ */
+export declare const getColorIndex: (value: string, arrayLength: number) => number;
+/**
+ * Maps a string to a colour from the deterministic palette.
+ */
+export declare const getColorFromName: (value: string) => string;
+/**
+ * WCAG 2.1 contrast ratio between two hex colours. Inlined here (rather than
+ * imported) so this token module stays dependency-free.
+ */
+export declare const contrastRatio: (color1: string, color2: string) => number;
+/**
+ * Picks the higher-contrast of black/white for the given background, using
+ * the WCAG contrast ratio (more correct than the old YIQ heuristic).
+ * Import from "@instruments/materia-ui/tokens/color".
+ */
+export declare const getReadableTextColor: (bgHex: string) => "#000000" | "#FFFFFF";
+/**
+ * Generates initials from a name for avatar fallbacks.
+ */
+export declare const getInitials: (name: string) => string;

package/dist/tokens/color.js

@@ -0,0 +1,230 @@
+/**
+ * Deterministic colour utilities inspired by the Midday project.
+ *
+ * Provides a stable mapping from an input string to a colour from a
+ * predefined palette. Useful for avatars, category labels, etc.
+ */
+// Category palette
+/**
+ * DETERMINISTIC_COLORS utility.
+ * Import from "@instruments/materia-ui/tokens/color".
+ */
+export const DETERMINISTIC_COLORS = [
+    // Primary
+    "#FF6900",
+    "#00D084",
+    "#0693E3",
+    "#8ED1FC",
+    "#9900EF",
+    "#EB144C",
+    "#FF9F1C",
+    "#39CCCC",
+    "#0074D9",
+    "#3D9970",
+    "#B04632",
+    "#DC2626",
+    "#059669",
+    "#6B7280",
+    // Extended
+    "#FCB900",
+    "#ABB8C3",
+    "#F78DA7",
+    "#0079BF",
+    "#B6BBBF",
+    "#FF5A5F",
+    "#F7C59F",
+    "#8492A6",
+    "#4D5055",
+    "#AF5A50",
+    "#F9D6E7",
+    "#B5EAEA",
+    "#B388EB",
+    "#FF78CB",
+    "#4E5A65",
+    "#01FF70",
+    "#85144B",
+    "#F012BE",
+    "#7FDBFF",
+    "#AAAAAA",
+    "#111111",
+    "#001F3F",
+    "#5E6A71",
+    "#75D701",
+    "#B6C8A9",
+    "#00A9FE",
+    "#EAE8E1",
+    "#CD346C",
+    "#FF6FA4",
+    "#D667FB",
+    "#0080FF",
+    "#656D78",
+    "#F8842C",
+    "#FF8CFF",
+    "#647F6A",
+    "#5E574E",
+    "#EF5466",
+    "#B0E0E6",
+    "#EB5E7C",
+    "#8A2BE2",
+    "#6B7C85",
+    "#8C92AC",
+    "#6C587A",
+    "#52A1FF",
+    "#32CD32",
+    "#E04F9F",
+    "#915C83",
+    "#4C6B88",
+    "#587376",
+    "#C46210",
+    "#65B0D0",
+    "#2F4F4F",
+    "#528B8B",
+    "#8B4513",
+    "#4682B4",
+    "#CD853F",
+    "#FFA07A",
+    "#CD5C5C",
+    "#483D8B",
+    "#696969",
+];
+// Neutral grey fallback
+const DEFAULT_COLOR = "#6B7280";
+/**
+ * Produces a deterministic positive integer hash for a given string.
+ */
+export const customHash = (value) => {
+    // Multiplicative hash without bitwise operators (polynomial rolling hash)
+    // 2^31 - 1
+    const MOD = 2_147_483_647;
+    const BASE = 31;
+    let hash = 0;
+    for (const ch of value) {
+        hash = (hash * BASE + (ch.codePointAt(0) ?? 0)) % MOD;
+    }
+    return hash;
+};
+/**
+ * Returns a stable index for `value` within a given array length.
+ */
+export const getColorIndex = (value, arrayLength) => {
+    const hashValue = customHash(value);
+    return hashValue % arrayLength;
+};
+/**
+ * Maps a string to a colour from the deterministic palette.
+ */
+export const getColorFromName = (value) => {
+    if (!value) {
+        return DEFAULT_COLOR;
+    }
+    const index = getColorIndex(value, DETERMINISTIC_COLORS.length);
+    return DETERMINISTIC_COLORS[index] ?? DEFAULT_COLOR;
+};
+const WHITESPACE_RE = /\s+/u;
+const HASH_PREFIX_RE = /^#/u;
+const SHORT_HEX_RE = /^[\da-f]{3}$/iu;
+const LONG_HEX_RE = /^[\da-f]{6}$/iu;
+const SHORT_HEX_LENGTH = 3;
+const LONG_HEX_LENGTH = 6;
+const SRGB_GAMMA_THRESHOLD = 0.04045;
+const SRGB_GAMMA_EXPONENT = 2.4;
+const CONTRAST_OFFSET = 0.05;
+/**
+ * Parses a hex colour string (3 or 6 digit, with or without leading `#`) into
+ * an { r, g, b } triple.
+ */
+const hexToRgb = (hex) => {
+    const cleaned = hex.replace(HASH_PREFIX_RE, "");
+    let r;
+    let g;
+    let b;
+    if (cleaned.length === SHORT_HEX_LENGTH) {
+        if (!SHORT_HEX_RE.test(cleaned)) {
+            return null;
+        }
+        const [rChar, gChar, bChar] = cleaned;
+        if (rChar === undefined || gChar === undefined || bChar === undefined) {
+            return null;
+        }
+        r = Number.parseInt(rChar + rChar, 16);
+        g = Number.parseInt(gChar + gChar, 16);
+        b = Number.parseInt(bChar + bChar, 16);
+    }
+    else if (cleaned.length === LONG_HEX_LENGTH) {
+        if (!LONG_HEX_RE.test(cleaned)) {
+            return null;
+        }
+        r = Number.parseInt(cleaned.slice(0, 2), 16);
+        g = Number.parseInt(cleaned.slice(2, 4), 16);
+        b = Number.parseInt(cleaned.slice(4, 6), 16);
+    }
+    else {
+        return null;
+    }
+    if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) {
+        return null;
+    }
+    return { b, g, r };
+};
+/**
+ * Converts a single sRGB channel (0-255) to its linear-light value.
+ */
+const srgbToLinear = (value) => {
+    const v = value / 255;
+    return v <= SRGB_GAMMA_THRESHOLD
+        ? v / 12.92
+        : ((v + 0.055) / 1.055) ** SRGB_GAMMA_EXPONENT;
+};
+/**
+ * WCAG 2.1 relative luminance for an sRGB colour.
+ */
+const relativeLuminance = (r, g, b) => 0.2126 * srgbToLinear(r) +
+    0.7152 * srgbToLinear(g) +
+    0.0722 * srgbToLinear(b);
+/**
+ * WCAG 2.1 contrast ratio between two hex colours. Inlined here (rather than
+ * imported) so this token module stays dependency-free.
+ */
+export const contrastRatio = (color1, color2) => {
+    const rgb1 = hexToRgb(color1);
+    const rgb2 = hexToRgb(color2);
+    if (!(rgb1 && rgb2)) {
+        throw new Error(`Invalid hex color: ${rgb1 ? color2 : color1}`);
+    }
+    const l1 = relativeLuminance(rgb1.r, rgb1.g, rgb1.b);
+    const l2 = relativeLuminance(rgb2.r, rgb2.g, rgb2.b);
+    const lighter = Math.max(l1, l2);
+    const darker = Math.min(l1, l2);
+    return (lighter + CONTRAST_OFFSET) / (darker + CONTRAST_OFFSET);
+};
+/**
+ * Picks the higher-contrast of black/white for the given background, using
+ * the WCAG contrast ratio (more correct than the old YIQ heuristic).
+ * Import from "@instruments/materia-ui/tokens/color".
+ */
+export const getReadableTextColor = (bgHex) => {
+    const bg = bgHex.startsWith("#") ? bgHex : `#${bgHex}`;
+    return contrastRatio(bg, "#000000") >= contrastRatio(bg, "#FFFFFF")
+        ? "#000000"
+        : "#FFFFFF";
+};
+/**
+ * Generates initials from a name for avatar fallbacks.
+ */
+export const getInitials = (name) => {
+    if (!name) {
+        return "";
+    }
+    const parts = name.trim().split(WHITESPACE_RE);
+    const [firstPart, ...rest] = parts;
+    if (firstPart === undefined || firstPart === null || firstPart === "") {
+        return "";
+    }
+    if (rest.length === 0) {
+        return firstPart.charAt(0).toUpperCase();
+    }
+    const lastPart = rest.at(-1) ?? firstPart;
+    const first = firstPart.charAt(0);
+    const last = lastPart.charAt(0);
+    return `${first}${last}`.toUpperCase();
+};

package/dist/tokens/component-sizes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The shared component size scale, kept free of imports so tooling without a
+ * DOM library (the agent package) can read it.
+ *
+ * @module
+ */
+/**
+ * Shared component size scale used across UI components.
+ * Keep this file icon-agnostic; icon-specific mapping lives in components/icon.tsx
+ *
+ * 2xs < xs < sm < base < lg < xl < 2xl < 3xl
+ */
+export declare const COMPONENT_SIZES: readonly ["2xs", "xs", "sm", "base", "lg", "xl", "2xl", "3xl"];
+export type ComponentSize = (typeof COMPONENT_SIZES)[number];

package/dist/tokens/component-sizes.js

@@ -0,0 +1,22 @@
+/**
+ * The shared component size scale, kept free of imports so tooling without a
+ * DOM library (the agent package) can read it.
+ *
+ * @module
+ */
+/**
+ * Shared component size scale used across UI components.
+ * Keep this file icon-agnostic; icon-specific mapping lives in components/icon.tsx
+ *
+ * 2xs < xs < sm < base < lg < xl < 2xl < 3xl
+ */
+export const COMPONENT_SIZES = [
+    "2xs",
+    "xs",
+    "sm",
+    "base",
+    "lg",
+    "xl",
+    "2xl",
+    "3xl",
+];

package/dist/tokens/control-line.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wrapper for a checkbox or radio that sits beside text. Pair it with the
+ * type role of the label (for example `text-paragraph-sm`) on the same
+ * element: `h-lh` makes the wrapper exactly one line of that role tall, and
+ * the control is centred inside it, so it lands on the centre of the label's
+ * first line however many lines the label wraps to.
+ */
+export declare const CONTROL_LINE_CLASSES = "flex h-lh shrink-0 items-center";

package/dist/tokens/control-line.js

@@ -0,0 +1,8 @@
+/**
+ * Wrapper for a checkbox or radio that sits beside text. Pair it with the
+ * type role of the label (for example `text-paragraph-sm`) on the same
+ * element: `h-lh` makes the wrapper exactly one line of that role tall, and
+ * the control is centred inside it, so it lands on the centre of the label's
+ * first line however many lines the label wraps to.
+ */
+export const CONTROL_LINE_CLASSES = "flex h-lh shrink-0 items-center";

package/dist/tokens/direction.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Flex direction types.
+ * Used by `Flex` and `Stack` via the `direction` prop.
+ * Note: Stack uses `"column"` instead of `"col"` for consistency with CSS.
+ */
+export type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";

package/dist/tokens/direction.js

@@ -0,0 +1 @@
+export {};

package/dist/tokens/element.d.ts

@@ -0,0 +1,46 @@
+import type * as React from "react";
+/**
+ * Closed element vocabularies for the design system's polymorphic `as` prop.
+ *
+ * The safety thesis (modelled on Polar's Orbit "LLM-safe design system"): a
+ * component's `as` prop draws from an AUTHORED, CLOSED menu of host elements -
+ * never the infinite space of raw HTML. `as="button"` is a *type error*, not a
+ * silent escape hatch, because the correct answer is the Button component. This
+ * is the vocabulary constraint the zero-raw-element experiment is built on.
+ *
+ * Two vocabularies:
+ * - {@link LayoutElement} - structural/decorative hosts for the layout
+ *   primitives (Box, Stack, Flex, Container, Section, Center). `span` lives here
+ *   (not in TEXT) because a decorative inline wrapper wants Box/Container
+ *   semantics, not Text's `max-w-prose text-pretty` baggage.
+ * - {@link TextElement} - textual hosts for the Text primitive. NO `"label"`:
+ *   `ComponentProps<"p">` lacks `htmlFor`, so a correct label would fail to
+ *   typecheck - use the Label component for labels.
+ *
+ * @module
+ */
+/** Structural/decorative host elements a layout primitive may render via `as`. */
+export declare const LAYOUT_ELEMENTS: readonly ["div", "span", "main", "nav", "header", "footer", "section", "article", "aside", "ul", "ol", "li", "figure", "figcaption"];
+/** A host element a layout primitive may render via `as`. */
+export type LayoutElement = (typeof LAYOUT_ELEMENTS)[number];
+/**
+ * The ref a layout primitive accepts. Widened to HTMLElement so a component
+ * rendering `as="ul"` (or any other layout host) can forward its own element's
+ * ref; a div ref still fits.
+ */
+export type LayoutRef = React.Ref<HTMLElement>;
+/**
+ * The DOM props a layout primitive types for any host element: its event
+ * handlers and ref. A component whose own props are `ComponentProps<"ul">` can
+ * then spread them onto `<Flex as="ul">`; a div's props still fit.
+ */
+export type LayoutHostAttributes = React.DOMAttributes<HTMLElement> & {
+    /** Ref to the rendered host, whichever element `as` selects. */
+    ref?: LayoutRef | undefined;
+};
+/** The div props that {@link LayoutHostAttributes} replaces. */
+export type LayoutHostKey = keyof React.DOMAttributes<HTMLDivElement> | "ref";
+/** Textual host elements the Text primitive may render via `as`. */
+export declare const TEXT_ELEMENTS: readonly ["p", "span", "legend", "figcaption", "dt", "dd", "li"];
+/** A host element Text may render via `as`. */
+export type TextElement = (typeof TEXT_ELEMENTS)[number];

package/dist/tokens/element.js

@@ -0,0 +1,47 @@
+/**
+ * Closed element vocabularies for the design system's polymorphic `as` prop.
+ *
+ * The safety thesis (modelled on Polar's Orbit "LLM-safe design system"): a
+ * component's `as` prop draws from an AUTHORED, CLOSED menu of host elements -
+ * never the infinite space of raw HTML. `as="button"` is a *type error*, not a
+ * silent escape hatch, because the correct answer is the Button component. This
+ * is the vocabulary constraint the zero-raw-element experiment is built on.
+ *
+ * Two vocabularies:
+ * - {@link LayoutElement} - structural/decorative hosts for the layout
+ *   primitives (Box, Stack, Flex, Container, Section, Center). `span` lives here
+ *   (not in TEXT) because a decorative inline wrapper wants Box/Container
+ *   semantics, not Text's `max-w-prose text-pretty` baggage.
+ * - {@link TextElement} - textual hosts for the Text primitive. NO `"label"`:
+ *   `ComponentProps<"p">` lacks `htmlFor`, so a correct label would fail to
+ *   typecheck - use the Label component for labels.
+ *
+ * @module
+ */
+/** Structural/decorative host elements a layout primitive may render via `as`. */
+export const LAYOUT_ELEMENTS = [
+    "div",
+    "span",
+    "main",
+    "nav",
+    "header",
+    "footer",
+    "section",
+    "article",
+    "aside",
+    "ul",
+    "ol",
+    "li",
+    "figure",
+    "figcaption",
+];
+/** Textual host elements the Text primitive may render via `as`. */
+export const TEXT_ELEMENTS = [
+    "p",
+    "span",
+    "legend",
+    "figcaption",
+    "dt",
+    "dd",
+    "li",
+];

package/dist/tokens/emphasis.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Emphasis system for the Materia design system.
+ *
+ * `Emphasis` is the canonical fill-treatment vocabulary - how strongly a
+ * surface is filled - and is orthogonal to {@link Tone} (which colour). A tone
+ * and an emphasis compose: `tone="danger"` + `emphasis="soft"` is the muted red
+ * treatment, `tone="danger"` + `emphasis="solid"` the filled one.
+ *
+ * Like {@link Tone}, components subset this with `Extract<Emphasis, …>` and
+ * cva-backed components anchor their variant map `satisfies Record<Emphasis, …>`
+ * so the fill vocabulary stays in lockstep with the canon.
+ *
+ * `link` is deliberately NOT a member: it is a Button-only extension expressed
+ * as `ButtonEmphasis = Emphasis | "link"`, so no other component inherits an
+ * inline-link treatment it has no styling for.
+ *
+ * @module
+ */
+/** The canonical fill-treatment vocabulary. */
+export declare const EMPHASES: readonly ["solid", "soft", "outline", "ghost", "transparent"];
+/** A single fill treatment. Subset with `Extract<Emphasis, …>`; extend (e.g. Button's `link`) with a union. */
+export type Emphasis = (typeof EMPHASES)[number];

package/dist/tokens/emphasis.js

@@ -0,0 +1,26 @@
+/**
+ * Emphasis system for the Materia design system.
+ *
+ * `Emphasis` is the canonical fill-treatment vocabulary - how strongly a
+ * surface is filled - and is orthogonal to {@link Tone} (which colour). A tone
+ * and an emphasis compose: `tone="danger"` + `emphasis="soft"` is the muted red
+ * treatment, `tone="danger"` + `emphasis="solid"` the filled one.
+ *
+ * Like {@link Tone}, components subset this with `Extract<Emphasis, …>` and
+ * cva-backed components anchor their variant map `satisfies Record<Emphasis, …>`
+ * so the fill vocabulary stays in lockstep with the canon.
+ *
+ * `link` is deliberately NOT a member: it is a Button-only extension expressed
+ * as `ButtonEmphasis = Emphasis | "link"`, so no other component inherits an
+ * inline-link treatment it has no styling for.
+ *
+ * @module
+ */
+/** The canonical fill-treatment vocabulary. */
+export const EMPHASES = [
+    "solid",
+    "soft",
+    "outline",
+    "ghost",
+    "transparent",
+];