cathode

My personal design system for my pet projects.

Dark-only CSS design system: inky surfaces, hairline borders, monospace for data, arcade semantic color. Built to be driven by AI agents.

A dark room lit by a monitor — modern skeleton, retro soul, and the retro stays a whisper.

Install

As a dependency:

npm install @sethlivingston/cathode

@import "@sethlivingston/cathode";

Or straight from a CDN (fonts resolve automatically — they ship in the package):

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@sethlivingston/cathode/dist/cathode.css"
/>

Tokens only (bring your own components):

@import "@sethlivingston/cathode/tokens";

For AI agents

AGENTS.md is the system's constitution — identity, the three laws (tokens only · mono for data · color means something), hard rules, strong defaults, and canonical snippets. Point your agent at it from a project's CLAUDE.md / system prompt:

This project uses the Cathode design system.
Follow node_modules/@sethlivingston/cathode/AGENTS.md when writing any UI.

What's inside

• Tokens (src/tokens.css) — surfaces, text, accent, arcade palette, type scale, 4px spacing grid, shape, motion, layers. All --ct-*.
• Base — element defaults: typography, links, code/kbd, scrollbars, selection, focus ring.
• Components (.ct- prefix) — buttons, forms (input/select/textarea/ checkbox/radio/switch/validation), badges & status dots, cards & stats, tables, navbar/sidebar/tabs/breadcrumb, modal (<dialog>)/toast/tooltip, progress/meter/spinner, alerts, empty states, layout helpers (.ct-shell, .ct-container, .ct-stack, .ct-cluster, .ct-grid).
• Fonts — IBM Plex Sans + IBM Plex Mono (latin, woff2), self-hosted, OFL-1.1.

No build step required to use it; npm run build regenerates dist/cathode.css from the src/ layers after edits.

Demo

Open demo/index.html for the full component gallery.

Releasing

The published package is @sethlivingston/cathode, versioned by the root package.json. To cut a release:

1. Run npm version patch (or minor / major) — this bumps package.json, rebuilds dist/ (the bundle banner embeds the version), commits, and creates the v<version> tag in one step.
2. Push it all: git push origin main --follow-tags
3. The Release workflow validates the build, publishes to npm via OIDC trusted publishing with provenance, and creates the GitHub release.

If you bump the version by hand instead, remember npm run build before committing — the workflow fails if the committed dist/ doesn't match src/.

Prerequisites: the npm-publish GitHub environment (tag policy v*) and an npm trusted-publisher binding to .github/workflows/release.yml.

License

MIT. Bundled IBM Plex fonts are licensed under the SIL Open Font License 1.1, © IBM Corp.