Chroma

RGB Contrast Utility Library

Chroma is a lightweight, fully typed TypeScript utility library for working with CSS RGB colours, random colour generation, and WCAG contrast ratios.

It is designed for simple browser and canvas use cases where colours need to be generated, converted to CSS, or adjusted to meet accessible contrast levels.

📦 Installation

Install from npm:

npm install @crisvsgame/chroma

Import the main class:

import { Chroma } from "@crisvsgame/chroma";

🚀 Quick Start

import { Chroma } from "@crisvsgame/chroma";

const bg = Chroma.randomRgb();
const fg = Chroma.randomWithContrast(bg);

document.body.style.backgroundColor = Chroma.rgbToCss(bg);
document.body.style.color = Chroma.rgbToCss(fg);

Generate a random accessible colour pair:

const { bg, fg } = Chroma.randomPair();

console.log(Chroma.rgbToCss(bg));
console.log(Chroma.rgbToCss(fg));
console.log(Chroma.contrast(bg, fg));

🌐 CDN / Browser ESM

Chroma can also be imported directly in the browser through jsDelivr:

<script type="module">
    import { Chroma } from "https://cdn.jsdelivr.net/npm/@crisvsgame/[email protected]/dist/index.js";

    const { bg, fg } = Chroma.randomPair();

    document.body.style.backgroundColor = Chroma.rgbToCss(bg);
    document.body.style.color = Chroma.rgbToCss(fg);
</script>

🔧 Features

• Random integer generation
• Random float generation
• Random RGB colour generation
• RGB to CSS rgb(...) conversion
• WCAG contrast ratio calculation
• WCAG AA/AAA contrast constants
• Contrast checking
• Contrast adjustment
• Random accessible colour pairs
• Zero runtime dependencies
• Fully typed TypeScript API

♿ WCAG Constants

Chroma.WCAG_AA_LARGE; // 3
Chroma.WCAG_AA_NORMAL; // 4.5
Chroma.WCAG_AAA_LARGE; // 4.5
Chroma.WCAG_AAA_NORMAL; // 7

🎨 Public API

Chroma.randomInt(min, max);
Chroma.randomFloat(min, max);
Chroma.randomRgb();
Chroma.rgbToCss(rgb);
Chroma.contrast(first, second);
Chroma.meetsContrast(first, second, ratio);
Chroma.adjustToContrast(base, color, options);
Chroma.randomWithContrast(base, options);
Chroma.randomPair();

Fully typed imports:

import { Chroma, VERSION, type Rgb, type RgbPair, type ContrastOptions, type ContrastDirection } from "@crisvsgame/chroma";

console.log(VERSION);

📂 Project Structure

src/
    Chroma.ts
    index.ts
test/
    Chroma.test.ts
dist/ # generated build output published to npm
    Chroma.d.ts
    Chroma.d.ts.map
    Chroma.js
    Chroma.js.map
    index.d.ts
    index.d.ts.map
    index.js
    index.js.map
.gitignore
LICENSE
README.md
package-lock.json
package.json
tsconfig.json

🧪 Testing

Run the test suite:

npm test

The tests cover public API behaviour, validation, random helper invariants, and WCAG contrast guarantees.

🛠️ Build

Build the library:

npm run build

📝 License

MIT License

🔗 Links

• npm: https://www.npmjs.com/package/@crisvsgame/chroma
• Source Code: https://github.com/CRISvsGAME/chroma