AxiomCSS

Configuration

At the heart of Axiom CSS lies a comprehensive design token system that transforms how you approach interface design. Rather than scattering magic numbers throughout your stylesheets, every visual decision flows from a central configuration that ensures consistency, enables systematic customisation, and scales effortlessly with your project.

The configuration system treats design as a set of relationships rather than isolated values. Change your base hue, and watch as borders, backgrounds, and text colours all adjust harmoniously. Modify your spacing scale, and see how buttons, forms, and layouts maintain their proportional relationships.

Design Token Philosophy

Design tokens are the atomic units of your design system—the foundational decisions that cascade through every aspect of your interface. Axiom CSS organises these tokens into logical groups that work together to create cohesive experiences:

  • Semantic naming that describes purpose rather than appearance
  • Contextual relationships where tokens reference and build upon each other
  • Automatic theme adaptation through invertible colour systems
  • Mathematical scaling that ensures visual harmony

Colour System

The colour system is built around two primary concepts: a neutral base palette and semantic colour relationships. The base palette generates from just two values—hue and saturation—creating a cohesive neutral scale that works in both light and dark themes.

--base-hue: 220;
--base-saturation: 16%;

--base-50: hsl(var(--base-hue), calc(var(--base-saturation) * 0.95), 98%);
--base-100: hsl(var(--base-hue), calc(var(--base-saturation) * 1.0), 95%);
/* ... through to base-900 */

The invertible colour tokens (prefixed with i-) automatically adapt to light and dark themes, maintaining semantic meaning while adjusting visual appearance. Text colours, background colours, and border colours all reference these tokens, ensuring consistency across theme changes.

Spacing & Sizing

Spatial relationships follow a mathematical scale based on a base size and scale ratio. This creates predictable, harmonious spacing that works across different screen sizes and contexts.

--base-size: 40px;
--size-scale-ratio: 2;

--size-xs: calc(var(--base-size) / (var(--size-scale-ratio) * var(--size-scale-ratio)));
--size-sm: calc(var(--base-size) / var(--size-scale-ratio));
--size-md: var(--base-size);
--size-lg: calc(var(--base-size) * var(--size-scale-ratio));

Typography follows a similar approach, with font sizes calculated from a base size and scale ratio. This ensures consistent visual hierarchy and readable text across all interface elements.

Component Tokens

Higher-level components like buttons, forms, and tables have their own token systems that reference the foundational tokens. This creates a hierarchy where global changes cascade appropriately while allowing for component-specific customisation.

--input-bg-color: var(--i-bg-base-high);
--input-text-color: var(--i-text-base-secondary);
--input-border-color: var(--i-line-base-medium);
--input-focus-color: var(--blue);

Benefits of Token-Based Design

This systematic approach to design tokens delivers several key advantages:

  • Global consistency — Change a base value and see it propagate throughout your interface
  • Theme flexibility — Support multiple themes without duplicating component styles
  • Maintainable customisation — Modify the design system without touching utility classes
  • Semantic clarity — Token names describe intent rather than appearance
  • Scalable complexity — Add new tokens and relationships as your system grows

Customisation Approach

To customise Axiom CSS for your project, focus on the foundational tokens first. Adjust base hues, saturation levels, spacing scales, and typography ratios. These changes will cascade through the entire system, maintaining relationships while adapting to your visual requirements.

The token system is designed to be forked and modified. Take what works, change what doesn't, and add what you need. The systematic approach ensures that your customisations will scale consistently across your entire interface.