Mid Engineering Logo

Mid Engineering Docs

Constellation

Introducing Constellation—a color conversion tool that converts your lousy HEX-based base tokens into beautiful, modern color spaces using gamma-correct calculations and proper matrix transformations.

Install

Get started straight away by installing the Constellation package, either locally or globally. The package is less than 25kb.

Install using npm:

bash

# locally

npm i @razorloaf/constellation

# globally

npm i -g @razorloaf/constellation

Features

  1. Dual Function: Locate and Transform

  1. Dual Function: Locate and Transform
  1. Dual Function: Locate and Transform

  1. Single cli-helper dependency

  1. Single cli-helper dependency
  1. Single cli-helper dependency

  1. Converts HEX to Alpha, OKLCH, and P3A formats

  1. Converts HEX to Alpha, OKLCH, and P3A formats
  1. Converts HEX to Alpha, OKLCH, and P3A formats

  1. Supports light and dark themes

  1. Supports light and dark themes
  1. Supports light and dark themes

Constellation doesn't just reshuffle your existing colors—it performs precise conversions through multiple spaces that on average produce < 0.050 Delta E round trip results.

Constellation doesn't just reshuffle your existing colors—it performs precise conversions through multiple spaces that on average produce < 0.050 Delta E round trip results.
Constellation doesn't just reshuffle your existing colors—it performs precise conversions through multiple spaces that on average produce < 0.050 Delta E round trip results.

User Guide: Locate

Locate is powerful if you want to quickly transform a single HEX value into the various color spaces.

Example:

js

import { locate } from '@razorloaf/constellation';

import { locate } from '@razorloaf/constellation';
import { locate } from '@razorloaf/constellation';

// Get color formats (second param is 'light' or 'dark' theme)

// Get color formats (second param is 'light' or 'dark' theme)
// Get color formats (second param is 'light' or 'dark' theme)

const color = locate('#1331AA', 'light');

const color = locate('#1331AA', 'light');
const color = locate('#1331AA', 'light');

console.log(color.hex); // #1331AA

console.log(color.hex); // #1331AA
console.log(color.hex); // #1331AA

console.log(color.hexa); // #0020A3EC

console.log(color.hexa); // #0020A3EC
console.log(color.hexa); // #0020A3EC

console.log(color.oklch); // oklch(38.9% 0.1941 265.7)

console.log(color.oklch); // oklch(38.9% 0.1941 265.7)
console.log(color.oklch); // oklch(38.9% 0.1941 265.7)

console.log(color.p3a); // color(display-p3 0 0.1271 0.6398 / 0.925)

console.log(color.p3a); // color(display-p3 0 0.1271 0.6398 / 0.925)
console.log(color.p3a); // color(display-p3 0 0.1271 0.6398 / 0.925)

What to see support for HSL, CMYK, and other spaces in the future?

Request more color spaces

User Guide: Transform

The transform function is key when converting entire color files at once. It's smart enough to detect new additions, dark-theme colors, and formats for good housekeeping.

Before:

css

// Before

// Before
// Before

:root {

:root {
:root {

/* blue - Hex */

/* blue - Hex */
/* blue - Hex */

--blue-900: #5573EC;

--blue-900: #5573EC;
--blue-900: #5573EC;

}

}
}

After:

css

// after

// after
// after

:root {

:root {
:root {

/* blue - Hex */

/* blue - Hex */
/* blue - Hex */

--blue-900: #5573EC;

--blue-900: #5573EC;
--blue-900: #5573EC;

/* blue - Alpha */

/* blue - Alpha */
/* blue - Alpha */

--blue-900-alpha: #002DE3AA;

--blue-900-alpha: #002DE3AA;
--blue-900-alpha: #002DE3AA;

/* blue - OKLCH */

/* blue - OKLCH */
/* blue - OKLCH */

--blue-900-oklch: oklch(59.7% 0.1851 269.6);

--blue-900-oklch: oklch(59.7% 0.1851 269.6);
--blue-900-oklch: oklch(59.7% 0.1851 269.6);

/* blue - Display-P3 Alpha*/

/* blue - Display-P3 Alpha*/
/* blue - Display-P3 Alpha*/

--blue-900-p3a: color(display-p3 0 0.1765 0.8882 / 0.667);

--blue-900-p3a: color(display-p3 0 0.1765 0.8882 / 0.667);
--blue-900-p3a: color(display-p3 0 0.1765 0.8882 / 0.667);

}

}
}

Basic Commands

Constellation was made to be deliberatly simple. Run the commands in your terminal and Constellation will do the rest.

Basic transformation:

bash

npx constellation transform path/to/colors.css

npx constellation transform path/to/colors.css
npx constellation transform path/to/colors.css

Output to a different file:

bash

npx constellation transform path/to/colors.css dist/color-spaces.css

npx constellation transform path/to/colors.css dist/color-spaces.css
npx constellation transform path/to/colors.css dist/color-spaces.css

Force regeneration of all colors:

bash

npx constellation transform path/to/colors.css --force

npx constellation transform path/to/colors.css --force
npx constellation transform path/to/colors.css --force

Themes

Constellation detects themes in two ways:

  1. Any token containing -dark anywhere in its name

  1. Any token containing -dark anywhere in its name
  1. Any token containing -dark anywhere in its name

  1. Colors inside [data-theme="dark"]

  1. Colors inside [data-theme="dark"]
  1. Colors inside [data-theme="dark"]

Example:

css

:root {

/* pink - Hex */

--pink-100: #FEF6FA;

--pink-200: #FCE8F2;

/* ...more HEX shades... */

/* pink - Hex (Dark) */

--pink-100-dark: #290A19;

--pink-200-dark: #521432;

/* ...more dark HEX shades... */

}

If you append -dark to your token name Constellation will clean your core css file for good house keeping and developer experience. As you can see we strip -dark from the token name and format for easy theming.

Output:

css

:root {

/* pink - Hex */

--pink-100: #FEF6FA;

--pink-200: #FCE8F2;

/* ...more HEX shades... */

/* pink - Alpha */

--pink-100-alpha: #E2007009;

--pink-200-alpha: #DE006F17;

/* ...more Alpha shades... */

/* pink - OKLCH */

--pink-100-oklch: oklch(98.0% 0.0100 344.9);

--pink-200-oklch: oklch(95.0% 0.0253 345.6);

/* ...more OKLCH shades... */

/* pink - Display-P3 Alpha */

--pink-100-p3a: color(display-p3 0.8889 0 0.4444 / 0.035);

--pink-200-p3a: color(display-p3 0.8696 0 0.4348 / 0.090);

/* ...more P3a shades... */

}

[data-theme="dark"] {

/* pink - Hex (Dark) */

--pink-100: #290A19;

--pink-200: #521432;

/* ...more dark HEX shades... */

/* pink - Alpha (Dark) */

--pink-100-alpha: #F300571A;

--pink-200-alpha: #F9198647;

/* ...more dark Alpha shades... */

/* pink - OKLCH (Dark) */

--pink-100-oklch: oklch(20.4% 0.0556 353.0);

--pink-200-oklch: oklch(30.6% 0.0970 354.7);

/* ...more dark OKLCH shades... */

/* pink - Display-P3 Alpha (Dark) */

--pink-100-p3a: color(display-p3 0.9576 0 0.3406 / 0.102);

--pink-200-p3a: color(display-p3 0.976 0.0989 0.5233 / 0.277);

/* ...more dark P3a shades... */

}

Footnotes

  1. This open source package is being maintained by Joshua Hoy.

  1. Licensed under MIT. See LICENSE file for complete terms.

  1. While attribution is appreciated, it's not required for implementation in commercial projects.

Mid Engineering © 2025