color-string

color-string is a small, dependency-light JavaScript module for converting between CSS color string syntax and plain numeric arrays. Its get namespace parses hex (3/4/6/8-digit), rgb()/rgba(), hsl()/hsla(), and hwb() strings — including both legacy comma-separated syntax and the modern CSS Color Module 4 space/slash notation — into [channel, channel, channel, alpha] tuples, along with named CSS keywords via the companion color-name package. Its to namespace does the reverse, turning numeric channel values back into spec-compliant CSS strings.

Unusually for a utility this size, it ships hand-written TypeScript declarations and a tsd-based type-test suite alongside a plain node:assert test file, and is published as a single ESM file with one runtime dependency. It sits underneath the popular color package and a long tail of CSS-in-JS, design-tool, and theming libraries that need to accept freeform color input from users or config and normalize it before doing further math on it.

What You Get

• A single dependency-light ESM module exporting get and to namespaces for parsing and generating CSS colors.
• Hex parsing supporting 3, 4, 6, and 8-digit forms (short and alpha variants).
• Full rgb()/rgba()/hsl()/hsla()/hwb() parsing, covering both legacy comma-separated syntax and modern space/slash CSS Color 4 syntax.
• Round-trip generators (to.hex, to.rgb, to.rgb.percent, to.hsl, to.hwb, to.keyword) that turn numeric channel values back into spec-compliant CSS strings.
• Named CSS/X11 keyword recognition and reverse keyword lookup via the color-name dependency.
• Bundled TypeScript type definitions (index.d.ts) plus a tsd-based type-test suite.

Common Use Cases

• Design tool color pickers that accept freeform hex/rgb/hsl/hwb text input and normalize it to one internal model.
• CSS-in-JS or theming libraries that normalize user-supplied color props into numeric tuples before applying opacity math.
• Color manipulation packages (like color) that use it as the parsing entry point before running conversions or blending.
• Build-time site/icon generators that accept color strings from config or frontmatter and need normalized CSS output.

Under The Hood

Architecture color-string ships as a single ~230-line ESM file (index.js) exporting a plain object cs with two namespaces: get (parsing, which dispatches on the string’s 3-character prefix to hsl, hwb, or a default rgb regex parser) and to (generation, with sub-methods like to.rgb.percent attached directly to the base functions). There are no classes or module-level mutable state beyond a reverseNames lookup table built once at load time from the color-name package’s keyword map. Every parser and generator is a pure function operating on plain arrays, with clamping centralized in one shared clamp helper. Because cs.get’s prefix-based switch falls through to cs.get.rgb for anything not starting with hsl/hwb, that function’s regex set is a single point of failure for the majority of parse paths.

Tech Stack Pure JavaScript (ESM, Node >=18), with exactly one runtime dependency, color-name (^2.0.0), for keyword-to-RGB and reverse lookups. Dev tooling is xo (an opinionated, stricter ESLint preset) for linting and tsd for type-testing index.d.ts; the test runner is plain Node assert, not Jest or Mocha. The package is published with only index.js and index.d.ts per its files field, under MIT. GitHub Actions CI runs npm test across Node 18, 20, and 22.

Code Quality test.js is roughly 15KB of straight-line assert.deepEqual calls with no framework structure (no describe/it blocks), but it exercises a wide range of format variants — percentages, scientific notation, deg suffixes, negative/wrapping hues, keyword casing, and mixed comma/space syntax. There is no explicit error handling: parse failures return null rather than throwing, and the to.* generators do not validate their numeric inputs, so malformed calls can silently produce NaN or malformed strings. Naming is terse but consistent. Type safety comes entirely from the separately maintained index.d.ts plus tsd, not from TypeScript source. No code-coverage tooling is configured.

What Makes It Unique The library isn’t algorithmically novel — it’s a direct, regex-based implementation of the CSS Color spec’s string grammar, and there are several comparable parsers in the ecosystem. Its value is in being minimal, dependency-light (one dependency), broadly adopted as the parsing layer under the color package and a long tail of CSS tooling, and unusually well type-tested for a project this size.