Material You Color

3.0.2 · active · verified Fri Apr 17

materialyoucolor is a pure Python library that implements the Material You color generation algorithms. It allows developers to extract dominant colors from images, generate custom color palettes, and apply Material You dynamic theming principles to their applications. As of version 3.0.2, it is actively developed with periodic updates, offering a robust solution for creating adaptive and personalized user interfaces.

Common errors

```
ModuleNotFoundError: No module named 'materialyoucolor.palettes'
```
cause Attempting to import from an incorrect or deprecated module path. Common when migrating from v2.x to v3.x where the module structure changed.

fix Verify the correct module path in the v3.x documentation. For example, `from materialyoucolor.palettes.tonal_palette import TonalPalette`.
```
ValueError: invalid literal for int() with base 10: '#FF00A3'
```
cause Passing a hex color string directly to a function that expects an integer (e.g., `Hct.from_int()`).

fix Convert the hex string to an integer: `Hct.from_int(int(hex_string[1:], 16))`.
```
AttributeError: 'Hct' object has no attribute 'get_argb'
```
cause Using an outdated method call (`get_argb`) on an `Hct` object after upgrading to version 3.x.

fix Access the ARGB integer directly via the `argb` attribute: `hct_instance.argb`.

Warnings

breaking Version 3.0.0 introduced significant API changes, including module restructuring and class name alterations, to align with `material-color-utilities` 0.2.0. This impacts import paths and method calls.
Fix: Review the official GitHub README and `material-color-utilities` documentation for the new module structure and API. Update all import statements and method calls accordingly.
gotcha The `Hct.from_int()` method and other core color functions expect an integer representation of an ARGB color, not a hexadecimal string directly. Passing a hex string will result in a `ValueError`.
Fix: Always convert hex color strings (e.g., '#RRGGBB') to integers using `int(hex_string[1:], 16)` before passing them to `Hct.from_int()` or similar functions.
deprecated The `get_argb()` method on `Hct` objects, common in earlier versions, has been replaced. Direct attribute access to `argb` is now the standard.
Fix: Replace `hct_instance.get_argb()` with `hct_instance.argb`.

Install

pip install materialyoucolor Install stable release

Imports

Hct

from materialyoucolor.hct.hct import Hct

QuantizerCelebi

from materialyoucolor.quantize.quantizer_celebi import QuantizerCelebi

SchemeFidelity
wrong:
```
from materialyoucolor.scheme import SchemeFidelity
```
correct:
```
from materialyoucolor.scheme.scheme_fidelity import SchemeFidelity
```
Scheme classes are directly under `materialyoucolor.scheme.<scheme_name>` in v3.x, not directly under `materialyoucolor.scheme`.

TonalPalette

wrong:

from materialyoucolor.palette.tonal_palette import TonalPalette

correct:

from materialyoucolor.palettes.tonal_palette import TonalPalette

The top-level module is `palettes` (plural), not `palette` (singular).

Quickstart

This quickstart demonstrates how to generate a Material You color scheme using a seed color. It shows how to convert a hex string to the `Hct` format and then use a `SchemeFidelity` to create both light and dark themes, printing some of the key generated colors.

from materialyoucolor.hct.hct import Hct
from materialyoucolor.scheme.scheme_fidelity import SchemeFidelity

# Define a seed color (e.g., from an image or a brand color)
seed_hex = "#FF00A3" # A vibrant magenta

# Convert hex string to integer for Hct
seed_argb_int = int(seed_hex[1:], 16)
seed_color_hct = Hct.from_int(seed_argb_int)

# Generate a Material You color scheme
# You can choose different schemes like SchemeVibrant, SchemeContent, etc.
# Set is_dark=True for a dark theme
scheme_light = SchemeFidelity(seed_color_hct, is_dark=False, contrast_level=0.0)
scheme_dark = SchemeFidelity(seed_color_hct, is_dark=True, contrast_level=0.0)

print("--- Light Scheme ---")
print(f"Primary color: {scheme_light.primary.hex}")
print(f"On Primary color: {scheme_light.on_primary.hex}")
print(f"Background color: {scheme_light.background.hex}")
print(f"Surface color: {scheme_light.surface.hex}")
print(f"Error color: {scheme_light.error.hex}")

print("\n--- Dark Scheme ---")
print(f"Primary color: {scheme_dark.primary.hex}")
print(f"Background color: {scheme_dark.background.hex}")

view raw JSON →