Harmony: Accessible UI Color Palette

The Harmony palette is designed to elevate control over color contrast in your design system.

• Uses OKLCH and APCA for highly consistent color shades
• Has P3 options for modern screens
• Created to keep 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 v4

Simply import @evilmartians/harmony/tailwind.css:

/* app.css, or anywhere within Tailwind-aware context */
@import "tailwindcss";
@import "@evilmartians/harmony/tailwind.css";

Tailwind v3

// 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

2. 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)

Development

Prerequisites

Dependency	Version	Description
Deno	^2.0	Runtime
Lefthook	^0.7.0	Git-hooks manager

Publication Workflow

The project uses changesets to manage versioning and changelog. Typical workflow is as follow:

1. make changes to codebase,
2. run deno task changesets at project root and follow prompt to generate a "changeset" (logging a change),
3. commit both (1) and (2) into git.

The changesets Github action is triggered on push to main and will create a corresponding "Changesets: Versioning & Publication" pull request, which, upon merged, will trigger publication of the new version to NPM.