@sethlivingston/cathode 0.1.0

package/AGENTS.md

@@ -0,0 +1,137 @@
+# Cathode — Agent Guidelines
+
+You are styling an app with **Cathode**, a dark-only design system. This document
+is your constitution: the defaults here are very strong. Follow them unless you
+have a specific, articulable reason not to — and when you deviate, say so
+explicitly in your summary/PR description so a human can review the call.
+
+## Identity in one paragraph
+
+A dark room lit by a monitor. Inky near-black surfaces, precise 1px-ruled boxes,
+squared corners, comfortable density. Sans-serif prose, **monospace for all
+data**. One magenta accent for interactivity, plus a palette of saturated arcade
+hues that always carry meaning. A stranger sees a sharp modern app; a nerd
+notices the wink. The wink stays a whisper: no pixel fonts, no scanlines, no
+8-bit borders in app chrome.
+
+## The three laws
+
+1. **Tokens only.** Never write a raw color, font-family, font-size, spacing
+   value, radius, shadow, or z-index. Every visual property comes from a
+   `--ct-*` token. If no token fits, the answer is almost always the nearest
+   token — not a new value.
+2. **Mono for data.** IDs, counts, timestamps, durations, file paths, versions,
+   money, table numerics, badges, keyboard keys: `--ct-font-mono` (use `.ct-data`,
+   `.ct-num`, `.ct-label-mono`, or components that bake it in). Prose, labels,
+   headings, buttons: sans. Never the reverse.
+3. **Color means something.** Green = success, red = danger/destructive,
+   amber = warning, cyan = info, magenta accent = interactive/brand. Never use a
+   status hue decoratively, and never encode status with a categorical hue
+   (orange/lime/pink/indigo — those are free for tags, charts, and series).
+
+## Hard rules (never violate)
+
+- Dark only. No light theme, no `prefers-color-scheme` branching.
+- Elevation is border brightness (`--ct-border` → `--ct-border-bright`), not
+  box-shadows. The only permitted shadows are the built-in focus glow and
+  `.ct-dot`'s glow.
+- Corners are `--ct-radius` (2px). Exceptions that are already baked in:
+  radio dots and status dots are round. Nothing else is.
+- Spacing sits on the 4px grid via `--ct-space-*`. No odd-pixel nudging.
+- One `.ct-button--primary` per view, maximum. It is the single magenta action.
+- `.ct-button--danger` only for destructive actions, and destructive actions
+  always confirm via `.ct-modal`.
+- Focus stays visible. Never `outline: none` without the system's replacement
+  (inputs already do this correctly).
+- Respect the components' ARIA hooks: active nav uses `aria-current="page"`,
+  active tab `aria-selected="true"`, invalid inputs `aria-invalid="true"`,
+  selected rows `aria-selected="true"`. Styling is attached to those attributes
+  on purpose — set the attribute, get the style.
+
+## Strong defaults (deviate only with stated reason)
+
+- Compose pages from existing components before inventing anything. The kit:
+  buttons, fields/inputs/select/textarea/check/radio/switch, badges/dots, cards/
+  stats, tables, navbar/sidebar/tabs/breadcrumb, modal/toast/tooltip, progress/
+  meter/spinner, alert, empty state, and layout helpers (`.ct-shell`,
+  `.ct-container`, `.ct-stack`, `.ct-cluster`, `.ct-grid`).
+- New component needed? Build it from tokens, follow the naming scheme
+  (`.ct-thing`, `.ct-thing--variant`, `.ct-thing__part`), keep it in one CSS
+  file, and flag it as a candidate for the system.
+- Empty lists/zero states use `.ct-empty` — never a blank region.
+- Page titles use `h1`–`h3` defaults; section micro-headers use `.ct-label-mono`.
+- Buttons: default for secondary actions, `--ghost` for toolbars and inline
+  affordances, `--sm` inside tables and cards.
+- Use native `<dialog>` for modals and the `.ct-toasts` container for toasts.
+
+## Canonical snippets
+
+Status badge + data:
+
+```html
+<td><span class="ct-badge ct-badge--success">pass</span></td>
+<td class="ct-num">1,204</td>
+<td><span class="ct-data">2026-06-10 14:32</span></td>
+```
+
+Form field with validation:
+
+```html
+<div class="ct-field">
+  <label class="ct-label ct-label--required" for="name">Project name</label>
+  <input class="ct-input" id="name" aria-invalid="true" />
+  <span class="ct-error">Name is already taken.</span>
+</div>
+```
+
+App shell:
+
+```html
+<body class="ct-shell">
+  <nav class="ct-navbar">
+    <span class="ct-navbar__brand">Acme</span>
+    <span class="ct-navbar__spacer"></span>
+    <button class="ct-button ct-button--sm ct-button--primary">Deploy</button>
+  </nav>
+  <aside class="ct-sidebar">
+    <div class="ct-sidebar__section">Workspace</div>
+    <a class="ct-nav-item" aria-current="page" href="/">Overview</a>
+    <a class="ct-nav-item" href="/runs">Runs</a>
+  </aside>
+  <main class="ct-main ct-stack">…</main>
+</body>
+```
+
+Custom-hued tag (categorical, no fixed meaning):
+
+```html
+<span class="ct-badge" style="--badge-hue: var(--ct-pink)">design</span>
+```
+
+## Don't / Do
+
+| Don't | Do |
+|---|---|
+| `color: #22c55e` | `color: var(--ct-green)` |
+| `padding: 10px` | `padding: var(--ct-space-2) var(--ct-space-3)` |
+| `border-radius: 8px` | `border-radius: var(--ct-radius)` |
+| `box-shadow: 0 4px 12px …` on hover | brighten the border: `border-color: var(--ct-border-bright)` |
+| Timestamp in sans | `<span class="ct-data">…</span>` |
+| Red "Delete" link that fires immediately | `.ct-button--danger` opening a `.ct-modal` confirm |
+| Two primary buttons side by side | one `--primary`, one default |
+| Inventing a quieter gray | `--ct-text-dim` or `--ct-text-faint` |
+
+## Token quick reference
+
+| Group | Tokens |
+|---|---|
+| Surfaces | `--ct-bg-0..3` (page → hover), `--ct-border`, `--ct-border-bright` |
+| Text | `--ct-text`, `--ct-text-dim`, `--ct-text-faint` |
+| Accent | `--ct-accent`, `--ct-accent-bright`, `--ct-accent-glow`, `--ct-on-accent` |
+| Status | `--ct-green`, `--ct-red`, `--ct-amber`, `--ct-cyan` |
+| Categorical | `--ct-orange`, `--ct-lime`, `--ct-pink`, `--ct-indigo` |
+| Fonts | `--ct-font-sans`, `--ct-font-mono` |
+| Sizes | `--ct-text-xs/sm/md/lg/xl/2xl/3xl` |
+| Space | `--ct-space-1..8` = 4/8/12/16/24/32/48/64px |
+| Shape/motion | `--ct-radius`, `--ct-ease`, `--ct-quick`, `--ct-slow` |
+| Layers | `--ct-z-nav/modal/toast/tooltip` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seth Livingston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# 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.
+
+![cathode screenshot](demo/screenshot@2x.png)
+
+## Install
+
+As a dependency:
+
+```sh
+npm install @sethlivingston/cathode
+```
+
+```css
+@import "@sethlivingston/cathode";
+```
+
+Or straight from a CDN (fonts resolve automatically — they ship in the package):
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@sethlivingston/cathode/dist/cathode.css"
+/>
+```
+
+Tokens only (bring your own components):
+
+```css
+@import "@sethlivingston/cathode/tokens";
+```
+
+## For AI agents
+
+[`AGENTS.md`](./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:
+
+```md
+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`](./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. Bump `version` in `package.json`, run `npm run build`, and commit (dist is
+   committed; CI fails if it drifts from src).
+2. Tag the commit `v<version>` (e.g. `v0.2.0`) and push the tag.
+3. The Release workflow validates the build, publishes to npm via OIDC trusted
+   publishing with provenance, and creates the GitHub release.
+
+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](https://github.com/IBM/plex/blob/master/LICENSE.txt),
+© IBM Corp.