AGENT SKILL

material-theme-builder

Generate Material Design 3 color themes programmatically from a source color using @material/material-color-utilities, the same engine that powers the Material Theme Builder. Use this when the user asks to generate an M3 color palette, create a custom theme from a brand color, or export M3 tokens to CSS, JSON, or framework configs.

License 许可
Apache-2.0
最近更新
2026-09-05
Stars
★ 0
Forks
0

01 前言 Front Matter

name
material-theme-builder
license
Apache-2.0
description
Generate Material Design 3 color themes programmatically from a source color using @material/material-color-utilities, the same engine that powers the Material Theme Builder. Use this when the user asks to generate an M3 color palette, create a custom theme from a brand color, or export M3 tokens to CSS, JSON, or framework configs.

02 资源文件 1

03 SKILL.md 正文

Material Theme Builder

Overview

Generate complete Material Design 3 color themes programmatically from any source color. This skill uses @material/material-color-utilities — the same color algorithm library that powers Google's Material Theme Builder — to produce accessible light/dark palettes, tonal ranges, and design tokens ready for CSS, JSON, or any framework.

Keywords: Material Theme Builder, color generation, dynamic color, theme export, @material/material-color-utilities, HCT, tonal palette, source color, brand color, CSS tokens, JSON export

When to Use

  • "Generate an M3 theme from my brand color"
  • "Create M3 color tokens from #FF9800"
  • "Export M3 palette as CSS custom properties"
  • Creating a new M3 project and need a complete color token set
  • Converting a hex brand color into a full M3 palette
  • Generating both light and dark theme tokens programmatically

How It Works

Material Color Utilities uses the HCT color space (Hue, Chroma, Tone) — a perceptually uniform color model built on CAM16 and L* — to generate five tonal palettes from a single source color:

  1. Primary — derived from the source color's hue
  2. Secondary — desaturated variant of the source hue
  3. Tertiary — complementary hue for contrast
  4. Neutral — very low chroma for surfaces and backgrounds
  5. Neutral Variant — slightly chromatic neutral for outlines

Each palette contains tones 0–100. Specific tones are mapped to semantic color roles (e.g., primary = tone 40 in light, tone 80 in dark).

Install

npm install @material/material-color-utilities

Generate a Theme

Use the generate-theme.mjs script in this skill's directory:

node generate-theme.mjs "#FF9800"                     # CSS output (default tonal-spot)
node generate-theme.mjs "#FF9800" --json               # JSON output
node generate-theme.mjs "#FF9800" --scheme expressive   # Expressive scheme variant

Available Scheme Variants

The --scheme flag selects from 9 dynamic color strategies defined in material-color-utilities:

Scheme Description
tonal-spot Default — balanced, versatile (used by Android Material You)
content Colors derived with fidelity to the source, good for photo-based themes
expressive Intentionally detached from source for bold, playful palettes
fidelity High fidelity to source hue, chroma-capped for accessibility
fruit-salad Vibrant, playful secondary and tertiary from offset hues
monochrome Achromatic — all palettes have zero chroma
neutral Near-achromatic — very low chroma for subtle, muted themes
rainbow Wide hue spread across primary, secondary, and tertiary
vibrant Saturated, colorful variant of tonal-spot

Quick Start (Node.js)

import {
  argbFromHex,
  hexFromArgb,
  themeFromSourceColor,
} from "@material/material-color-utilities";

// Generate from any hex source color
const theme = themeFromSourceColor(argbFromHex("#FF9800"));

// Extract light scheme
const light = theme.schemes.light.toJSON();
for (const [role, argb] of Object.entries(light)) {
  console.log(`${role}: ${hexFromArgb(argb)}`);
}

Full Theme with Surface Containers

The base themeFromSourceColor provides core roles. Surface container tones are derived from the neutral palette at specific tones:

import {
  argbFromHex,
  hexFromArgb,
  themeFromSourceColor,
} from "@material/material-color-utilities";

const theme = themeFromSourceColor(argbFromHex("#FF9800"));
const neutral = theme.palettes.neutral;
const primary = theme.palettes.primary;
const secondary = theme.palettes.secondary;
const tertiary = theme.palettes.tertiary;

// Light surface containers (tone values per M3 spec)
const lightSurfaces = {
  surface:                 neutral.tone(98),
  surfaceDim:              neutral.tone(87),
  surfaceBright:           neutral.tone(98),
  surfaceContainerLowest:  neutral.tone(100),
  surfaceContainerLow:     neutral.tone(96),
  surfaceContainer:        neutral.tone(94),
  surfaceContainerHigh:    neutral.tone(92),
  surfaceContainerHighest: neutral.tone(90),
};

// Dark surface containers
const darkSurfaces = {
  surface:                 neutral.tone(6),
  surfaceDim:              neutral.tone(6),
  surfaceBright:           neutral.tone(24),
  surfaceContainerLowest:  neutral.tone(4),
  surfaceContainerLow:     neutral.tone(10),
  surfaceContainer:        neutral.tone(12),
  surfaceContainerHigh:    neutral.tone(17),
  surfaceContainerHighest: neutral.tone(22),
};

// Fixed colors (consistent across light and dark)
const fixed = {
  primaryFixed:              primary.tone(90),
  onPrimaryFixed:            primary.tone(10),
  primaryFixedDim:           primary.tone(80),
  onPrimaryFixedVariant:     primary.tone(30),
  secondaryFixed:            secondary.tone(90),
  onSecondaryFixed:          secondary.tone(10),
  secondaryFixedDim:         secondary.tone(80),
  onSecondaryFixedVariant:   secondary.tone(30),
  tertiaryFixed:             tertiary.tone(90),
  onTertiaryFixed:           tertiary.tone(10),
  tertiaryFixedDim:          tertiary.tone(80),
  onTertiaryFixedVariant:    tertiary.tone(30),
};

Export Formats

CSS Custom Properties

function schemeToCss(scheme, selector = ":root") {
  const entries = Object.entries(scheme.toJSON());
  const props = entries
    .map(([key, argb]) => {
      const token = key.replace(/([A-Z])/g, "-$1").toLowerCase();
      return `  --md-sys-color-${token}: ${hexFromArgb(argb)};`;
    })
    .join("\n");
  return `${selector} {\n${props}\n}`;
}

console.log(schemeToCss(theme.schemes.light));
console.log(schemeToCss(theme.schemes.dark, '[data-theme="dark"]'));

JSON

function schemeToJson(scheme) {
  const result = {};
  for (const [key, argb] of Object.entries(scheme.toJSON())) {
    result[key] = hexFromArgb(argb);
  }
  return result;
}

const output = {
  source: "#FF9800",
  light: schemeToJson(theme.schemes.light),
  dark: schemeToJson(theme.schemes.dark),
};
console.log(JSON.stringify(output, null, 2));

Apply to DOM

import { applyTheme } from "@material/material-color-utilities";

const systemDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
applyTheme(theme, { target: document.body, dark: systemDark });

Custom Colors (Extended Palette)

Add brand-specific colors that harmonize with the generated theme:

const theme = themeFromSourceColor(argbFromHex("#FF9800"), [
  {
    name: "brand-green",
    value: argbFromHex("#4CAF50"),
    blend: true, // harmonize with the source color
  },
  {
    name: "warning",
    value: argbFromHex("#FFC107"),
    blend: false, // keep exact hue
  },
]);

// Access custom colors
for (const custom of theme.customColors) {
  console.log(`${custom.color.name}:`);
  console.log(`  light: ${hexFromArgb(custom.light.color)}`);
  console.log(`  dark:  ${hexFromArgb(custom.dark.color)}`);
}

Platform Libraries

Platform Package
TypeScript @material/material-color-utilities (npm)
Dart material_color_utilities (pub.dev)
Java/Kotlin Built into MDC-Android
Swift Source in material-color-utilities repo
C++ Source in material-color-utilities repo

Checklist

  • [ ] Source color chosen (brand primary or user-provided hex)
  • [ ] @material/material-color-utilities installed
  • [ ] Light and dark schemes generated via themeFromSourceColor
  • [ ] Surface container tokens derived from neutral palette tones
  • [ ] Fixed accent colors derived from primary/secondary/tertiary palette tones
  • [ ] Tokens exported in the target format (CSS, JSON, or framework config)
  • [ ] Custom/extended colors added if needed (with harmonization)
  • [ ] Both light and dark themes tested for WCAG contrast compliance

Resources

04 同仓库更多 Skills

pohlai88
pohlai88/afenda-xforge-v5

vercel-react-best-practices

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

★ 0
pohlai88
pohlai88/afenda-xforge-v5

turborepo

Turborepo monorepo build system and orchestration. Covers task pipelines, dependsOn syntax, caching configuration, remote cache, filtering, CI optimization, environment variables, workspace management, watch mode, package boundaries, and code generation. Use when configuring tasks, creating packages, setting up monorepo, sharing code between apps, running changed packages, debugging cache, optimizing CI, resolving workspace dependencies, enforcing package boundaries, or generating code.

★ 0
pohlai88
pohlai88/afenda-xforge-v5

tailwind

Tailwind CSS v4 patterns and design systems. Use when configuring Tailwind themes, building components, implementing dark mode, using container queries, migrating from v3, integrating shadcn/ui, or fixing build errors. Use for tailwind, css, styling, theme, design-tokens.

★ 0
pohlai88
pohlai88/afenda-xforge-v5

pnpm-workspace

pnpm workspace monorepo management with filtering, catalogs, and shared configs. Use when setting up monorepos, managing workspace dependencies, filtering package commands, or sharing configuration across packages.

★ 0
pohlai88
pohlai88/afenda-xforge-v5

material-design-3-typography

Applies Material Design 3 Expressive typography principles including variable fonts, type scales, and hierarchy. Use this when working on text styling, type hierarchy, readable interfaces, or when the user asks to apply Material Design 3 typography guidelines.

★ 0
pohlai88
pohlai88/afenda-xforge-v5

material-design-3-shape

Applies Material Design 3 Expressive shape and containment principles including rounded corners, morphing shapes, and container design. Use this when working on component shapes, borders, containment, or when the user asks to apply Material Design 3 shape guidelines.

★ 0