@evilmartians/harmony

Harmony: Accessible UI Color Palette

The Harmony palette is designed to elevate control over color contrast in your design system. With the OKLCH color space and the innovative APCA contrast algorithm, Harmony offers highly consistent color shades, previously unavailable P3 gamut colors, and precise control over text and UI element contrast.

  Made by Evil Martians, product consulting for developer tools.

Features

• Equal contrast within lightness groups
• Mirrored contrast pairs
• Contrast levels for readability
• Tailwind compatibility
• P3 gamut for maximum color

Installation

npm install @evilmartians/harmony

Usage with Tailwind

Harmony can work as drop-in replacement for the Tailwind color palette:

// tailwind.config.js

import harmonyPalette from "@evilmartians/harmony/tailwind";

export default {
  theme: {
    colors: harmonyPalette,
  },
  //...
};

⚠️ Harmony uses oklch colors and so requires a polyfill for old browsers

1. Install PostCSS plugin that polyfills oklch colors

npm install -D @csstools/postcss-oklab-function

1. Enable it in postcss.config.js:

export default {
    plugins: {
        tailwindcss: {},
+        '@csstools/postcss-oklab-function': { 'preserve': true },
        autoprefixer: {},
    },
}

Vanilla CSS

Harmony palette provides a set of files with css variables. Each file contains all shades for one color in OKLCH with RGB fallbacks for old browsers. Just import colors you need and use them in css:

@import '@evilmartians/harmony/css/orange.css';

h1 {
  color: var(--orange-600);
}

Harmony also provides an index.css file that imports all other css files. 👮WARNING: this file is huge and should be used only in combination with PurgeCSS (with variables option enabled), other tools that can clean unused css variables, or if you really need all the colors.

@import '@evilmartians/harmony/css/index.css

/* now you can use any color */
h1 {
  color: var(--orange-600);
}

h2 {
  color: var(--red-300);
}

Other formats

Plain javascript object with colors without tailwind's specifics can be imported from @evilmartians/harmony/base

import palette from "@evilmartians/harmony/base";
console.log(palette.red["50"]); // => oklch(0.988281 0.0046875 20)

Changelog

1.2.0 (2023-11-25)

New features

• Add @evilmartians/harmony/css/index.css file that imports all other css files. Closes #4.

Bug fixes

• Remove spaces between variable names and values in generated css for smaller minified css files. Closes #7.

Improvements

• Add CHANGELOG.md