@instruments/materia-ui 0.1.0

package/dist/data/material-colors.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Default material colour palette - 65 swatches organised in 13 rows x 5 columns.
+ *
+ * Each row is one colour family, so a palette picker can offer a swatch per family.
+ * Organised by colour family, starting with neutrals (most common for materials)
+ * then progressing through the colour wheel.
+ *
+ * Row layout: Neutrals (5 rows) → Yellow → Green → Teal → Blue → Purple → Pink → Red → Orange
+ */
+export declare const DEFAULT_MATERIAL_COLORS: readonly ["fbfbfb", "dfdfdf", "b7b5b8", "777777", "000000", "eef2f5", "d8dbe2", "aeb6b9", "646c79", "002f43", "f6f6ee", "ece9da", "cfd0c0", "948d7b", "615b4d", "f4f0e7", "ded6cb", "c9ae9b", "927668", "4b2a23", "fffce9", "f9efd4", "efdcb2", "c5af8a", "9e805c", "fffdc4", "ffef76", "f0d262", "dba946", "b37b3e", "d7daaf", "d0cb6d", "88a85f", "269141", "29642e", "d8ecea", "a7dfd6", "54b3ab", "008d9e", "006268", "ccd8e4", "9abacf", "5f89bb", "0e5aa8", "012360", "ddcfde", "b89abe", "a26e95", "69227e", "3b0550", "f6c7d1", "f179a6", "d94792", "d2006b", "8a0151", "fcbaac", "ff6c64", "e1455b", "df002d", "b30038", "feba71", "ff983b", "fa6000", "cf3a00", "9f2000"];
+export type MaterialColor = (typeof DEFAULT_MATERIAL_COLORS)[number];
+/**
+ * Number of columns in the default colour grid layout
+ */
+export declare const DEFAULT_COLOR_COLUMNS = 5;
+/**
+ * Preview colour indices for collapsed state - 27 colours representing ALL colour families.
+ * Each of the 13 colour rows gets 2 representatives (light + medium/dark), plus 1 extra neutral.
+ *
+ * Goal: Show the full spectrum in mini mode. Expanded mode adds more shades within each family.
+ */
+export declare const PREVIEW_COLOR_INDICES: readonly [0, 2, 4, 5, 7, 10, 12, 16, 18, 21, 23, 26, 28, 31, 33, 36, 38, 41, 43, 46, 48, 51, 53, 56, 58, 61, 63];
+/**
+ * Check if a colour string is a light colour (for contrast/border visibility).
+ * Supports hex strings (with or without #) and HSL strings.
+ */
+export declare const isLightColor: (color: string) => boolean;
+/**
+ * Convert a hex colour string to a CSS HSL string via colorscope.
+ * @param hex - Hex colour with or without # (e.g., "fbfbfb")
+ * @returns HSL string (e.g., "hsl(0, 0%, 98%)")
+ */
+export declare const hexToHsl: (hex: string) => string;
+/**
+ * Get the HSL lightness value from a hex colour (0-100), via colorscope.
+ */
+export declare const getHexLightness: (hex: string) => number;
+/**
+ * Colour ring structure for the radial picker.
+ */
+export interface ColorRing {
+    colors: string[];
+    ring: number;
+}
+/**
+ * Curated colours for the radial picker, organised by hue wheel.
+ * Colours progress clockwise: red → orange → yellow → green → teal → blue → purple → pink
+ * Ring 0: 1 (white center)
+ * Ring 1: 6 (light pastels, ~60° apart)
+ * Ring 2: 12 (medium tones, ~30° apart)
+ * Ring 3: 18 (saturated colours, ~20° apart)
+ * Ring 4: 24 (dark colours + neutrals)
+ */
+export declare const MATERIAL_COLOR_RINGS: ColorRing[];
+/**
+ * Flat array of all material colours in HSL format.
+ */
+export declare const DEFAULT_MATERIAL_COLORS_HSL: string[];

package/dist/data/material-colors.js

@@ -0,0 +1,440 @@
+import { hexToHsl as colorscopeHexToHsl, hexToRgb as colorscopeHexToRgb, } from "@instruments/colorscope/convert";
+/**
+ * Default material colour palette - 65 swatches organised in 13 rows x 5 columns.
+ *
+ * Each row is one colour family, so a palette picker can offer a swatch per family.
+ * Organised by colour family, starting with neutrals (most common for materials)
+ * then progressing through the colour wheel.
+ *
+ * Row layout: Neutrals (5 rows) → Yellow → Green → Teal → Blue → Purple → Pink → Red → Orange
+ */
+export const DEFAULT_MATERIAL_COLORS = [
+    // Row 1: Pure neutrals (white → black)
+    // white
+    "fbfbfb",
+    // light grey
+    "dfdfdf",
+    // grey
+    "b7b5b8",
+    // medium grey
+    "777777",
+    // black
+    "000000",
+    // Row 2: Cool grays / Blue-grays
+    // cool white
+    "eef2f5",
+    // silver
+    "d8dbe2",
+    // cool grey
+    "aeb6b9",
+    // steel
+    "646c79",
+    // dark blue-gray
+    "002f43",
+    // Row 3: Warm grays / Greige
+    // warm white
+    "f6f6ee",
+    // greige light
+    "ece9da",
+    // sage grey
+    "cfd0c0",
+    // warm grey
+    "948d7b",
+    // brown grey
+    "615b4d",
+    // Row 4: Warm beige / Taupe
+    // ivory
+    "f4f0e7",
+    // beige
+    "ded6cb",
+    // taupe
+    "c9ae9b",
+    // warm brown
+    "927668",
+    // dark brown
+    "4b2a23",
+    // Row 5: Cream / Tan
+    // cream white
+    "fffce9",
+    // cream
+    "f9efd4",
+    // light tan
+    "efdcb2",
+    // tan
+    "c5af8a",
+    // brown
+    "9e805c",
+    // Row 6: Yellow / Gold
+    // light yellow
+    "fffdc4",
+    // yellow
+    "ffef76",
+    // gold
+    "f0d262",
+    // amber
+    "dba946",
+    // brown-gold
+    "b37b3e",
+    // Row 7: Yellow-green / Olive
+    // sage
+    "d7daaf",
+    // olive
+    "d0cb6d",
+    // green
+    "88a85f",
+    // bright green
+    "269141",
+    // forest
+    "29642e",
+    // Row 8: Teal / Cyan
+    // light teal
+    "d8ecea",
+    // aqua
+    "a7dfd6",
+    // teal
+    "54b3ab",
+    // dark teal
+    "008d9e",
+    // deep teal
+    "006268",
+    // Row 9: Blue
+    // light blue
+    "ccd8e4",
+    // sky blue
+    "9abacf",
+    // blue
+    "5f89bb",
+    // royal blue
+    "0e5aa8",
+    // navy
+    "012360",
+    // Row 10: Purple / Violet
+    // lavender
+    "ddcfde",
+    // light purple
+    "b89abe",
+    // purple
+    "a26e95",
+    // dark purple
+    "69227e",
+    // deep purple
+    "3b0550",
+    // Row 11: Pink
+    // light pink
+    "f6c7d1",
+    // pink
+    "f179a6",
+    // hot pink
+    "d94792",
+    // magenta
+    "d2006b",
+    // burgundy
+    "8a0151",
+    // Row 12: Red
+    // light coral
+    "fcbaac",
+    // coral red
+    "ff6c64",
+    // red
+    "e1455b",
+    // pure red
+    "df002d",
+    // dark red
+    "b30038",
+    // Row 13: Orange
+    // light orange
+    "feba71",
+    // orange
+    "ff983b",
+    // bright orange
+    "fa6000",
+    // rust
+    "cf3a00",
+    // dark orange
+    "9f2000",
+];
+const HSL_LIGHTNESS_REGEX = /hsl\(\s*\d+\s*,\s*\d+%?\s*,\s*(?<lightness>\d+)%?\s*\)/u;
+/**
+ * Number of columns in the default colour grid layout
+ */
+export const DEFAULT_COLOR_COLUMNS = 5;
+/**
+ * Preview colour indices for collapsed state - 27 colours representing ALL colour families.
+ * Each of the 13 colour rows gets 2 representatives (light + medium/dark), plus 1 extra neutral.
+ *
+ * Goal: Show the full spectrum in mini mode. Expanded mode adds more shades within each family.
+ */
+export const PREVIEW_COLOR_INDICES = [
+    // Row 1: Neutrals (3 - full range)
+    // white
+    0,
+    // grey
+    2,
+    // black
+    4,
+    // Row 2: Cool grays (2)
+    // cool white
+    5,
+    // cool grey
+    7,
+    // Row 3: Warm grays (2)
+    // warm white
+    10,
+    // sage grey
+    12,
+    // Row 4: Beige/taupe (2)
+    // beige
+    16,
+    // taupe
+    18,
+    // Row 5: Cream/tan (2)
+    // cream
+    21,
+    // tan
+    23,
+    // Row 6: Yellow (2)
+    // yellow
+    26,
+    // amber
+    28,
+    // Row 7: Green (2)
+    // olive
+    31,
+    // bright green
+    33,
+    // Row 8: Teal (2)
+    // aqua
+    36,
+    // dark teal
+    38,
+    // Row 9: Blue (2)
+    // sky blue
+    41,
+    // royal blue
+    43,
+    // Row 10: Purple (2)
+    // light purple
+    46,
+    // dark purple
+    48,
+    // Row 11: Pink (2)
+    // pink
+    51,
+    // magenta
+    53,
+    // Row 12: Red (2)
+    // coral red
+    56,
+    // pure red
+    58,
+    // Row 13: Orange (2)
+    // orange
+    61,
+    // rust
+    63,
+];
+/**
+ * Check if a colour string is a light colour (for contrast/border visibility).
+ * Supports hex strings (with or without #) and HSL strings.
+ */
+export const isLightColor = (color) => {
+    // Handle HSL format: hsl(h, s%, l%)
+    if (color.startsWith("hsl")) {
+        const lightnessText = HSL_LIGHTNESS_REGEX.exec(color)?.groups?.lightness;
+        if (lightnessText !== undefined) {
+            return Math.trunc(Number(lightnessText)) > 70;
+        }
+        return false;
+    }
+    // Handle hex format (with or without #). RGB channels via colorscope.
+    const rgb = colorscopeHexToRgb(color);
+    if (rgb === null) {
+        return false;
+    }
+    // Perceptual-weight luminance; >0.7 keeps the established light/dark cutoff.
+    const luminance = (0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b) / 255;
+    return luminance > 0.7;
+};
+/**
+ * Convert a hex colour string to a CSS HSL string via colorscope.
+ * @param hex - Hex colour with or without # (e.g., "fbfbfb")
+ * @returns HSL string (e.g., "hsl(0, 0%, 98%)")
+ */
+export const hexToHsl = (hex) => {
+    const hsl = colorscopeHexToHsl(hex);
+    if (hsl === null) {
+        return "hsl(0, 0%, 0%)";
+    }
+    return `hsl(${Math.round(hsl.h)}, ${Math.round(hsl.s)}%, ${Math.round(hsl.l)}%)`;
+};
+/**
+ * Get the HSL lightness value from a hex colour (0-100), via colorscope.
+ */
+export const getHexLightness = (hex) => {
+    const hsl = colorscopeHexToHsl(hex);
+    return hsl === null ? 0 : Math.round(hsl.l);
+};
+/**
+ * Curated colours for the radial picker, organised by hue wheel.
+ * Colours progress clockwise: red → orange → yellow → green → teal → blue → purple → pink
+ * Ring 0: 1 (white center)
+ * Ring 1: 6 (light pastels, ~60° apart)
+ * Ring 2: 12 (medium tones, ~30° apart)
+ * Ring 3: 18 (saturated colours, ~20° apart)
+ * Ring 4: 24 (dark colours + neutrals)
+ */
+export const MATERIAL_COLOR_RINGS = [
+    // Ring 0: Center - white
+    {
+        colors: [hexToHsl("fbfbfb")],
+        ring: 0,
+    },
+    // Ring 1: 6 light pastels (~60° spacing around wheel)
+    {
+        colors: [
+            // peach (H:10)
+            hexToHsl("fcbaac"),
+            // light yellow (H:58)
+            hexToHsl("fffdc4"),
+            // light green (H:64)
+            hexToHsl("d7daaf"),
+            // light teal (H:174)
+            hexToHsl("d8ecea"),
+            // light blue (H:210)
+            hexToHsl("ccd8e4"),
+            // light pink (H:347)
+            hexToHsl("f6c7d1"),
+        ],
+        ring: 1,
+    },
+    // Ring 2: 12 medium tones (~30° spacing)
+    {
+        colors: [
+            // coral (H:3)
+            hexToHsl("ff6c64"),
+            // light orange (H:31)
+            hexToHsl("feba71"),
+            // yellow (H:53)
+            hexToHsl("ffef76"),
+            // olive (H:57)
+            hexToHsl("d0cb6d"),
+            // green (H:86)
+            hexToHsl("88a85f"),
+            // aqua (H:170)
+            hexToHsl("a7dfd6"),
+            // teal (H:175)
+            hexToHsl("54b3ab"),
+            // sky blue (H:204)
+            hexToHsl("9abacf"),
+            // blue (H:213)
+            hexToHsl("5f89bb"),
+            // lavender (H:290)
+            hexToHsl("b89abe"),
+            // pink (H:338)
+            hexToHsl("f179a6"),
+            // red (H:352)
+            hexToHsl("e1455b"),
+        ],
+        ring: 2,
+    },
+    // Ring 3: 18 saturated/dark colours (~20° spacing)
+    {
+        colors: [
+            // pure red (H:348)
+            hexToHsl("df002d"),
+            // rust (H:17)
+            hexToHsl("cf3a00"),
+            // bright orange (H:23)
+            hexToHsl("fa6000"),
+            // orange (H:28)
+            hexToHsl("ff983b"),
+            // amber (H:40)
+            hexToHsl("dba946"),
+            // gold (H:47)
+            hexToHsl("f0d262"),
+            // bright green (H:135)
+            hexToHsl("269141"),
+            // forest (H:125)
+            hexToHsl("29642e"),
+            // dark teal (H:186)
+            hexToHsl("008d9e"),
+            // deep teal (H:183)
+            hexToHsl("006268"),
+            // royal blue (H:210)
+            hexToHsl("0e5aa8"),
+            // navy (H:219)
+            hexToHsl("012360"),
+            // dark purple (H:286)
+            hexToHsl("69227e"),
+            // deep purple (H:283)
+            hexToHsl("3b0550"),
+            // purple (H:315)
+            hexToHsl("a26e95"),
+            // hot pink (H:329)
+            hexToHsl("d94792"),
+            // magenta (H:329)
+            hexToHsl("d2006b"),
+            // dark red (H:341)
+            hexToHsl("b30038"),
+        ],
+        ring: 3,
+    },
+    // Ring 4: 24 colours - warm tones, neutrals, and darks (completing the palette)
+    {
+        colors: [
+            // dark brown (H:10)
+            hexToHsl("4b2a23"),
+            // dark orange (H:12)
+            hexToHsl("9f2000"),
+            // taupe dark (H:20)
+            hexToHsl("927668"),
+            // taupe (H:25)
+            hexToHsl("c9ae9b"),
+            // brown orange (H:31)
+            hexToHsl("b37b3e"),
+            // brown (H:33)
+            hexToHsl("9e805c"),
+            // tan (H:38)
+            hexToHsl("c5af8a"),
+            // beige (H:41)
+            hexToHsl("efdcb2"),
+            // cream (H:44)
+            hexToHsl("f9efd4"),
+            // warm beige (H:35)
+            hexToHsl("ded6cb"),
+            // sage (H:64)
+            hexToHsl("cfd0c0"),
+            // burgundy (H:325)
+            hexToHsl("8a0151"),
+            // light purple (H:296)
+            hexToHsl("ddcfde"),
+            // dark blue-gray (H:198)
+            hexToHsl("002f43"),
+            // silver (H:222)
+            hexToHsl("d8dbe2"),
+            // cool white (H:206)
+            hexToHsl("eef2f5"),
+            // warm white (H:42)
+            hexToHsl("f4f0e7"),
+            // ivory (H:60)
+            hexToHsl("f6f6ee"),
+            // cream white (H:52)
+            hexToHsl("fffce9"),
+            // warm white (H:50)
+            hexToHsl("ece9da"),
+            // light grey
+            hexToHsl("dfdfdf"),
+            // cool grey
+            hexToHsl("aeb6b9"),
+            // steel grey
+            hexToHsl("646c79"),
+            // black
+            hexToHsl("000000"),
+        ],
+        ring: 4,
+    },
+];
+/**
+ * Flat array of all material colours in HSL format.
+ */
+export const DEFAULT_MATERIAL_COLORS_HSL = DEFAULT_MATERIAL_COLORS.map(hexToHsl);

package/dist/data/token-gallery.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Design-token gallery data for `@instruments/materia-ui`.
+ *
+ * The canonical, framework-agnostic description of the design system's visual
+ * tokens - colours, shadows, blurs, radii, the type ramp, and the motion scale.
+ * Each entry pairs a token's Tailwind utility with its semantic key, display
+ * name and resolved value, so a gallery can render the live token and label it
+ * without hardcoding anything.
+ *
+ * This is the single source shared by the package's own Storybook token gallery
+ * (`src/stories/design-tokens.stories.tsx`) and the MateriaUI documentation site
+ * (`apps/materia-ui`). It lives in the public `./data/*` export tree precisely so
+ * the site can import it across the package boundary - deep-importing
+ * `src/stories` would violate the layer doctrine the site demonstrates.
+ *
+ * Only pure data lives here; the Storybook preview components (swatch/shadow/blur
+ * cells) stay beside the story in `design-tokens.stories.helpers.tsx`.
+ *
+ * @module
+ */
+/**
+ * A single visual token: the Tailwind utility that applies it, a semantic key,
+ * a display name, and the resolved CSS value (light theme) for reference.
+ */
+export interface TokenSwatch {
+    /** The Tailwind utility class that applies this token (e.g. `"bg-primary"`). */
+    class: string;
+    /** Semantic token key (e.g. `"primary"`, `"gray-500"`, `"brand-accent"`). */
+    key: string;
+    /** Human-readable display name. */
+    name: string;
+    /** The resolved CSS value in the light theme, shown as reference copy. */
+    value: string;
+}
+/** Look up a token by its `key`. Throws if the key is missing. */
+export declare const findByKey: <T extends {
+    key: string;
+}>(items: readonly T[], key: string) => T;
+/** Core semantic surface + text colours (the everyday palette). */
+export declare const BASE_COLORS: readonly TokenSwatch[];
+/** The neutral gray ramp (50 → 950). */
+export declare const GRAY_COLORS: readonly TokenSwatch[];
+/** Status + brand families, each a soft / accent / foreground triad. */
+export declare const SEMANTIC_COLORS: readonly TokenSwatch[];
+/** Translucent black / white overlays across the opacity scale. */
+export declare const ALPHA_COLORS: readonly TokenSwatch[];
+/** Box-shadow elevation ladder (gray-900 tinted, layered, with a 1px ring from `sm` up). */
+export declare const BOX_SHADOWS: readonly TokenSwatch[];
+/** Inset (inner) shadow ladder (from Figma). */
+export declare const INSET_SHADOWS: readonly TokenSwatch[];
+/** Drop-shadow (filter) ladder. */
+export declare const DROP_SHADOWS: readonly TokenSwatch[];
+/** Blur (filter) scale. */
+export declare const BLURS: readonly TokenSwatch[];
+/** Backdrop-blur scale (from Figma - mirrors the blur scale). */
+export declare const BACKDROP_BLURS: readonly TokenSwatch[];
+/**
+ * A radius token: its Tailwind utility, key, name, and resolved pixel value.
+ * The pixel value is theme-neutral, so a gallery can render it directly.
+ */
+export interface RadiusToken {
+    /** The Tailwind utility class (e.g. `"rounded-md"`). */
+    class: string;
+    /** Semantic key. */
+    key: string;
+    /** Display name (e.g. `"md"`, `"modal"`). */
+    name: string;
+    /** Resolved radius in CSS px (e.g. `"8px"`, `"36px"`). */
+    value: string;
+}
+/**
+ * The radius ladder (2xs → 5xl) plus the dedicated `rounded-modal` (36px) and
+ * `rounded-full`. The system's surface-weight story reads 16 inner · 24 card ·
+ * 36 dialog: `rounded-2xl` (16px) for inner elements, `rounded-3xl` (24px) for
+ * cards, and `rounded-modal` (36px) for dialogs.
+ */
+export declare const RADII: readonly RadiusToken[];
+/**
+ * One step of the type ramp - a `--text-*` token. The site renders each step at
+ * true size via its `cssVar` (and the paired `--…--line-height`), so the ramp is
+ * the design system's entire type scale, largest first.
+ */
+export interface TypeStep {
+    /** The Tailwind utility class (e.g. `"text-title"`). */
+    class: string;
+    /** The CSS custom property carrying the font size (e.g. `"--text-title"`). */
+    cssVar: string;
+    /** Semantic key. */
+    key: string;
+    /** Display name (e.g. `"Title"`, `"Paragraph"`). */
+    name: string;
+    /** Resolved font size for reference (rem, with px in parens). */
+    size: string;
+}
+/** The full type ramp, ordered display-first (title) down to `2xs`. */
+export declare const TYPE_RAMP: readonly TypeStep[];
+/**
+ * A duration token from the motion scale. `ms` is the raw value (for demos) and
+ * `cssVar` is the custom property to bind a transition to.
+ */
+export interface MotionDuration {
+    /** The CSS custom property (e.g. `"--duration-quick"`). */
+    cssVar: string;
+    /** Semantic key. */
+    key: string;
+    /** Duration in milliseconds. */
+    ms: number;
+    /** Display name. */
+    name: string;
+}
+/** The duration scale, instant → slow. Mirrors the canonical `durations` in tokens/motion.ts. */
+export declare const DURATIONS: readonly MotionDuration[];
+/**
+ * An easing token from the motion scale. `curve` is the raw `cubic-bezier(…)`
+ * (for SVG curve drawing + demos) and `cssVar` binds a transition timing.
+ */
+export interface MotionEasing {
+    /** The CSS custom property (e.g. `"--ease-out"`). */
+    cssVar: string;
+    /** The raw `cubic-bezier(…)` value. */
+    curve: string;
+    /** Semantic key. */
+    key: string;
+    /** Display name. */
+    name: string;
+}
+/** The three curves. Mirrors the canonical `easings` in tokens/motion.ts. */
+export declare const EASINGS: readonly MotionEasing[];