Skip to content

Color System ​

Colour in AdminVora is generated, not picked. Every ramp is produced programmatically in OKLCH so that contrast, harmony, and dark-mode behaviour are guaranteed rather than hoped for.


Why OKLCH ​

Traditional hex/HSL palettes have a structural flaw: equal lightness numbers do not produce equal perceived lightness.

HSL — all at 50% lightness, wildly different perceived brightness:
  hsl(60 100% 50%)   yellow  ████  very bright
  hsl(240 100% 50%)  blue    ████  very dark

OKLCH — all at 60% lightness, uniform perceived brightness:
  oklch(60% .18 60)  amber   ████
  oklch(60% .18 240) blue    ████

Consequences for a design system:

BenefitDetail
Predictable contrastStep 600 clears 4.5:1 on white for every hue, automatically
Consistent rampsThe same lightness curve works for yellow and indigo
Safe interpolationcolor-mix() in OKLCH never passes through muddy grey
Wide gamutP3 displays get richer colour; sRGB fallbacks are emitted automatically
Meaningful hue rotationChanging only H rebrands the system without breaking contrast

Browser support is universal in our target matrix (Chrome 111+, Safari 15.4+, Firefox 113+). A @supports fallback emits sRGB hex for older engines. See Browser Support.


Ramp construction ​

Every hue uses the same lightness and chroma curve. Only H changes.

StepLightnessChroma factorRole
5097%0.08Faintest tint — soft badge backgrounds
10094%0.16Hover on soft backgrounds
20089%0.30Borders on soft surfaces
30082%0.50Disabled solid fills
40072%0.74Dark-mode text/accents
50063%0.93Illustration, chart series
60055%1.00Primary action — 4.5:1+ on white
70047%0.91Hover on primary
80040%0.74Active/pressed
90033%0.56Text on light tints
95024%0.39Dark-mode soft backgrounds
scss
// src/scss/abstracts/_functions.scss
@function av-ramp($hue, $chroma: 0.19) {
  $L: (50: 97%, 100: 94%, 200: 89%, 300: 82%, 400: 72%, 500: 63%,
       600: 55%, 700: 47%, 800: 40%, 900: 33%, 950: 24%);
  $C: (50: .08, 100: .16, 200: .30, 300: .50, 400: .74, 500: .93,
       600: 1,  700: .91, 800: .74, 900: .56, 950: .39);

  $out: ();
  @each $step, $l in $L {
    $out: map.set($out, $step, #{'oklch(#{$l} #{$chroma * map.get($C, $step)} #{$hue})'});
  }
  @return $out;
}

The 14 hues ​

NameHuePrimary use
neutral258 @ C 0.008Text, surfaces, borders — a slightly cool grey, not pure
blue258Default brand, information
indigo275Alternative brand
violet295Chart series, accent
purple310Chart series
fuchsia330Accent, chart
pink350Accent, chart
rose15Danger alternative
red27Danger
orange55Warning alternative
amber75Warning
yellow95Chart, highlight
lime130Chart
green150Success
emerald165Success alternative
teal180Chart
cyan210Chart
sky235Info

Note — neutral is not oklch(L 0 0). A chroma of 0.008 at hue 258 makes greys read as deliberate rather than dead. It also means neutrals harmonise with the brand hue automatically when you rebrand.

The neutral ramp (extended) ​

Neutrals need more steps than colours because dark mode uses fine-grained elevation.

StepLight-mode useDark-mode use
0Card background (white)—
50Page backgroundPrimary text
100Sunken wells—
200Subtle borders—
300Default bordersSecondary text
400Disabled textMuted text
500Subtle textSubtle text
600Muted textDisabled text
700Secondary textStrong borders
750—Default borders
800—Subtle borders
850—Overlay surface
900Primary textRaised surface
925—Sunken surface
950—Page background

Semantic mapping ​

scss
@layer tokens {
  :root {
    /* Brand */
    --av-color-primary:          var(--av-blue-600);
    --av-color-primary-hover:    var(--av-blue-700);
    --av-color-primary-active:   var(--av-blue-800);
    --av-color-primary-subtle:   var(--av-blue-50);
    --av-color-primary-border:   var(--av-blue-200);
    --av-color-primary-text:     var(--av-blue-800);
    --av-text-on-primary:        var(--av-neutral-0);

    /* Status */
    --av-color-success:          var(--av-green-600);
    --av-color-success-subtle:   var(--av-green-50);
    --av-color-success-border:   var(--av-green-200);
    --av-color-success-text:     var(--av-green-800);

    --av-color-warning:          var(--av-amber-500);
    --av-color-warning-subtle:   var(--av-amber-50);
    --av-color-warning-border:   var(--av-amber-200);
    --av-color-warning-text:     var(--av-amber-900);   /* amber needs a darker text step */

    --av-color-danger:           var(--av-red-600);
    --av-color-danger-subtle:    var(--av-red-50);
    --av-color-danger-border:    var(--av-red-200);
    --av-color-danger-text:      var(--av-red-800);

    --av-color-info:             var(--av-sky-600);
    --av-color-info-subtle:      var(--av-sky-50);
    --av-color-info-border:      var(--av-sky-200);
    --av-color-info-text:        var(--av-sky-800);
  }

  [data-bs-theme="dark"] {
    /* Solid fills lighten; soft backgrounds become the 950 step */
    --av-color-primary:          var(--av-blue-500);
    --av-color-primary-hover:    var(--av-blue-400);
    --av-color-primary-active:   var(--av-blue-300);
    --av-color-primary-subtle:   var(--av-blue-950);
    --av-color-primary-border:   var(--av-blue-800);
    --av-color-primary-text:     var(--av-blue-300);

    --av-color-success:          var(--av-green-500);
    --av-color-success-subtle:   var(--av-green-950);
    --av-color-success-border:   var(--av-green-800);
    --av-color-success-text:     var(--av-green-300);
    /* …same pattern for warning, danger, info */
  }
}

Important — dark mode is not "invert the ramp". Solid fills move up one or two steps (600 → 500) because a dark background makes colours read darker. Soft backgrounds jump to the 950 step. Text on soft backgrounds uses 300, not 800.


Automatic text-on-colour ​

Never hard-code white text on a brand colour. If someone rebrands to amber, white text fails contrast. Compute it:

scss
@function av-on-color($bg-lightness) {
  @return if($bg-lightness > 62%, var(--av-neutral-950), var(--av-neutral-0));
}

.btn-primary {
  background: var(--av-color-primary);
  color: var(--av-text-on-primary);
}

--av-text-on-primary is emitted by the token build, which evaluates the OKLCH lightness of the resolved primary and picks black or white. Runtime equivalent, for user-chosen accent colours:

js
// src/js/utils/color.js
export function onColor(cssColor) {
  const { l } = parseOklch(cssColor);
  return l > 0.62 ? 'var(--av-neutral-950)' : 'var(--av-neutral-0)';
}

Progressive enhancement with the native CSS function, where supported:

scss
@supports (color: contrast-color(red)) {
  .btn-primary { color: contrast-color(var(--av-color-primary)); }
}

Contrast guarantees ​

Verified by npm run lint:tokens across every preset × light/dark. Failing the table fails CI.

PairRequiredActual (aurora/light)
text-primary on surface-base7:1 (AAA)16.1:1
text-primary on surface-raised7:117.4:1
text-secondary on surface-raised4.5:18.9:1
text-muted on surface-raised4.5:15.2:1
text-muted on surface-sunken4.5:14.7:1
text-on-primary on color-primary4.5:15.1:1
color-danger-text on color-danger-subtle4.5:17.3:1
border-default on surface-raised3:13.4:1
focus-color on surface-raised3:14.9:1

text-subtle is the only role permitted below 4.5:1 (it sits at 3.1:1) and is restricted to decorative or ≥ 18.66 px text. Stylelint flags it on small text.


Chart palettes ​

Charts need a categorical palette that is distinguishable and that belongs to the theme. Each preset lists eight colours by hand, in order, in tools/presets.mjs; the build emits them as --av-chart-1 to --av-chart-8, with 9 and 10 as lighter repeats of 1 and 2.

scss
/* Generated for every preset, light and dark. Aurora shown. */
[data-av-preset="aurora"] {
  --av-chart-1: oklch(55% 0.19 262);   /* series 1 is the preset's own hue */
  --av-chart-2: oklch(56% 0.13 155);
  --av-chart-3: oklch(56% 0.17 300);
  --av-chart-4: oklch(60% 0.14 55);
  --av-chart-5: oklch(58% 0.11 235);
  /* … to --av-chart-10 */
}
[data-av-preset="aurora"][data-bs-theme="dark"] {
  --av-chart-1: oklch(69% 0.18 262);   /* lifted to read on a dark card */
  /* … */
}

Why curated rather than generated:

  • Evenly spaced hues at one lightness merge. The earlier build rotated a colour wheel at fixed lightness and chroma. That looks orderly and fails in greyscale and for colour-blind readers, and on warm themes it put red beside green.
  • Lightness varies between neighbours, so adjacent series separate even without hue.
  • The build checks it. Series 1 to 5 must clear 3:1 against the card in both modes, and neighbouring series must stay apart under simulated deuteranopia and protanopia, or npm run tokens fails.
  • Dark mode lifts, it does not re-pick. Each colour moves into a lightness band that reads on a dark card, with its hue unchanged, so a series is the same series in both modes.

A chart with five or fewer series is readable by colour alone. Beyond five, the runtime gives the series alternating dash patterns automatically, so lines stay distinguishable without colour.


Data-visualisation gradients ​

scss
.av-chart-gradient-primary {
  --av-grad-from: oklch(from var(--av-color-primary) l c h / .28);
  --av-grad-to:   oklch(from var(--av-color-primary) l c h / 0);
  background: linear-gradient(to bottom, var(--av-grad-from), var(--av-grad-to));
}

The oklch(from …) relative-colour syntax derives a transparent version of whatever the primary currently is — including a runtime-set custom brand colour.


Elevation-aware colour in dark mode ​

Material's insight, implemented with tokens: in dark themes, higher elevation means a lighter surface, because more ambient light reaches a raised plane.

scss
[data-bs-theme="dark"] {
  --av-surface-base:    var(--av-neutral-950);   /* 0dp */
  --av-surface-sunken:  var(--av-neutral-925);   /* -1dp */
  --av-surface-raised:  var(--av-neutral-900);   /* 1dp */
  --av-surface-overlay: var(--av-neutral-850);   /* 8dp */
  --av-surface-float:   var(--av-neutral-800);   /* 16dp */
}

Combined with a 1px inner top highlight, this reads as depth without any shadow:

scss
[data-bs-theme="dark"] .av-card {
  box-shadow:
    0 1px 3px 0 oklch(0% 0 0 / .4),
    inset 0 1px 0 0 oklch(100% 0 0 / .04);
}

Colour-blind and forced-colour modes ​

Simulation ​

bash
npm run test:visual -- --grep colorblind

Renders every page through deuteranopia, protanopia, and tritanopia SVG filters and compares against approved baselines.

Forced colours (Windows High Contrast) ​

scss
@media (forced-colors: active) {
  .av-card    { border: 1px solid CanvasText; }
  .btn        { border: 1px solid ButtonText; forced-color-adjust: none; }
  .btn-primary{ background: Highlight; color: HighlightText; }
  .av-badge   { border: 1px solid CanvasText; }
  :focus-visible { outline: 2px solid Highlight; }
  .av-chart   { forced-color-adjust: none; }   /* charts must keep their own colours */
}

Rebranding: the complete recipe ​

There is no @use 'adminvora' with (…) map of SCSS variables; that configuration surface does not exist and never did. What replaces it is shorter for the common case and blunter for the rare one.

If one of the shipped presets is close enough, it is an attribute and no build at all:

html
<html data-av-preset="matsuba">

If you need your own brand, override the ramp in a stylesheet loaded after tokens.css. The whole product paints through --av-primary-*, so the eleven steps are the entire surface:

css
:root {
  --av-primary-500: oklch(63% 0.16 152);   /* green */
  --av-primary-600: oklch(55% 0.17 152);
  --av-primary-700: oklch(47% 0.15 152);
  /* …50–950; the mid steps are what buttons, links and focus rings use */
}

If you want the greys to pick up a matching tint too, that is a regenerate rather than an override: the neutral ramp is built by ramp() in tools/build-tokens.mjs from a hue and a chroma, and changing those two numbers there and running npm run tokens rewrites every neutral step consistently. Doing it by hand in CSS means writing out eleven more values and keeping them in step with the light and dark aliases, which is exactly the bookkeeping the generator exists to do.

Whichever route you take, verify — a rebrand is the one change that can quietly break contrast in one mode while looking correct in the other:

bash
npm run check:tokens       # every var(--av-…) still resolves
npm run test:contrast      # every preset × 2 modes at 4.5:1, measured in the browser
npm run test:visual        # nothing shifted structurally

Read next: Typography.

Documentation for @creativeigniter/adminvora