Create a Theme

term.css themes override 10 CSS custom properties. You can create a theme manually or use the CLI generator.

Theme File Structure

A theme file overrides variables in a single :root block using light-dark() for both modes:

/* my-theme.css */

:root {
  color-scheme: light dark;

  --t-bg: light-dark(oklch(0.97 0.01 200), oklch(0.15 0.02 200));
  --t-fg: light-dark(oklch(0.20 0.02 200), oklch(0.85 0.02 200));
  --t-muted: light-dark(oklch(0.45 0.02 200), oklch(0.58 0.02 200));
  --t-accent: light-dark(oklch(0.45 0.15 200), oklch(0.75 0.15 200));
  --t-accent2: light-dark(oklch(0.50 0.15 200), oklch(0.65 0.15 200));
  --t-surface: light-dark(oklch(0.93 0.01 200), oklch(0.20 0.02 200));
  --t-border: light-dark(oklch(0.80 0.01 200), oklch(0.30 0.02 200));
  --t-red: light-dark(oklch(0.55 0.20 25), oklch(0.65 0.20 25));
  --t-yellow: light-dark(oklch(0.55 0.16 85), oklch(0.78 0.16 85));
  --t-green: light-dark(oklch(0.50 0.17 145), oklch(0.72 0.19 145));
}

/* Manual overrides */
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }

Variable Reference

Contrast Requirements

The CLI generator validates these automatically and exits with an error if any ratio fails.

CLI Generator

Generate a complete theme from a single hue value:

npx termcss --hue 200 --name ocean

Options:

FLAGS

--hue <0-360> Base hue for the theme (required)

--name <name> Theme name (required)

--chroma <0-0.4> Color intensity (default: 0.15)

--out <path> Output path (default: ./<name>.css)

The generator creates both dark and light mode values with consistent lightness steps, and validates WCAG AA contrast for every color pair.

Example

# Generate an ocean theme
npx termcss --hue 200 --name ocean

# Generate a warm theme with lower chroma
npx termcss --hue 30 --name warm --chroma 0.10

# Output to a custom path
npx termcss --hue 280 --name purple --out ./my-theme.css

OKLCH Color Space

term.css uses OKLCH for all colors. OKLCH is a perceptually uniform color space where:

• L (Lightness): 0 = black, 1 = white. Equal steps look equal.
• C (Chroma): 0 = gray, higher = more saturated.
• H (Hue): 0-360 degree color wheel.

This makes it possible to generate mathematically correct themes by fixing lightness values and rotating the hue.

Community Themes

To submit a theme:

1. Create a theme file in src/themes/
2. Ensure all contrast ratios pass (pnpm check:contrast validates all shipped themes)
3. Test in both dark and light modes
4. Submit a PR to the GitHub repo