The ZUI ecosystem

I just wrote about the ecosystem of apps around Otter, and it turns out I’ve done the same thing to ZUI, my CSS-first UI library. The core of ZUI is, and always will be, the CSS. But a design system lives or dies by how pleasant it is to actually use day to day, so a small ecosystem of tooling has grown up around it: framework components, editor tooling, a Raycast extension, and a documentation theme.

(If you’re curious about what’s inside the CSS itself, I covered that in The modern CSS hiding inside ZUI.)

TL;DR

• The core is one npm package: @mrmartineau/zui, CSS first, classes optional
• Framework components for React, Astro, Solid, Svelte and Vue ship in the same package, so you don’t have to remember class names
• A VS Code extension published alongside each release adds autocomplete and colour previews for classes and design tokens
• A Raycast extension (based on the Tailwind one) searches classes, tokens, snippets, and docs without opening a browser
• The docs site is built with Astro and ZUI, and its guts are published as @mrmartineau/zui-theme so other projects can use them

The core: one npm package

For most users, the main part of the ecosystem is the npm package. Install it, import the stylesheet, and you have the whole library:

npm install @mrmartineau/zui

@import '@mrmartineau/zui/css';

From there you can use ZUI the pure-CSS way: write HTML, apply the classes, done. Everything else in this post is optional. Optional, but I use all of it every day, because remembering class names is the part that actually slows you down.

Framework components

If you use React, Astro, Solid, Svelte, or Vue, ZUI ships components for each of them as subpath exports of the same package:

import { Button } from '@mrmartineau/zui/react'

export function App() {
  return <Button>Click me</Button>
}

---
import { Button } from '@mrmartineau/zui/astro'
---

<Button>Click me</Button>

You could absolutely just use the base classes directly, nothing stops you. But if you did, you’d need to remember which classes each component requires, and for anything beyond a button that gets a little tricky. The framework wrappers exist so you don’t have to hold that in your head. They apply the right classes for you and expose the variants as typed props, so autocomplete answers the question instead of the docs. Start there, and drop down to raw classes when you need something a wrapper doesn’t cover.

---

The VS Code extension

Once ZUI is installed, two tools make day-to-day development with it much easier. The first is the VS Code extension, which is published alongside each ZUI release so it always matches the current version of the library.

It gives you autocomplete for ZUI’s CSS classes, custom properties, and design tokens, plus inline colour previews for the colour tokens. It’s a simple thing, but it changes the workflow from “alt-tab to the docs, find the class, copy it” to just typing and picking from a list.

The Raycast extension

The second is my favourite, because I’m a big fan of Raycast (this is becoming a pattern: there’s an Otter Raycast extension too). The ZUI Raycast extension is based on the excellent Tailwind CSS extension, and it lets me search ZUI’s CSS classes and design tokens, copy code snippets for any framework, and search the documentation, all from the launcher.

In practice it means I almost never have to dip into the documentation website while building. Forgotten the name of a spacing token, or which class a badge variant needs? Open Raycast, type a few characters, copy the answer, carry on. For a one-person design system that matters more than it sounds like it should. If looking something up costs a browser tab and thirty seconds, I start guessing instead, and guessing is how a design system drifts.

The docs site, and the theme it spawned

ZUI’s documentation lives at zui.zander.wtf. It’s built with Astro and, naturally, built with ZUI: the library documents itself using its own components, tokens, and theming (including the theme picker I wrote about in the CSS post).

While building it, I extracted the reusable parts (layouts, navigation, components, and helpers for generating documentation sites) into their own published package: @mrmartineau/zui-theme. It even ships a create-zui-docs scaffolding command, so other projects can spin up a ZUI-styled docs site without copying mine. And to keep myself honest, the ZUI docs site itself consumes the published theme, so if the theme breaks, my own docs break first.

---

Like the Otter ecosystem, none of these pieces is particularly complicated on its own. The CSS does the hard work once: the tokens, the components, the theming. Everything around it (wrappers, autocomplete, launcher search, a docs theme) exists so that reaching for ZUI is never the slow option. If you’re building your own design system, even a personal one, the tooling around it is what turns “a stylesheet I made” into something you’ll still be using in two years.