@instruments/materia-ui 0.1.0

package/dist/tokens/responsive.js

@@ -0,0 +1,270 @@
+import { BREAKPOINTS } from "./breakpoint.js";
+/**
+ * Screen breakpoint prefixes (viewport media queries)
+ */
+export const SCREEN_PREFIX = {
+    "2xl": "2xl:",
+    "2xs": "2xs:",
+    "3xl": "3xl:",
+    base: "",
+    lg: "lg:",
+    md: "md:",
+    sm: "sm:",
+    xl: "xl:",
+    xs: "xs:",
+};
+/**
+ * Container query prefixes
+ */
+export const CONTAINER_PREFIX = {
+    "2xl": "@2xl:",
+    "2xs": "@2xs:",
+    "3xl": "@3xl:",
+    base: "",
+    lg: "@lg:",
+    md: "@md:",
+    sm: "@sm:",
+    xl: "@xl:",
+    xs: "@xs:",
+};
+const LOCAL_DEV_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "0.0.0.0"]);
+/** True only in a local-dev browser session - gates noisy consumer-misuse warnings. */
+export const isLocalDevBrowser = () => typeof window !== "undefined" &&
+    (window.location.protocol === "file:" ||
+        LOCAL_DEV_HOSTS.has(window.location.hostname));
+/**
+ * Check if a value is a responsive object (vs a bare static value).
+ */
+export const isResponsiveValue = (value) => value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    !Array.isArray(value);
+/**
+ * Returns the Tailwind class prefix for a given breakpoint and responsive mode.
+ *
+ * In `"screen"` mode, returns viewport prefixes like `"md:"`.
+ * In `"container"` mode, returns container-query prefixes like `"@md:"`.
+ * The `"base"` breakpoint always returns an empty string.
+ *
+ * @param breakpoint - Target breakpoint name
+ * @param mode - `"screen"` (default) for viewport media queries, `"container"` for container queries
+ * @returns The Tailwind prefix string (e.g., `"lg:"`, `"@lg:"`, or `""` for base)
+ */
+export const getBreakpointPrefix = (breakpoint, mode = "screen") => mode === "container"
+    ? CONTAINER_PREFIX[breakpoint]
+    : SCREEN_PREFIX[breakpoint];
+/**
+ * Generate responsive classes from a value and class map
+ *
+ * @param value - Static value or responsive object
+ * @param classMap - Map of value to class name (without breakpoint prefix)
+ * @param mode - "screen" (default) or "container"
+ * @returns Array of class names with appropriate breakpoint prefixes
+ *
+ * @example
+ * ```ts
+ * const GAP_CLASS = { xs: "gap-2", sm: "gap-3", base: "gap-4" };
+ * getResponsiveClasses("base", GAP_CLASS, "screen");
+ * // → ["gap-4"]
+ *
+ * getResponsiveClasses({ base: "xs", md: "base" }, GAP_CLASS, "screen");
+ * // → ["gap-2", "md:gap-4"]
+ *
+ * getResponsiveClasses({ base: "xs", md: "base" }, GAP_CLASS, "container");
+ * // → ["gap-2", "@md:gap-4"]
+ * ```
+ */
+export const getResponsiveClasses = (value, classMap, mode = "screen") => {
+    if (value === undefined) {
+        return [];
+    }
+    const classes = [];
+    const prefixMap = mode === "container" ? CONTAINER_PREFIX : SCREEN_PREFIX;
+    // Static value (not responsive object)
+    if (!isResponsiveValue(value)) {
+        const cls = classMap[value];
+        if (cls) {
+            classes.push(cls);
+        }
+        return classes;
+    }
+    // Responsive object - handle base first
+    const baseValue = value.base;
+    if (baseValue !== undefined) {
+        const cls = classMap[baseValue];
+        if (cls) {
+            classes.push(cls);
+        }
+    }
+    // Handle each breakpoint
+    for (const bp of BREAKPOINTS) {
+        const bpValue = value[bp];
+        if (bpValue !== undefined) {
+            const cls = classMap[bpValue];
+            if (cls) {
+                classes.push(`${prefixMap[bp]}${cls}`);
+            }
+        }
+    }
+    // The type rejects `@`-container keys, so one can only arrive through an
+    // untyped caller. Warn in local dev rather than dropping it without a trace.
+    // For container-driven layout, use `responsiveMode`.
+    if (isLocalDevBrowser()) {
+        for (const key of Object.keys(value)) {
+            if (key.startsWith("@")) {
+                reportError(new Error(`getResponsiveClasses: container-query key "${key}" is ignored - ` +
+                    `container keys are only honored on component \`size\`. For ` +
+                    `container-responsive layout use responsiveMode="container".`));
+            }
+        }
+    }
+    return classes;
+};
+/** Prefix every whitespace-separated token in a (possibly multi-class) string. */
+const prefixClassTokens = (classes, prefix) => prefix === ""
+    ? classes
+    : classes
+        .split(/\s+/u)
+        .filter(Boolean)
+        .map((token) => `${prefix}${token}`)
+        .join(" ");
+const isContainerKey = (key) => key.startsWith("@");
+/** The breakpoint names as plain strings, for matching `@`-key suffixes. */
+const BREAKPOINT_NAMES = BREAKPOINTS;
+/** Sort rank for a container key: standard `@sm`..`@3xl` ascending, arbitrary last. */
+const containerKeyRank = (containerKey) => {
+    const index = BREAKPOINT_NAMES.indexOf(containerKey.slice(1));
+    return index === -1 ? BREAKPOINTS.length : index;
+};
+/**
+ * Non-base entries of a responsive object, emitted viewport keys first
+ * (ascending by breakpoint) then container keys. When a viewport and a container
+ * rule target the same property and both match, container wins - but that
+ * precedence comes from Tailwind's GENERATED-STYLESHEET order (container-query
+ * rules are emitted after media-query rules), NOT from the order class names
+ * appear in the class attribute. Emitting container entries last here just keeps
+ * the class string legible and consistent with that cascade; it does not itself
+ * decide the winner. Container keys are canonically sorted (standard `@sm`..
+ * `@3xl` ascending, arbitrary/named containers last in author order) for
+ * deterministic output. Prefixes are derived where the key type is known
+ * (viewport → `SCREEN_PREFIX[bp]`, container → the `@`-key verbatim).
+ */
+const orderedResponsiveEntries = (obj) => {
+    const entries = [];
+    for (const bp of BREAKPOINTS) {
+        const value = obj[bp];
+        if (value !== undefined) {
+            entries.push([bp, SCREEN_PREFIX[bp], value]);
+        }
+    }
+    const containerEntries = [];
+    for (const [key, value] of Object.entries(obj)) {
+        if (isContainerKey(key) && value !== undefined) {
+            containerEntries.push([key, `${key}:`, value]);
+        }
+    }
+    // Stable sort keeps arbitrary container keys (equal rank) in author order.
+    containerEntries.sort(([keyA], [keyB]) => containerKeyRank(keyA) - containerKeyRank(keyB));
+    return [...entries, ...containerEntries];
+};
+/** Resolve one non-base entry to its (prefixed or literal-override) classes. */
+const responsiveEntryClasses = (entry, classMap, literalOverrides) => {
+    const [key, prefix, sizeValue] = entry;
+    const literal = literalOverrides?.[`${key}:${sizeValue}`];
+    if (literal !== undefined && literal !== "") {
+        return literal;
+    }
+    const cls = classMap[sizeValue];
+    return cls ? prefixClassTokens(cls, prefix) : "";
+};
+/**
+ * Resolve a responsive value whose class map holds MULTI-class strings (e.g. a
+ * component `size` scale like `"h-9 px-3 text-sm"`).
+ *
+ * Unlike {@link getResponsiveClasses} - which prefixes only the first token and
+ * is meant for single-class layout maps - this prefixes EVERY token per
+ * breakpoint (`md:h-10 md:px-4 md:text-sm`), so each utility actually responds.
+ * A static value returns its base classes; an object resolves `base` (or
+ * `fallback`) unprefixed, then appends each breakpoint's classes so larger
+ * breakpoints win by media-query specificity.
+ *
+ * Object keys may be viewport breakpoints AND/OR `@`-prefixed container-query
+ * keys, freely mixed (`{ base: "sm", lg: "base", "@sm": "xl" }`). Bare keys →
+ * media queries; `@`-keys → container queries; on a tie the container key wins
+ * (emitted last - see {@link orderedResponsiveEntries}).
+ *
+ * IMPORTANT: the prefixed combinations must exist in the compiled CSS. Tailwind
+ * cannot statically see these runtime concatenations, so the viewport AND
+ * container size combos are force-emitted by the `@source inline(...)` safelist
+ * in shared-styles.css. Arbitrary/named container keys (`@[240px]/card`) cannot
+ * be safelisted - pass their fully-prefixed class strings via `literalOverrides`
+ * (keyed `"<key>:<sizeValue>"`) so the scanner sees them as literals.
+ *
+ * @param value - Static size or a mixed viewport/container responsive object
+ * @param classMap - Map of size → (multi-class) class string
+ * @param fallback - Size used for `base` when the object omits it (the component default)
+ * @param literalOverrides - Optional literal class strings for arbitrary container keys
+ */
+export const getResponsiveSizeClasses = (value, classMap, fallback, literalOverrides) => {
+    const resolved = value ?? fallback;
+    if (!isResponsiveValue(resolved)) {
+        return classMap[resolved] ?? "";
+    }
+    const out = [];
+    const baseClasses = classMap[resolved.base ?? fallback];
+    if (baseClasses) {
+        out.push(baseClasses);
+    }
+    for (const entry of orderedResponsiveEntries(resolved)) {
+        const cls = responsiveEntryClasses(entry, classMap, literalOverrides);
+        if (cls) {
+            out.push(cls);
+        }
+    }
+    return out.join(" ");
+};
+/**
+ * Resolve the base {@link ComponentSize}-style value for a responsive prop:
+ * the object's `base` key, the static value itself, or the `fallback`.
+ * Pass this to cva so `defaultVariants` + size-dependent `compoundVariants`
+ * still resolve for the base breakpoint.
+ */
+export const resolveResponsiveBase = (value, fallback) => {
+    if (value === undefined) {
+        return fallback;
+    }
+    return isResponsiveValue(value) ? (value.base ?? fallback) : value;
+};
+/**
+ * Like {@link getResponsiveSizeClasses} but returns ONLY the non-base
+ * overrides (a static value → `""`). Use when cva already applies the base size
+ * (and its compoundVariants) via {@link resolveResponsiveBase}, and you only
+ * need to layer `md:…`/`@sm:…` overrides on top. Supports mixed viewport/
+ * container keys and the same `literalOverrides`.
+ */
+export const getResponsiveSizeOverrides = (value, classMap, literalOverrides) => {
+    if (value === undefined || !isResponsiveValue(value)) {
+        return "";
+    }
+    const out = [];
+    for (const entry of orderedResponsiveEntries(value)) {
+        const cls = responsiveEntryClasses(entry, classMap, literalOverrides);
+        if (cls) {
+            out.push(cls);
+        }
+    }
+    return out.join(" ");
+};
+/**
+ * Push responsive classes to an array (mutates the array)
+ * Convenience wrapper around getResponsiveClasses for the pattern used in Flex
+ *
+ * @param classes - Array to push classes into
+ * @param value - Static value or responsive object
+ * @param classMap - Map of value to class name
+ * @param mode - "screen" (default) or "container"
+ */
+export const pushResponsiveClasses = (classes, value, classMap, mode = "screen") => {
+    const responsiveClasses = getResponsiveClasses(value, classMap, mode);
+    classes.push(...responsiveClasses);
+};

package/dist/tokens/shadows.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shadow design tokens for use in JavaScript/TypeScript contexts.
+ * These mirror the CSS custom properties in shared-styles.css.
+ *
+ * Use these when you need shadows in style props (e.g., Motion animations)
+ * where CSS classes aren't available.
+ *
+ * @example
+ * import { shadows } from "@instruments/materia-ui/tokens/shadows";
+ *
+ * <motion.div style={{ boxShadow: shadows.xl }} />
+ */
+export declare const shadows: {
+    /** Exceptional staged surface */
+    readonly "2xl": "0 60px 120px 0 rgb(17 24 39 / 0.07), 0 30px 60px 0 rgb(17 24 39 / 0.06), 0 15px 30px 0 rgb(17 24 39 / 0.05), 0 7.5px 15px 0 rgb(17 24 39 / 0.04), 0 3px 6px 0 rgb(17 24 39 / 0.03), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** Quiet directional shadow */
+    readonly "2xs": "0 1px 1px 0 rgb(17 24 39 / 0.03)";
+    /** Exceptional staged surface */
+    readonly "3xl": "0 80px 160px 0 rgb(17 24 39 / 0.08), 0 40px 80px 0 rgb(17 24 39 / 0.07), 0 20px 40px 0 rgb(17 24 39 / 0.06), 0 10px 20px 0 rgb(17 24 39 / 0.05), 0 4px 8px 0 rgb(17 24 39 / 0.04), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** Exceptional staged surface */
+    readonly "4xl": "0 100px 200px 0 rgb(17 24 39 / 0.09), 0 50px 100px 0 rgb(17 24 39 / 0.08), 0 25px 50px 0 rgb(17 24 39 / 0.07), 0 12.5px 25px 0 rgb(17 24 39 / 0.06), 0 5px 10px 0 rgb(17 24 39 / 0.05), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** Dialogs, sheets, and sidepanels */
+    readonly lg: "0 25px 50px 0 rgb(17 24 39 / 0.05), 0 12px 24px 0 rgb(17 24 39 / 0.04), 0 6px 12px 0 rgb(17 24 39 / 0.03), 0 3px 6px 0 rgb(17 24 39 / 0.02), 0 1.5px 3px 0 rgb(17 24 39 / 0.02), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** Anchored overlays and menus */
+    readonly md: "0 17.54px 23.39px 0 rgb(17 24 39 / 0.04), 0 9.4px 12.5px 0 rgb(17 24 39 / 0.03), 0 5.25px 7px 0 rgb(17 24 39 / 0.02), 0 2.79px 3.72px -2px rgb(17 24 39 / 0.01), 0 1.16px 1.5px 0 rgb(17 24 39 / 0.01), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** No shadow */
+    readonly none: "none";
+    /** Cards, toasts, and lowest elevated surfaces */
+    readonly sm: "0 18px 47px 0 rgb(17 24 39 / 0.03), 0 7.5px 19px 0 rgb(17 24 39 / 0.02), 0 4px 10.5px 0 rgb(17 24 39 / 0.02), 0 2.3px 5.8px 0 rgb(17 24 39 / 0.01), 0 0.5px 1.3px 0 rgb(17 24 39 / 0.01), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** Exceptional staged surface */
+    readonly xl: "0 40px 80px 0 rgb(17 24 39 / 0.06), 0 20px 40px 0 rgb(17 24 39 / 0.05), 0 10px 20px 0 rgb(17 24 39 / 0.04), 0 5px 10px 0 rgb(17 24 39 / 0.03), 0 2px 4px 0 rgb(17 24 39 / 0.02), 0 0 0 1px rgb(17 24 39 / 0.05)";
+    /** Ringless bordered control and inline callout shadow */
+    readonly xs: "0 0 4px 0 rgb(17 24 39 / 0.04)";
+};
+/**
+ * Shadow under each card in a fanned stack (SwatchFan, EditorialCard stack).
+ * A tighter, darker drop than the elevation scale, so overlapping cards
+ * separate from each other rather than from the page.
+ */
+export declare const fanCardShadow = "0 7px 10px -1px rgba(0, 0, 0, 0.1), 0 3.5px 7px -2px rgba(0, 0, 0, 0.1)";
+/** Inner shadow tokens */
+export declare const innerShadows: {
+    /** inset 0 1px 0 0 rgb(0 0 0 / 0.05) */
+    readonly "2xs": "inset 0 1px 0 0 rgb(0 0 0 / 0.05)";
+    /** inset 0 2px 4px 0 rgb(0 0 0 / 0.05) */
+    readonly sm: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)";
+    /** inset 0 1px 1px 0 rgb(0 0 0 / 0.05) */
+    readonly xs: "inset 0 1px 1px 0 rgb(0 0 0 / 0.05)";
+};
+/** Drop shadow tokens (for CSS filter) */
+export declare const dropShadows: {
+    /** 0 25px 25px rgb(0 0 0 / 0.15) */
+    readonly "2xl": "drop-shadow(0 25px 25px rgb(0 0 0 / 0.15))";
+    /** 0 4px 4px rgb(0 0 0 / 0.15) */
+    readonly lg: "drop-shadow(0 4px 4px rgb(0 0 0 / 0.15))";
+    /** 0 3px 3px rgb(0 0 0 / 0.12) */
+    readonly md: "drop-shadow(0 3px 3px rgb(0 0 0 / 0.12))";
+    /** 0 1px 2px rgb(0 0 0 / 0.15) */
+    readonly sm: "drop-shadow(0 1px 2px rgb(0 0 0 / 0.15))";
+    /** 0 9px 7px rgb(0 0 0 / 0.1) */
+    readonly xl: "drop-shadow(0 9px 7px rgb(0 0 0 / 0.1))";
+    /** 0 1px 1px rgb(0 0 0 / 0.05) */
+    readonly xs: "drop-shadow(0 1px 1px rgb(0 0 0 / 0.05))";
+};
+export type ShadowSize = keyof typeof shadows;
+export type InnerShadowSize = keyof typeof innerShadows;
+export type DropShadowSize = keyof typeof dropShadows;

package/dist/tokens/shadows.js

@@ -0,0 +1,64 @@
+/**
+ * Shadow design tokens for use in JavaScript/TypeScript contexts.
+ * These mirror the CSS custom properties in shared-styles.css.
+ *
+ * Use these when you need shadows in style props (e.g., Motion animations)
+ * where CSS classes aren't available.
+ *
+ * @example
+ * import { shadows } from "@instruments/materia-ui/tokens/shadows";
+ *
+ * <motion.div style={{ boxShadow: shadows.xl }} />
+ */
+export const shadows = {
+    /** Exceptional staged surface */
+    "2xl": "0 60px 120px 0 rgb(17 24 39 / 0.07), 0 30px 60px 0 rgb(17 24 39 / 0.06), 0 15px 30px 0 rgb(17 24 39 / 0.05), 0 7.5px 15px 0 rgb(17 24 39 / 0.04), 0 3px 6px 0 rgb(17 24 39 / 0.03), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** Quiet directional shadow */
+    "2xs": "0 1px 1px 0 rgb(17 24 39 / 0.03)",
+    /** Exceptional staged surface */
+    "3xl": "0 80px 160px 0 rgb(17 24 39 / 0.08), 0 40px 80px 0 rgb(17 24 39 / 0.07), 0 20px 40px 0 rgb(17 24 39 / 0.06), 0 10px 20px 0 rgb(17 24 39 / 0.05), 0 4px 8px 0 rgb(17 24 39 / 0.04), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** Exceptional staged surface */
+    "4xl": "0 100px 200px 0 rgb(17 24 39 / 0.09), 0 50px 100px 0 rgb(17 24 39 / 0.08), 0 25px 50px 0 rgb(17 24 39 / 0.07), 0 12.5px 25px 0 rgb(17 24 39 / 0.06), 0 5px 10px 0 rgb(17 24 39 / 0.05), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** Dialogs, sheets, and sidepanels */
+    lg: "0 25px 50px 0 rgb(17 24 39 / 0.05), 0 12px 24px 0 rgb(17 24 39 / 0.04), 0 6px 12px 0 rgb(17 24 39 / 0.03), 0 3px 6px 0 rgb(17 24 39 / 0.02), 0 1.5px 3px 0 rgb(17 24 39 / 0.02), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** Anchored overlays and menus */
+    md: "0 17.54px 23.39px 0 rgb(17 24 39 / 0.04), 0 9.4px 12.5px 0 rgb(17 24 39 / 0.03), 0 5.25px 7px 0 rgb(17 24 39 / 0.02), 0 2.79px 3.72px -2px rgb(17 24 39 / 0.01), 0 1.16px 1.5px 0 rgb(17 24 39 / 0.01), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** No shadow */
+    none: "none",
+    /** Cards, toasts, and lowest elevated surfaces */
+    sm: "0 18px 47px 0 rgb(17 24 39 / 0.03), 0 7.5px 19px 0 rgb(17 24 39 / 0.02), 0 4px 10.5px 0 rgb(17 24 39 / 0.02), 0 2.3px 5.8px 0 rgb(17 24 39 / 0.01), 0 0.5px 1.3px 0 rgb(17 24 39 / 0.01), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** Exceptional staged surface */
+    xl: "0 40px 80px 0 rgb(17 24 39 / 0.06), 0 20px 40px 0 rgb(17 24 39 / 0.05), 0 10px 20px 0 rgb(17 24 39 / 0.04), 0 5px 10px 0 rgb(17 24 39 / 0.03), 0 2px 4px 0 rgb(17 24 39 / 0.02), 0 0 0 1px rgb(17 24 39 / 0.05)",
+    /** Ringless bordered control and inline callout shadow */
+    xs: "0 0 4px 0 rgb(17 24 39 / 0.04)",
+};
+/**
+ * Shadow under each card in a fanned stack (SwatchFan, EditorialCard stack).
+ * A tighter, darker drop than the elevation scale, so overlapping cards
+ * separate from each other rather than from the page.
+ */
+export const fanCardShadow = "0 7px 10px -1px rgba(0, 0, 0, 0.1), 0 3.5px 7px -2px rgba(0, 0, 0, 0.1)";
+/** Inner shadow tokens */
+export const innerShadows = {
+    /** inset 0 1px 0 0 rgb(0 0 0 / 0.05) */
+    "2xs": "inset 0 1px 0 0 rgb(0 0 0 / 0.05)",
+    /** inset 0 2px 4px 0 rgb(0 0 0 / 0.05) */
+    sm: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)",
+    /** inset 0 1px 1px 0 rgb(0 0 0 / 0.05) */
+    xs: "inset 0 1px 1px 0 rgb(0 0 0 / 0.05)",
+};
+/** Drop shadow tokens (for CSS filter) */
+export const dropShadows = {
+    /** 0 25px 25px rgb(0 0 0 / 0.15) */
+    "2xl": "drop-shadow(0 25px 25px rgb(0 0 0 / 0.15))",
+    /** 0 4px 4px rgb(0 0 0 / 0.15) */
+    lg: "drop-shadow(0 4px 4px rgb(0 0 0 / 0.15))",
+    /** 0 3px 3px rgb(0 0 0 / 0.12) */
+    md: "drop-shadow(0 3px 3px rgb(0 0 0 / 0.12))",
+    /** 0 1px 2px rgb(0 0 0 / 0.15) */
+    sm: "drop-shadow(0 1px 2px rgb(0 0 0 / 0.15))",
+    /** 0 9px 7px rgb(0 0 0 / 0.1) */
+    xl: "drop-shadow(0 9px 7px rgb(0 0 0 / 0.1))",
+    /** 0 1px 1px rgb(0 0 0 / 0.05) */
+    xs: "drop-shadow(0 1px 1px rgb(0 0 0 / 0.05))",
+};

package/dist/tokens/size.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Size system for the Materia design system.
+ *
+ * Defines a shared T-shirt size scale (`ComponentSize`) used by most
+ * components (Button, Icon, Badge, etc.). Domain-specific size scales
+ * for specialised color/media preview components live in their own
+ * sibling token modules alongside this file.
+ *
+ * @module
+ */
+import type { ComponentSize } from "./component-sizes.js";
+import type { ResponsiveValue } from "./responsive.js";
+export { COMPONENT_SIZES } from "./component-sizes.js";
+export type { ComponentSize } from "./component-sizes.js";
+/**
+ * A component `size`: a single {@link ComponentSize}, or an object keyed by
+ * viewport breakpoints AND/OR `@`-prefixed container-query variants, freely
+ * mixed - e.g. `{ base: "sm", md: "lg" }` (viewport) or
+ * `{ base: "sm", md: "base", "@sm": "xl" }` (viewport + container in one).
+ * Bare keys respond to the window; `@`-keys respond to the nearest `@container`
+ * ancestor. Resolve to classes with `getResponsiveSizeClasses` from
+ * `tokens/responsive`; backing CSS comes from the `@source inline(...)` safelist
+ * in shared-styles.css.
+ */
+export type ResponsiveSize = ResponsiveValue<ComponentSize>;
+/**
+ * Canonical control heights per size token - the single source of truth so
+ * that ANY form-row control (Button, Input, Select, Combobox, InputGroup,
+ * NativeSelect, PhoneInput, …) is exactly the same height at a given `size`,
+ * and therefore aligns when placed next to another. Heights match the Figma
+ * Button ladder (sm 32 / default 36 / lg 40 / xl 48 / xxl 64), extended with
+ * Materia's extra small/interpolated steps.
+ *
+ * Compose it in a size cva: `${CONTROL_HEIGHT_CLASSES[size]} <padding> <text>`.
+ * Never hardcode a `h-*` in a control's size scale - pull it from here.
+ */
+export declare const CONTROL_HEIGHT_CLASSES: Record<ComponentSize, string>;
+/**
+ * Build a size→class record for a control by prefixing the shared canonical
+ * height onto each size's own padding/text/gap extras. Guarantees height
+ * alignment across controls by construction.
+ */
+export declare const withControlHeights: (extras: Record<ComponentSize, string>) => Record<ComponentSize, string>;

package/dist/tokens/size.js

@@ -0,0 +1,46 @@
+/**
+ * Size system for the Materia design system.
+ *
+ * Defines a shared T-shirt size scale (`ComponentSize`) used by most
+ * components (Button, Icon, Badge, etc.). Domain-specific size scales
+ * for specialised color/media preview components live in their own
+ * sibling token modules alongside this file.
+ *
+ * @module
+ */
+import { COMPONENT_SIZES } from "./component-sizes.js";
+export { COMPONENT_SIZES } from "./component-sizes.js";
+/**
+ * Canonical control heights per size token - the single source of truth so
+ * that ANY form-row control (Button, Input, Select, Combobox, InputGroup,
+ * NativeSelect, PhoneInput, …) is exactly the same height at a given `size`,
+ * and therefore aligns when placed next to another. Heights match the Figma
+ * Button ladder (sm 32 / default 36 / lg 40 / xl 48 / xxl 64), extended with
+ * Materia's extra small/interpolated steps.
+ *
+ * Compose it in a size cva: `${CONTROL_HEIGHT_CLASSES[size]} <padding> <text>`.
+ * Never hardcode a `h-*` in a control's size scale - pull it from here.
+ */
+export const CONTROL_HEIGHT_CLASSES = {
+    "2xs": "h-6",
+    xs: "h-7",
+    sm: "h-8",
+    base: "h-9",
+    lg: "h-10",
+    xl: "h-12",
+    "2xl": "h-14",
+    "3xl": "h-16",
+};
+/**
+ * Build a size→class record for a control by prefixing the shared canonical
+ * height onto each size's own padding/text/gap extras. Guarantees height
+ * alignment across controls by construction.
+ */
+export const withControlHeights = (extras) => {
+    // Seed from the real Record so the result is properly typed with no cast.
+    const result = { ...CONTROL_HEIGHT_CLASSES };
+    for (const size of COMPONENT_SIZES) {
+        result[size] = `${CONTROL_HEIGHT_CLASSES[size]} ${extras[size]}`;
+    }
+    return result;
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Square icon-control size ramp for the Materia design system.
+ *
+ * Shared by Checkbox and ExpandButton - both render a square, icon-bearing
+ * control (checkbox box / expand toggle) sized off the common
+ * {@link ComponentSize} scale. Extracted so the two cva definitions consume
+ * one source instead of hand-writing matching size rows.
+ *
+ * @module
+ */
+import type { ComponentSize } from "./size.js";
+/** Tailwind size + icon-size classes for each square control size. */
+export declare const SQUARE_CONTROL_SIZE_CLASSES: Record<ComponentSize, string>;

package/dist/tokens/square-control.js

@@ -0,0 +1,21 @@
+/**
+ * Square icon-control size ramp for the Materia design system.
+ *
+ * Shared by Checkbox and ExpandButton - both render a square, icon-bearing
+ * control (checkbox box / expand toggle) sized off the common
+ * {@link ComponentSize} scale. Extracted so the two cva definitions consume
+ * one source instead of hand-writing matching size rows.
+ *
+ * @module
+ */
+/** Tailwind size + icon-size classes for each square control size. */
+export const SQUARE_CONTROL_SIZE_CLASSES = {
+    "2xs": "size-3.5 rounded-sm [&_svg]:size-2.5",
+    xs: "size-4 rounded-sm [&_svg]:size-2.5",
+    sm: "size-4.5 [&_svg]:size-3",
+    base: "size-5 [&_svg]:size-3.5",
+    lg: "size-5.5 [&_svg]:size-4",
+    xl: "size-6 [&_svg]:size-4.5",
+    "2xl": "size-7 [&_svg]:size-5",
+    "3xl": "size-8 [&_svg]:size-6",
+};

package/dist/tokens/swatch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Swatch size system for the Materia design system.
+ *
+ * Chip sizes (circle/pill) use {@link swatchSizeMap}/{@link swatchSizePx};
+ * tile sizes (square material/image cards) use
+ * {@link swatchTileSizeMap}/{@link swatchTileSizePx}. Used by SwatchVisual,
+ * SwatchGroup, SwatchSelector, ColorPicker, and the Swatch tile renderer.
+ *
+ * @module
+ */
+import type { ComponentSize } from "./size.js";
+/**
+ * Chip swatch size system (circle/pill shapes).
+ * Used by SwatchVisual, SwatchGroup, SwatchSelector, ColorPicker.
+ */
+export type SwatchSize = "xs" | "sm" | "base" | "lg" | "xl" | "2xl";
+/**
+ * Chip-shape swatch sizes (circle/pill). Alias of {@link SwatchSize} - the
+ * discriminated `Swatch` type narrows `kind="circle" | "pill"` to this so a
+ * tile-only step (`3xs`/`2xs`) on a chip is a compile error.
+ */
+export type SwatchChipSize = SwatchSize;
+/**
+ * Tile-shape swatch sizes (square material/image cards). Superset of
+ * {@link SwatchSize} that adds the two tiniest steps (`3xs`/`2xs`).
+ */
+export type SwatchTileSize = "3xs" | "2xs" | "xs" | "sm" | "base" | "lg" | "xl" | "2xl";
+/** Tailwind size classes for each chip swatch size */
+export declare const swatchSizeMap: Record<SwatchSize, string>;
+/**
+ * Icon size for each swatch size (used by the Swatch icon overlay and
+ * SwatchGroupItem). Keyed by the full {@link SwatchTileSize} set so the map is
+ * total even though the chip icon path can only ever be reached with a
+ * {@link SwatchChipSize} (`3xs`/`2xs` are type-excluded from chips).
+ */
+export declare const swatchIconSizeMap: Record<SwatchTileSize, ComponentSize>;
+/** Pixel values for JS calculations (e.g., motion animations) */
+export declare const swatchSizePx: Record<SwatchSize, number>;
+/** Tailwind size classes for each tile swatch size (16–112px). */
+export declare const swatchTileSizeMap: Record<SwatchTileSize, string>;
+/** Pixel values for JS calculations (e.g., motion animations) */
+export declare const swatchTileSizePx: Record<SwatchTileSize, number>;

package/dist/tokens/swatch.js

@@ -0,0 +1,80 @@
+/**
+ * Swatch size system for the Materia design system.
+ *
+ * Chip sizes (circle/pill) use {@link swatchSizeMap}/{@link swatchSizePx};
+ * tile sizes (square material/image cards) use
+ * {@link swatchTileSizeMap}/{@link swatchTileSizePx}. Used by SwatchVisual,
+ * SwatchGroup, SwatchSelector, ColorPicker, and the Swatch tile renderer.
+ *
+ * @module
+ */
+/** Tailwind size classes for each chip swatch size */
+export const swatchSizeMap = {
+    // 56px
+    "2xl": "size-14",
+    // 28px (default)
+    base: "size-7",
+    // 32px
+    lg: "size-8",
+    // 24px
+    sm: "size-6",
+    // 48px
+    xl: "size-12",
+    // 20px
+    xs: "size-5",
+};
+/**
+ * Icon size for each swatch size (used by the Swatch icon overlay and
+ * SwatchGroupItem). Keyed by the full {@link SwatchTileSize} set so the map is
+ * total even though the chip icon path can only ever be reached with a
+ * {@link SwatchChipSize} (`3xs`/`2xs` are type-excluded from chips).
+ */
+export const swatchIconSizeMap = {
+    "2xl": "base",
+    "2xs": "2xs",
+    "3xs": "2xs",
+    base: "xs",
+    lg: "xs",
+    sm: "2xs",
+    xl: "sm",
+    xs: "2xs",
+};
+/** Pixel values for JS calculations (e.g., motion animations) */
+export const swatchSizePx = {
+    "2xl": 56,
+    base: 28,
+    lg: 32,
+    sm: 24,
+    xl: 48,
+    xs: 20,
+};
+/** Tailwind size classes for each tile swatch size (16–112px). */
+export const swatchTileSizeMap = {
+    // 112px
+    "2xl": "size-28",
+    // 24px
+    "2xs": "size-6",
+    // 16px
+    "3xs": "size-4",
+    // 64px
+    base: "size-16",
+    // 80px
+    lg: "size-20",
+    // 48px
+    sm: "size-12",
+    // 96px
+    xl: "size-24",
+    // 40px
+    xs: "size-10",
+};
+/** Pixel values for JS calculations (e.g., motion animations) */
+export const swatchTileSizePx = {
+    "2xl": 112,
+    "2xs": 24,
+    "3xs": 16,
+    base: 64,
+    lg: 80,
+    sm: 48,
+    xl: 96,
+    xs: 40,
+};