claude-code/packages/@ant/ink/docs/04-theme-system.md

Chapter 4: Theme System

The theme system provides consistent, accessible color palettes across the application. It supports dark mode, light mode, ANSI-only terminals, and colorblind-accessible variants.

ThemeProvider

Wraps the application to provide theme context.

import { ThemeProvider } from '@anthropic/ink'

function App() {
  return (
    <ThemeProvider initialState="dark" onThemeSave={(setting) => saveConfig(setting)}>
      <MyComponent />
    </ThemeProvider>
  )
}

Props

Prop	Type	Description
children	ReactNode	Child components
initialState	ThemeSetting	Initial theme (default: loads from config)
onThemeSave	(setting: ThemeSetting) => void	Called when theme is saved

Theme Configuration Injection

Before mounting, inject config persistence callbacks:

import { setThemeConfigCallbacks } from '@anthropic/ink'

setThemeConfigCallbacks({
  loadTheme: () => configStore.get('theme', 'dark'),
  saveTheme: (setting) => configStore.set('theme', setting),
})

Theme Settings

type ThemeSetting = 'auto' | 'dark' | 'light' | 'light-daltonized' | 'dark-daltonized' | 'light-ansi' | 'dark-ansi'
type ThemeName = 'dark' | 'light' | 'light-daltonized' | 'dark-daltonized' | 'light-ansi' | 'dark-ansi'

Theme	Description
dark	Dark theme with RGB colors (default)
light	Light theme with RGB colors
dark-daltonized	Colorblind-accessible dark theme
light-daltonized	Colorblind-accessible light theme
dark-ansi	Dark theme using only 16 ANSI colors
light-ansi	Light theme using only 16 ANSI colors
auto	Follows terminal's dark/light mode (resolved at runtime)

Theme Hooks

useTheme()

Returns the resolved theme name and setter.

const [currentTheme, setTheme] = useTheme()
// currentTheme: ThemeName (never 'auto')
// setTheme: (setting: ThemeSetting) => void

useThemeSetting()

Returns the raw setting (may be 'auto').

const setting = useThemeSetting()  // 'auto' | 'dark' | ...

usePreviewTheme()

Returns preview controls for a theme picker UI.

const { setPreviewTheme, savePreview, cancelPreview } = usePreviewTheme()

// Show preview
setPreviewTheme('light')

// User confirms
savePreview()

// User cancels
cancelPreview()

Theme Color Palette

Every theme defines these semantic color keys:

Brand & Identity

Key	Purpose
claude	Brand orange
claudeShimmer	Lighter brand orange (animated)
permission	Permission/blue
permissionShimmer	Lighter permission blue
autoAccept	Electric violet
planMode	Teal/sage
ide	Muted blue

Semantic Colors

Key	Purpose
text	Primary text color
inverseText	Text on inverse backgrounds
inactive	Dimmed/disabled elements
inactiveShimmer	Lighter inactive
subtle	Very subtle text
suggestion	Interactive/accent
background	General background accent
success	Positive/success
error	Negative/error
warning	Caution/warning
warningShimmer	Lighter warning
merged	Merged state

Diff Colors

Key	Purpose
diffAdded	Added lines background
diffRemoved	Removed lines background
diffAddedDimmed	Dimmed added
diffRemovedDimmed	Dimmed removed
diffAddedWord	Word-level added
diffRemovedWord	Word-level removed

UI Colors

Key	Purpose
promptBorder	Input prompt border
promptBorderShimmer	Lighter prompt border
bashBorder	Shell block border
selectionBg	Text selection highlight background
userMessageBackground	User message background
userMessageBackgroundHover	User message hover
messageActionsBackground	Action buttons background

Agent Colors

Key	Purpose
red_FOR_SUBAGENTS_ONLY	Agent color assignment
blue_FOR_SUBAGENTS_ONLY	Agent color assignment
green_FOR_SUBAGENTS_ONLY	Agent color assignment
yellow_FOR_SUBAGENTS_ONLY	Agent color assignment
purple_FOR_SUBAGENTS_ONLY	Agent color assignment
orange_FOR_SUBAGENTS_ONLY	Agent color assignment
pink_FOR_SUBAGENTS_ONLY	Agent color assignment
cyan_FOR_SUBAGENTS_ONLY	Agent color assignment

Using Theme Colors in Components

ThemedText

<Text color="success">Operation complete</Text>
<Text color="error" bold>Failed!</Text>
<Text color="claude">Claude says...</Text>
<Text dimColor>Secondary info</Text>
<Text backgroundColor="userMessageBackground">Highlighted</Text>

ThemedBox

<Box borderStyle="single" borderColor="permission" backgroundColor="userMessageBackground">
  <Text>Themed content</Text>
</Box>

color() Utility

import { color, useTheme } from '@anthropic/ink'

function MyComponent() {
  const [themeName] = useTheme()
  const paint = color('success', themeName)
  // paint('text') returns ANSI-colored string
}

Daltonized Themes

The daltonized themes (light-daltonized, dark-daltonized) are designed for users with protanopia/deuteranopia:

• Green/red diffs replaced with blue/red
• Status colors use blue instead of green
• Warning colors adjusted for better distinction
• All color pairs verified for sufficient contrast

System Theme Detection

When ThemeSetting is 'auto':

1. Seeds from $COLORFGBG environment variable
2. Queries terminal via OSC 11 for live background color
3. Watches for changes (terminal theme switch) in real-time
4. Resolves to 'dark' or 'light' based on detected brightness