Color System

color_goal = $ARGUMENTS

Color systems fail more often from absent judgment than absent math — this skill exists to supply that judgment, backed by deterministic helpers when scale or consistency require them.

For methods, review loops, and helper-script patterns: !references/color-method.md

Calibration

• Color is relational. Judge any color by what it sits on, sits next to, carries as text, and represents as state — never in isolation. Palette that reads well as a list of values but fails on buttons, badges, forms, charts, tables, or dark mode is unfinished.
• Fit beats theory. Infer feeling, trust, energy, emphasis from the actual task. Theoretically elegant palette that feels wrong in context is wrong. Don't force work into canned categories or "what palette type is this?".
• Reason in lightness, chroma, hue. Lightness → hierarchy & legibility. Chroma → intensity & restraint. Hue → temperature, meaning, emotional direction. State changes move by lightness and chroma first, dramatic hue jumps last.
• Passing contrast is necessary, not sufficient. System can pass WCAG and still feel generic, noisy, flat, or emotionally wrong.
• Differentiate on purpose. Fitting category expectations vs claiming visual territory others avoid is a conscious choice — state which you're making.
• Match depth to stage. Early exploration wants direction and interpretation, not token architecture. Reserve ramps, tokens, and validation for refinement.

Scripts: instrument, not author

Stay in plain-language reasoning for direction work and small critiques. Reach for a helper script only after anchors and behavior are clear, or when scale/consistency/validation matters. Good uses:

• generating tonal ramps from chosen anchors
• testing contrast and pairing likely foregrounds
• deriving hover/active/disabled/selected variants
• checking collisions between primary, info, success, selected
• comparing alternate variants side by side
• auditing a codebase for hardcoded or drifting colors
• attaching usage metadata to formalized tokens (intended use, avoid cases, contrast reqs, component bindings)

Never let a script choose the design direction.

Diagnose root, not symptom

Name the failure class before changing colors. Most palette failures are structure failures before hue failures. Common roots:

• weak lightness structure
• too much chroma everywhere
• semantic collisions (primary/info/success/selected too close)
• accent overuse — emphasis is strong only when rare
• dark-theme over-saturation
• components bypassing the intended system and improvising locally

Fix shared color logic before adding one-off exceptions.

Heuristics

• Neutrals usually do more product work than accents.
• Brand color is rarely the right choice for backgrounds, borders, or semantic states.
• Simpler system applied faithfully beats a clever, fragile one.
• Gradients, glows, and tinted shadows are part of the color system when they materially affect perception.
• Token names follow meaning, not appearance.
• Semantic state colors serve interfaces that truly need them — not mandatory for every system.
• Output drifting toward a generic agent palette → stop, restate the intended feeling in plain language.

Output

Smallest useful artifact for the moment — root-cause critique, first-impression read plus diagnosis, 2-4 distinct directions w/ tradeoffs (vary emotional logic and hierarchy, not just accent hue), palette brief of anchors and relationships, semantic role/token recommendations, helper-script plan, or migration plan.

When proposing multiple directions, for each give: what it feels like, what it makes easy, what it makes risky, whether it fits or differentiates, where it fails if pushed too far.

If context is thin, inspect what exists (brand cues, current tokens, screenshots, code, component library, complaints) first, then ask at most one targeted question — only when the answer would materially change the direction.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JHostalek
• Source: JHostalek/dotclaude
• License: CC0-1.0
• Homepage: https://jhostalek.github.io/dotclaude/

Install and usage instructions live in the source repository linked above.