Theming - terminal-kit

❯

# theming

terminal-kit uses scoped CSS variables on .terminal-theme. Components read tokens like var(--terminal-dim) — never hard-coded hex values.

──

install

Installing any component pulls in terminal-window, which merges theme tokens and utility classes into your global stylesheet via the shadcn CLI. You do not need a separate @import for theme CSS. See installation.md.

──

built-in themes

Pass theme on TerminalWindow — default, grok, or claude. Each palette includes dark and light tokens.

~/agent

? for shortcuts · ← for agentsmax

──

component layouts

Several components switch layout when the active palette is claude. Each reads the theme from the nearest .terminal-theme ancestor (and from a TerminalThemeProvider when you wire one at the app root). Pass theme="claude" on TerminalWindow so tokens and auto layouts stay in sync.

ThinkingIndicator — variant="auto" uses the symbol loop; variant="dots" forces the dot matrix.
Input — layout="auto" stacks the field with top/bottom borders; layout="inline" keeps the bordered box with status on the right. Use metaLeft / metaRight for the hint row.
EditBlock — layout="auto" renders a flat diff (green dot, Update(path), +/- rows); layout="panel" keeps the bordered panel.
QuestionPrompt — layout="auto" uses the flat card list with ❯ gutter; layout="panel" keeps the legacy bordered card.

──

sessioncontent integration

Some props are read by SessionContent from its children, not by the child component itself. Style streamed lines with className on StreamText (e.g. text-[var(--terminal-dim)]).

StreamText sessionPause — optional ms to wait after the line finishes before revealing the next child when streaming is on. Only StreamText types this prop; do not add it to Message, EditBlock, QuestionPrompt, etc. Defaults to estimateStreamDurationMs(text).
Other children — SessionContent estimates the pause automatically (e.g. user Message ~280ms, EditBlock ~520ms). Adjust stagger on SessionContent for the fallback when no heuristic matches.
ThinkingIndicator sessionTail — skip the streaming queue and pin the indicator at the transcript tail (live thinking).

──

scoped tokens

TerminalWindow renders with the terminal-theme class and the matching palette class (e.g. terminal-theme-claude). Pass theme on the window — child components inherit tokens and layout="auto" behavior from that wrapper. Override individual tokens on the window or on a parent wrapper, not on every line component.

<TerminalWindow
  className="[--terminal-teal:#7dd3fc]"
  path="~/agent"
>
  {/* --terminal-teal is scoped to this window */}
</TerminalWindow>

──

dark and light

v1 ships built-in themes (default, grok, claude) with two appearances each: dark and light. Three mechanisms control which one you see:

Site mode (recommended) — when html does not have .dark, the active theme class (e.g. .terminal-theme-grok) switches to its light palette. Pair with next-themes so your app toggle updates html.dark.
Per-window override — variant="light" adds the theme's light class (e.g. .terminal-theme-claude-light) and forces the light palette even when the site is in dark mode.
Explicit light class — add terminal-theme-light (default) or terminal-theme-grok-light / terminal-theme-claude-light via className.

Wire next-themes at your app root:

// app/layout.tsx
import { ThemeProvider } from "@/components/theme-provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="dark" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

// TerminalWindow follows html.dark — light site mode → light terminal palette

──

multiple themes

For brand-specific palettes beyond the built-ins — solarized, high-contrast, product-specific — define a wrapper class that sets the same --terminal-* variables and pass it to TerminalWindow:

/* globals.css — after terminal-kit install */
.terminal-theme-solarized {
  --terminal-bg: #002b36;
  --terminal-editor-bg: #073642;
  --terminal-fg: #839496;
  --terminal-dim: #586e75;
  --terminal-teal: #2aa198;
  --terminal-green: #859900;
  --terminal-blue: #268bd2;
  --terminal-border: rgba(131, 148, 150, 0.2);
}

// app/page.tsx
<TerminalWindow className="terminal-theme-solarized" path="~/agent">
  {/* uses solarized tokens */}
</TerminalWindow>

You can ship as many named palettes as you want in your app stylesheet. Built-in themes use .terminal-theme-default, .terminal-theme-grok, and .terminal-theme-claude; custom classes follow the same token pattern.

──

token reference

Common variables (full set lives in your merged globals after install):

Variable	Use
--terminal-bg	Page / shell background
--terminal-editor-bg	TerminalWindow chrome background
--terminal-fg	Primary text
--terminal-dim	Secondary text, metadata
--terminal-teal	Input prompt accent
--terminal-green	Success, command prompt
--terminal-blue	Links, command lines
--terminal-red	Errors, deletions
--terminal-border	Window and panel borders
--terminal-input-border	Input field border (Claude palette)
--terminal-preview-bg	Optional inline frame background (falls back to editor-bg)
--terminal-preview-border	Optional inline frame border (falls back to border)
--terminal-progress-fill	Header progress bar fill
--terminal-session-pad-x	Horizontal session padding

Layout tokens (--terminal-radius-*, --terminal-session-*) and diff colors (--terminal-diff-*) follow the same override pattern. Optional --terminal-preview-* tokens soften inline frames that are not full window chrome — Claude defines tuned values; other palettes fall back to --terminal-editor-bg and --terminal-border.