Skip to content
Axiomatic Color

HTML / Vanilla JS Integration

This guide shows you how to integrate the Axiomatic Color into a plain HTML project.

1. Setup

Section titled “1. Setup”

First, install the CLI and generate your theme CSS.

Terminal window
# Recommended
pnpm add -D @axiomatic-design/color
pnpm exec axiomatic init
pnpm exec axiomatic build --out ./public/theme.css


# Best-effort (if you prefer npm)
npm install -D @axiomatic-design/color
npx axiomatic init
npx axiomatic build --out ./public/theme.css

Link the CSS in your HTML file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link
      rel="stylesheet"
      href="https://unpkg.com/@axiomatic-design/color@latest/engine.css"
    />
    <link rel="stylesheet" href="/theme.css" />
    <title>My App</title>
  </head>
  <body>
    <!-- Content goes here -->
  </body>
</html>

2. Using Surfaces

Section titled “2. Using Surfaces”

In HTML, you apply surfaces using the generated utility classes.

<!-- The page surface sets the background for the body -->
<body class="surface-page">
  <main style="padding: 2rem;">
    <!-- A card surface -->
    <div class="surface-card" style="padding: 2rem; border-radius: 8px;">
      <h2 class="text-strong">Hello World</h2>
      <p class="text-subtle">
        This card is automatically themed based on its context.
      </p>
    </div>
  </main>
</body>

3. The Theme Toggle

Section titled “3. The Theme Toggle”

To handle Dark Mode, use the library’s ThemeManager.

<button id="theme-toggle">Toggle Theme</button>


<script type="module">
  import { ThemeManager } from "https://unpkg.com/@axiomatic-design/color@latest/browser";


  const toggle = document.getElementById("theme-toggle");
  const manager = new ThemeManager();


  // Optional persistence: ThemeManager doesn't own localStorage.
  const saved = localStorage.getItem("theme");
  if (saved === "light" || saved === "dark" || saved === "system") {
    manager.setMode(saved);
  }


  toggle.addEventListener("click", () => {
    const next = manager.resolvedMode === "light" ? "dark" : "light";
    manager.setMode(next);
    localStorage.setItem("theme", next);
  });
</script>