DOCSEARCHbyAlgolia
Submit Docs

Material Color Utilities

repository·main·Indexed 25 days ago

https://github.com/material-foundation/material-color-utilities

A collection of low-level algorithms and utilities that power the Material Design 3 (M3) dynamic color system. It enables the generation of accessible, personalized color schemes from dynamic inputs like wallpapers using the HCT (Hue, Chroma, Tone) color space. Available for C++, Dart, Java, Swift, Kotlin, and TypeScript (@material/material-color-utilities). Key features include color quantization, scoring for UI suitability, and tonal palette generation.

Tokens
13.2K
Snippets
16
Records
89
Agent score
80%

What's inside Material Color Utilities

  1. Overview of Material Color Utilities

    main
    Material Color Utilities (MCU) is a collection of color libraries containing algorithms and utilities designed to power dynamic color systems. It enables the generation of beautiful, accessible color schemes based on dynamic inputs (such as a user's wallpaper) rather than relying on hand-picked colors. This supports Material 3's dynamic color system, providing flexibility, personalization, and visual accessibility through color contrast control.

  3. Overview of material_color_utilities

    main

    The material_color_utilities package provides the low-level algorithms and utilities that power the Material Design 3 color system. It includes capabilities for:

    • Choosing theme colors from images.
    • Creating tones of colors.
    • Working within a specialized color space.

    Note: This is a low-level package. If you want to implement high-level Material 3 features like dynamic color or color harmonization in an app, you should use the dynamic_color package instead.

  4. What is a DynamicScheme?

    main

    A DynamicScheme is the core interface for dynamic color clients. Instead of hardcoding specific color values, developers use a DynamicScheme to map color roles to actual colors.

    Think of the UI as a paint-by-number canvas: the color roles are the "numbers" (e.g., primary, onPrimary, surface), and the DynamicScheme provides the actual paint (the color values) for those numbers. This abstraction allows the app to update its entire color palette dynamically while ensuring that accessibility constraints (like contrast) and visual preferences are maintained.

  5. Understand the components of Material Color Utilities

    main

    The library is modular, allowing for the integration of specific subsets. The following components are available:

    • blend: Interpolate, harmonize, animate, and gradate colors in HCT.
    • contrast: Measure contrast and obtain contrastful colors.
    • dislike: Check and fix universally disliked colors.
    • dynamiccolor: Obtain colors that adjust based on UI state (dark theme, style, preferences, contrast requirements, etc.).
    • hct: A color space (hue, chrome, tone) based on CAM16 x L*, accounting for viewing conditions.
    • palettes: Provides Tonal palettes (colors varying only in tone) and Core palettes (sets of tonal palettes used to create Material color schemes).
    • quantize: Converts an image into N colors (uses Celebi, which runs Wu, then WSMeans).
    • scheme: Creates static and dynamic color schemes from a single color or a core palette.
    • score: Ranks colors for suitability for theming.
    • temperature: Obtains analogous and complementary colors.
    • utilities:
      • Color: Converts between color spaces for HCT/CAM16.
      • Math: Functions for hue normalization (0-360), clamping, etc.
      • String: Converts between strings and integers.

  7. Understand the HCT color system

    main

    HCT (Hue, Chroma, Tone) is a perceptually accurate color measurement system. Unlike traditional color spaces, it is designed to accurately render how colors appear in different lighting environments by using the CAM16 color appearance model. It allows you to manipulate color based on human perception rather than just raw light measurements.

    let hct = Hct.from(hue, chroma, tone)
let hct = Hct.fromInt(0x00000000)

  8. Understanding Cam16 and Viewing Conditions

    main

    Cam16 is a color appearance model that accounts for viewing conditions (e.g., lighting at noon vs. night, or background color differences). It aims to represent human perception of color accurately.

    In MCU, Cam16 is implemented using the ViewingCondition class to define the environment. Using different ViewingCondition objects with the same hex code can result in distinct Cam16 objects.

    A Cam16 object can be uniquely determined by:

    • A triple of {j, chroma, hue} (Cam16-JCH) OR {j, m, s} (Cam16-UCS) and hue.
    • A triple of jstar, astar, and bstar (Cam16-UCS).

    MCU specifically utilizes two sub-spaces:

    1. Cam16-JCH: Uses components j, chroma, and hue.
    2. Cam16-UCS: Uses components jstar, astar, and bstar.

  9. Constraints in Dynamic Scheme generation

    main

    When generating a DynamicScheme, MCU operates under two types of constraints:

    Hard constraints (Mandatory)

    • Contrast Ratio: Foreground and background contrast must fall within a specified range.
    • Role Tone Ranges: Specific color roles must fall within defined tone ranges.
    • Tone Delta: The difference in tone between a color and its Container counterpart (e.g., primary and primaryContainer) must exceed a minimum threshold.
    • Secondary Container Chroma: secondaryContainer prioritizes matching chroma over tone, meaning it may adjust tone specifically to get as close to the desired chroma as possible.
    • Tertiary Container: tertiaryContainer must not be lightened if it is disliked.

    Soft constraints (Ideal targets)

    • Reference Standard: Tones should stay as close to a "reference standard" as possible.
    • Even Distribution: Tones should ideally be distributed evenly across the color set.
    • Ideal Contrast: While specific contrast levels are preferred, they are not strictly required as long as minimum accessibility standards are met.

  10. Understand the HCT color space

    main

    Material Color Utilities (MCU) uses the HCT color space to manipulate colors predictably. HCT is defined by three dimensions:

    • Hue: The perception of color (e.g., red, blue). It is a circular spectrum from 0 to 360.
    • Chroma: The intensity or colorfulness of a color. 0 is completely gray; values in MCU typically top out around 120.
    • Tone: The perceived lightness or darkness (luminance). It ranges from 0 (pure black) to 100 (pure white).

    Tone is the most critical dimension for visual accessibility, as the difference in tone between two colors determines their contrast ratio.

  11. How MCU derives a Dynamic Scheme

    main

    Material Color Utilities (MCU) generates a DynamicScheme by solving algebraic formulas that balance visual accessibility, expression, and color trueness. The generation process follows five sequential steps:

    1. Starting tone specs: MCU assigns initial tone values to color roles based on the theme (e.g., primary might be Tone 40 in Light theme and Tone 80 in Dark theme). In non-fidelity schemes, these tones remain fixed. In fidelity schemes, they are subject to adjustment.
    2. Hue & chroma spec: MCU assigns hue and chroma values based on the scheme variant specification (e.g., matching the source color's hue or applying a specific hue shift).
    3. Fidelity tone adjustments: If a color is visually suboptimal or "impossible" (the hue cannot reach the target chroma at the assigned tone), MCU adjusts the tone using one of two behaviors:
      • Source: Adjusts the color's tone to match the source color's tone.
      • Reach Chroma: Adjusts the color's tone until the chroma reaches the value specified by the Variant.
    4. Global tone constraints: MCU applies global constraints to maintain visual hierarchy. These constraints take priority over fidelity tone adjustments if a conflict occurs.
    5. Contrast tone adjustments & requirements: MCU performs a final pass to ensure contrast ratios between foreground and background colors meet target levels. If a target is not met, the foreground color's tone is adjusted. While targets aim for specific levels, they are designed to ensure minimum WCAG/GAR requirements are met even if the exact target ratio is mathematically unreachable (e.g., against a mid-tone background).

  12. Understand Tonal Palettes and Key Colors

    main

    A Tonal Palette is a collection of colors that share the same hue and chroma but vary in Tone (lightness). MCU generates six core tonal palettes:

    • primary
    • secondary
    • tertiary
    • neutral
    • neutral variant
    • error

    Each palette contains tones ranging from 0 to 100.

    Key Colors are derived from a Source Color. A key color represents the hue and chroma of a tonal palette. Dynamic color generation uses 5 key colors to generate the 5 foundational tonal palettes used to build a dynamic scheme.