Colors & Design Tokens

Axiom01 enforces a semantic color system powered by OKLCH math. Colors are assigned by their structural role, rather than hardcoded hex values, ensuring perfect contrast and automatic dark mode scaling.

The OKLCH Advantage

Axiom01 uses OKLCH — a perceptually uniform color space. Unlike HSL or RGB, OKLCH guarantees that color tokens maintain consistent visual brightness and contrast across all hues and themes, delivering WCAG AAA compliance natively at the framework root.

The Flaw with HSL

Yellow and Blue at 50% HSL Lightness appear drastically different in perceptual brightness, causing contrast failures when theming.

The OKLCH Fix

Axiom01's mathematically calculated OKLCH tokens lock lightness scaling, ensuring that swapping the primary hue variable preserves contrast perfectly.

Core Token Families

Never hardcode a color. Instead, use these semantic CSS variables across your stylesheets to inherit the theme perfectly.

Primary

var(--a-color-primary-container)

--a-color-primary

The brand color. Use for core actions and active states.

Secondary

var(--a-color-secondary-container)

--a-color-secondary

Secondary actions and less prominent highlights.

Surface

var(--a-color-surface-variant)

--a-color-surface

The main background and card structural color.

Status Families

Available status variations follow the exact same base, on-base, container, and on-container pattern. They can be invoked by wrapping content in <div class="success">, or styling with the tokens directly.

Success

--a-color-success

Warning

--a-color-warning

Error

--a-color-error

Info

--a-color-info

Comprehensive Color Swatches

These swatches demonstrate all the generated CSS color variables available in the Axiom01 theme. They automatically respond to Light/Dark mode.

Primary --a-color-primary

Primary Container --a-color-primary-container

Secondary --a-color-secondary

Secondary Container --a-color-secondary-container

Surface --a-color-surface

Surface Variant --a-color-surface-variant

Surface Sunken --a-color-surface-sunken

Background --a-color-background

Color Combinations & Best Practices

Axiom01 guarantees high-contrast text by pairing every color with an on- counterpart. You must follow these combinations to ensure WCAG AAA accessibility.

Never mix and match: If the background is var(--a-color-primary), the text must be var(--a-color-on-primary).
Avoid generic colors: Do not use CSS keywords like red or blue. Always use the semantic status tokens (--a-color-error, --a-color-info).
Containers for subtlety: Use the -container variants for large backgrounds and alerts, which are softer and have high contrast text (on-[color]-container).
Borders: Always use --a-color-outline for standard structural borders, as it scales intelligently in dark mode.

Color Harmony & Combinations

Every color in Axiom01 is mathematically calculated using OKLCH math. Every token works together beautifully across all themes.

Analogous Harmony

Colors that sit next to each other on the color wheel create calm cohesion.

Complementary

Opposite colors create maximum contrast and striking visual impact.

Semantic Pairing

Semantic colors convey meaning and reinforce user expectations.

Dark Mode by Default

Automatic Lightness Scaling

In most frameworks, you have to manually define a "dark" version of every color. With Axiom01, the math does the work. By simply toggling data-theme="dark" on the HTML element, the OKLCH variables automatically shift their lightness coordinates.

You never have to write a @media (prefers-color-scheme: dark) block again. The --a-color-surface goes dark, --a-color-on-surface turns light, and your primary brand color shifts to maintain optimal WCAG contrast against the new background.

Container and On-Container Colors

Subtle Backgrounds with High Contrast Text

When you need a subtle background for an element (like an alert box or a selected item), you shouldn't use the raw primary color, nor should you arbitrarily lower opacity.

Axiom01 provides -container tokens that automatically generate a soft, low-chroma version of the color, paired with a high-contrast on-[color]-container token for the text.

Primary Container

Success Container

Warning Container

Preset Gradients

Axiom01 includes several beautiful, pre-configured gradients that use your theme's semantic colors to create rich visual textures. Simply apply these utility classes or use the variables directly.

Primary to Secondary

background: linear-gradient(...)

Info to Primary

background: linear-gradient(...)

Subtle Surface

background: linear-gradient(...)

22 Built-in Themes

Axiom01 ships with 22 meticulously crafted themes. You don't need to configure colors if you don't want to. Simply append a data-theme="[theme-name]" to your <html> element to instantly reskin your entire app.

light

dark

corporate-clean

synthwave-84

nordic-calm

vintage-paper

dracula

solarized-light

solarized-dark

luxe-black

minty-fresh

desert-sunset

deep-ocean

gruvbox-dark

sakura-blossom

matcha-green

monokai-pro

slate-gray

tropical-splash

candy-pop

rose-pine

midnight-moss

Creating Custom Themes

Since the entire color system is built on dynamic OKLCH variables driven by master hue tokens, creating a custom theme (like an "ocean" theme) requires only a few lines of CSS applied to a root selector.

Defining a Theme

Simply override the root hue and structural tokens for your theme selector.

/* Apply via <html data-theme="ocean"> */
[data-theme="ocean"] {
  /* Shift the primary brand color to a deep teal */
  --a-hue-primary: 180;
  
  /* Give the surface a subtle blue tint */
  --a-hue-surface: 190;
  --chroma-surface: 0.05;

  /* Reshape structural tokens to feel softer */
  --a-border-radius-base: 0.75rem;
  --a-border-radius-large: 1.5rem;
}

Axiom01's internal math will automatically calculate every container, outline, hover state, and contrast color based on these base tokens.