Introduction

Axiom CSS is a small, no-build CSS starting point. It provides design tokens, sensible defaults for HTML elements, and a set of utility classes, all derived from mathematical relationships rather than arbitrary numbers.

It's not really a framework. It's more like a well-considered set of CSS files you can drop into a project and then make your own.

What about Tailwind?

Tailwind is excellent. It's battle-tested, has a vast ecosystem, and its build process is fast and mature. If you're already productive with Tailwind, there's probably no reason to switch.

But Axiom isn't trying to be Tailwind. It's exploring different ideas:

  • No build step required. Tailwind's CLI is quick, but you still need Node, a config file, and a build process. Axiom is just CSS files. Drop them in and go.
  • The base layer does real work. In Tailwind, unstyled HTML looks like unstyled HTML; you add classes to make things look good. In Axiom, buttons, forms, tables, and typography are styled by default. You add classes to override, not to establish.
  • A curated utility set. Tailwind aims to be comprehensive, with any CSS property available as a class. Axiom is deliberately smaller. It covers common cases and expects you to write CSS for the rest.
  • Mathematical foundations. Font sizes, spacing, and line heights all derive from scales rather than arbitrary values. Change one variable and the system adjusts proportionally.
  • One type scale, one knob. Font sizes derive from a single base value and scale ratio. Change --type-scale and the entire hierarchy adjusts. Fluid headings are opt-in via a container class, not baked into the defaults.

If any of that sounds interesting, Axiom might be worth a look, even if you don't adopt it wholesale. Ideas are portable.

A starting point, not a cage

Everything in Axiom uses CSS custom properties. The config file isn't sacred; it's designed to be modified. Change the colors to match your brand. Adjust the typographic scale. Alter the geometric progression for spacing. Delete what you don't need.

And you're not limited to utility classes. Write your own CSS. Use inline styles where they make sense. Reference the custom properties directly. There's no dogma here; use whatever approach works for your project.

The goal isn't to avoid writing CSS. It's to give you a solid starting point and get out of your way.

The no-build philosophy

There's a quiet movement happening in web development. People are rediscovering that you can build things with HTML, a bit of CSS, and maybe a sprinkle of JavaScript. No webpack, no npm install, no waiting for builds. Server-rendered HTML. Hypermedia. The basics, done well.

Tools like HTMX, Alpine.js, and Datastar let you enhance your HTML with behaviour while keeping your DOM as the source of truth. Frameworks like Laravel and Rails are leaning back into server rendering. Even WordPress developers, who've always found build tooling an awkward fit, are part of this world.

If you're working this way, you might want a CSS system that matches the philosophy. Something you can drop into a project with a few <link> tags and get to work. No node_modules, no configuration.

That's the world Axiom was designed for. But if you're using React, Vue, Angular, or anything else, that's fine too. It's just CSS. It works everywhere.

The mathematical bit

Most CSS systems pick values that "look right": 14px here, 18px there, 24px somewhere else. It works, but there's no relationship between the numbers.

Axiom takes a different approach. Font sizes follow a typographic scale (the Major Third by default, ratio 1.25). Spacing follows a geometric progression. Line heights are explicit named values chosen for each context. Everything derives from a small set of base values.

Does this matter? Maybe not for every project. But it means when you tweak one variable, everything else adjusts proportionally. And it means there's a logic to the system you can learn, rather than memorizing arbitrary values.

The four layers

Axiom is organized into four CSS files:

  1. config.css: CSS custom properties. The design tokens that everything else references.
  2. base.css: A modern reset and sensible defaults for HTML elements. Forms, tables, typography; all styled without needing classes.
  3. custom.css: A place for your own component patterns. Mostly empty by default.
  4. utility.css: Single-purpose utility classes for when you need them. Loaded last so they always win.

Use what you need

Here's the thing: you don't have to use all four layers.

If you like utility classes, use the full stack. But if you find utility-first CSS distasteful (plenty of people do, and that's fine), you can skip utility.css entirely. Just use config.css and base.css. You'll get a solid foundation: well-considered typography, sensible element defaults, and a complete set of CSS custom properties you can use in your own stylesheets.

The layers are genuinely independent. Take what's useful, leave what isn't.

If you use all four layers

Load them in this order:

<link rel="stylesheet" href="config.css">
<link rel="stylesheet" href="base.css">
<link rel="stylesheet" href="custom.css">
<link rel="stylesheet" href="utility.css">

The order matters because each layer builds on the previous one, and utilities need to come last so they can override everything else.

If you just want the foundation

This is perfectly valid:

<link rel="stylesheet" href="config.css">
<link rel="stylesheet" href="base.css">

You'll get the reset, the typography, the element styles, and access to all the CSS custom properties for your own use. Write your CSS however you like, referencing var(--size-md) or var(--blue-500) as needed.

Installation

There's no npm package. No CDN (yet). Axiom is currently just an idea being built in public.

If you want to try it, grab the CSS files directly:

That's it. No build step. No configuration. Just CSS.

If there's interest, we'll look at a proper GitHub release and maybe a CDN. But for now, this is the whole distribution method.

What's next

Browse the documentation to see what's available. The Config section explains the design tokens. The Utility section documents the classes you'll use most often.

This is all a work in progress. Things will change. If you build something with it, you're an early adopter: thank you, and sorry in advance for any breaking changes.