dynamic-colorscheme

A lightweight TypeScript/JavaScript package for generating Material Design 3 dynamic color schemes. Built on top of Material Color Utilities, it allows you to create consistent, accessible, and theme-aware color palettes from a single seed color.

✨ Features

• 🎨 Generate full Material Design color schemes (light or dark) from a seed color.
• ♿ Contrast-aware and accessible by default.
• 🔄 Includes dynamic roles: primary, secondary, tertiary, error, surface, background, outline, etc.
• 🔧 Supports contrast level adjustment (-1.0 → low, 0.0 → normal, 1.0 → high).
• 📦 Simple TypeScript API with type definitions.

📦 Installation

npm install dynamic-colorscheme

or with Yarn:

yarn add dynamic-colorscheme

🚀 Usage

import { createColorScheme, Brightness, ColorScheme } from "dynamic-colorscheme";

// Generate a light scheme from a blue seed color
const lightScheme: ColorScheme = createColorScheme("#3a3a3a", "light");

// Generate a dark scheme with higher contrast
const darkScheme: ColorScheme = createColorScheme("#3a3a3a", "dark", 0.5);

console.log(lightScheme.primary); // e.g. "#6750A4"
console.log(darkScheme.surface);  // e.g. "#121212"

🎨 API

createColorScheme(seedColor: string, brightness?: Brightness, contrastLevel?: number): ColorScheme

Parameters

• seedColor: string — Hex color string (#RRGGBB) used as the seed.
• brightness: "light" | "dark" — Defaults to "light".
• contrastLevel: number — Contrast adjustment (-1.0 → low, 0.0 → default, 1.0 → high). Defaults to 0.0.

Returns

A fully populated ColorScheme object:

interface ColorScheme {
  brightness: "light" | "dark";

  primary: string;
  onPrimary: string;
  primaryContainer: string;
  onPrimaryContainer: string;
  primaryFixed: string;
  onPrimaryFixed: string;
  primaryFixedDim: string;
  onPrimaryFixedVariant: string;

  secondary: string;
  onSecondary: string;
  secondaryContainer: string;
  onSecondaryContainer: string;
  secondaryFixed: string;
  onSecondaryFixed: string;
  secondaryFixedDim: string;
  onSecondaryFixedVariant: string;

  tertiary: string;
  onTertiary: string;
  tertiaryContainer: string;
  onTertiaryContainer: string;
  tertiaryFixed: string;
  onTertiaryFixed: string;
  tertiaryFixedDim: string;
  onTertiaryFixedVariant: string;

  error: string;
  onError: string;
  errorContainer: string;
  onErrorContainer: string;

  surface: string;
  onSurface: string;
  surfaceDim: string;
  surfaceBright: string;
  surfaceContainerLowest: string;
  surfaceContainerLow: string;
  surfaceContainer: string;
  surfaceContainerHigh: string;
  surfaceContainerHighest: string;
  surfaceVariant: string;
  onSurfaceVariant: string;

  outline: string;
  outlineVariant: string;
  shadow: string;
  scrim: string;

  inverseSurface: string;
  inversePrimary: string;

  surfaceTint: string;
}

🛠 Example: Apply to a UI

import { createColorScheme } from "dynamic-colorscheme";

// Pick a brand color
const scheme = createColorScheme("#ff5722", "light");

document.body.style.backgroundColor = scheme.surface;
document.body.style.color = scheme.onSurface;

const button = document.createElement("button");
button.style.backgroundColor = scheme.primary;
button.style.color = scheme.onPrimary;
button.innerText = "Click Me";
document.body.appendChild(button);

📚 Related

• Material Design 3
• Material Color Utilities