@feanor08/terminal-ui

A flexible terminal/workbench design system. Early v0.1.0 — API is not yet stable.

Lightweight React + CSS component library. Structured so its design tokens can export to iTerm2 color schemes, CSS themes, and other application palettes without touching React at all.

Install

npm install @feanor08/terminal-ui

Peer dependencies: react ^18, react-dom ^18.

React usage

import '@feanor08/terminal-ui/styles.css';
import {
  TerminalShell,
  TerminalTitlebar,
  TerminalPanel,
  TerminalMetric,
  TerminalStatusTag,
  TerminalProgressBar,
  TerminalCommandBar,
} from '@feanor08/terminal-ui';

export function App() {
  return (
    <TerminalShell theme="dark">
      <TerminalTitlebar title="my app" />
      <TerminalPanel title="Overview">
        <TerminalMetric label="requests" value="1,204" delta="+8%" deltaDirection="up" />
        <TerminalStatusTag variant="success" dot>online</TerminalStatusTag>
        <TerminalProgressBar label="CPU" value={64} />
      </TerminalPanel>
      <TerminalCommandBar prompt="$" placeholder="run a command…" />
    </TerminalShell>
  );
}

Available components

| Component | Description | |---|---| | TerminalShell | Root wrapper. Sets theme class, scanline overlay. | | TerminalTitlebar | macOS-style title bar with traffic-light dots. | | TerminalPanel | Bordered panel with optional title and header slot. | | TerminalStatusTag | Inline status badge (info / success / warning / danger / accent / muted). | | TerminalMetric | Label + large value + optional delta. | | TerminalTable | Typed data table with column renderers. | | TerminalTabs | Tab bar with accessible role="tab" markup. | | TerminalCommandBar | Prompt + text input styled as a shell prompt. | | TerminalToast | Alert/notification bar with dismiss button. | | TerminalProgressBar | Track + fill bar with variant colors. | | TerminalKbd | Keyboard shortcut display (⌘ + S). |

CSS-only usage

No React required. Import the stylesheet and use the generated class names:

<link rel="stylesheet" href="node_modules/@feanor08/terminal-ui/dist/styles.css" />

<div class="tui-panel">
  <div class="tui-panel__header">
    <span class="tui-panel__title">Status</span>
  </div>
  <div class="tui-panel__body">
    <span class="tui-status-tag tui-status-tag--success">online</span>
  </div>
</div>

Or import the pre-generated standalone CSS theme from dist-themes/:

<link rel="stylesheet" href="dist-themes/css/all-themes.css" />

Theming with CSS variables

All components consume CSS custom properties prefixed --tui-*. Override any variable on :root or a scoped selector:

:root {
  --tui-accent: #f97316;   /* swap accent to orange */
  --tui-bg:     #0a0a0a;   /* deeper background */
}

Switch to the built-in light theme by adding the .tui-light class to your root element:

<TerminalShell theme="light">…</TerminalShell>
// or in plain HTML:
<div class="tui-light">…</div>

Creating a new token theme

1. Copy src/tokens/terminal-dark.json to src/tokens/my-theme.json.
2. Edit the meta block: set name, slug, appearance, author, description.
3. Change color values to taste.
4. Import and register it:

// src/tokens/index.ts (or your own file)
import myTheme from './my-theme.json';
import type { TerminalTokens } from '@feanor08/terminal-ui';

export const MY_THEME = myTheme as TerminalTokens;

5. Pass it to any export function:

import { tokensToCss, tokensToIterm } from '@feanor08/terminal-ui';
const css = tokensToCss(MY_THEME, ':root');
const plist = tokensToIterm(MY_THEME);

Exporting iTerm2 themes

npm run export:iterm

Writes .itermcolors plist files to dist-themes/iterm/. Double-click any file to install into iTerm2, or import via Preferences → Profiles → Colors → Color Presets → Import.

See dist-themes/README.md for the full token → iTerm2 color key mapping.

Exporting CSS themes

npm run export:css

Writes CSS custom property files to dist-themes/css/. Useful for non-React apps, static sites, or terminal web UIs that want the same palette.

Export both at once

npm run export:themes

Design goals

• Tokens first. Colors, spacing, and type live in JSON. Components and export scripts are consumers of that data, not the source of truth.
• No runtime overhead. CSS variables resolve at paint time. Zero JS for theming.
• Portable palette. The same token file can drive a React UI, an iTerm2 profile, a static CSS theme, or anything else a script can write.
• Typed schema. TerminalTokens interface enforces token shape at compile time.

Non-goals

• Tailwind or CSS-in-JS integration.
• Backend or API assumptions.
• App-specific data or business logic.
• Animation library.
• Full design system scale (this is intentionally minimal).

License

MIT