@sandlada/material-theme-cli

A CLI based on the Material Design dynamic color system. Given a source color, it generates theme data and palette tokens and prints them to the terminal.

Runtime requirements: Node.js 22+ and ESM.

For the Simplified Chinese version, see README.zh-CN.md.

Installation

Global install

npm i -g @sandlada/material-theme-cli

Run locally in the repository

npm install
npm start -- "#0f774a"

npm start runs the build first and then launches the CLI entry point. For local development and verification, this is the most direct workflow.

Quick Start

The CLI has two main commands: g c (generate colors) and g p (generate palettes).

Generate Colors

material-theme-cli g c "#0f774a"

This prints CSS custom properties for all 59 Material Design color tokens to the terminal.

Generate Palettes (themed)

Generate all 6 Material palette families from a source color:

material-theme-cli g p "#0f774a"

Generate a Custom Palette

Create a single custom palette with your own prefix:

material-theme-cli g p my-brand "#0f774a"

Usage Guide

`g c` — Generate Colors

material-theme-cli g c [color] [options...]

Generates 59 Material Design color tokens (light + dark schemes). Each token emits a light-dark() value in CSS, or equivalent in other formats.

`g p` — Generate Palettes

Two modes depending on the number of arguments:

Themed palettes (1 argument): Generates all 6 palette families — primary, secondary, tertiary, error, neutral, neutral-variant.

material-theme-cli g p [color] [options...]

Custom palette (2 arguments): Generates a single palette with a custom prefix.

material-theme-cli g p [prefix] [color] [options...]

Backward compatibility: bare `[color]`

Running the CLI without a subcommand (e.g. material-theme-cli "#0f774a") is equivalent to g c. This is kept for backward compatibility.

Color Input Formats

The CLI accepts the following color syntaxes:

Syntax	Example	Description
Hex	`#0f774a`	Supports `#RGB`, `#RRGGBB`, `#RGBA`, and `#RRGGBBAA`. Pure hexadecimal values must keep the leading `#`, or they may be parsed as integers.
RGB	`rgb(15, 119, 74)`	Channels can be integers in the range `0-255`, or percentages from `0%-100%`.
RGBA	`rgba(15, 119, 74, 1)`	Only fully opaque alpha is accepted, meaning `1` or `100%`.
LAB	`lab(44.3, -15.2, 18.6)`	Converted directly from LAB values.
HCT	`hct(270, 75, 50)`	Useful when you want to provide Material color model values directly.
XYZ	`xyz(0.41, 0.21, 0.05)`	CIE XYZ (D65 white point) with normalized values (typically 0-1).
ARGB fn	`argb(0xff0f774a)`	Accepts a single ARGB integer.
ARGB int	`0xff0f774a` or `4278851722`	Supports decimal and `0x`-prefixed integers.
Random	`random`	Generates an opaque random color. `random-color` is also accepted for backward compatibility.

If the input is empty or unsupported, the CLI exits with an error.

random can be used in the positional argument and in the palette override options --primary, --secondary, --tertiary, --error, --neutral, and --neutral-variant.

Command Options

Common Options (all commands)

These options apply to g c, g p (both modes), and the bare [color] form.

Option	Default	Description
`--format <format>`	`css`	Output format. Supported values: `css`, `json`, `xml`, `yaml`, `js`, `ts`, and `csv`.
`--variant <variant>`	`neutral`	Dynamic scheme variant. Accepts numeric `0`–`8` or named: `MONOCHROME`, `NEUTRAL`, `TONAL_SPOT` / `TONALSPOT`, `VIBRANT`, `EXPRESSIVE`, `FIDELITY`, `CONTENT`, `RAINBOW`, `FRUIT_SALAD` / `FRUITSALAD`. Case-insensitive, underscores optional.
`--contrast-level <contrast-level>`	`0`	Contrast level. Only `-1`, `0`, and `1` are accepted.
`--spec-version <spec-version>`	`2025`	Design specification version. `2021`, `2025`, and `2026` are accepted. `2026` is mapped to the `2025` spec.
`--platform <platform>`	`phone`	Target platform. Only `phone` and `watch` are accepted.
`--primary <color>`	none	Overrides the primary palette.
`--secondary <color>`	none	Overrides the secondary palette.
`--tertiary <color>`	none	Overrides the tertiary palette.
`--error <color>`	none	Overrides the error palette.
`--neutral <color>`	none	Overrides the neutral palette.
`--neutral-variant <color>`	none	Overrides the neutral-variant palette.
`--var-prefix <prefix>`	auto*	Custom prefix for CSS variable / JSON / XML key names. Default: `md-sys-color-` for colors, `md-sys-ref-` for palettes. When provided, replaces the default verbatim — no infix is injected. On `g p` (custom), this option is ignored; the prefix comes from the positional argument.
`--help`	none	Displays help information.

* The actual default prefix depends on the command: g c defaults to md-sys-color, g p (themed) defaults to md-sys-ref. On g p (custom), the prefix is taken from the positional argument, and --var-prefix is ignored.

These palette override options accept the same syntax as the source color: Hex, RGB, RGBA, LAB, HCT, XYZ, ARGB function, and ARGB integer.

`g c` — Filtering Options

Option	Default	Description
`--include <token-name...>`	none	Whitelist. Keeps only the listed color tokens (e.g. `primary`, `on-primary`, `surface`).
`--exclude <token-name...>`	none	Blacklist. Removes the listed color tokens.

Notes:

--include and --exclude are mutually exclusive.
Names are normalized to kebab-case before matching (primaryContainer → primary-container).
Unknown names are reported as warnings and ignored.

`g p` (themed) — Palette Filtering Options

Option	Default	Description
`--include <token-name...>`	none	Keep only these palette families or specific tones (e.g. `primary`, `secondary-50`).
`--exclude <token-name...>`	none	Remove these palette families or specific tones. Mutually exclusive with `--include`.
`--tones <tone-list>`	`0..100`	Comma- or space-separated integer tones from `0` to `100` (e.g. `0, 10, 50, 100`). Limits all 6 families to these tones. `--palette-tones` is accepted as a deprecated alias.

`g p` (custom) — Palette Filtering Options

Option	Default	Description
`--include <token-name...>`	none	Keep only these tones from the custom palette (e.g. `my-prefix-10`, `my-prefix-50`, or plain `10`, `50`).
`--exclude <token-name...>`	none	Remove these tones from the custom palette. Mutually exclusive with `--include`.
`--tones <tone-list>`	`0..100`	Comma- or space-separated integer tones from `0` to `100`. Controls the default set of tones. `--palette-tones` is accepted as a deprecated alias.

For custom palettes, --include and --exclude extract the numeric tone from the token name. Plain numbers like 10 are also accepted. --include overrides --tones when both are provided.

Examples

Generate Colors (`g c`)

# Default CSS output
material-theme-cli g c "#0f774a"

# JSON output
material-theme-cli g c "#0f774a" --format json

# Only show primary and error tokens
material-theme-cli g c "#0f774a" --include primary error

# Exclude surface tokens
material-theme-cli g c "#0f774a" --exclude surface surface-dim surface-bright

# Custom variant and contrast
material-theme-cli g c "#0f774a" --variant FRUIT_SALAD --contrast-level 1

# Custom CSS variable prefix
material-theme-cli g c "#0f774a" --var-prefix my-app

# Override individual palette sources
material-theme-cli g c "#0f774a" --primary "#1d4ed8" --secondary "#14b8a6"

Generate Themed Palettes (`g p [color]`)

# Default: all 6 families × 101 tones = 606 tokens (CSS)
material-theme-cli g p "#0f774a"

# JSON output with selected tones
material-theme-cli g p "#0f774a" --format json --tones "0, 10, 50, 100"

# Limit to specific families
material-theme-cli g p "#0f774a" --include primary secondary

# Exclude neutral families
material-theme-cli g p "#0f774a" --exclude neutral neutral-variant

# Custom prefix
material-theme-cli g p "#0f774a" --var-prefix my-theme

Generate Custom Palette (`g p [prefix] [color]`)

# Single custom palette, all 101 tones
material-theme-cli g p my-brand "#0f774a"

# With specific tones
material-theme-cli g p my-brand "#0f774a" --tones "0, 50, 100"

# Include only specific tones
material-theme-cli g p my-brand "#0f774a" --include "10" --include "50"

# Exclude specific tones
material-theme-cli g p my-brand "#0f774a" --exclude my-brand-0 --exclude my-brand-100

Backward Compatibility (bare `[color]`)

# Equivalent to `g c`
material-theme-cli "#0f774a"
material-theme-cli random
material-theme-cli "#0f774a" --format json --include primary

Output Protocol

The CLI sends all output to stdout (the terminal). To save to a file, use shell redirection:

material-theme-cli g c "#0f774a" --format json > theme.json

Format Details

CSS: emits :root { ... } with --{prefix}-* custom properties using light-dark(light, dark) values. Default prefix: --md-sys-color- for color tokens, --md-sys-ref- for palette tokens. Custom --var-prefix replaces the default verbatim (no infix injection).
JSON / YAML: color output has top-level light, dark, scheme objects. Palette output has a top-level palette object.
XML: emits <?xml?> with <resources> containing <color> entries. Color names use _light / _dark suffixes.
JS / TS: emits ESM export const declarations with PascalCase + Light/Dark/Scheme suffixes.
CSV: header scheme,token-name,color-value with rows for each light/dark/scheme combination (colors) or each palette tone (palettes).

Keys are normalized to kebab-case (CSS, JSON), snake_case (XML), or PascalCase (JS/TS) and sorted alphabetically for deterministic output.

License

This project is released under the MIT License. See LICENSE for details. Third-party dependencies are governed by their own license terms.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.vscode		.vscode
docs		docs
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
index.js		index.js
package.json		package.json
rolldown.config.js		rolldown.config.js
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@sandlada/material-theme-cli

Installation

Global install

Run locally in the repository

Quick Start

Generate Colors

Generate Palettes (themed)

Generate a Custom Palette

Usage Guide

`g c` — Generate Colors

`g p` — Generate Palettes

Backward compatibility: bare `[color]`

Color Input Formats

Command Options

Common Options (all commands)

`g c` — Filtering Options

`g p` (themed) — Palette Filtering Options

`g p` (custom) — Palette Filtering Options

Examples

Generate Colors (`g c`)

Generate Themed Palettes (`g p [color]`)

Generate Custom Palette (`g p [prefix] [color]`)

Backward Compatibility (bare `[color]`)

Output Protocol

Format Details

License

About

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@sandlada/material-theme-cli

Installation

Global install

Run locally in the repository

Quick Start

Generate Colors

Generate Palettes (themed)

Generate a Custom Palette

Usage Guide

g c — Generate Colors

g p — Generate Palettes

Backward compatibility: bare [color]

Color Input Formats

Command Options

Common Options (all commands)

g c — Filtering Options

g p (themed) — Palette Filtering Options

g p (custom) — Palette Filtering Options

Examples

Generate Colors (g c)

Generate Themed Palettes (g p [color])

Generate Custom Palette (g p [prefix] [color])

Backward Compatibility (bare [color])

Output Protocol

Format Details

License

About

Topics

Resources

License

Code of conduct

Security policy

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

`g c` — Generate Colors

`g p` — Generate Palettes

Backward compatibility: bare `[color]`

`g c` — Filtering Options

`g p` (themed) — Palette Filtering Options

`g p` (custom) — Palette Filtering Options

Generate Colors (`g c`)

Generate Themed Palettes (`g p [color]`)

Generate Custom Palette (`g p [prefix] [color]`)

Backward Compatibility (bare `[color]`)