A color system that holds up in light, dark and every market

---
name: jubayer-colors
description: Builds and reviews color systems, including palettes and ramps, primitive and semantic tokens, format conversion, measured WCAG 2 and APCA contrast, gradients, dark mode and P3 fallbacks. Also covers color in bilingual Arabic/English and Bangla/English products, where meaning varies by culture (price up/down colors per market, never hue alone) and directional gradients, shadows and chart ramps must follow right-to-left layouts. Use when creating or auditing a palette or color tokens, choosing or converting colors, checking contrast, fixing dark mode, or adapting color for RTL or for another market.
---

# Colors

Treat color as a system: a few ramps, each step tied to a role, every token named for its job and every pair checked against the background it really sits on. When color goes wrong it is rarely one bad value. It is a value chosen without the ramp, a token reused because it happened to match, or a pair no one measured.

Color questions usually have an exact answer, so compute it. Do not estimate a value you can calculate, and do not report a contrast figure you have not measured.

Contrast requirements belong to `jubayer-accessibility`. Surfaces, shadows and icon color belong to `jubayer-ui`.

## Match the project's color system

Reuse the project's tokens and notation. A second representation added to fix one value makes the palette harder to reason about. A consistent hex system beats hex with `oklch()` scattered through it.

For a new system, `oklch()` is the best default, because its numbers behave the way the ramp rules below describe. Everywhere else, a color library produces the same ramp in the project's own notation ([color-formats.md](color-formats.md)).

## A system is ramps, not colors

One neutral ramp, one accent ramp and only the status ramps the product actually renders. A `warning` ramp nothing imports is maintenance for zero pixels. A second accent hue earns its place only when two things must be distinguishable at a glance.

## Every step has a job

A ramp is not a gradient to pick from by eye. Each step exists because a role needs it: page background, component hover, border, solid fill, body text. Do not generate a step no role consumes. Both the Tailwind `50` to `950` and Radix `1` to `12` conventions map to those roles ([palette-structure.md](palette-structure.md)).

## Name primitives by hue, semantics by role

Primitives name a value (`--blue-500`) and are never applied in a component. Semantic tokens name a job (`--color-text-secondary`), point at a primitive and are the only tier components reference.

That seam is what makes theming possible. Without it, dark mode means auditing every usage to work out which meant "the accent" and which just wanted blue ([token-naming.md](token-naming.md)).

## Use a token only in its role

Never borrow a token because its value is right today. A separator used as a text color works until borders get lighter, and then the text goes with them. If a role has no token, add the token.

## Hold the hue across the ramp

Four properties define a well-formed ramp:

- Steps step evenly in *perceived* lightness, not in whatever the format calls lightness.
- Hue stays constant end to end.
- Vividness peaks mid-ramp and falls off at both ends.
- Steps sit denser at the light end than at the dark end.

Both ends stop short of pure black and white, which cannot carry hue at all. Use a color library rather than eyeballing it ([palette-generation.md](palette-generation.md)).

## One color, one meaning

Use a color for one purpose across the whole interface, treating anything within `15°` of hue as the same color. If the accent means interactive, that hue on static text tells users to click something that is not clickable, and an interactive element rendered neutral misleads just as badly. Color is never the only carrier of meaning, which `jubayer-accessibility` owns.

## Fill exactly one action per view

When filled color encodes primary emphasis, one primary action gets it and peers stay neutral. Put the color on the background, not the label. A filled button reads as primary across the room; accent-colored text on a neutral button reads as a link.

Several colored backgrounds are fine when they encode distinct states or categories rather than competing as peers.

## Measure the rendered pair, then report

Measure a foreground against the background it actually renders on, not the page background. When a pair fails, report the pair, its measured value and the threshold it misses, then leave the colors alone. They are a design decision. Change them only when asked, and remeasure after ([contrast.md](contrast.md)).

## Pick a gradient's interpolation space

The space is a look, not a correctness setting.

- **`in oklab`** is the best default: even brightness, no hue surprises.
- **`in oklch`** travels around the hue wheel rather than through the middle, staying vivid and sweeping every hue between the stops. Reach for it when a two-hue gradient goes gray in the middle.
- **The sRGB default** darkens and mutes the midpoint. It is what most interfaces already have, because it is what you get without asking.

See [color-usage.md](color-usage.md).

## Color across cultures and in RTL

Hue meaning varies by culture and context, so it never carries meaning alone (WCAG 1.4.1 Use of Color): pair it with an icon, a sign or a label. Price changes are the documented case: in mainland China and some other East Asian markets red means up and green means down, so price colors follow the market or a user setting, never `lang`, and always come with an arrow and a sign. Name tokens by role (`success`, `danger`, `change-up`) so a market remaps one block. In RTL, gradients have no logical keywords and shadow x offsets are physical, so override directional ones under `:dir(rtl)`; keep chart legends and ramps running the same way as their axis. Arabic and Bangla text uses the same contrast thresholds, but keep it well clear of them ([color-across-cultures-and-rtl.md](color-across-cultures-and-rtl.md)).

## Before you finish

| Mistake | Fix |
| --- | --- |
| A raw value where the project has a token | Reuse or add the role token, in the project's notation |
| An isolated `oklch()` value dropped into a hex codebase | Keep the established notation unless a migration is in scope |
| A primitive like `--blue-500` used directly in a component | Point a semantic token at it |
| Token named for its appearance (`--color-blue-button`) or first use (`--color-sidebar-gray`) | Name it for its role: `--color-accent-solid`, `--color-bg-surface` |
| `--color-primary` meaning the brand and `--color-text-primary` meaning body text | Reserve `accent` for the brand; let `primary` mean "most prominent of its group" |
| Semantic token used outside its role (separator as text) | Add a token for the missing role; never borrow by value |
| Ramp built by varying HSL lightness | Rebuild against perceived lightness with a constant hue |
| Ramp spaced evenly across the full range | Tighten the light end until `50` and `100` read as two surfaces |
| Same saturation number reused across hues | Match the proportion of each hue's own maximum, not the raw value |
| Status hue that collides with the accent hue | Move it until destructive and primary read apart side by side |
| Dark mode made by mechanically reversing the light palette | Reverse as a starting point, then reduce vividness, widen the dark end and recheck every pair |
| `prefers-color-scheme` setting some tokens and a `.dark` class setting others | Pick one switching mechanism and use it throughout |
| Contrast fixed by changing hue | Change lightness, the channel contrast responds to |
| P3 color with no sRGB fallback | Declare the sRGB value first, then override inside `@media (color-gamut: p3)` |
| Red and green hard-coded for price up and down | `--color-change-up` / `--color-change-down` set per market or user setting, with an arrow and a sign |
| Token named `--color-green` or `--color-positive` where a market may remap it | Name the role: `--color-success`, `--color-change-up` |
| `linear-gradient(to right, ...)` fade or edge shadow that stays put in RTL | Override the direction or negate the x offset under `:dir(rtl)` |
| Chart legend running the opposite way to its mirrored axis | Mirror the legend and ramp with the axis, or mirror neither |
| Arabic or Bangla text in a light weight on a pair that barely passes | Regular or medium weight, and a pair well clear of the threshold |

## Reporting

**Severity.** `HIGH` makes content unreadable or assigns a misleading semantic color. `MEDIUM` is a noticeable theme, token, or gamut failure. `LOW` is isolated polish.

**Verification.** Without a browser: token values, the gamut of every declared color, both theme blocks present and contrast computed from the declared token pair. With one: the background actually rendered behind the text, including opacity and any image beneath it, measured in both light and dark. In the RTL locale, check every directional gradient, edge shadow and chart legend. A failing pair is reported, not repainted. Report every check you could not run as `Not verified`.

**Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:

| Severity | Location | Before | After | Why |
| --- | --- | --- | --- | --- |

`Location` is `path/to/file:line`. `Why` names the principle and the user impact.

End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable color findings" and report verification.

## Origin

Based on Jakub Krehel's `better-colors` skill (MIT License), renamed and edited by Maniruzzaman Jubayer, with added right-to-left and bilingual rules. See LICENSE.