@bobfrankston/themecolors

Semantic terminal colors that adapt to light/dark backgrounds. Uses functional names (success, warn, error, info) instead of raw ANSI colors, so you don't have to worry about yellow-on-white or blue-on-black readability.

Install

npm install @bobfrankston/themecolors

Library usage

import { themeColors } from '@bobfrankston/themecolors';

const c = themeColors();           // auto-detect system theme
const c = themeColors('light');    // force light theme

// Basic semantic colors
console.log(c.success('done'));    // green
console.log(c.warn('careful'));    // yellow on dark, magenta on light
console.log(c.error('failed'));    // red
console.log(c.info('note'));       // blue
console.log(c.accent('highlight'));// cyan
console.log(c.muted('secondary'));// dim

// Combined styles (foreground + background)
console.log(c.header('Section'));  // white on blue background
console.log(c.complete('Done'));   // white on green background
console.log(c.note('Note'));       // black on yellow background
console.log(c.critical('FAIL'));   // white on red background
console.log(c.strong('Important'));// bold + adaptive fg

Legacy color-name aliases (red, yellow, green, blue, cyan, dim) are available for migration from raw ANSI usage.

Async detection (recommended when reliability matters)

import { detectThemeAsync, themeColors } from '@bobfrankston/themecolors';

const theme = await detectThemeAsync();   // asks the terminal directly via OSC 11
const c     = themeColors(theme);

detectThemeAsync() queries the terminal with an OSC color sequence, then falls back to the synchronous env/registry chain if the terminal doesn't reply. More reliable than detectTheme() when supported (Windows Terminal, modern xterm, iTerm2, gnome-terminal, konsole, alacritty, kitty, wezterm, VS Code integrated terminal).

Direct terminal-color query

For the actual color values (background, foreground, cursor, 16-color palette), import the /query subpath:

import { getTermTheme, isDarkTheme } from '@bobfrankston/themecolors/query';

const t = await getTermTheme();
// {
//   isDark: true,
//   background: { r, g, b, hex: '#1e1e1e', luminance: 30 },
//   foreground: { r, g, b, hex: '#d4d4d4', luminance: 212 },
//   cursor:     { ... },
//   palette: [Color×16],          // ANSI 0..15
//   source: 'osc' | 'colorfgbg' | 'none'
// }

if (await isDarkTheme()) { /* ... */ }

Options: getTermTheme({ timeoutMs: 250, queryPalette: true }). Skip the palette query for a faster ~3-round-trip detect.

CLI usage

themecolors                # semantic theme map as JSON (auto-detect)
themecolors -theme dark    # force dark
themecolors -theme light   # force light

termtheme                  # full readout of actual terminal colors
termtheme --json           # machine-readable
termtheme --brief          # just "light" or "dark"
termtheme --no-palette     # skip 16-color palette query (faster)

Output (string values for simple colors, arrays for combined styles):

{
  "theme": "light",
  "success": "green",
  "warn": "magenta",
  "error": "red",
  "info": "blue",
  "accent": "cyan",
  "muted": "dim",
  "italic": "italic",
  "bold": "bold",
  "underline": "underline",
  "strong": ["bold", "black"],
  "header": ["white", "bgBlue"],
  "complete": ["white", "bgGreen"],
  "note": ["black", "bgYellow"],
  "critical": ["white", "bgRed"],
  "banner": ["blue", "bgWhite"],
  "debug": "magenta",
  "progress": "black",
  "subtle": "gray"
}

This makes it usable from PowerShell or other scripts that need the color map. A PowerShell counterpart (themecolors.ps1) can consume this JSON and translate ANSI names to PowerShell ConsoleColor values.

Theme detection

detectTheme() — synchronous, first match wins:

1. TERMINAL_THEME env var (light or dark)
2. VS Code VSCODE_THEME_KIND
3. COLORFGBG (rxvt/xterm convention)
4. Windows registry AppsUseLightTheme
5. macOS Terminal / iTerm2 profile
6. Default: dark

detectThemeAsync() — same, but first tries OSC 11 against the terminal itself (cross-platform, ~tens of ms). Use this when you can await.

Customizing colors

Color mappings live in data/themes.json -- edit that file to change mappings or add new semantic names without modifying code.

{
  "semantics": {
    "success":  { "dark": "green", "light": "green" },
    "warn":     { "dark": "yellow", "light": "magenta" },
    "header":   { "dark": ["white", "bgBlue"], "light": ["white", "bgBlue"] }
  },
  "aliases": {
    "red": "error",
    "yellow": "warn"
  }
}

• semantics: each key becomes a color function with per-theme ANSI values
  • Values can be a single string ("green") or an array of ANSI format names (["white", "bgBlue"])
  • Arrays combine multiple styles (foreground, background, modifiers like bold/italic)
• aliases: shorthand names pointing to a semantic entry

Available ANSI format names

Foreground: red, green, yellow, blue, magenta, cyan, white, black, gray Background: bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite, bgBlack Modifiers: bold, dim, italic, underline, inverse, strikethrough