@scheme-tokens/material3

Generate 48 Material 3 system color roles from a source color as a scheme-tokens layer. By default, every role has light and dark values.

Install

pnpm add scheme-tokens @scheme-tokens/material3

Material 0.2.0 requires scheme-tokens: ^0.4.0. Both packages are ESM-only and support browsers and Node.js 24 or newer. See the TypeScript guide for supported compiler versions.

Generate a layer

import { material3 } from "@scheme-tokens/material3";

const material = material3("#6750a4");

The layer includes roles such as md.sys.color.primary, md.sys.color.on-primary, md.sys.color.surface, and md.sys.color.outline. Generated roles are public by default.

Compose a graph

The graph declares the modes and their default, then composes the generated layer:

import { defineTokenGraph } from "scheme-tokens";

const graph = defineTokenGraph({
  modes: ["light", "dark"],
  defaultMode: "light",
  layers: [material],
});

Compile the graph with compileTokenGraph(), then export it to CSS or serialize the resolved scheme. Default CSS names follow the role names, for example --md-sys-color-primary.

Map to application names

Keep the generated Material roles internal and expose the names your application actually uses. For shadcn/ui, those are names such as background, foreground, and primary:

import { material3 } from "@scheme-tokens/material3";
import { defineTokenGraph, tokenRef } from "scheme-tokens";

const material = material3("#6750a4", {
  visibility: "internal",
});

const graph = defineTokenGraph({
  modes: ["light", "dark"],
  defaultMode: "light",
  layers: [material],
  tokens: {
    background: tokenRef("md.sys.color.background"),
    foreground: tokenRef("md.sys.color.on-background"),
    primary: tokenRef("md.sys.color.primary"),
    "primary-foreground": tokenRef("md.sys.color.on-primary"),
  },
});

Default compilation resolves the internal Material roles and returns the public aliases. Graph-local tokens can override generated roles when needed.

Your app maps Material roles to its own semantic names; shadcn/Tailwind use those names. The mapping is application-owned. The core README shows the full shadcn mapping and .dark activation; the Material guide walks through CSS export. The Tailwind/shadcn guide connects --background and --primary to utilities such as bg-background and bg-primary.

Variants and contrast

import { material3 } from "@scheme-tokens/material3";

const material = material3("#6750a4", {
  specVersion: "2025",
  variant: "expressive",
  contrastLevel: 0.5,
});

| Setting | Default | Per-mode override | | --------------- | -------------- | ----------------- | | Source color | First argument | sourceColor | | variant | tonal-spot | Yes | | contrastLevel | 0 | Yes | | specVersion | 2021 | No | | visibility | public | No |

Source colors use #RRGGBB notation. Generated values are normalized to lowercase. Contrast ranges from -1 to 1. The 2025 spec supports neutral, tonal-spot, vibrant, and expressive; see the Material reference for the full variant list and input rules.

Configure modes

modeSettings replaces the default light/dark set. Its keys must match the graph's modes. Each entry can override source color, variant, and contrast independently:

import { material3, type Material3ModeSettings } from "@scheme-tokens/material3";
import { defineTokenGraph } from "scheme-tokens";

const modeSettings = {
  "light-high": {
    colorMode: "light",
    contrastLevel: 1,
  },
  "brand-dark": {
    colorMode: "dark",
    sourceColor: "#009489",
  },
} satisfies Material3ModeSettings<"light-high" | "brand-dark">;

const graph = defineTokenGraph({
  modes: ["light-high", "brand-dark"],
  defaultMode: "light-high",
  layers: [material3("#6750a4", { modeSettings })],
});

light and dark imply their colorMode. Custom names require it. A single-mode map is valid; an empty map is rejected.

TypeScript

TypeScript infers the generated role keys, modes, and visibility from inline options. For generic wrappers, reusable Material3Options, and optional settings, see the TypeScript reference.

Reference and licensing

• Material guide
• Material API, roles, and errors
• CSS export

The package bundles Material Color Utilities 0.4.0 and is licensed under MIT and Apache-2.0. See LICENSE, LICENSE-MATERIAL-COLOR-UTILITIES, and THIRD_PARTY_NOTICES.md.