Huescale

Generate perceptually uniform color palettes using the OKLCH color space, with DTCG-compliant design token export.

Features

• Perceptually uniform - Uses OKLCH color space for consistent lightness/chroma progression
• DTCG-compliant export - Outputs design tokens in DTCG 2025.10 format
• Pattern learning - Extracts transformation patterns from example palettes
• Multiple modes - Single, batch, and transformation modes (all combinable)
• Flexible input - Any stop position (100-1000) as anchor; supports hex, rgb, hsl, oklch, oklab
• Multiple exports - Console, JSON file, or clipboard (JSON/clipboard use DTCG format)

Installation

Use directly (no install)

# npm
npx huescale generate

# pnpm
pnpm dlx huescale generate

# yarn
yarn dlx huescale generate

# bun
bunx huescale generate

Install globally

# npm
npm install -g huescale

# pnpm
pnpm add -g huescale

# yarn
yarn global add huescale

# bun
bun add -g huescale

Quick Start

Interactive

huescale generate

Direct

# Single palette
huescale generate -c "#2D72D2" -s 500 -f hex -n "blue"

# Batch palettes
huescale generate -c "#2D72D2::500,#DB2C6F::600" -f hex

# Single transformation
huescale generate -c "#2D72D2>#FF6B6B::500" -f hex

# Export to JSON file (DTCG format)
huescale generate -c "#2D72D2" -e json -p ./tokens.json

# Copy to clipboard (DTCG format)
huescale generate -c "#2D72D2" -e clipboard

Usage

Modes

| Mode | Syntax | Description | | --------------------------- | ----------------------------------------------------------------- | -------------------------------------- | | Single | #2D72D2 | Generate palette from one color | | Batch | #2D72D2::500,#DB2C6F::600 | Multiple palettes at once | | Single Transform | #2D72D2>#FF6B6B::500 | Apply ref's appearance to target's hue | | One-to-Many Transform | #2D72D2>(#FF6B6B,#238551)::500 | Transform ref to multiple targets | | Batch Transform | #2D72D2>#FF6B6B::500,#48AFF0>#238551::600 | Multiple transformations at once | | Batch One-to-Many | #2D72D2>(#FF6B6B,#238551)::500,#48AFF0>(#DB2C6F,#FFB366)::600 | Multiple one-to-many transforms |

All modes support comma-separated or multi-line input for batch processing.

Options

| Flag | Short | Description | Default | | ---------- | ----- | -------------------------------------------- | -------------- | | --color | -c | Color input (see modes above) | - | | --stop | -s | Stop position (100-1000) | 500 | | --format | -f | Output format: hex, rgb, oklch, oklab| hex | | --name | -n | Palette name | - | | --export | -e | Export type: none, json, clipboard | none | | --path | -p | JSON output path | ./palette.json |

Stop Positions

| Stop | Description | | ---- | ------------------ | | 100 | Lightest | | 500 | Medium (reference) | | 1000 | Darkest |

DTCG Design Token Export

JSON and clipboard exports follow the DTCG 2025.10 specification. Color values use the structured OKLCH format with hex fallbacks:

{
  "blue": {
    "$type": "color",
    "$extensions": {
      "huescale": {
        "inputColor": "#2D72D2",
        "anchorStop": 500,
        "outputFormat": "hex"
      }
    },
    "500": {
      "$type": "color",
      "$value": {
        "colorSpace": "oklch",
        "components": [0.57, 0.15, 259],
        "hex": "#2D72D2"
      },
      "$extensions": {
        "huescale": {
          "position": 500,
          "formattedValue": "#2d72d2"
        }
      }
    }
  }
}

The $extensions namespace preserves generation metadata (input color, anchor stop, output format) for reproducibility.

How It Works

1. Pattern extraction - Analyzes example palettes to learn lightness/chroma/hue transformations relative to the reference stop (500)
2. Pattern application - Applies learned multipliers to generate all 10 stops from your anchor color
3. Gamut correction - Clamps colors to displayable sRGB while preserving perceptual characteristics

Development

git clone https://github.com/ryannono/huescale
cd huescale
pnpm install

pnpm dev        # Run CLI
pnpm test       # Run tests
pnpm check      # Type check
pnpm build      # Production build

Requirements: Node.js 18+, pnpm 10.14+

Tech Stack

• Effect-ts - Functional TypeScript framework
• culori - Color space conversions
• @clack/prompts - Interactive CLI prompts
• @effect/cli - Type-safe CLI builder

License

MIT

Perceptually uniform palettes, DTCG-compliant, type-safe from end to end.