@edelstone/tints-and-shades

Deterministic tint and shade generator for 6-character hex colors.
Used internally by the Tint & Shade Generator and published here as a standalone API.

Install

npm install @edelstone/tints-and-shades

API

calculateTints(colorValue: string, steps?: number[]): ScaleColor[]
calculateShades(colorValue: string, steps?: number[]): ScaleColor[]

type ScaleColor = {
  hex: string;
  ratio: number;
  percent: number;
};

Parameters

• colorValue
  6-character hex string without #, e.g. 3b82f6
  Must be a valid 6-character hex value.

• steps (optional)
  Array of finite numeric mix ratios.
  Example: [0, 0.1, 0.2, 0.3]

If omitted, the default steps are:

[0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]

Returns

An array of ScaleColor objects:

• hex: 6-character hex string (without #)
• ratio: numeric step ratio used for the mix
• percent: ratio expressed as a percentage (rounded to 1 decimal)

Example

import { calculateTints, calculateShades } 
  from "@edelstone/tints-and-shades";

const tints = calculateTints("000000", [0, 0.5, 1]);
const shades = calculateShades("ffffff", [0, 0.5, 1]);

Tints output:

[
  { "hex": "000000", "ratio": 0, "percent": 0 },
  { "hex": "808080", "ratio": 0.5, "percent": 50 },
  { "hex": "ffffff", "ratio": 1, "percent": 100 }
]

Shades output:

[
  { "hex": "ffffff", "ratio": 0, "percent": 0 },
  { "hex": "808080", "ratio": 0.5, "percent": 50 },
  { "hex": "000000", "ratio": 1, "percent": 100 }
]

Validation

• colorValue must be a 6-character hex string (no #).
• Invalid values throw a TypeError.
• steps must be an array of finite numbers.
• Invalid steps input throws a TypeError.

Learn more

• Calculation method and rationale available on the Tint & Shade Generator docs.

Development

From repo root:

npm run build:api
npm run test:api

From package directory:

npm run build
npm run test