Styling Guide

Master Axiom01's design system: tokens, variables, and semantic approach

What is Axiom01?

Axiom01 is a semantic-first UI framework that prioritizes clean, accessible code. Instead of utility classes, Axiom01 uses semantic HTML and CSS variables to create beautiful interfaces with minimal markup.

Core Principles

  • Semantic HTML First — Use meaningful elements like <article>, <section>, <nav>
  • One Class Per Component — Use class="card" instead of multiple utility classes
  • CSS Variables for Theming — Change colors globally with --a-color-primary, --a-color-success
  • Accessible by Default — WCAG 2.1 AA compliance built-in to all components
  • Dark Mode Ready — Automatic theme switching with data-theme="dark"

Design Tokens

Axiom01 provides 149 design tokens across colors, spacing, typography, and shadows. All tokens use CSS variables for consistency and easy theming.

Color Tokens

Replace hardcoded colors with semantic CSS variables that automatically work in light and dark modes:

--a-color-primary

Main brand • Buttons, links

--a-color-secondary

Secondary • Alternative actions

--a-color-success

Success • Confirmations

--a-color-error

Error • Destructive actions

--a-color-warning

Warning • Alerts, caution

--a-color-info

Info • Hints, help text

--a-color-surface

Background • Page/card surface

--a-color-surface-variant

Variant surface • Hover states

--a-color-text

Primary text • Body content

--a-color-on-surface-variant

Muted text • Secondary info

--a-color-outline

Borders • Dividers, outlines

--a-color-primary-container

Primary container • Backgrounds

Using Color Variables

/* ✓ RIGHT - Use CSS variables */
.button-primary {
  background: var(--a-color-primary);
  color: var(--a-color-on-primary);
  border: none;
}

/* ❌ WRONG - Hardcoded colors */
.button-primary {
  background: #007bff;
  color: white;
}

Spacing Tokens

Axiom01 uses a modular spacing scale based on --a-space-unit (default 1rem). All spacing uses predictable intervals:

xs

--a-space-xs

0.25rem (4px)

s

--a-space-s

0.5rem (8px)

m

--a-space-m

1rem (16px)

l

--a-space-l

1.5rem (24px)

Using Spacing Variables

/* ✓ RIGHT - Use spacing tokens */
.card {
  padding: var(--a-space-l);
  margin-bottom: var(--a-space-m);
}

/* ❌ WRONG - Hardcoded sizes */
.card {
  padding: 24px;
  margin-bottom: 16px;
}

Typography Tokens

Typography is handled through semantic HTML and automatic styling. Use heading tags (<h1> through <h6>) instead of custom styles.

Serif

--a-font-family-serif

Display Headings

Display headings, quotes

Sans

--a-font-family-sans

Body Text

Body text, UI

Mono

--a-font-family-mono

Code Blocks

Code blocks, literals

Weight

--a-font-weight-*

Regular
Medium
Bold

Headings, emphasis, UI

Core Components

Axiom01 provides semantic components designed for common UI patterns. Use these instead of creating custom classes.

Buttons

Use the .button class with semantic variations:

HTML

<button class="button primary">Primary</button>
<button class="button secondary">Secondary</button>
<button class="button danger">Danger</button>
<button class="button outline">Outline</button>

Cards

Use the .card class to group related content:

Card Title

Flexible containers for any content.

Another Card

Use semantic sections within cards.

HTML

<article class="card">
  <header>
    <h3>Card Title</h3>
  </header>
  <p>Content goes here.</p>
  <footer>
    <button class="button primary">
      Action
    </button>
  </footer>
</article>

Alerts

Use semantic alert classes for notifications:

Success! Your changes have been saved.
Error: Something went wrong. Try again.
Warning: This action cannot be undone.
Info: This is an informational message.

Best Practices

✓ DO: Use Semantic HTML

<nav role="navigation">
  <ul>
    <li><a href="/">Home</a></li>
  </ul>
</nav>

<main>
  <article>
    <header>
      <h1>Article Title</h1>
    </header>
    <p>Content...</p>
  </article>
</main>

✗ DON'T: Use Custom Classes

<div class="navbar">
  <div class="navbar-item">
    <a href="/">Home</a>
  </div>
</div>

✓ DO: Use CSS Variables

.my-component {
  color: var(--a-color-text);
  background: var(--a-color-surface);
  padding: var(--a-space-m);
  font-family: var(--a-font-family-sans);
}

/* Automatically works in dark mode */

✗ DON'T: Hardcode Values

.my-component {
  color: #333;
  background: #fff;
  padding: 16px;
  font-family: Arial, sans-serif;
}

/* Breaks dark mode, hard to maintain */

Dark Mode

Dark mode is automatically handled by Axiom01. Simply use CSS variables and dark mode will work out of the box.

How Dark Mode Works

Add data-theme="dark" to your <html> tag:

<!-- Light mode (default) -->
<html data-theme="light">

<!-- Dark mode -->
<html data-theme="dark">

All Axiom01 colors automatically invert:

  • Light backgrounds → dark backgrounds
  • Dark text → light text
  • Subtle borders → bright borders
  • No hardcoded colors needed

Accessibility

Axiom01 is built with accessibility in mind. Follow these practices to ensure your interfaces remain accessible:

Semantic HTML for A11y

  • Use <nav> for navigation
  • Use <article> for independent content
  • Use <section> for thematic grouping
  • Use <header> and <footer> for page sections
  • Use proper heading hierarchy <h1> through <h6>
  • Always associate <label> with form controls using for attribute
  • Use <fieldset> and <legend> to group related fields

Form Accessibility

<form>
  <fieldset>
    <legend>Contact Information</legend>
    
    <label for="email">Email Address</label>
    <input type="email" id="email" required>
    
    <label for="message">Message</label>
    <textarea id="message"></textarea>
  </fieldset>
  
  <button type="submit" class="button primary">
    Send
  </button>
</form>

Color Contrast

Axiom01 ensures WCAG 2.1 AA color contrast standards:

  • Text meets minimum 4.5:1 contrast ratio
  • UI components meet 3:1 contrast ratio
  • Colors are not the only indicator
  • Dark mode maintains contrast automatically

Customization

Customize Axiom01 by overriding CSS variables. No need to modify the framework itself.

Custom Color Scheme

/* In your CSS */
:root {
  --a-color-primary: #FF6B6B;
  --a-color-secondary: #4ECDC4;
  --a-color-success: #2ECC71;
  --a-space-unit: 1rem;
  --a-heading-scale: 1.2;
}

/* Dark mode customization */
@media (prefers-color-scheme: dark) {
  :root {
    --a-color-primary: #FF8A8A;
    --a-color-surface: #1A1A1A;
  }
}

Resources

Component Browser

Explore all 73 production-ready components.

Getting Started

Learn how to set up and use Axiom01.

Icon Browser

Browse 2,900+ Axicons with variants.

Homepage

Learn about Axiom01's philosophy.