DittoTones

You can use your own design system by providing a Map<string, Ramp>.

Constraints:

1. Consistent Keys: All ramps in the Map must share the exact same shade keys. The constructor will throw if they differ.
2. Neutral Ramp: Include at least one neutral (gray) ramp. If the input color has very low chroma, dittoTones will match it against the least chromatic ramp available.

import { DittoTones } from 'dittotones';
import { parse, oklch, type Oklch } from 'culori';

const customRamps = new Map([
  [
    'brand',
    {
      '50': oklch(parse('oklch(98% 0.01 250)')) as Oklch,
      '500': oklch(parse('#3B82F6')) as Oklch,
      '950': oklch(parse('oklch(25% 0.05 250)')) as Oklch,
    },
  ],
]);

const ditto = new DittoTones({ ramps: customRamps });

Install the dittotones library via npm to transform any color into a full palette based on the perceptual DNA of a design system.

npm install dittotones

A Ramp is a type definition representing a collection of color steps. It is a Record<string, Oklch> where:

• The key is a string representing the step number (e.g., '1', '2', ..., '12').
• The value is an Oklch object (from the culori library) representing the color at that step.

This structure allows for easy programmatic access to color scales by step index.

When instantiating DittoTones, you can pass an options object to customize the generation behavior:

• ramps: A Map<string, Ramp> of reference palettes.
• preserveHueOffsets (boolean): If true, preserves hue shifts from reference ramps across the scale (e.g., if a design system's dark shades shift toward purple). Defaults to false.
• gamutMap (boolean): If true, maps output colors to the sRGB gamut by reducing chroma to prevent out-of-gamut colors when converting to hex. Defaults to true.

const ditto = new DittoTones({
  ramps: myRamps,
  preserveHueOffsets: true,
  gamutMap: false,
});

The .generate() method returns a GenerateResult object containing details about the input and the generated scale:

• inputColor: The parsed Oklch version of your input.
• matchedShade: The string key of the shade that most closely matched your input (e.g., `

The following design systems are available as bundled ramps:

dittoTones provides pre-configured ramps for several design systems as subpaths. Importing via subpaths ensures you only bundle the data you actually use.

import { tailwindRamps } from 'dittotones/ramps/tailwind';
import { radixRamps } from 'dittotones/ramps/radix';
import flexokiRamps from 'dittotones/ramps/flexoki'; // default export works too

The shoelaceRamps constant provides a collection of pre-configured color ramps based on the Shoelace design system. It is exported as a Map<string, Ramp>, where each key in the map corresponds to a color name (from shoelaceColors) and the value is a Ramp object. A Ramp is a record mapping shade names (strings) to Oklch color objects.

To use these ramps, iterate over the map or access specific color ramps by their key name.

import shoelaceRamps from './ramps/shoelace';

// Access a specific ramp by its key (e.g., 'blue')
const blueRamp = shoelaceRamps.get('blue');

if (blueRamp) {
  // Access a specific shade within the ramp
  const shade500 = blueRamp['500'];
  console.log(shade500);
}

The tailwindV3Ramps constant provides a collection of pre-configured color ramps based on Tailwind CSS v3 color palettes. Each entry in the Map is keyed by the color name (e.g., 'blue', 'red') and contains a Ramp object where keys are shade identifiers (e.g., '50', '500', '900') and values are Oklch color objects. This is useful for applying Tailwind-inspired color scales using OKLCH color space logic.

import tailwindV3Ramps from './src/ramps/tailwind-v3';

// Access a specific color ramp
const blueRamp = tailwindV3Ramps.get('blue');

if (blueRamp) {
  const shade500 = blueRamp['500'];
  console.log(shade500); // Returns an Oklch object
}