claude-theme

API Reference

Complete reference for the Claude White-Label Theme system APIs. This document covers the CLI commands, the Theme JSON schema, the browser runtime API, and all CSS custom properties.

CLI Commands
Theme JSON Schema
Browser API
CSS Custom Properties

CLI Commands

The CLI is the primary interface for theme management. All commands are available through:

node .claude/skills/whitelabel-theme/build-theme.js <command> [options]

Or via npm scripts:

npm run theme:<command> -- [options]

Global Options

Option	Description
`--help`	Show help message for a command
`--version`	Show CLI version
`--verbose`	Enable detailed output
`--silent`	Suppress non-error output

`apply`

Compiles a theme and applies it to the browser extension.

Usage:

node build-theme.js apply <theme.json> [options]

Arguments:

Argument	Type	Required	Description
`theme.json`	string	Yes	Path to the theme definition file

Options:

Option	Type	Default	Description
`--output`	string	`extension/`	Output directory for compiled extension
`--reload`	boolean	`true`	Auto-reload the browser extension

Example:

# Apply the dark theme
node build-theme.js apply themes/dark/theme.json

# Apply with custom output directory
node build-theme.js apply themes/nature/theme.json --output ./my-extension/

# Apply without auto-reload
node build-theme.js apply themes/cyberpunk/theme.json --no-reload

Output:

Compiling theme: Dark (by Core Team)
  ID: dark
  Version: 1.0.0
  Colors: 17 CSS variables
  Font: Inter (400, 600, 700)
  Logo: themes/dark/logo.svg
  Output: extension/

Extension compiled successfully!
  manifest.json   -- Browser extension manifest
  theme.css       -- Compiled CSS variables
  inject.js       -- Content injection script
  logo.svg        -- Theme logo (light variant)
  logo-dark.svg   -- Theme logo (dark variant)

`compile`

Compiles a theme to an extension directory without applying or reloading.

Usage:

node build-theme.js compile <theme.json> [options]

Arguments:

Argument	Type	Required	Description
`theme.json`	string	Yes	Path to the theme definition file

Options:

Option	Type	Default	Description
`--output`	string	`extension/`	Output directory

Example:

node build-theme.js compile themes/light/theme.json --output ./dist/extension/

`list`

Lists all available themes in a directory.

Usage:

node build-theme.js list [themes-dir] [options]

Arguments:

Argument	Type	Required	Description
`themes-dir`	string	No	Directory to scan (default: `themes/`)

Options:

Option	Type	Default	Description
`--format`	string	`table`	Output format: `table`, `json`, `names`
`--tags`	string	-	Filter by comma-separated tags

Example:

# List all themes
node build-theme.js list

# List themes in a custom directory
node build-theme.js list ./community-themes/

# Filter by tag
node build-theme.js list --tags dark,high-contrast

# JSON output for scripting
node build-theme.js list --format json

Output (table):

Available themes:
  dark             Dark         (v1.0.0)  Classic dark interface          [dark, default, blue]
  light            Light        (v1.0.0)  Clean light interface           [light, default, blue]
  high-contrast    High Contrast (v1.0.0) Maximum legibility             [accessibility, wcag-aaa]

3 themes found in themes/

`validate`

Validates a theme.json file against the schema and accessibility requirements.

Usage:

node build-theme.js validate <theme.json> [options]

Arguments:

Argument	Type	Required	Description
`theme.json`	string	Yes	Path to the theme file

Options:

Option	Type	Default	Description
`--verbose`	boolean	`false`	Show detailed validation results
`--strict`	boolean	`false`	Fail on warnings in addition to errors

Example:

# Basic validation
node build-theme.js validate themes/dark/theme.json

# Detailed output
node build-theme.js validate themes/custom/theme.json --verbose

# Strict mode (warnings become errors)
node build-theme.js validate themes/custom/theme.json --strict

Output (verbose):

Validating themes/custom/theme.json...

Schema Check:
  id:                OK  ("custom-theme")
  name:              OK  ("Custom Theme")
  version:           OK  ("1.0.0")
  author:            OK  ("Jane Doe")
  description:       OK  ("A warm autumn-inspired theme.")
  fontFamily:        OK  ("Inter")
  fontWeights:       OK  ([400, 600, 700])

Color Validation:
  backgroundPrimary:   #1a1a2e  OK
  backgroundSecondary: #16213e  OK
  textPrimary:         #eaeaea  OK
  accent:              #e94560  OK
  ...

Contrast Ratios:
  textPrimary on backgroundPrimary:   14.2:1  PASS (AA, AAA)
  textSecondary on backgroundPrimary:  8.7:1  PASS (AA, AAA)
  textMuted on backgroundPrimary:      4.8:1  PASS (AA)
  accent on backgroundPrimary:         5.1:1  PASS (AA)

Font Check:
  "Inter" available on Google Fonts: YES
  Weights [400, 600, 700] available: YES

Logo Check:
  themes/custom/logo.svg:       EXISTS (1.2KB)
  themes/custom/logo-dark.svg:  EXISTS (1.1KB)

Result: VALID (all checks passed)

`preview`

Opens a browser preview of a theme without installing it.

Usage:

node build-theme.js preview <theme.json> [options]

Arguments:

Argument	Type	Required	Description
`theme.json`	string	Yes	Path to the theme file

Options:

Option	Type	Default	Description
`--port`	number	`3456`	Port for the preview server
`--watch`	boolean	`false`	Reload on file changes
`--no-open`	boolean	`false`	Don’t auto-open browser

Example:

# Open preview
node build-theme.js preview themes/nature/theme.json

# Preview with hot reload
node build-theme.js preview themes/custom/theme.json --watch

# Preview on a different port
node build-theme.js preview themes/custom/theme.json --port 8080

`init`

Scaffolds a new theme with starter files.

Usage:

node build-theme.js init <theme-name> [options]

Arguments:

Argument	Type	Required	Description
`theme-name`	string	Yes	Theme ID (kebab-case)

Options:

Option	Type	Default	Description
`--template`	string	`dark`	Base template to use
`--author`	string	-	Theme author name
`--output`	string	`themes/`	Parent directory

Example:

# Create a new theme
node build-theme.js init ocean-breeze

# Create from light template
node build-theme.js init sunrise --template light --author "Your Name"

Generated files:

themes/ocean-breeze/
  theme.json         -- Theme definition with starter values
  logo.svg           -- Placeholder logo (dark bg variant)
  logo-dark.svg      -- Placeholder logo (light bg variant)
  README.md          -- Template for theme documentation

Theme JSON Schema

Complete Field Reference

Field	Type	Required	Default	Description	Example
`id`	string	Yes	-	Unique kebab-case identifier	`"ocean-breeze"`
`name`	string	Yes	-	Human-readable name	`"Ocean Breeze"`
`version`	string	Yes	-	SemVer version string	`"1.0.0"`
`author`	string	Yes	-	Creator name or username	`"Jane Doe"`
`description`	string	Yes	-	Short theme description	`"A calming ocean-inspired theme"`
`tags`	string[]	No	`[]`	Filter/search keywords	`["blue", "calm", "nature"]`
`license`	string	No	`"MIT"`	Content license	`"MIT"`
`fontFamily`	string	Yes	-	Google Fonts family name	`"Inter"`
`fontWeights`	number[]	Yes	-	Weights to load	`[400, 600, 700]`

Color Fields

Field	Type	Required	Description	Example
`colors.backgroundPrimary`	hex	Yes	Main background	`"#0d1117"`
`colors.backgroundSecondary`	hex	Yes	Cards, elevated surfaces	`"#161b22"`
`colors.backgroundTertiary`	hex	Yes	Inputs, dropdowns	`"#21262d"`
`colors.backgroundHover`	hex	No	Hover states	`"#30363d"`
`colors.textPrimary`	hex	Yes	Main text	`"#e6edf3"`
`colors.textSecondary`	hex	Yes	Secondary text	`"#b0c4de"`
`colors.textMuted`	hex	Yes	Timestamps, placeholders	`"#6b8cae"`
`colors.accent`	hex	Yes	Buttons, links, highlights	`"#58a6ff"`
`colors.accentHover`	hex	No	Accent on hover	`"#79c0ff"`
`colors.border`	hex	Yes	Dividers, outlines	`"#30363d"`
`colors.error`	hex	Yes	Error states	`"#ff5252"`
`colors.warning`	hex	Yes	Warning states	`"#ffd740"`
`colors.success`	hex	Yes	Success states	`"#69f0ae"`
`colors.terminalUser`	hex	Yes	User message color	`"#58a6ff"`
`colors.terminalAssistant`	hex	Yes	Assistant message color	`"#3fb950"`
`colors.terminalSystem`	hex	Yes	System message color	`"#d29922"`

Schema Validation Rules

Rule	Description
`id`	Must match `^[a-z0-9]+(-[a-z0-9]+)*$` (kebab-case)
`version`	Must match SemVer (`^\d+\.\d+\.\d+`)
Hex colors	Must match `^#[0-9A-Fa-f]{6}$` (6-digit hex)
`fontWeights`	Each value must be in `[100, 200, 300, 400, 500, 600, 700, 800, 900]`
Contrast	`textPrimary` on `backgroundPrimary` must be >= 4.5:1

Browser API

When the theme is active in the browser, a global API is exposed for programmatic control.

`window.__CLAUDE_THEME__`

The theme injector creates a global object on window that you can access from the browser console or userscripts.

Methods

`applyTokens(tokens)`

Applies theme tokens directly without reloading the extension.

Signature:

window.__CLAUDE_THEME__.applyTokens(tokens)

Parameters:

Parameter	Type	Description
`tokens`	Object	Key-value pairs of CSS variable names to values

Example:

// Tweak a single color on the fly
window.__CLAUDE_THEME__.applyTokens({
  '--theme-accent': '#ff6b6b',
  '--theme-accent-hover': '#ff8e8e'
});

// Change the background
window.__CLAUDE_THEME__.applyTokens({
  '--theme-bg-primary': '#1a1a2e',
  '--theme-bg-secondary': '#16213e'
});

Returns: void

`reset()`

Removes all theme overrides and restores Claude’s default appearance.

Signature:

window.__CLAUDE_THEME__.reset()

Example:

// Turn off theming
window.__CLAUDE_THEME__.reset();

Returns: void

`getActiveTheme()`

Returns the currently active theme’s metadata and colors.

Signature:

window.__CLAUDE_THEME__.getActiveTheme()

Returns:

{
  id: "dark",
  name: "Dark",
  version: "1.0.0",
  author: "Core Team",
  fontFamily: "Inter",
  colors: {
    backgroundPrimary: "#0d1117",
    backgroundSecondary: "#161b22",
    // ... all colors
  },
  tokens: {
    "--theme-bg-primary": "#0d1117",
    "--theme-bg-secondary": "#161b22",
    // ... all CSS variables
  }
}

Example:

const theme = window.__CLAUDE_THEME__.getActiveTheme();
console.log(`Current theme: ${theme.name} by ${theme.author}`);
console.log(`Primary bg: ${theme.colors.backgroundPrimary}`);

`reload()`

Force-reloads the current theme. Useful if styles get out of sync.

Signature:

window.__CLAUDE_THEME__.reload()

Example:

window.__CLAUDE_THEME__.reload();

`on(event, callback)`

Listen for theme events.

Signature:

window.__CLAUDE_THEME__.on(event, callback)

Events:

Event	Description	Callback Args
`applied`	Theme was applied	`{ id, name }`
`reset`	Theme was reset	`null`
`tokenChange`	A token was modified	`{ key, value }`

Example:

window.__CLAUDE_THEME__.on('applied', (theme) => {
  console.log(`Theme "${theme.name}" is now active`);
});

window.__CLAUDE_THEME__.on('tokenChange', ({ key, value }) => {
  console.log(`Token ${key} changed to ${value}`);
});

Events

The theme system dispatches CustomEvents on document:

// Listen for theme application
document.addEventListener('theme:applied', (e) => {
  console.log('Theme applied:', e.detail);
});

// Listen for theme reset
document.addEventListener('theme:reset', () => {
  console.log('Theme was reset');
});

CSS Custom Properties

The theme system injects the following CSS custom properties (variables) into the page. You can use these in custom stylesheets or browser extensions.

Layout & Background Colors

Variable	Default Source	Description
`--theme-bg-primary`	`colors.backgroundPrimary`	Main page background
`--theme-bg-secondary`	`colors.backgroundSecondary`	Cards, panels, message bubbles
`--theme-bg-tertiary`	`colors.backgroundTertiary`	Inputs, dropdowns, nested elements
`--theme-bg-hover`	`colors.backgroundHover`	Hover state backgrounds
`--theme-surface`	`colors.backgroundSecondary`	Synonym for secondary bg
`--theme-surface-elevated`	`colors.backgroundSecondary`	Elevated surfaces (with subtle shadow)

Text Colors

Variable	Default Source	Description
`--theme-text-primary`	`colors.textPrimary`	Main headings and body text
`--theme-text-secondary`	`colors.textSecondary`	Descriptions, secondary content
`--theme-text-muted`	`colors.textMuted`	Timestamps, placeholders, hints
`--theme-text-on-accent`	Auto-calculated	Text color for accent-colored buttons
`--theme-text-disabled`	Muted at 50%	Disabled button/input text

Accent Colors

Variable	Default Source	Description
`--theme-accent`	`colors.accent`	Primary accent (buttons, links)
`--theme-accent-hover`	`colors.accentHover`	Accent on hover/focus
`--theme-accent-subtle`	Accent at 15% opacity	Subtle accent backgrounds
`--theme-accent-border`	Accent at 30% opacity	Accent-tinted borders

Semantic Colors

Variable	Default Source	Description
`--theme-error`	`colors.error`	Error text, error borders
`--theme-error-bg`	Error at 15% opacity	Error backgrounds
`--theme-warning`	`colors.warning`	Warning text, warning borders
`--theme-warning-bg`	Warning at 15% opacity	Warning backgrounds
`--theme-success`	`colors.success`	Success text, success borders
`--theme-success-bg`	Success at 15% opacity	Success backgrounds

Border & Divider Colors

Variable	Default Source	Description
`--theme-border`	`colors.border`	Standard borders
`--theme-border-subtle`	Border at 50% opacity	Light dividers
`--theme-divider`	`colors.border`	Section dividers

Terminal / Conversation Colors

Variable	Default Source	Description
`--theme-terminal-user`	`colors.terminalUser`	User message indicators
`--theme-terminal-assistant`	`colors.terminalAssistant`	Assistant message indicators
`--theme-terminal-system`	`colors.terminalSystem`	System/status message indicators

Typography

Variable	Default Source	Description
`--theme-font-family`	`fontFamily`	Primary UI font
`--theme-font-mono`	System mono	Fallback monospace for code
`--theme-font-weight-normal`	400	Regular text weight
`--theme-font-weight-medium`	500 or first weight	Medium emphasis
`--theme-font-weight-bold`	700 or highest weight	Bold text

Shadow & Effects

Variable	Value	Description
`--theme-shadow-sm`	`0 1px 2px rgba(0,0,0,0.1)`	Small shadows
`--theme-shadow-md`	`0 4px 6px rgba(0,0,0,0.1)`	Medium shadows
`--theme-shadow-lg`	`0 10px 15px rgba(0,0,0,0.1)`	Large shadows
`--theme-focus-ring`	Accent with outline	Focus indicator for accessibility

Scrollbar

Variable	Description
`--theme-scrollbar-track`	Scrollbar track background
`--theme-scrollbar-thumb`	Scrollbar thumb color
`--theme-scrollbar-thumb-hover`	Scrollbar thumb on hover

Using CSS Variables in Custom Styles

You can reference theme variables in your own CSS:

/* Custom sidebar widget that matches the theme */
.my-widget {
  background-color: var(--theme-bg-secondary);
  color: var(--theme-text-primary);
  border: 1px solid var(--theme-border);
  font-family: var(--theme-font-family);
}

.my-widget:hover {
  background-color: var(--theme-bg-hover);
}

.my-widget .highlight {
  color: var(--theme-accent);
}

.my-widget .error {
  color: var(--theme-error);
  background-color: var(--theme-error-bg);
}

Programmatic Access

Read CSS variables from JavaScript:

// Get a variable value
const accent = getComputedStyle(document.documentElement)
  .getPropertyValue('--theme-accent')
  .trim();

// Set a variable (temporary override)
document.documentElement.style.setProperty('--theme-accent', '#ff0000');

// Remove override (revert to theme default)
document.documentElement.style.removeProperty('--theme-accent');

Exit Codes

The CLI uses standard exit codes:

Code	Meaning
`0`	Success
`1`	General error
`2`	Invalid arguments or usage
`3`	Validation failure
`4`	File not found
`5`	Network error (font loading, etc.)

This site is open source. Improve this page.

claude-theme

API Reference

Table of Contents

CLI Commands

Global Options

apply

compile

list

validate

preview

init

Theme JSON Schema

Complete Field Reference

Color Fields

Schema Validation Rules

Browser API

window.__CLAUDE_THEME__

Methods

applyTokens(tokens)

reset()

getActiveTheme()

reload()

on(event, callback)

Events

CSS Custom Properties

Layout & Background Colors

Text Colors

Accent Colors

Semantic Colors

Border & Divider Colors

Terminal / Conversation Colors

Typography

Shadow & Effects

Scrollbar

Using CSS Variables in Custom Styles

Programmatic Access

Exit Codes

`apply`

`compile`

`list`

`validate`

`preview`

`init`

`window.__CLAUDE_THEME__`

`applyTokens(tokens)`

`reset()`

`getActiveTheme()`

`reload()`

`on(event, callback)`