material-color-utilities: HCT color space and dynamic palettes for Material Design 3

What HCT is and why Material Design 3 built a new color space for it

HCT is a color space assembled from two existing standards. Hue and chroma come from CAM16, a color appearance model that accounts for viewing conditions such as ambient lighting, background brightness, and surrounding colors. Tone comes from L*, the perceptual lightness scale in CIELAB. Combining them produces a space where shifting tone while holding hue and chroma constant yields a color series that reads as consistent brightness across different displays and conditions.

The hct component implements that space. It differs from HSL and HSV, which use mathematical hue values that do not reflect human perception: two colors with the same HSL saturation can appear dramatically different in brightness to the eye. HCT removes that disconnect. Material Design 3's dynamic color system depends on this property to produce accessible palettes algorithmically, replacing the older practice of designers picking each tone individually to satisfy contrast requirements.

Eleven self-contained components, and the subset MDC-Android explicitly skips

The library divides its functionality into 11 components, each in its own folder with its own tests, designed to work independently so consumers can import subsets without taking the whole library. The README names that goal explicitly, pointing to the way Material Design Components and Android System UI embed subsets for their own use.

MDC-Android is cited as an example consumer that does not need quantization, scoring, or image extraction. Those 3 components handle the pipeline for extracting a palette from a source image: quantize turns an image into N representative colors, score ranks them for suitability as a theme seed, and the extraction path builds on both. A static scheme from a designer-specified seed skips all three.

The remaining 8 handle the core color work: blend for harmonization and interpolation, contrast for accessibility measurement, dislike for filtering unpleasant colors, dynamiccolor for state-aware palette generation, hct for the color space, palettes for tonal ranges, scheme for building schemes, temperature for analogous and complementary colors, and utilities for lower-level conversions.

Finding the package: TypeScript on npm, Dart on pub.dev, Java inside MDC-Android

The TypeScript implementation is published as @material/material-color-utilities on npm, at npmjs.com/package/@material/material-color-utilities. The README gives no install command, so the entry point is that npm listing. For Dart, material_color_utilities is on pub.dev. Java ships as part of MDC-Android, Material Design Components for Android, documented at github.com/material-components/material-components-android.

C++, Swift, and Kotlin implementations live in the repository's own cpp/, swift/, and kotlin/ top-level directories. The README does not list separate package registries for those three. Because the components are designed to be self-contained, the README notes that consumers can integrate subsets into other libraries rather than importing the whole package, which is how MDC-Android and Android System UI consume them.

Dynamic color and schemes that respond to dark mode, contrast preferences, and UI state

The dynamiccolor component generates colors that change based on active UI state: dark mode versus light mode, high-contrast versus standard contrast, and any custom preferences the application exposes. A single source color or core palette goes in, and the component produces the appropriate color for each semantic role (primary, secondary, surface, error) for the current conditions.

The scheme component provides ready-made static and dynamic color schemes built from either a single color or a core palette. A static scheme is a fixed set of colors, while a dynamic scheme recomputes colors as UI state changes. Both paths start from tonal palettes, which are ranges of colors that vary only in tone while holding hue and chroma constant. That property is what HCT provides, which is why the scheme system and the color space are tightly coupled in the library's design.

The quantize pipeline: Celebi orchestrates Wu, then WSMeans, to extract N colors from an image

The quantize component uses a three-algorithm chain that the README names explicitly: Celebi, which runs Wu, then WSMeans. Wu is a histogram-based color quantizer that produces a coarse initial palette quickly. WSMeans (Weighted Square Means) refines that initial set. Celebi is the wrapper that sequences the two. The README gives the algorithm composition but does not describe the API inputs, outputs, or parameters of the quantize call itself.

This chain is the part of the library that MDC-Android deliberately excludes. A team implementing image-based color theming, where the app adapts its palette to a user's wallpaper or selected photo, is the audience for these three components. Teams building static schemes from pre-chosen seed colors have no use for quantize and can omit that folder entirely.

After quantizing, the score component ranks the extracted colors for suitability as a theme seed. Near-grays and similar non-chromatic colors may appear frequently in an image but score poorly as theme seeds, so score filters before scheme generation.

The dislike component filters universally unpleasant colors, but its criteria are not documented

The dislike component's stated purpose is to check whether a color is universally disliked and, if so, fix it. The README records that purpose in the components table and says nothing more. What makes a color universally disliked, how the check determines it, and what the corrected color looks like relative to the original are all absent from the README.

That gap is relevant for any design system that builds on this library. A color the dislike check marks for correction could be a deliberate palette choice, and a silent modification of it at runtime is the kind of failure that surfaces late in development. A developer who needs to understand when this check fires and what it changes has to consult the source code in the dislike/ folder or the dev_guide/ directory in the repository, since the README provides only the component name and a one-line description.

Material Theme Builder as the no-code path and what the six-language layout looks like

For teams that need the palette but not the algorithm, Material Theme Builder provides 2 access points: a Figma plugin (plugin ID 1034969338659738588 in the Figma community) and a web tool at material-foundation.github.io/material-theme-builder. Both let designers try dynamic color themes and see how they transform a design. Using either tool requires no code and no library dependency. The README positions them as the design-workflow entry point.

For code-level adoption, the repository layout separates each language into its own top-level directory: cpp/, dart/, java/, kotlin/, swift/, and typescript/. A concepts/ folder and dev_guide/ folder sit alongside the language directories and hold documentation beyond what the README covers. The last push to the repository was on 2026-08-21. The library is distributed under the Apache-2.0 licence.

Editorial conclusion

Use material-color-utilities when you need Material Design 3's color algorithms in your own code: HCT color space calculations, dynamic scheme generation, or image-based palette extraction. Skip it when all you need is a ready-made palette: Material Theme Builder at material-foundation.github.io/material-theme-builder generates schemes from a source color without any code. If you do adopt the library, check the dislike component's behavior in your target environment before shipping, since the README does not define what it considers universally disliked or when the check fires.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. material-foundation/material-color-utilities on GitHub
4. README