MaterialDesignColors.jl GitHub

Reference#

Every exported name, grouped by what it is for. Implementation internals — the CAM16 intermediates and the gamut solver's helpers — are documented in the source but deliberately kept out of the manual.

Module#

MaterialDesignColors

source 
MaterialDesignColors

A pure-Julia implementation of the HCT color space and the Material Design 3 color system: CAM16 appearance modelling, tonal palettes, scheme generation, and WCAG contrast helpers.

Ported from Google's material-color-utilities (Apache-2.0). See NOTICE.

Color space#

MaterialDesignColors.HCT

source 
HCT

A color in the HCT (Hue, Chroma, Tone) perceptual color space.

Fields

  • hue::Float64: 0–360 (circular). The perceived color on the color wheel.

  • chroma::Float64: 0–~113 (gamut-dependent max). Saturation intensity.

  • tone::Float64: 0 (black)–100 (white). Perceptual lightness (CIE L*).

MaterialDesignColors.HCT — Tuple{Real, Real, Real}

source 
HCT(hue, chroma, tone)

Construct an HCT color. Values are stored as-is; use to_hex to convert to sRGB (which may gamut-map the chroma if needed).

MaterialDesignColors.hct — Tuple{AbstractString}

source 
hct(hex::AbstractString) → HCT

Parse a hex color string (e.g. "#6750A4") to the HCT color space.

Examples

c = hct("#6750A4")
# HCT(281.8, 46.3, 40.0)  (approximately)

MaterialDesignColors.hct — Tuple{ColorTypes.Colorant}

source 
hct(c::Colorant) -> HCT

Convert any color from the ColorTypes ecosystem into HCT.

MaterialDesignColors.to_hex — Tuple{ColorTypes.Colorant}

source 
to_hex(c::Colorant) -> String

Format any color from the ColorTypes ecosystem as an uppercase #RRGGBB.

MaterialDesignColors.to_hex — Tuple{HCT}

source 
to_hex(c::HCT) → String

Convert an HCT color to the closest sRGB hex string ("#RRGGBB"). If the requested chroma is not achievable in sRGB, the maximum achievable chroma at the given hue and tone is used instead.

Examples

to_hex(HCT(281.8, 46.3, 40.0))  # "#6750A4" (approximately)

Tonal palettes#

MaterialDesignColors.TonalPalette

source 
TonalPalette

A color palette derived from a single hue and chroma, generating hex colors at any requested tone (0–100).

Fields

  • hue::Float64: Hue angle in degrees [0, 360).

  • chroma::Float64: Chroma value for this palette.

  • cache::Dict{Int,String}: Lazily populated tone → hex cache.

Examples

p = tonal_palette("#6750A4")
p[40]   # "#6750A4" (approximately)
p[80]   # a lighter version
p[10]   # a much darker version

MaterialDesignColors.TonalPalette — Tuple{Real, Real}

source 
TonalPalette(hue, chroma)

Create a tonal palette from explicit hue and chroma values.

MaterialDesignColors.precompute! — Tuple{TonalPalette}

source 
precompute!(p::TonalPalette)

Eagerly compute and cache all standard MD3 tone stops.

MaterialDesignColors.tonal_palette — Tuple{AbstractString}

source 
tonal_palette(seed_hex::AbstractString) → TonalPalette

Create a tonal palette from a seed hex color. Extracts hue and chroma from the seed using the HCT color space.

Examples

p = tonal_palette("#6750A4")
p[40]  # HCT at tone 40; to_hex(p[40]) ≈ "#6750A4"
p[90]  # light container color

MaterialDesignColors.tone_at — Tuple{TonalPalette, Int64}

source 
tone_at(p::TonalPalette, tone::Int) → HCT

Alias for p[tone].

Schemes#

MaterialDesignColors.color_scheme — Tuple{AbstractString}

source 
color_scheme(seed; dark=false, secondary=nothing, tertiary=nothing)

Generate the 34 MD3 color roles from seed, as RGB{Float64} values. Use hex_scheme when you need CSS hex strings instead.

MaterialDesignColors.color_scheme_pair — Tuple{AbstractString}

source 
color_scheme_pair(seed; secondary=nothing, tertiary=nothing)

The light and dark schemes for one seed, as RGB{Float64} values.

MaterialDesignColors.hex_scheme — Tuple{AbstractString}

source 
color_scheme(seed; dark=false, secondary=nothing, tertiary=nothing,
             contrast=:standard) → Dict{Symbol,String}

Generate a complete MD3 color scheme (29+ roles) from a seed color.

Arguments

  • seed::AbstractString: Primary seed hex color (e.g. "#6750A4").

  • dark::Bool=false: Generate dark mode scheme if true.

  • secondary::Union{AbstractString,Nothing}=nothing: Override the derived secondary palette with a custom seed hex.

  • tertiary::Union{AbstractString,Nothing}=nothing: Override the derived tertiary palette with a custom seed hex.

  • contrast::Symbol=:standard: Contrast level (:standard, :medium, :high). Currently only :standard is implemented.

Returns

A Dict{Symbol,String} mapping role names (e.g. :primary, :on_surface) to hex color strings.

Examples

scheme = color_scheme("#6750A4")
scheme[:primary]            # "#6750A4" (approximately)
scheme[:primary_container]  # light purple

dark_scheme = color_scheme("#6750A4"; dark=true)
dark_scheme[:primary]       # "#D0BCFF" (lighter for dark backgrounds)

MaterialDesignColors.hex_scheme_pair — Tuple{AbstractString}

source 
color_scheme_pair(seed; secondary=nothing, tertiary=nothing,
                  contrast=:standard) → (light, dark)

Generate both light and dark color schemes in one call. Returns a tuple of (light_scheme, dark_scheme).

Contrast#

MaterialDesignColors.contrast_ratio — Tuple{AbstractString, AbstractString}

source 
contrast_ratio(hex1::AbstractString, hex2::AbstractString) → Float64

Compute the WCAG 2.1 contrast ratio between two hex colors. Returns a value in [1, 21]. A ratio ≥ 4.5 meets WCAG AA for normal text; ≥ 3.0 meets AA for large text; ≥ 7.0 meets AAA.

Examples

contrast_ratio("#000000", "#FFFFFF")  # 21.0
contrast_ratio("#6750A4", "#FFFFFF")  # ≈ 5.3

MaterialDesignColors.contrast_ratio — Tuple{Float64, Float64}

source 
contrast_ratio(tone1::Float64, tone2::Float64) → Float64

Compute contrast ratio from two CIE L* tone values (0–100). Useful for checking contrast between HCT tones without converting to hex.

MaterialDesignColors.darker_tone — Tuple{Float64, Float64}

source 
darker_tone(tone::Float64, ratio::Float64) → Float64

Find the darkest tone (in CIE L*) that achieves at least the given contrast ratio against the input tone. Returns NaN if impossible.

MaterialDesignColors.lighter_tone — Tuple{Float64, Float64}

source 
lighter_tone(tone::Float64, ratio::Float64) → Float64

Find the lightest tone (in CIE L*) that achieves at least the given contrast ratio against the input tone. Returns NaN if impossible.

MaterialDesignColors.meets_aa — Tuple{AbstractString, AbstractString}

source 
meets_aa(hex_fg::AbstractString, hex_bg::AbstractString;
         large_text::Bool=false) → Bool

Check if a foreground/background color pair meets WCAG 2.1 AA contrast requirements. Normal text requires ≥ 4.5:1; large text requires ≥ 3.0:1.

MaterialDesignColors.meets_aaa — Tuple{AbstractString, AbstractString}

source 
meets_aaa(hex_fg::AbstractString, hex_bg::AbstractString;
          large_text::Bool=false) → Bool

Check if a foreground/background color pair meets WCAG 2.1 AAA contrast requirements. Normal text requires ≥ 7.0:1; large text requires ≥ 4.5:1.

Index#