Unlocked

~/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.

  • RoleCreator & maintainer
  • Timeline2024 – Now
  • StackZeus CSS, Next.js, SCSS
Zeus CSS Website

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.

  1. 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.

  2. 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.

  3. 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