colord

Colord is a small, zero-dependency TypeScript library for parsing, converting, and manipulating colors. It exposes a single immutable Colord class with a chainable API for reading and transforming color values across HEX, RGB, HSL, and HSV, while an official plugin system adds support for CMYK, LAB, LCH, XYZ, HWB, CSS color names, color mixing, and WCAG accessibility calculations without growing the core bundle beyond roughly 1.8 KB brotli-compressed.

The library targets performance- and bundle-size-sensitive contexts — design tools, CSS-in-JS libraries, and UI component kits — where a general-purpose color library like color or tinycolor2 is heavier than needed. A dedicated benchmark suite, run in CI on every push, tracks conversion throughput and bundle size against those rivals to catch regressions in either.

What You Get

• Chainable, immutable Colord instances for HEX/RGB/HSL/HSV conversion and manipulation (lighten, darken, saturate, rotate, mix, invert)
• A roughly 1.8 KB (brotli) zero-dependency core, with official plugins (cmyk, lab, lch, xyz, hwb, names, minify, mix, harmonies, a11y) opted in per byte budget
• Full TypeScript types shipped in the package itself, including typed exports for every supported color-object shape
• A WCAG 2.0 accessibility plugin (a11y) for relative luminance, contrast ratio, and isReadable() checks
• A benchmark suite, enforced in CI, comparing throughput and bundle size against color, tinycolor2, and ac-colors

Common Use Cases

• Converting user-entered or design-token colors between HEX/RGB/HSL/HSV inside a design tool or theme editor
• Checking text/background color pairs for WCAG AA/AAA contrast compliance in an accessibility audit
• Generating color mixes, tints, shades, and tones for a design system’s palette generator
• Normalizing arbitrary CSS color strings, including CSS Color Level 4 formats, before storing or re-serializing them
• Minifying generated CSS color values to their shortest valid representation in a build pipeline

Under The Hood

Architecture

Colord centers on a single Colord class (src/colord.ts) that stores colors internally as an unrounded RGBA object and exposes conversion/manipulation methods that each return a new instance, keeping the API chainable and immutable. Parsing runs through parse.ts, which holds format-detection tables (parsers.string, parsers.object) populated by the colorModels/ modules (hex, rgb, hsl, hsv, plus plugin-added cmyk/lab/lch/xyz/hwb); extend.ts implements the plugin mechanism itself, patching the Colord prototype and the shared parser tables at runtime while TypeScript declare module blocks in each plugin file add the corresponding typed methods to the class without touching its source. This separation lets official plugins (a11y, mix, names, minify, harmonies, and the extra color spaces) extend both behavior and types while the core stays confined to HEX/RGB/HSL/HSV.

Tech Stack

The library is written in strict TypeScript with zero runtime dependencies, built with Rollup into both CJS and ESM outputs (plus per-plugin .d.ts files) and minified with rollup-plugin-terser. Bundle size is enforced with size-limit, which fails the build if the core or any individual plugin crosses its configured byte budget (e.g. 2 KB for the core, 0.5-1.5 KB per plugin). Tests run under Jest with ts-jest; linting uses ESLint with the @typescript-eslint recommended rules plus Prettier integration. GitHub Actions runs two workflows: a standard CI job across Node 18/20/22, and a separate pinned-environment benchmark workflow that compares colord’s throughput and size against color, tinycolor2, and ac-colors on every push and pull request.

Code Quality

The test suite spans roughly 1,400 lines across colord.test.ts, plugins.test.ts, delta-e00.test.ts, and parse-complexity.test.ts, covering conversion round-trips across every supported color model, plugin behavior, and edge cases like hue-wrapping at exactly 360 degrees; the README advertises 100% coverage via a Codecov badge tracked in CI. Helper functions carry explicit doc comments explaining non-obvious choices — for example, clampHue()’s comment documents why a two-step modulo is used instead of the canonical single-expression form, to avoid floating-point drift on already-in-range values. Parsing failures are handled by returning null rather than throwing, which the Colord constructor treats as a documented fallback to black rather than a swallowed error. Naming is consistent and the codebase has no untyped any usage in the reviewed core files.

API Design The public surface is small and consistent: one factory function (colord()), one class, and every mutator-style method (lighten, saturate, rotate, alpha, hue) returns either a new immutable instance or, in a getter/setter overload, a plain value — the same pattern repeats across the whole API so there is little to memorize. Plugins extend this surface additively via extend([plugin]) and are opt-in per byte cost, so consumers only pay for the color spaces or utilities they actually import. Every exported color-object shape (RgbColor, HslaColor, etc.) is independently importable for consumers’ own type annotations, and the README documents every plugin with runnable, copy-pasteable examples showing exact input/output values.