Accent-hue blacks

Accent-hue blacks (core rule)

Blacks and dark neutrals must pair with the accent. A blue theme with a red-based near-black clashes even when both look "dark" in isolation.

Rule

When a dark neutral has saturation > 0, its hue must equal the theme / accent hue.

if saturation > 0 → hue = accent hue
if saturation = 0 → achromatic OK (#000, neutral gray)

Same logic in any color space, HSL, HSV, OKLCH, LCH, etc. Convert to read/write hue; apply the rule on the hue channel.

Saturation 0 = true neutral black or gray. No hue to align.

Saturation > 0 = tinted dark. Hue must follow accent, not warm default, not random gray from a library.

Why this goes wrong

• Uses #000, #111, #1a1a1a (often warm or green-shifted in perception)
• Pulls "slate" or "zinc" scales from a component library without matching brand hue
• Blue accent + hsl(0, 10%, 8%) or stone/warm gray stack → subtle red/yellow cast against blue

Examples

Blue accent, hsl(220, 85%, 55%)

A true achromatic (hsl(0, 0%, 7%), saturation 0) is not a clash, it has no hue to conflict, see the rule above. It can read flat beside saturated UI; a slight accent-hue tint (hsl(220, 10%, 12%)) usually feels more intentional, but the neutral is allowed.

Green accent, hsl(145, 60%, 45%)

• Dark text on light: hsl(145, 8%, 12%) not hsl(30, 8%, 12%)

Workflow

1. Set accent hue once (--accent-h: 220 or from primary token).
2. For each dark neutral (background, text, border) with saturation > 0: - Set h = --accent-h - Tune s and l for contrast and hierarchy only
3. Leave s = 0 only for true black/white/gray when you want achromatic.

CSS tokens

:root {
  --accent-h: 220;
  --accent-s: 85%;
  --accent-l: 55%;

  --color-primary: hsl(var(--accent-h) var(--accent-s) var(--accent-l));

  /* Tinted darks, hue locked to accent */
  --color-bg:        hsl(var(--accent-h) 12% 7%);
  --color-surface:   hsl(var(--accent-h) 10% 11%);
  --color-text:      hsl(var(--accent-h) 8% 92%);
  --color-text-muted: hsl(var(--accent-h) 6% 62%);

  /* Achromatic escape hatch */
  --color-black: hsl(0 0% 0%);
}

Dark mode: same rule, elevated surfaces use accent hue with lower l, not a unrelated gray scale.

OKLCH

/* accent ~ oklch(0.55 0.18 250) → hue 250 */
--color-bg: oklch(0.14 0.02 250);   /* h matches accent */
--color-bg-bad: oklch(0.14 0.02 25); /* warm hue, clashes with blue accent */

If c > 0 (or chroma equivalent), h = accent h.

Audit

For each near-black / dark gray with measurable saturation:

1. Read hue of accent / primary
2. Read hue of dark neutral
3. If neutral s > 0 (or chroma > 0) and hues differ → High, retint to accent hue

Flag common library grays (zinc, stone, neutral) under a saturated brand unless their hue was deliberately aligned.

Building the palette

Sleak's accent + accent-hue-black rules above are the sharpened version of the conventional palette method. The underlying construction recipe:

One monochromatic ramp built from the brand hue, each step with a defined job and a contrast floor (against the lightest/background):

• Greys carry a tinge of the primary hue (saturate slightly, don't use pure neutral), this is exactly the accent-hue blacks rule. Use s: 0 only when you deliberately want true achromatic.
• Apply the brand colour to interactive elements, not decoration, it teaches users what's clickable. (Sleak goes further: reserve full accent for the single primary task.)
• If the brand colour carries meaning (e.g. red = errors) or is too light/dark to hit contrast, use the darkest/white variation for actions instead, or add a 3:1 border.

Keep the ramp lean. A few tints (mixed toward white) and shades (mixed toward black) per colour, plus a slim neutral set, no more. Too many near-identical steps invite inconsistency and misuse; add an option only when a real need appears. Store them as tokens.

Darken/lighten without muddiness. Mixing a colour with pure black or white can turn it muddy, a darkened yellow drifts toward brown. Mix toward a neighbouring hue instead (deepen yellow with a little orange) to keep the shade clean.

Start in black and white. Design the interface in greys first, it forces you to solve spacing, size, and contrast before colour, and colour then goes only where it carries meaning. And avoid pure #000 on pure #fff: the maximal contrast causes eye strain over long reading, prefer a very dark grey (which also satisfies the accent-hue-black rule above).

System colours, you need three, each paired with an icon (never colour alone):

System-colour text needs ≥ 4.5:1; system-colour icons/components need ≥ 3:1.

Light & dark mode: slide, don't invert

Switching themes is not colour inversion. Flipping every value (light ↔ dark) breaks hierarchy and produces harsh, muddy results. Instead, slide each colour along its range to the equivalent role in the other mode, keeping the palette's relationships intact.

Preserve relative luminance across modes

A surface keeps its relative brightness rank when you toggle modes. The surface that is brightest relative to its neighbours in light mode stays the brightest relative to its neighbours in dark mode, the whole set slides down the luminance range together; it doesn't flip.

Elevation governs luminance

Surface luminance is driven by elevation, how close a surface sits to the user:

• Surfaces closer to the user (higher elevation) have higher luminance.
• In dark mode, elevated surfaces (cards, menus, modals, popovers) get lighter as they rise, not darker. The base/background is the darkest; each layer above lifts.
• In light mode, the ordering is preserved by the same range-slide; don't invert it into a contradictory stack.

Model elevation as steps on one luminance ramp and reuse the same ramp in both modes:

/* one ramp; each mode slides the same roles along it */
:root { /* light */
  --surface-0: hsl(var(--accent-h) 10% 99%);  /* base */
  --surface-1: hsl(var(--accent-h) 10% 97%);  /* raised card */
  --surface-2: hsl(var(--accent-h) 10% 95%);  /* menu / modal, closest to user */
}
:root[data-theme="dark"] { /* slid down the range, elevation still lifts luminance */
  --surface-0: hsl(var(--accent-h) 12% 9%);   /* base, darkest */
  --surface-1: hsl(var(--accent-h) 11% 13%);  /* raised card, lighter */
  --surface-2: hsl(var(--accent-h) 10% 17%);  /* menu / modal, lightest */
}

Neutrals still follow accent-hue blacks; re-check contrast.md after the slide (a pair that passed in light mode is a different ratio in dark).

Common mistakes

Fixes

1. Define the single primary task for the view; give it the only full-accent control.
2. Strip decorative accent from icons, section chrome, and non-action headings.
3. Use opacity tints only on states tied to the primary path (selected, focus, progress).
4. Define --accent-h (or equivalent) at theme root for neutrals (see accent-hue blacks).
5. Replace tinted darks whose hue ≠ accent hue.
6. Keep saturation low on neutrals (often 6–15%), hue harmonizes; chroma is for actions.

Do / Don't

Notes

• Contrast / a11y: Retinting hue rarely breaks WCAG if lightness is unchanged; re-check contrast after shifts.
• Multi-accent brands: Use dominant UI accent hue for neutrals, or split by surface role, document the choice.
• Print / exports: Same rule when generating theme tokens for Figma or design systems.