~/work/zeus-css
Zeus CSS
A fluid CSS framework that builds a design system out of a few tokens. I wrote it so people and AI tools could read the same source.

01The problem
Every new project started the same way. I rebuilt the tokens, redid the colour logic, wrote breakpoints by hand and watched design decisions get scattered across class names. Two years ago I started testing how much of that modern CSS could do for me. It began as five small frameworks: fluid sizing with clamp(), generated utilities, semantic naming and tokenization.
Then AI assistants became part of the workflow, and the old problem came back in a new form. If the assistant can't see the real design system, it guesses colours and spacing, and the design drifts again.
02The approach
I merged the five experiments into one engine with one rule: you define a few tokens and Zeus works out the rest. Most of what I've learned about CSS architecture went into making that rule hold up.
- The fluid part is one Sass math core. You give it a minimum and a maximum, and it writes the clamp() with container query units. Type, spacing, borders and icons all use it, so I don't write breakpoints for fluid values anymore.
- Colour is OKLCH. Five base colours turn into 135 tokens, including light, muted, surface and border variants, and they update live through relative colour syntax.
- You can use it as utility classes, SCSS mixins or plain CSS variables, all from one override file, in any framework.
03Key decisions
A few decisions shaped Zeus more than any single feature.
- 01
It generates the system
Zeus doesn't ship a theme you have to fight. It builds the design system from your tokens, so the output is predictable and easy to override.
- 02
Built for AI tools too
The tokens ship as W3C DTCG JSON, the same format Figma variables use, along with an llms.txt and a generated cheatsheet. That way an AI-assisted Figma-to-code workflow reads the same source of truth as the team. An MCP server is next on my list.
- 03
Open source, no runtime
It's MIT licensed with zero dependencies. There's a precompiled stylesheet if you don't want a build step, and the utilities work with PurgeCSS. You can install it from npm or read every line on GitHub.
04Results
Zeus CSS is on version 1.1. The docs, a playground and a full breakdown of how it works are on zeuscss.com.
- 3K+npm downloads
- 135Tokens from 5 base colours
- 629Utility classes