Appearance
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:
| Benefit | Detail |
|---|---|
| Predictable contrast | Step 600 clears 4.5:1 on white for every hue, automatically |
| Consistent ramps | The same lightness curve works for yellow and indigo |
| Safe interpolation | color-mix() in OKLCH never passes through muddy grey |
| Wide gamut | P3 displays get richer colour; sRGB fallbacks are emitted automatically |
| Meaningful hue rotation | Changing 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.
| Step | Lightness | Chroma factor | Role |
|---|---|---|---|
| 50 | 97% | 0.08 | Faintest tint — soft badge backgrounds |
| 100 | 94% | 0.16 | Hover on soft backgrounds |
| 200 | 89% | 0.30 | Borders on soft surfaces |
| 300 | 82% | 0.50 | Disabled solid fills |
| 400 | 72% | 0.74 | Dark-mode text/accents |
| 500 | 63% | 0.93 | Illustration, chart series |
| 600 | 55% | 1.00 | Primary action — 4.5:1+ on white |
| 700 | 47% | 0.91 | Hover on primary |
| 800 | 40% | 0.74 | Active/pressed |
| 900 | 33% | 0.56 | Text on light tints |
| 950 | 24% | 0.39 | Dark-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
| Name | Hue | Primary use |
|---|---|---|
neutral | 258 @ C 0.008 | Text, surfaces, borders — a slightly cool grey, not pure |
blue | 258 | Default brand, information |
indigo | 275 | Alternative brand |
violet | 295 | Chart series, accent |
purple | 310 | Chart series |
fuchsia | 330 | Accent, chart |
pink | 350 | Accent, chart |
rose | 15 | Danger alternative |
red | 27 | Danger |
orange | 55 | Warning alternative |
amber | 75 | Warning |
yellow | 95 | Chart, highlight |
lime | 130 | Chart |
green | 150 | Success |
emerald | 165 | Success alternative |
teal | 180 | Chart |
cyan | 210 | Chart |
sky | 235 | Info |
Note —
neutralis notoklch(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.
| Step | Light-mode use | Dark-mode use |
|---|---|---|
0 | Card background (white) | — |
50 | Page background | Primary text |
100 | Sunken wells | — |
200 | Subtle borders | — |
300 | Default borders | Secondary text |
400 | Disabled text | Muted text |
500 | Subtle text | Subtle text |
600 | Muted text | Disabled text |
700 | Secondary text | Strong borders |
750 | — | Default borders |
800 | — | Subtle borders |
850 | — | Overlay surface |
900 | Primary text | Raised 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.
| Pair | Required | Actual (aurora/light) |
|---|---|---|
text-primary on surface-base | 7:1 (AAA) | 16.1:1 |
text-primary on surface-raised | 7:1 | 17.4:1 |
text-secondary on surface-raised | 4.5:1 | 8.9:1 |
text-muted on surface-raised | 4.5:1 | 5.2:1 |
text-muted on surface-sunken | 4.5:1 | 4.7:1 |
text-on-primary on color-primary | 4.5:1 | 5.1:1 |
color-danger-text on color-danger-subtle | 4.5:1 | 7.3:1 |
border-default on surface-raised | 3:1 | 3.4:1 |
focus-color on surface-raised | 3:1 | 4.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 tokensfails. - 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 colorblindRenders 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 structurallyRead next: Typography.