What is the better-colors skill?
The better-colors skill is a folder in Jakub Krehel's skills repo for building and auditing color systems. It generates ramps, maps their steps to roles and token names, converts color notation and measures rendered contrast pairs. It will not report a contrast value it did not measure or estimate a color it could compute.
A skill that treats color as a system of ramps, roles and tokens rather than a pile of hex values. It builds the system, audits an existing one and measures contrast on the pairs that actually render.
Its first rule is evidence. A broken role mapping, a failing pair and an out of gamut step are findings. Notation, a tinted neutral and a gradient's interpolation space are project choices and are left alone.
How a color system gets built
- One neutral ramp, one accent ramp and only the status ramps the product renders. A warning ramp nothing imports is not generated.
- Every step has a job, such as page background, hover, border, solid fill or body text.
- Primitives are named by hue, like --blue-600. Semantic tokens are named by role, like --color-text-secondary, and only those are used in components.
- Ramps hold one hue end to end, built with a color library and never by eye.
Measuring contrast
The skill measures a foreground against the background it really renders on, including alpha and images beneath it. When a pair fails, it reports the pair, the value and the threshold missed, and leaves the colors alone unless you ask.
Who better-colors suits
Best for
- Starting a palette or token layer for a new project.
- Cleaning up a codebase with hex, rgb and oklch literals scattered through components.
- Adding dark mode tokens and checking every pair afterward.
Not for
- Deciding whether a pair must pass. That requirement belongs to better-accessibility.
- Shadows, surfaces and icon color, which belong to better-ui.
- Extracting a design system from existing work. Related: extract-design-system.
Use it with UiChemy
Settle your tokens first, then bring the design into WordPress through UiChemy Figma to WordPress or Composer, and measure contrast again on the converted page. Click Get Started on uichemy.com.
How to install Better Colors Skill: Palettes, Tokens and Contrast
git clone https://github.com/jakubkrehel/skills.gitClone the repository
Run
git clone https://github.com/jakubkrehel/skills.git. The skill is in skills/better-colors.Copy the folder
Copy skills/better-colors to the place your agent loads skills from, keeping the reference files such as contrast.md, palette-generation.md and token-naming.md next to SKILL.md.
Alternative for Claude Code
Run
/plugin marketplace add jakubkrehel/skillsand then/plugin install interfaces@interfaces, as the README documents.Ask for a color job
Ask for a palette, a token rename, a notation conversion or a contrast audit of a named file. Say whether you want edits or a report only.
Check that it loaded
Ask it to check one component's colors. It should name the tokens, measure the rendered pair rather than guess, and finish with a findings table and Block or Approve.
Key features
- Match the project firstThe skill reuses the project's tokens and notation, because a consistent hex system beats hex with oklch scattered through it. New systems default to oklch.
- Ramps with a purposeEach step maps to a role, using either the Tailwind 50 to 950 or the Radix 1 to 12 convention. Steps no role consumes are not generated.
- Two token tiersPrimitives name a value and never appear in components. Semantic tokens name a job, point at a primitive and are the only tier components reference.
- Use a token only in its roleA separator color used as text works until borders get lighter. If a role has no token, the skill adds one instead of borrowing.
- Constant hue rampsA ramp holds one hue, peaks in vividness mid-ramp and steps more finely at the light end, about 0.04 to 0.05 of OKLCH lightness per step.
- One color, one meaningColors within 15 degrees of OKLCH hue count as the same color. A status hue should sit at least 15 degrees from the accent.
- One filled action per viewWhen filled color marks primary emphasis, one action gets it and peers stay neutral. Color goes on the background, not the label.
- Measured contrast onlyThe skill measures the rendered pair in light and dark, and reports pair, value and missed threshold without changing colors unprompted.
- Gradient and gamut handlingGradients default to in oklab, with in oklch for two hue gradients that go gray. Out of gamut values need an sRGB fallback declared first.
- Detection tableA before you finish table flags patterns like hsl ramps differing only in lightness, text-white on a Tailwind 500 fill and dark tokens that merely reverse the light ramp.
Frequently asked questions
What is the better-colors skill?
It is a skill in Jakub Krehel's skills repository that builds and audits color systems. It generates ramps, maps steps to roles and token names, converts notation between formats and measures contrast on rendered pairs, and it writes everything in the notation your project already uses.
How do I install better-colors?
Clone jakubkrehel/skills and copy skills/better-colors, with its reference files, into your agent's skills folder. In Claude Code you can run the plugin marketplace add and plugin install commands from the README instead. Then ask for a palette, token naming or a contrast check.
Why does better-colors prefer OKLCH?
For a new system, oklch is the default because its numbers behave the way the ramp rules describe, with perceived lightness running from 0 to 1. If your project already uses hex or another notation, the skill keeps that notation, since consistency matters more than switching.
Does better-colors fix failing contrast automatically?
No. It reports the failing pair, its measured value and the threshold it misses, then leaves the colors alone because they are a design decision. When you ask for a change, it adjusts lightness, the channel contrast responds to, and measures again afterward.
Which AI coding agents can use better-colors?
The README documents a Claude Code plugin install, and the skill folder includes an agents/openai.yaml file. For other agents, copy the folder to their skills location. The README lists no other agents, so check that yours reads SKILL.md folders before relying on it.
How are primitive and semantic tokens different?
Primitives name a value, such as --blue-600, and are never used directly in components. Semantic tokens name a job, such as --color-text-secondary, point at a primitive and are the only tier components reference. That split lets a theme repoint colors without touching component code.
Where can I get a full interface review that includes color?
Better-interface combines every better skill, including colors, into a single review across accessibility, layout, writing, typography, color and UI polish. The better-colors skill itself measures the rendered pair in light and dark and reports pair, value and missed threshold without changing colors unprompted. Related: theme-factory and tailwind-design-system.