The Complete Production SOP: How to Deploy and Run Chroma.js Perceptually Uniform Color Scales in Autonomous AI Agents
Step-by-step SOP to install and run Chroma.js Perceptually Uniform Color Scales in Codex, Claude Code, and Cursor. Includes verified prompts and troubleshooting.
Technical Overview & Architectural Context
Autonomous coding agents frequently generate flawed color scales for data visualization and cartography. When instructed to build heatmaps, choropleths, or multi-series charts, agents default to standard RGB or HSL interpolation. This mathematical interpolation creates uneven perceptual gradations, leading to murky desaturated midtone bands (the 'gray dead zone') and jarring contrast spikes where intermediate data points appear disproportionately prominent or completely invisible. Furthermore, agents regularly neglect accessibility standards like WCAG contrast ratios and fail to account for non-linear human visual perception across different hues. Without deterministic guardrails, agents invent ad-hoc hex values that look inconsistent across differing display gamuts and break data readability. The chromajs-color-scales-ramps skill solves this by constraining the agent to strict procedural boundaries using Chroma.js. It enforces LCH/Lab color mode interpolations, spline-based Bezier smoothing across multi-point anchors, and automatic lightness correction. By integrating this SKILL.md into Codex, Claude Code, Cursor, or Windsurf, agents predictably output perceptually uniform, publication-grade palettes that adhere strictly to domain limits and contrast thresholds.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into the agent runtime directory.
Autonomous agent runtimes like Claude Code, Cursor, and Codex automatically discover procedural capabilities from designated skill repositories. To install `chromajs-color-scales-ramps`, mount the SKILL.md file into your project's `.agents/skills` or `.cursor/rules` path. This ensures that the agent reads the runtime triggers, permissions, and mathematical SOP before generating any color utility code.
mkdir -p .agents/skills/chromajs-color-scales-ramps && cat << 'EOF' > .agents/skills/chromajs-color-scales-ramps/SKILL.md
---
name: "chromajs-color-scales-ramps"
description: "Generate perceptually uniform data visualization color ramps and scales with Chroma.js."
metadata:
author: "Gregor Aisch"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "create color ramp chromajs"
- "use colorbrewer palette chroma"
- "interpolate colors bezier chroma"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# Chroma.js Perceptually Uniform Color Scales
Builds data color scales using Chroma.js: Bezier interpolation, light correction, diverging color ramps, ColorBrewer palettes, and quantile scale categorization.
## When to Invoke
Invoke this skill whenever you need to:
- create color ramp chromajs
- use colorbrewer palette chroma
- interpolate colors bezier chroma
## Execution SOP & Rules
1. Generate scales with chroma.scale(['#fafa6e', '#2A4858']).mode('lch').colors(6).
2. Enable chroma.bezier(colors).scale().correctLightness() to eliminate dark midtone bands.
3. Leverage standard ColorBrewer palettes: chroma.scale('RdYlBu').domain([0, 100]).
4. Validate that text placed over generated colors satisfies WCAG readability requirements.
## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.
EOF---
name: "chromajs-color-scales-ramps"
description: "Generate perceptually uniform data visualization color ramps and scales with Chroma.js."
metadata:
author: "Gregor Aisch"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "create color ramp chromajs"
- "use colorbrewer palette chroma"
- "interpolate colors bezier chroma"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Keep the SKILL.md lean and avoid pasting entire Chroma.js API documentation; agents only require the procedural invariants (e.g., LCH mode, bezier smoothing, correctLightness) to eliminate token waste.
Ensure directory permissions allow write access within the current workspace only. SKILL.md specifies `shell_exec: false` and `net_access: false` to ensure 98/100 sandbox safety.
Environment Secrets & Dependency Validation
Ensure required npm runtime packages are installed and type definitions are resolved without exposing sensitive tokens.
Chroma.js runs purely in-process and does not require external API tokens or remote credentials. However, the agent execution environment must have `chroma-js` installed in `node_modules` and exposed via `package.json`. Validating package presence prevents the agent from attempting unauthorized global npm installations during generation cycles.
pnpm add chroma-js && pnpm add -D @types/chroma-js{
"dependencies": {
"chroma-js": "^3.1.2"
},
"devDependencies": {
"@types/chroma-js": "^3.1.1",
"typescript": "^5.4.0"
}
}Never put internal registry tokens or auth headers in agent instructions; configure standard npmrc files at the root level if using private registries.
Verify that your tsconfig has `esModuleInterop: true` or `allowSyntheticDefaultImports: true`, as Chroma.js is commonly consumed via CommonJS wrappers in legacy codebases.
Intent Matching & Trigger Invocation
Prompt the agent using explicit trigger phrases to guarantee SOP adherence.
Agents dynamically select skills based on trigger phrase alignment. By prefixing requests with phrases specified in the frontmatter—such as `interpolate colors bezier chroma` or `create color ramp chromajs`—the orchestrator loads the Chroma.js SOP into active system context rather than relying on ungrounded heuristics.
import chroma from 'chroma-js';
export interface ColorRampOptions {
anchors: string[];
steps: number;
correctLightness?: boolean;
}
export function generatePerceptualRamp({
anchors,
steps,
correctLightness = true,
}: ColorRampOptions): string[] {
let scale = chroma.bezier(anchors).scale();
if (correctLightness) {
scale = scale.correctLightness();
}
return scale.mode('lch').colors(steps);
}Anchor multi-point palettes using distinct lightness extremes (e.g., light yellow `#fafa6e` to deep teal `#2A4858`) to allow `correctLightness()` to build linear luminance slopes.
Do not pass more than 5 anchor hex values into `chroma.bezier()`; Bezier curves with excessive control points cause severe color oscillation and out-of-gamut clipping.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks to validate color contrast, array lengths, and TypeScript types.
Before the agent finishes the task, it must execute a test harness to verify that the generated scales do not yield NaN values, conform to requested domain bounds, and produce hex codes with sufficient contrast against background canvases.
pnpm tsc --noEmit && pnpm testimport { describe, it, expect } from 'vitest';
import chroma from 'chroma-js';
import { generatePerceptualRamp } from '../src/utils/paletteGenerator';
describe('Perceptual Color Scales', () => {
it('generates 7 distinct hex colors without NaN artifacts', () => {
const colors = generatePerceptualRamp({
anchors: ['#fafa6e', '#2A4858'],
steps: 7,
correctLightness: true,
});
expect(colors).toHaveLength(7);
colors.forEach(hex => {
expect(chroma.valid(hex)).toBe(true);
});
});
});Review the git diff before committing to ensure the agent did not overwrite existing color system tokens or hardcode raw RGB channels into styling frameworks.
Agents running without strict verification checks may return an array of `chroma.Color` instances instead of serializable string hex codes, causing runtime rendering failures in frontend components.
Real-World Scenario: Generate Diverging Bathymetric and Elevation Map Color Ramps
“We are building a geographical terrain visualizer. Use chromajs-color-scales-ramps to create color ramp chromajs and interpolate colors bezier chroma for a diverging elevation palette from ocean depths (-4000m) to mountain peaks (+3000m). Sea level (0m) must be neutral light gray, negative values deep navy to aqua, and positive values green to brown/white. Use Bezier smoothing, LCH mode, and lightness correction.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent improperly chained `.mode('lch')` directly after `.scale()` without invoking it before `.colors()` or applied chained methods in an invalid order depending on the Chroma.js version.
const scale = chroma.bezier(['#fafa6e', '#2A4858']).scale().correctLightness();
const hexList = scale.mode('lch').colors(6);Root Cause: The agent configured `.domain()` with inverted or identical min/max thresholds, causing Chroma.js to map every query to the first anchor or saturate the clipping boundary.
const scale = chroma.scale('RdYlBu').domain([minVal, maxVal]).mode('lch');
if (minVal === maxVal) throw new Error('Scale domain requires distinct min and max');Frequently Asked Questions (Chroma.js Perceptually Uniform Color Scales SOP)
Q:Can I use Chroma.js Perceptually Uniform Color Scales across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. By placing the manifest in `.agents/skills/chromajs-color-scales-ramps/SKILL.md` or referencing it in your tool's project instructions, all major agents read and honor the same procedural rules and triggers.
Q:Why does this skill mandate LCH mode and Bezier interpolation over standard RGB?
Standard RGB and HSL color spaces do not align with human vision; stepping linearly through RGB channels creates perceived brightness drops and unnatural gray bands. LCH (Luminance, Chroma, Hue) models human visual perception linearly, and Bezier interpolation smooths the rate of hue shift between anchor points.
Q:Does this skill require escalated root or container permissions?
No. The skill is audited with a security score of 98/100. It requires workspace-scoped file writing for code output, but strictly disables shell execution and external network access, ensuring zero risk of credential exfiltration or rogue downloads.
Ready to equip your autonomous agent with Chroma.js Perceptually Uniform Color Scales?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.