material-theme-builder 2.1.2 → 3.0.0

package/dist/index.d.ts

@@ -1,9 +1,56 @@
 import { CustomColor, TonalPalette } from '@material/material-color-utilities';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/** DTCG color value (direct, non-alias) */
+type DtcgColorValue = {
+    colorSpace: string;
+    components: number[];
+    alpha: number;
+    hex: string;
+};
+/** A single DTCG color token */
+type DtcgColorToken = {
+    $type: "color";
+    $value: string | DtcgColorValue;
+    $description?: string;
+    $extensions: Record<string, unknown>;
+};
+/** A palette group: tone number → token */
+type DtcgPaletteGroup = Record<string, DtcgColorToken>;
+/** Direct RGBA color value for a Figma variable */
+type FigmaVariableColor = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/** Alias reference to another Figma variable by path */
+type FigmaVariableAlias = {
+    alias: string;
+};
+/** A per-mode value: either a direct color or an alias */
+type FigmaVariableValue = FigmaVariableColor | FigmaVariableAlias;
+/** A flat variable descriptor ready for the Figma Variables API */
+type FigmaVariable = {
+    path: string;
+    description?: string;
+    scopes?: string[];
+    values: Record<string, FigmaVariableValue>;
+};
+
+/** Options for the Tailwind CSS exporter. */
+type TailwindOptions = {
+    /** When true, append a shadcn CSS variable block after the Tailwind theme. */
+    shadcn?: boolean;
+};
+
+/** A custom color defined with a hex string instead of an ARGB integer. */
 type HexCustomColor = Omit<CustomColor, "value"> & {
     hex: string;
 };
+/** Available Material You color scheme variants. */
+declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];
+type SchemeName = (typeof schemeNames)[number];
+/** Configuration for the Material Color Utilities builder. */
 type McuConfig = {
     /** Source color in hex format (e.g., "#6750A4") used to generate the color scheme */
     source: string;
@@ -44,63 +91,22 @@ type McuConfig = {
      */
     prefix?: string;
 };
-declare const schemeNames: readonly ["tonalSpot", "monochrome", "neutral", "vibrant", "expressive", "fidelity", "content"];
-type SchemeName = (typeof schemeNames)[number];
-declare const tokenDescriptions: {
-    readonly background: "Default background color for screens and large surfaces.";
-    readonly error: "Color for error states, used on elements like error text and icons.";
-    readonly errorContainer: "Fill color for error container elements like error banners.";
-    readonly inverseOnSurface: "Color for text and icons on inverse surface backgrounds.";
-    readonly inversePrimary: "Primary color used on inverse surface, e.g. buttons on snackbars.";
-    readonly inverseSurface: "Background for elements that require reverse contrast, such as snackbars.";
-    readonly onBackground: "Color for text and icons displayed on the background.";
-    readonly onError: "Color for text and icons on error-colored elements.";
-    readonly onErrorContainer: "Color for text and icons on error container elements.";
-    readonly onPrimary: "Color for text and icons on primary-colored elements like filled buttons.";
-    readonly onPrimaryContainer: "Color for text and icons on primary container elements like tonal buttons.";
-    readonly onPrimaryFixed: "Color for text and icons on primary fixed elements, constant across themes.";
-    readonly onPrimaryFixedVariant: "Lower-emphasis color for text and icons on primary fixed elements.";
-    readonly onSecondary: "Color for text and icons on secondary-colored elements.";
-    readonly onSecondaryContainer: "Color for text and icons on secondary container elements.";
-    readonly onSecondaryFixed: "Color for text and icons on secondary fixed elements, constant across themes.";
-    readonly onSecondaryFixedVariant: "Lower-emphasis color for text and icons on secondary fixed elements.";
-    readonly onSurface: "High-emphasis color for text and icons on surface backgrounds.";
-    readonly onSurfaceVariant: "Medium-emphasis color for text and icons on surface variant backgrounds.";
-    readonly onTertiary: "Color for text and icons on tertiary-colored elements.";
-    readonly onTertiaryContainer: "Color for text and icons on tertiary container elements.";
-    readonly onTertiaryFixed: "Color for text and icons on tertiary fixed elements, constant across themes.";
-    readonly onTertiaryFixedVariant: "Lower-emphasis color for text and icons on tertiary fixed elements.";
-    readonly outline: "Subtle color for borders and dividers to create visual separation.";
-    readonly outlineVariant: "Lower-emphasis border color used for decorative dividers.";
-    readonly primary: "Main brand color, used for key components like filled buttons and active states.";
-    readonly primaryContainer: "Fill color for large primary elements like cards and tonal buttons.";
-    readonly primaryFixed: "Fixed primary color that stays the same in light and dark themes.";
-    readonly primaryFixedDim: "Dimmed variant of the fixed primary color for lower emphasis.";
-    readonly scrim: "Color overlay for modals and dialogs to obscure background content.";
-    readonly secondary: "Accent color for less prominent elements like filter chips and selections.";
-    readonly secondaryContainer: "Fill color for secondary container elements like tonal buttons and input fields.";
-    readonly secondaryFixed: "Fixed secondary color that stays the same in light and dark themes.";
-    readonly secondaryFixedDim: "Dimmed variant of the fixed secondary color for lower emphasis.";
-    readonly shadow: "Color for elevation shadows applied to surfaces and components.";
-    readonly surface: "Default surface color for cards, sheets, and dialogs.";
-    readonly surfaceBright: "Brightest surface variant, used for elevated surfaces in dark themes.";
-    readonly surfaceContainer: "Middle-emphasis container color for grouping related content.";
-    readonly surfaceContainerHigh: "Higher-emphasis container color for elements like cards.";
-    readonly surfaceContainerHighest: "Highest-emphasis container color for text fields and other input areas.";
-    readonly surfaceContainerLow: "Lower-emphasis container color for subtle surface groupings.";
-    readonly surfaceContainerLowest: "Lowest-emphasis container, typically the lightest surface in light theme.";
-    readonly surfaceDim: "Dimmest surface variant, used for recessed areas or dark theme backgrounds.";
-    readonly surfaceTint: "Tint color applied to surfaces for subtle primary color elevation overlay.";
-    readonly surfaceVariant: "Alternative surface color for differentiated areas like sidebar backgrounds.";
-    readonly tertiary: "Third accent color for complementary elements that balance primary and secondary.";
-    readonly tertiaryContainer: "Fill color for tertiary container elements like complementary cards.";
-    readonly tertiaryFixed: "Fixed tertiary color that stays the same in light and dark themes.";
-    readonly tertiaryFixedDim: "Dimmed variant of the fixed tertiary color for lower emphasis.";
-};
-type TokenName = keyof typeof tokenDescriptions;
+/**
+ * Build a Material You color theme from a hex source color.
+ *
+ * Returns an object with lazy accessors for CSS, JSON, Figma variables,
+ * and Figma DTCG tokens.
+ *
+ * @example
+ * ```ts
+ * const theme = builder("#6750A4");
+ * const css = theme.toCss();
+ * const json = theme.toJson();
+ * ```
+ */
 declare function builder(hexSource: McuConfig["source"], { scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, customColors: hexCustomColors, prefix, }?: Omit<McuConfig, "source">): {
-    toCss(): string;
-    toJson(): {
+    toCss: () => string;
+    toJson: () => {
         seed: string;
         coreColors: Record<string, string>;
         extendedColors: {
@@ -112,54 +118,33 @@ declare function builder(hexSource: McuConfig["source"], { scheme, contrast, pri
         schemes: Record<string, Record<string, string>>;
         palettes: Record<string, Record<string, string>>;
     };
-    toFigmaTokens(): {
+    toFigmaVariables: () => FigmaVariable[];
+    toFigmaTokens: () => {
         "Light.tokens.json": {
+            $extensions: {
+                "com.figma.modeName": string;
+            };
             ref: {
-                palette: Record<string, Record<string, {
-                    $type: "color";
-                    $value: {
-                        colorSpace: "srgb";
-                        components: number[];
-                        alpha: number;
-                        hex: string;
-                    };
-                    $extensions: {
-                        "com.figma.scopes": string[];
-                        "com.figma.isOverride": boolean;
-                    };
-                }>>;
+                palette: Record<string, DtcgPaletteGroup>;
             };
             sys: {
-                color: Record<string, unknown>;
+                color: Record<string, DtcgColorToken>;
             };
+        };
+        "Dark.tokens.json": {
             $extensions: {
                 "com.figma.modeName": string;
             };
-        };
-        "Dark.tokens.json": {
             ref: {
-                palette: Record<string, Record<string, {
-                    $type: "color";
-                    $value: {
-                        colorSpace: "srgb";
-                        components: number[];
-                        alpha: number;
-                        hex: string;
-                    };
-                    $extensions: {
-                        "com.figma.scopes": string[];
-                        "com.figma.isOverride": boolean;
-                    };
-                }>>;
+                palette: Record<string, DtcgPaletteGroup>;
             };
             sys: {
-                color: Record<string, unknown>;
-            };
-            $extensions: {
-                "com.figma.modeName": string;
+                color: Record<string, DtcgColorToken>;
             };
         };
     };
+    toTailwind: (options?: TailwindOptions) => string;
+    toFlutter: () => string;
     mergedColorsLight: {
         [x: string]: number;
     };
@@ -176,16 +161,4 @@ declare function builder(hexSource: McuConfig["source"], { scheme, contrast, pri
     };
 };
 
-declare function Mcu({ source, scheme, contrast, primary, secondary, tertiary, neutral, neutralVariant, error, colorMatch, customColors, prefix, children, }: McuConfig & {
-    children?: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-
-type Api = {
-    initials: McuConfig;
-    setMcuConfig: (config: McuConfig) => void;
-    getMcuColor: (colorName: TokenName, theme?: string) => string;
-    allPalettes: Record<string, TonalPalette>;
-};
-declare const useMcu: () => Api;
-
-export { Mcu, builder, useMcu };
+export { type McuConfig, builder };