Advanced Color Details

Axiom01's color system is built on a powerful and flexible HSL (Hue, Saturation, Lightness) model, leveraging CSS variables to create dynamic and themeable palettes. This approach ensures consistency, accessibility, and effortless customization across all themes, including dark mode.

The HSL Color Model in Axiom01

Unlike fixed hex or RGB values, Axiom01 defines core colors using HSL components. This allows for easy manipulation of hue, saturation, and lightness independently, making it simple to generate variations (e.g., lighter/darker shades, desaturated versions) and create entirely new themes by adjusting just a few root variables. The HSL model is intuitive and aligns well with human perception of color.

:root {
		 --a-color-primary-hue: 220;    /* Base hue for the primary color (0-360) */
		 --a-saturation-primary: 70%;   /* Base saturation for primary colors (0-100%) */
		 --a-brightness-primary: 50%;   /* Base brightness for primary colors (0-100%) */

		 /* These are then used to construct the final color variables */
		 --a-color-primary: hsl(var(--a-color-primary-hue), var(--a-saturation-primary), var(--a-brightness-primary));
		 --a-color-primary-light: hsl(var(--a-color-primary-hue), var(--a-saturation-primary), calc(var(--a-brightness-primary) + 20%));
		 --a-color-primary-dark: hsl(var(--a-color-primary-hue), var(--a-saturation-primary), calc(var(--a-brightness-primary) - 20%));
 }

By only overriding the HSL component variables (e.g., `--a-color-primary-hue`), the entire derived palette automatically adjusts, maintaining harmonious relationships between colors.

Core Color Variables for Customization

These are the fundamental HSL component variables that drive Axiom01's theming. By overriding these in your :root or a [data-theme] block, you can completely change your application's look and feel. Axiom01 then uses these components to generate a full, accessible palette.

Variable	Description	Example Value
`--a-color-primary-hue`	Base hue for the primary color.	`220`
`--a-saturation-primary`	Base saturation for primary colors.	`70%`
`--a-brightness-primary`	Base brightness for primary colors.	`50%`
`--a-color-secondary-hue`	Base hue for the secondary color.	`280`
`--a-saturation-secondary`	Base saturation for secondary colors.	`60%`
`--a-brightness-secondary`	Base brightness for secondary colors.	`50%`
`--a-color-tertiary-hue`	Base hue for the tertiary color.	`180`
`--a-saturation-tertiary`	Base saturation for tertiary colors.	`50%`
`--a-brightness-tertiary`	Base brightness for tertiary colors.	`50%`
`--a-saturation-mono`	Saturation for monochromatic/neutral colors.	`5%`
`--a-brightness-text-on-dark`	Brightness for text on dark backgrounds.	`98%`

Generated Color Palette & Accessibility

From the core HSL components, Axiom01 automatically generates a comprehensive set of semantic color variables. These include not only the main colors (e.g., --a-color-primary) but also their accessible "on-color" counterparts (e.g., --a-color-on-primary) and "container" variants (e.g., --a-color-primary-container).

--a-color-[name]: The main color for a given semantic role (e.g., primary, secondary, error).
--a-color-on-[name]: A color guaranteed to have sufficient contrast when placed on top of --a-color-[name]. This is typically used for text or icons.
--a-color-[name]-container: A lighter/darker variant of the main color, often used for backgrounds of elements that contain content related to that semantic role.
--a-color-on-[name]-container: A color guaranteed to have sufficient contrast when placed on top of --a-color-[name]-container.
--a-color-on-gradient: A color guaranteed to have sufficient contrast when placed on top of a gradient background, particularly --a-gradient-primary. This is typically used for text or icons in hero sections.

This system ensures that text and interactive elements always have an accessible contrast ratio against their background, adhering to WCAG 2.1 AA guidelines by default.

Primary

var(--a-color-primary)

On Primary

var(--a-color-on-primary)

Primary Container

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

On Primary Container

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

Text

On Gradient

var(--a-color-on-gradient)

Secondary

var(--a-color-secondary)

On Secondary

var(--a-color-on-secondary)

Secondary Container

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

On Secondary Container

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

Tertiary

var(--a-color-tertiary)

On Tertiary

var(--a-color-on-tertiary)

Tertiary Container

var(--a-color-tertiary-container)

On Tertiary Container

var(--a-color-on-tertiary-container)

Surface

var(--a-color-surface)

On Surface

var(--a-color-on-surface)

Surface Variant

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

On Surface Variant

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

Error

var(--a-color-error)

On Error

var(--a-color-on-error)

Error Container

var(--a-color-error-container)

On Error Container

var(--a-color-on-error-container)

Success

var(--a-color-success)

On Success

var(--a-color-on-success)

Success Container

var(--a-color-success-container)

On Success Container

var(--a-color-on-success-container)

Warning

var(--a-color-warning)

On Warning

var(--a-color-on-warning)

Warning Container

var(--a-color-warning-container)

On Warning Container

var(--a-color-on-warning-container)

Info

var(--a-color-info)

On Info

var(--a-color-on-info)

Info Container

var(--a-color-info-container)

On Info Container

var(--a-color-on-info-container)

Dark Mode Implementation

Axiom01 provides robust dark mode support out-of-the-box. This is achieved by overriding the core HSL component variables and surface colors within a html[data-theme="dark"] selector. When the data-theme attribute on the <html> element is set to dark, the framework automatically switches to the dark color palette.

/* Example of dark mode overrides in axiom.css or your custom stylesheet */
 html[data-theme="dark"] {
		 /* Adjust primary brightness for dark mode if needed */
		 --a-brightness-primary: 60%; /* Brighter primary for dark backgrounds */

		 /* Invert surface and on-surface colors */
		 --a-color-surface-hue: var(--a-color-primary-hue); /* Often same hue as primary */
		 --a-color-surface-saturation: 10%;
		 --a-color-surface-brightness: 15%; /* Dark surface */
		 --a-color-on-surface-brightness: 90%; /* Light text on dark surface */

		 /* Adjust container colors for dark mode */
		 --a-color-primary-container-brightness: 30%;
		 --a-color-on-primary-container-brightness: 95%;
		 /* ... and so on for other colors */
 }

The `theme toggle` button (usually found in the header) handles the JavaScript logic for switching the `data-theme` attribute and persisting the user's preference in `localStorage`.

Customizing Colors

The easiest way to customize Axiom01's colors is by overriding the HSL component variables in your :root or a specific [data-theme] block. This allows you to define your brand's primary hue, saturation, and brightness, and let Axiom01 generate the rest of the palette for you.

/* Example: Customizing primary color to a vibrant green */
 :root {
		 --a-color-primary-hue: 120; /* Green hue */
		 --a-saturation-primary: 80%;
		 --a-brightness-primary: 40%;
 }

 /* Example: Creating a custom theme */
 html[data-theme="my-custom-theme"] {
		 --a-color-primary-hue: 300; /* Purple hue */
		 --a-saturation-primary: 70%;
		 --a-brightness-primary: 60%;

		 --a-color-surface: hsl(var(--a-color-primary-hue), 10%, 15%); /* Dark surface */
		 --a-color-on-surface: hsl(var(--a-color-primary-hue), 10%, 90%); /* Light text */
		 /* ... and so on for other HSL components and surface colors */
 }

For interactive customization and to generate your own theme code, visit the Theme Customization Wizard.