Material color utilities

Overview

Material color utilities

Algorithms and utilities that power the Material Design 3 (M3) color system, including choosing theme colors from images and creating tones of colors; all in a new color space.

Code availability

Language Availability Package
C/C++ Coming soon
Dart material_color_utilities
Java
Objective-C Coming soon
TypeScript

Need another platform/language? Open an issue.

Usage

Image to color

A common use case for this library is extracting a single color from an image. Here's how to do that:

Coming soon

Cheat sheet

library cheat sheet

Background

Learn about the M3 color system.

Components

The library is built out of multiple components

  • each with its own folder and tests
  • each as small as possible

This enables easy merging and updating of subsets into other libraries, such as Material Design Components, Android System UI, etc.

  • Not all consumers will need every component — ex. MDC doesn’t need quantization/scoring/image extraction

Quantize

  • Turns a wallpaper into N colors
  • Celebi, which runs Wu, then WSMeans

Score

  • Rank colors for suitability for theming
  • Quantize buckets a wallpaper into 128 colors
  • Enables deduplicating and ranking that output.

Scheme

  • Mapping from roles, i.e. names like primary, to colors.

Palettes

  • Tonal Palette — range of colors that varies only in tone
  • Core Palette — set of tonal palettes needed to create Material color schemes

HCT

  • Hue, chroma, tone
  • A new color space based on CAM16 x L*
  • Accounts for viewing conditions

Blend

  • Color interpolation in HCT
  • Harmonizing, animations, gradients

Utils

  • Color — conversions between color spaces needed to implement HCT/CAM16
  • Math — functions for ex. ensuring hue is between 0 and 360, clamping, etc.

Design Tooling

The Material Theme Builder Figma plugin is recommended for design workflows. It delivers dynamic color to where design is done. Designers can take an existing design, and see what it looks like under different themes, with just a couple clicks.

Comments
  • Getting the color tone value in a palette

    Getting the color tone value in a palette

    My usecase is generating relative tones. Right now, I have to loop through TonalPalette results with floating point precision to get the nearest tone value of my input color. Would it be possible to add a helper fn that returns the tone value of input color in the palette that TonalPalette creates?

    opened by mystrdat 6
  • How is neutral color created?

    How is neutral color created?

    Sorry if this is not the right place to ask but I want to know how the neutral color is created. Is it hard coded to certain shade of gray or is it derived from the primary color? If so, what is the calculation for conversion between primary and neutral color?

    opened by Whip 4
  • NPM package.json missing

    NPM package.json missing "main" definition

    When using the TypeScript library I ran into the following error:

    Module not found: Error: Can't resolve '@material/material-color-utilities' in '...'
    

    This is due to the following line missing in package.json:

    "main": "./dist/index.js",
    

    This in package version 0.1.1

    opened by niekvb 2
  • Question about Scheme and/or ColorPalette behavior

    Question about Scheme and/or ColorPalette behavior

    Consider the following code:

    import 'package:flutter/material.dart';
    import 'package:material_color_utilities/material_color_utilities.dart';
    
    void main() {
      const color = Colors.blue;
      final scheme = Scheme.light(color.value);
    }
    

    Should color.value be equal to scheme.primary? Right now these two values are different.

    I can see that Scheme.light calls CorePalette.of(color) and then assign corePalette.primary.get(40) as the primary color. Maybe another question would be should corePalette.primary.get(40) be equal to the color that was provided initially?

    I was also reading the color system page, and seems like the primary color should have a tone of 40. So I'm just wondering what's the expected behavior when using Scheme.light and/or CorePlatte.of?

    question 
    opened by zeshuaro 2
  • The chroma results seem incorrect for colors near amber

    The chroma results seem incorrect for colors near amber

    Ref: color amber (0xffffbf00) / RGB(255, 191, 0) / HSV(hue: 45° (44.941), saturation: 100% (1.000), value: 100% (1.000)) // hsla(45, 100%, 50%, 1.0) // hsluv H: 57.150, S: 100.026, L: 81.031 // CIELuv L: 81.031, C: 99.176, H: 57.150

    HCT tests for this color produces a chroma of 60.7, yet it is fully saturated using all other tested spaces/models (see above). HCT tests have been run using the dart package imported as well as using the test web page for .Net C##. The results are identical using either approach (web tests or inline/imported dart packages).

    Is this correct or is this a result of the CAM16 derivation?

    We are excited about HCT and hope to use it to classify and describe colors, e.g. pale, vivid, dull, etc. To replace HSV with HCT -- the desired approach -- we would rely heavily on the chroma and tonal values produced by HCT.

    opened by TriMontana 1
  • Update the value of the Dart package's `repository` field

    Update the value of the Dart package's `repository` field

    Hi, I see this is a read-only mirror (so I'm opening an issue instead of a PR). It would be useful to update the value the the Dart package's repository field to include information about the package's path within the repo - as well as the repo's url itself. This helps tooling know where to find the dart code, now which commits actually affect the dart package, ...

    Here's what the field should look like:

    repository: https://github.com/material-foundation/material-color-utilities/tree/main/dart
    

    Thanks!

    opened by devoncarew 1
  • HCT produces unexpected RGB values

    HCT produces unexpected RGB values

    This is most noticable when the seed color is yellow:

    Untitled Background color is Primary 98.

    I have made a graph that shows the RGB value, with chroma set to 100: different-models I included CAM16 (that also seems to be broken) and HSL as a reference. These images were made using my C# library, but it shouldn't have any differences, as most of it is just the Java version copy-pasted. I also added every test from the Dart library, which are all passing.

    Setting the chroma to a lower value seems to alleviate the problem a bit: different-chromas This was made with Flutter, here is the code for that:

    import 'package:flutter/material.dart';
    import 'package:material_color_utilities/material_color_utilities.dart';
    
    void main() {
      runApp(CustomPaint(
        painter: ColorsPainter(),
      ));
    }
    
    class ColorsPainter extends CustomPainter {
      @override
      void paint(Canvas canvas, Size size) {
        for (double x = 0; x < 360; x++) {
          for (double y = 0; y < 100; y++) {
            HctColor hct = HctColor.from(x, 100, y);
            canvas.drawCircle(Offset(x, y), 1, Paint()..color = Color(hct.toInt()));
          }
        }
      }
    
      @override
      bool shouldRepaint(ColorsPainter oldDelegate) {
        return false;
      }
    }
    

    Flutter code for the CAM16 graph (produces the same result as C# above):

    import 'package:flutter/material.dart';
    import 'package:material_color_utilities/material_color_utilities.dart';
    
    void main() {
      runApp(CustomPaint(
        painter: ColorsPainter(),
      ));
    }
    
    class ColorsPainter extends CustomPainter {
      @override
      void paint(Canvas canvas, Size size) {
        for (double x = 0; x < 360; x++) {
          for (double y = 0; y < 100; y++) {
            Cam16 cam = Cam16.fromJch(y, 100, x);
            canvas.drawCircle(
                Offset(x, y), 1, Paint()..color = Color(cam.viewedInSRgb));
          }
        }
      }
    
      @override
      bool shouldRepaint(ColorsPainter oldDelegate) {
        return false;
      }
    }
    
    opened by albi005 1
  • Add

    Add "type": "module" to support Node's ES module loader

    For the TypeScript package, the published package.json does not include a { "type": "module" } specification, which means that Node treats the package modules as CommonJS modules. However, the compiled output only contains ECMAScript modules (e.g. export statements).

    This means that the package cannot be imported using vanilla Node.js, because it treats the package/modules as CommonJS modules. There isn't really a way to override this behaviour as a library user.

    This results in syntax errors, for example:

    (node:11542) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
    (Use `node --trace-warnings ...` to show where the warning was created)
    /my-project/node_modules/@material/material-color-utilities/dist/index.js:17
    export * from './blend/blend';
    ^^^^^^
    
    SyntaxError: Unexpected token 'export'
        at Object.compileFunction (node:vm:352:18)
        at wrapSafe (node:internal/modules/cjs/loader:1027:15)
        at Module._compile (node:internal/modules/cjs/loader:1063:27)
        at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
        at Module.load (node:internal/modules/cjs/loader:975:32)
        at Function.Module._load (node:internal/modules/cjs/loader:822:12)
        at ModuleWrap.<anonymous> (node:internal/modules/esm/translators:170:29)
        at ModuleJob.run (node:internal/modules/esm/module_job:198:25)
        at async Promise.all (index 0)
        at async ESMLoader.import (node:internal/modules/esm/loader:385:24)
    
    Node.js v17.8.0
    

    This should be resolvable by either publishing CommonJS modules, or by making it explicit that this package uses ECMAScript modules. The latter can be achieved by adding {"type": "module"} to package.json or by using .mjs extensions. In addition, all compiled imports should explicitly specify the file extension (see #35).

    See also:

    • https://nodejs.org/dist/latest-v17.x/docs/api/packages.html
    • https://nodejs.org/dist/latest-v17.x/docs/api/esm.html
    opened by victorandree 1
  • fix[typescript]: Change `type` to `module` in `package.json`

    fix[typescript]: Change `type` to `module` in `package.json`

    Reflects the fact that the package uses ESM not CommonJS.

    This repo is not currently accepting external contributions, but feature requests and bug reports are very welcome!

    opened by michaelurban 1
  • Not accepting external contributions

    Not accepting external contributions

    The issues tab of several GitHub repos are full of front-end developers asking for updates on Material 3/You. MDC, Angular, everyone is wondering how/when they can start using Material 3.

    Frankly, I'm tried of seeing devs whine, sometimes for years, about Material support in Angular or X/Y/Z projects instead of contributing to the development of the libraries themselves.

    Lack of HCT support is the only thing keeping me from using Material 3's color system in a web app today. I was surprised to see a TypeScript library with no accompanying Sass library. I was shocked to see that this repo is not open to external contributions. I didn't even know it existed until a Google employee pointed me to it.

    I'm willing to do a line-by-line port of the TypeScript material-color-utilities to Sass, this week, if that port has a path to release.

    Some questions:

    1. Is Sass support planned?
    2. If Sass support is planned, is development underway?
    3. If Sass support is planned, when is it expected to be released?
    4. If Sass support is planned, can the development work be done in public?
    5. If no one has started working on Sass support, does a port created by an external developer have a chance of being included in this repo?
    6. Why is this repo not referenced anywhere on material.io?
    opened by michaelurban 1
  • High level description of algorithms

    High level description of algorithms

    I'm very interested in high level description of algorithms and formulas from this project.

    Do you mind to write a blog post about how all these things work? 🙏

    documentation 
    opened by FluorescentHallucinogen 1
  • [Java] Blend harmonize function not working properly?

    [Java] Blend harmonize function not working properly?

    Describe the bug I'm trying to create a theme with three extra colors for these extra states: "warn", "info" and "success". As stated in the MD3 guidelines, custom colors should be harmonized with the rest of the palette but the generated tonal palette is not equal to the one generated by the MD3 Theme Builder.

    To Reproduce

    // My primary color is the default one of the MD3 Theme Builder
    Hct primary = Hct.from(298.980997210704, 47.8565263749703, 40.08324408746242); // Also HEX: #6750a4
    Hct success = Hct.from(145.74707292816973, 53.04624876358251, 40.46292958087737); // Also HEX: #1C6E25
    
    // Then armonize the success color
    int harmonized = Blend.harmonize(success.toInt());
    
    // Then generate TonalPalette as shown on the MD3 Theme Builder
    int[] tones = new int[]{100, 99, 98, 95, 90, 80, 70, 60, 50, 40, 35, 30, 25, 20, 15, 10, 5, 0};
    TonalPalette hmzPalette = TonalPalette.fromInt(harmonized);
    
    Map<Integer, String> colors = new LinkedHashMap<>();
    for (int tone : tones) {
        // Colors are also converted to HEX strings with no alpha
        colors.put(tone, Utils.toHexNoAlpha(hmzPalette.tone(tone)));
    }
    
    // Print the map
    

    The results are:

    {
      "100": "#FFFFFF",
      "99": "#F5FFF5",
      "98": "#E9FFED",
      "95": "#C0FFD6",
      "90": "#9BF5C0", // Expected #92F7BD
      "80": "#80D9A5", // Expected #75DAA2
      "70": "#64BC8B", // Expected #59BE88
      "60": "#48A172", // Expected #3CA36F
      "50": "#2B865A", // Expected #178857
      "40": "#006D43",
      "35": "#005F3A",
      "30": "#005231",
      "25": "#004529",
      "20": "#003920",
      "15": "#002D19",
      "10": "#002111",
      "5": "#001509",
      "0": "#000000"
    }
    

    Tones from 90 to 50 are not right.

    Expected behavior I expect TonalPalette to generate the same colors or at least to be much more precise as the colors shown by the MD3 Theme Builder. If I'm doing something wrong, then I expect the documentation here on this repository or on the MD3 guidelines website to be more precise

    Notes I tested this primarily in Java, but I think the issue is present in all the other languages too

    opened by palexdev 0
  • Rename HCT to Hct

    Rename HCT to Hct

    Import package name correctly.

    https://github.com/zmaplex/material-color-utilities/blob/605ea9e25153986df6b9984145813309fe838394/typescript/hct/hct.ts#L45

    This repo is not currently accepting external contributions, but feature requests and bug reports are very welcome!

    opened by zmaplex 1
  • Use with latest Node.JS does NOT work because imports and exports do not follow ES6 modules rules, need file extension on import path.

    Use with latest Node.JS does NOT work because imports and exports do not follow ES6 modules rules, need file extension on import path.

    Hello I tried to use this module with Next.JS and it was returning the 'ERR_MODULE_NOT_FOUND' when trying to use it. To fix the issue I added the ".js" extension to all the exports and imports on all files.

    opened by edgarlcs 1
  • Kotlin Multiplatform library

    Kotlin Multiplatform library

    Hello, it'd be cool to support Kotlin Multiplatform as there are already apps with their UI implemented in Kotlin on both iOS and Android.

    Making it can be fairly easy as you can start by converting the Java code to Kotlin before improving the API and ensuring you don't depend on JVM only APIs.

    opened by LouisCAD 1
Owner
null
A Flutter plugin that exposes Monet (Material You, Material 3) system colors on Android 12.

Monet Colors A Flutter plugin that exposes Monet (Material You, Material 3) system colors on Android 12. Returns null on unsupported platforms and lea

İhsan Işık 3 Aug 26, 2022
Okan YILDIRIM 37 Jul 10, 2022
Utilities to make working with 'Duration's easier.

duration Utilities to make working with 'Duration's easier. NOTE: Use prettyDuration, prettySeconds, prettyMilliseconds instead of printDuration, prin

null 45 Sep 21, 2022
Generates utilities to aid in serializing to/from JSON.

Provides Dart Build System builders for handling JSON. json_serializable Package: https://pub.dev/packages/json_serializable Source code The core pack

Google 1.4k Jan 8, 2023
🚀The Flutter dart code generator from zeplin. ex) Container, Text, Color, TextStyle, ... - Save your time.

Flutter Gen Zeplin Extension ?? The Flutter dart code generator from zeplin. ex) Container, Text, Color, TextStyle, ... - Save your time. ⬇ 1.1k Getti

NAVER 49 Oct 12, 2022
Random color generator for Flutter

Random color generator Pub link: https://pub.dartlang.org/packages/random_color This library will generate random colors that are visually pleasing an

Luka Knezic 56 Jun 13, 2022
Flutter plugin to help experiment with different Color Schemes without pain.

Random Color Scheme Making a coherent Material Design theme is hard. This is a Flutter plugin that generates a random color pallet based on Material D

Bernardo Ferrari 77 Dec 6, 2022
Material color picker, you can customize colors. Selection in two step, first main color and after shades.

Flutter Material Color Picker Material Color picker is a Flutter widget, that can be customizable. By default, it's Material Colors, but you can defin

Jean-Charles Moussé 70 Nov 25, 2022
Automatically generate profile picture with random first name and background color. But you can still provide pictures if you have them. As the default color, based on the name of the first letter. :fire: :fire: :fire:

FLUTTER PROFILE PICTURE Automatically generate profile picture with random first name and background color. But you can still provide pictures if you

Aditya Dharmawan Saputra 10 Dec 20, 2022
ThemeX is an easy theme manipulation. Only inform primary color and the ThemeX generate all color combination palette for you

ThemeX is an easy theme manipulation basied on Material Design. Only inform primary color and the ThemeX generate all color combination palette for yo

Michael S. Lopes 2 Jan 31, 2022
Simulate color blindness in color themes.

Color Blindness on Flutter Every app has colors. How to make sure they are accessible? How to avoid accessibility issues as other people in the same p

Bernardo Ferrari 58 Dec 19, 2022
Color picker for Flutter, based on the Google Docs color picker.

Material ColorPicker Color picker for Flutter, based on the Google Docs color picker. Getting Started You can embed into your material app or use it o

Razvan Lung 103 Oct 30, 2022
A Fluter tabview that text color can change with animation and bg color change with animation

float_tab A Fluter tabview that text color can change with animation and bg color change with animation Getting Started This project is a starting poi

ventureli 1 Dec 8, 2021
A package can help you to change your flutter app's statusbar's color or navigationbar's color programmatically.

flutter_statusbarcolor A package can help you to change your flutter app's statusbar's color or navigationbar's color programmatically. Getting Starte

Zero 201 Nov 10, 2022
Flutter color picker - A color picker for your flutter app

flutter_hsvcolor_picker A HSV color picker for your flutter app. RGB HSV Wheel Hue Saturation Values. Getting Started Installation https://pub.dev/pac

FlutterCandies 49 Dec 8, 2022
Color matching game - A Crossplatform Color Matching Game made with Flutter

color_matching_game A Color Matching Game built with Flutter. It is a simple app made without adding a plug-in. Play by specifying the red, green and

Yusuke Ishimi 6 Nov 21, 2022
A colorful TabBar Flutter library with color animating indicator where each tab has a color. (inspired by SmartNews app)

Flutter Colorful TabBar A colorful TabBar for Flutter where each tab has a color (inspired by SmartNews app). Getting Started Add this to your package

null 8 Jun 17, 2022
null 0 Feb 2, 2022
meg4cyberc4t 11 Oct 24, 2022
An elegant, object-oriented implementation of the Material Design color palettes and swatches.

Contents Overview Getting Started Palette interface Numeric indexes X Named constructors Swatch interface Swatch in action Gradient interface Demo app

Dartoos 8 Nov 2, 2022