GETTING STARTED

Five minutes from empty folder to first Cathode UI component on screen.

Install

npm install @cathode-ui/react

# Peer deps (usually already present):
npm install react react-dom framer-motion @phosphor-icons/react

Import the tokens

Cathode UI ships a single tokens.css that publishes every color, spacing, motion, sound, and haptic token as CSS custom properties. Import it once at your app's root.

// app entry (main.tsx / _app.tsx / root layout)
import '@cathode-ui/react/tokens.css';
import '@cathode-ui/react/fonts.css';  // optional — loads JetBrains Mono

Wrap your app

CathodeProvider carries runtime settings — theme mode, motion intensity, whether haptics and sound are enabled, an optional AI provider. Every prop has a sensible default, so an empty provider is fine.

import { CathodeProvider } from '@cathode-ui/react';

export function App() {
  return (
    <CathodeProvider>
      <YourUI />
    </CathodeProvider>
  );
}

Render something

import { TerminalFrame, Pill, Button, PixelBar } from '@cathode-ui/react';

<TerminalFrame title="STATUS">
  <Pill title="ONLINE" accent="success" active />
  <PixelBar level={0.6} cells={24} fill="var(--cathode-color-success)" />
  <Button variant="primary">SUBMIT</Button>
</TerminalFrame>

Theming

Cathode UI follows prefers-color-scheme by default. Light is the CSS root default (avoids flash-of-dark on light-mode devices), dark kicks in via media query. Pin explicitly with either:

// document-level override
<html data-theme="dark">…</html>

// or scoped via the provider
<CathodeProvider theme="dark">…</CathodeProvider>

Feedback opt-ins

Haptics are on by default; sounds are off (unexpected audio is hostile). Enable sound globally with sound={true} on the provider, or opt out of either per-component via a feedback={false} prop.

AI (optional)

Components like TextField, SearchBar, Chat, and Button light up additional behavior when you hand the provider a CathodeAIProvider. See the AI providers page for the interface.

Next: browse the token palette, or jump to the component index.