saltcat-color-tokens

User-friendly wrapper around saltcat-color-palette for parsing Tailwind-style color tokens with advanced grading and LUT controls.

Installation

npm install saltcat-color-tokens

Usage

Basic Color Token Parsing

import { parseColorToken } from 'saltcat-color-tokens';

// Parse Tailwind-style color tokens
const blue500 = parseColorToken('blue-500');    // Returns hex color
const red300 = parseColorToken('red-300');      // Returns hex color
const black = parseColorToken('black');         // Returns #000000
const white = parseColorToken('white');         // Returns #ffffff

Get All Shades of a Color

import { getShades } from 'saltcat-color-tokens';

const blueShades = getShades('blue');
// Returns: { 50: '#...', 100: '#...', ..., 900: '#...' }

Configuration

Configure color grading and brightness controls:

import { configure } from 'saltcat-color-tokens';

configure({
  minBrightness: 0.1,
  maxBrightness: 0.9,
  grading: {
    red: { lift: 0.1, gamma: 1.2, gain: 1.0 },
    green: { lift: 0, gamma: 1.0, gain: 1.1 },
    blue: { lift: 0, gamma: 1.0, gain: 0.9 }
  }
});

Node.js Configuration File

In Node.js environments, you can create a saltcat-color-tokens.mjs file in your project root:

// saltcat-color-tokens.mjs
export default {
  minBrightness: 0.05,
  maxBrightness: 0.95,
  grading: {
    luminance: { lift: 0, gamma: 1.1, gain: 1 }
  },
  lut: './path/to/your/lut.cube'
};

Supported Colors

All standard Tailwind CSS colors are supported:

• Grays: slate, gray, zinc, neutral, stone
• Colors: red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose
• Special: black, white

Shades

Standard Tailwind shades: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900

Features

• Color Grading: Advanced lift/gamma/gain controls for fine-tuning colors
• Brightness Clamping: Ensure colors stay within specified brightness ranges
• LUT Support: Apply 3D lookup tables in Node.js environments (requires saltcat-color-palette)
• Environment Detection: Automatic Node.js vs browser detection
• Configuration: Flexible configuration system with file-based config support

API

parseColorToken(token: string): string

Parses a Tailwind-style color token and returns a hex color string.

• token - Color token in format "color-shade" (e.g., "blue-500") or "black"/"white"

getShades(colorName: string): object

Returns an object with all shades (50-900) for a given color name.

• colorName - Name of the color (e.g., "blue", "red")

configure(config: object): void

Updates the global configuration.

• config.minBrightness - Minimum brightness clamp (0-1)
• config.maxBrightness - Maximum brightness clamp (0-1)
• config.grading - Color grading controls
• config.lut - Path to LUT file (Node.js only)

defaultConfig

The default configuration object.

Scripts

• npm run build - Build distribution files
• npm run test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run test:coverage - Run tests with coverage
• npm run dev - Run development version

Dependencies

• colorjs.io - Advanced color manipulation
• chroma-js - Color scale generation
• saltcat-color-palette - Core color grading and LUT functionality

License

MIT