Material You CLI Plugin

A staticbolt CLI plugin that registers a palette command for generating Material You (Material Design 3) color palettes. It builds a full color system from a single seed color with Google's Material Design 3 algorithm.

Installation

The plugin ships as part of @staticbolt/core. You do not need to install anything else.

Usage

In your .staticbolt.ts configuration file:

import { defineConfig } from "@staticbolt/core";
import { materialYouCliPlugin } from "@staticbolt/core/plugins";

export default defineConfig({
  plugins: [materialYouCliPlugin()],
});

Then run from the command line:

npx staticbolt palette --color "#ff0000" --style TONAL_SPOT
# or using the alias
npx staticbolt material-you --color "#ff0000" --style TONAL_SPOT

# Save to a CSS file
npx staticbolt palette --color "#ff0000" --style TONAL_SPOT --raw > palette.css

# Output as JSON
npx staticbolt palette --color "#ff0000" --format json

Plugin Options

`command`

Type: string
Default: "palette"

The name of the CLI command to register.

materialYouCliPlugin({
  command: "color-palette",
});

`aliases`

Type: string[]
Default: ["material-you"]

Other names that also run the palette command.

materialYouCliPlugin({
  aliases: ["material-you", "palette"],
});

`color`

Type: string
Default: undefined (required at runtime)

Default seed color in HEX format. If provided, this sets the default value for the --color command-line option.

materialYouCliPlugin({
  color: "#ff0000",
});

`style`

Type: "SPRITZ" | "TONAL_SPOT" | "VIBRANT" | "EXPRESSIVE" | "RAINBOW" | "FRUIT_SALAD" | "CONTENT" | "MONOCHROMATIC"
Default: "TONAL_SPOT"

Default Material You generation style. If provided, this sets the default value for the --style command-line option.

materialYouCliPlugin({
  style: "VIBRANT",
});

`format`

Type: "css" | "json"
Default: "css"

Default output format. If provided, this sets the default value for the --format command-line option.

materialYouCliPlugin({
  format: "json",
});

`raw`

Type: boolean
Default: false

Default raw output flag. If true, the output has no syntax highlighting. If provided, this sets the default value for the --raw command-line option.

materialYouCliPlugin({
  raw: true,
});

Command Line Options

`--color <value>` / `-c <value>`

Required. The seed color to generate the palette from. Must be a HEX color in the format #RRGGBB.

npx staticbolt palette --color "#ff0000"
npx staticbolt palette -c "#ff0000"

`--style <value>` / `-s <value>`

Optional. The Material You generation style. One of: SPRITZ, TONAL_SPOT, VIBRANT, EXPRESSIVE, RAINBOW, FRUIT_SALAD, CONTENT, MONOCHROMATIC.

npx staticbolt palette --color "#ff0000" --style VIBRANT
npx staticbolt palette -c "#ff0000" -s VIBRANT

`--format <value>` / `-f <value>`

Optional. The output format: css or json.

npx staticbolt palette --color "#ff0000" --format json
npx staticbolt palette -c "#ff0000" -f json

`--raw` / `-r`

Optional. Print output without syntax highlighting.

npx staticbolt palette --color "#ff0000" --raw
npx staticbolt palette -c "#ff0000" -r

Generation Styles

Material You supports multiple palette generation approaches:

TONAL_SPOT: tonal variations of the seed color (default, recommended)
VIBRANT: saturated colors
EXPRESSIVE: more expressive and varied colors
SPRITZ: like TONAL_SPOT, with different hue shifts
RAINBOW: colors spread across the full spectrum
FRUIT_SALAD: a playful, colorful palette
CONTENT: tuned for content-heavy interfaces
MONOCHROMATIC: variations of a single hue

Output Formats

CSS Format

Generates CSS custom properties organized by color role:

:root {
  --clr-seed: #f00;
  --style: "TONAL_SPOT";

  /* pure */
  --clr-white: #fff;
  --clr-black: #000;

  /* primary */
  --clr-primary-10: #21005d;
  --clr-primary-50: #371e55;
  /* ... more shades ... */
}

The CSS output includes color shades at tonal ranges: 10, 50, 100, 150, ..., 950, 990. Each role's first and last tones, 0 and 1000, are left out of the CSS. The JSON output keeps them.

JSON Format

Generates a JSON object with color arrays grouped by role:

{
  "system_primary": ["#000", "#21005d", "#371e55", ...],
  "system_secondary": [...],
  "system_tertiary": [...]
}

Behavior

When executed, the palette command:

Validates the seed color is a valid HEX color in format #RRGGBB
Generates a Material You palette using the specified generation style
Formats the output according to the specified format (CSS or JSON)
Applies syntax highlighting (unless --raw is specified)
Outputs to stdout (can be redirected to a file)

This plugin usually goes last in the plugins array, next to the other CLI plugins. It does not take part in the build pipeline itself.

Examples

Generate a vibrant palette and save it to a CSS file:

npx staticbolt palette --color "#ff6b6b" --style VIBRANT --raw > vibrant.css

Generate a rainbow palette as JSON:

npx staticbolt palette --color "#3498db" --style RAINBOW --format json

Use default configuration from plugin options:

materialYouCliPlugin({
  color: "#ff0000",
  style: "TONAL_SPOT",
});

Then run with defaults:

npx staticbolt palette