主题与样式

§1 大局观

Claude Code 中的终端样式不是粉笔的薄包装。 它是一个故意分层的系统，必须至少能够承受三个恶劣环境：VS Code 的嵌入式终端（其颜色支持是谎言）、tmux（默默地丢弃真彩色背景）和 Apple 终端（根本无法处理 24 位 SGR 序列）。 每一层都有一个单独的工作，并且它们组合得很干净。

§2 主题类型系统

核心数据结构位于 utils/theme.ts。 这 Theme type 是约 70 个命名字符串槽的平面记录。 每个槽都保存一个原始颜色值 - 没有嵌套，没有令牌内令牌。 这种平坦度是有意为之的：任何地方的任何组件都可以在 O(1) 中查找颜色，无限分辨率循环的风险为零。

export type Theme = {
  // Brand identity
  claude: string          // rgb(215,119,87) — "Claude orange"
  claudeShimmer: string  // Lighter version for shimmer animation

  // UI surface roles
  promptBorder: string
  userMessageBackground: string
  selectionBg: string    // Alt-screen text selection highlight

  // Semantic roles
  success: string
  error: string
  warning: string

  // Diff colors (4 variants per operation)
  diffAdded: string
  diffAddedDimmed: string
  diffAddedWord: string

  // Agent colors — named to discourage general use
  red_FOR_SUBAGENTS_ONLY: string
  blue_FOR_SUBAGENTS_ONLY: string
  // ... 6 more

  // Rainbow colors for ultrathink keyword highlighting
  rainbow_red: string
  rainbow_red_shimmer: string
  // ... 12 more rainbow slots
}

命名约定讲述了一个故事。 _FOR_SUBAGENTS_ONLY 后缀充当 lint-time 护栏——您可以直观地 grep 查找误用情况。 这 Shimmer 后缀表示颜色纯粹作为脉冲动画中较亮的步骤存在，绝不适用于静态文本。 这 _FOR_SYSTEM_SPINNER 后缀将克劳德自己的旋转器使用的蓝色与用户可见的权限提示隔离开来。

六大主题

正好有六个具体主题对象，由 ThemeName union:

export const THEME_NAMES = [
  'dark',
  'light',
  'light-daltonized',
  'dark-daltonized',
  'light-ansi',
  'dark-ansi',
] as const

export const THEME_SETTINGS = ['auto', ...THEME_NAMES] as const
// ThemeSetting is stored in config; ThemeName is resolved at runtime

The auto 设置仅在配置存储中有效 - 它被解析为 dark or light 通过在运行时遵循系统的暗/亮模式，然后替换为具体的 ThemeName 在任何组件接触颜色标记之前。

§3 深色、浅色、道尔顿化——实际变化是什么

这三个系列（深色、浅色、道尔顿化）的区别不仅仅在于亮度。 道尔顿化变体系统地用蓝红色区别取代了绿红色区别，因为绿色盲（最常见的色盲形式）会影响绿色通道。 以下是三个黑暗变体中一些关键标记的变化：

请注意 success in dark-daltonized 是亮蓝色，而不是绿色。 患有绿色盲的人不能依靠绿色来表示“好”——所以道尔顿化的主题取代了蓝色，这是在一个完全不同的频道上。 这 diffAdded 出于同样的原因，令牌从深绿色变为深蓝色。

§4 colorize.ts — 终端环境问题

这就是工程变得有趣的地方。 该文件打开时会显示两个长块注释，解释两个单独的终端环境错误，然后在模块加载时修复这两个错误 - 在渲染任何颜色之前。

问题 1：VS Code 对其颜色支持撒谎

function boostChalkLevelForXtermJs(): boolean {
  // xterm.js has supported truecolor since 2017, but code-server/Coder
  // containers often don't set COLORTERM=truecolor. chalk's supports-color
  // doesn't recognize TERM_PROGRAM=vscode (it only knows iTerm.app/
  // Apple_Terminal), so it falls through to the -256color regex → level 2.
  // At level 2, chalk.rgb() downgrades to the nearest 6×6×6 cube color:
  // rgb(215,119,87) (Claude orange) → idx 174 rgb(215,135,135) — washed-out salmon.
  if (process.env.TERM_PROGRAM === 'vscode' && chalk.level === 2) {
    chalk.level = 3
    return true
  }
  return false
}

export const CHALK_BOOSTED_FOR_XTERMJS = boostChalkLevelForXtermJs()

该评论值得仔细阅读。 克劳德牌橙子 rgb(215,119,87) 变成褪色的鲑鱼 rgb(215,135,135) 在 256 色模式下，因为立​​方体量化以错误的方向舍入。 该代码不会在 VS Code 中接受品牌颜色损坏，而是在检测到时手动将粉笔提升到级别 3（真彩色） TERM_PROGRAM=vscode.

问题 2：tmux 丢弃真彩色背景

function clampChalkLevelForTmux(): boolean {
  // tmux parses truecolor SGR (\e[48;2;r;g;bm) into its cell buffer correctly,
  // but its client-side emitter only re-emits truecolor to the outer terminal
  // if the outer terminal advertises Tc/RGB capability. Default tmux config
  // doesn't set this. Without it, backgrounds are simply dropped — bg=default
  // → black on dark profiles.
  // Clamping to level 2 makes chalk emit 256-color (\e[48;5;Nm),
  // which tmux passes through cleanly. grey93 (255) is visually identical.
  if (process.env.CLAUDE_CODE_TMUX_TRUECOLOR) return false
  if (process.env.TMUX && chalk.level > 2) {
    chalk.level = 2
    return true
  }
  return false
}

export const CHALK_CLAMPED_FOR_TMUX = clampChalkLevelForTmux()

这两个调用的顺序很重要： boostChalkLevelForXtermJs 首先运行。 如果有人在 tmux 内的 VS Code 终端内运行 Claude Code（常见于远程开发设置），则首先进行升压，然后钳位将其重新钳位回 2。钳位胜过 tmux 的升压，因为 tmux 的直通限制是一个硬约束，如果不重新配置就无法解决该限制 tmux 本身。 逃生舱口是 CLAUDE_CODE_TMUX_TRUECOLOR=1，对于已正确配置的用户跳过限制 terminal-overrides ,*:Tc 在他们的 tmux 配置中。

colorize() 调度表

正确设置粉笔级别后，实际的颜色调度是一个简单的解析器：

export const colorize = (
  str: string,
  color: string | undefined,
  type: ColorType,  // 'foreground' | 'background'
): string => {
  if (color.startsWith('ansi:')) {
    // Routes to chalk.red / chalk.bgRed etc.
    return type === 'foreground' ? chalk.red(str) : chalk.bgRed(str)
  }
  if (color.startsWith('#')) {
    return type === 'foreground'
      ? chalk.hex(color)(str)
      : chalk.bgHex(color)(str)
  }
  if (color.startsWith('ansi256')) {
    // Parses ansi256(N) → chalk.ansi256(N)
  }
  if (color.startsWith('rgb')) {
    // Parses rgb(r,g,b) → chalk.rgb(r,g,b)
  }
}

字符串前缀调度意味着颜色格式是自描述的。 任何已解析主题令牌的组件都会返回一个字符串，该字符串告诉 colorize 确切地说它是什么颜色——不需要单独的类型标签。

§5 styles.ts — TypeScript 类型的终端布局

The Styles 输入 ink/styles.ts Claude Code 相当于 CSS 属性对象，但用于终端渲染。 它涵盖布局（通过 Yoga 的 Flexbox）、尺寸、边框、溢出、文本换行和颜色——所有这些都是只读的 TypeScript 属性。

export type TextStyles = {
  readonly color?: Color            // Raw color value, not a theme key
  readonly backgroundColor?: Color
  readonly dim?: boolean
  readonly bold?: boolean
  readonly italic?: boolean
  readonly underline?: boolean
  readonly strikethrough?: boolean
  readonly inverse?: boolean
}

// Color is a discriminated union of all supported formats:
export type Color = RGBColor | HexColor | Ansi256Color | AnsiColor
// where RGBColor = `rgb(${number},${number},${number})`
// and   AnsiColor = 'ansi:black' | 'ansi:red' | ... (16 ANSI names)

这里的关键架构决策： TextStyles.color 始终是原始的 Color 值，从来不是主题键。 源码中的评论很明确： “颜色是原始值——主题解析发生在组件层。” 这意味着 styles.ts and colorize.ts 完全不知道主题。 他们是纯粹的机械师。 仅组件层（通过 design-system/color.ts）从主题标记到原始颜色的桥梁。

风格 → 瑜伽映射

默认导出的是 styles.ts 是一个应用了 Styles 对象到 LayoutNode （瑜伽布局引擎）。 这就是 Ink 在你书写时所说的 <Box flexDirection="row" padding={2}>:

const styles = (
  node: LayoutNode,
  style: Styles = {},
  resolvedStyle?: Styles,  // Full current style, for diff application
): void => {
  applyPositionStyles(node, style)
  applyOverflowStyles(node, style)
  applyMarginStyles(node, style)
  applyPaddingStyles(node, style)
  applyFlexStyles(node, style)
  applyDimensionStyles(node, style)
  applyDisplayStyles(node, style)
  applyBorderStyles(node, style, resolvedStyle)
  applyGapStyles(node, style)
}

The resolvedStyle 参数专门针对 applyBorderStyles。 当样式更新作为差异应用时（仅更改的属性）， borderStyle 可能在差异中但是 borderTop 可能不会——因为它没有改变。 解析后的样式带有先前的完整值，因此即使差异是部分的，该函数也可以正确设置所有四个边框边缘。

一项值得注意的财产： noSelect。 这控制是否在全屏模式下从文本选择中排除框的单元格。 这 'from-left-edge' 变体将每行的排除从第 0 课 列扩展到框的右边缘 - 经过专门设计，以便在差异面板上单击并拖动时不会意外地将行号前缀和差异符号复制到剪贴板中。

§6 design-system/color.ts — 连接主题和原始颜色

这个文件很小，但它是建筑粘合剂。 这是唯一将主题键字符串解析为原始颜色值的地方：

export function color(
  c: keyof Theme | Color | undefined,
  theme: ThemeName,
  type: ColorType = 'foreground',
): (text: string) => string {
  return text => {
    if (!c) return text

    // Raw color values bypass theme lookup entirely
    if (
      c.startsWith('rgb(') || c.startsWith('#') ||
      c.startsWith('ansi256(') || c.startsWith('ansi:')
    ) {
      return colorize(text, c, type)
    }

    // Theme key → raw color → chalk output
    return colorize(text, getTheme(theme)[c as keyof Theme], type)
  }
}

返回值是柯里化函数，而不是字符串。 这意味着组件可以创建着色器一次（例如，在渲染函数的顶部）并在多个文本字符串中重用它们，从而避免重复的主题查找。 检查原始颜色前缀意味着您可以传递主题键，例如 "claude" 或者像这样的原始颜色 "rgb(215,119,87)" ——两者的工作都是透明的。

§7 /theme 和 /color 命令

/theme 命令

The /theme 命令呈现完整的交互 ThemePicker 里面的组件 Pane （包裹着 color="permission" - 这是蓝色/紫色许可请求颜色，使选择器在视觉上与正常输出不同）：

// commands/theme/theme.tsx
export const call: LocalJSXCommandCall = async (onDone, _context) => {
  return <ThemePickerCommand onDone={onDone} />
}

function ThemePickerCommand({ onDone }: Props) {
  const [, setTheme] = useTheme()

  return (
    <Pane color="permission">
      <ThemePicker
        onThemeSelect={setting => {
          setTheme(setting)
          onDone(`Theme set to ${setting}`)
        }}
        onCancel={() => onDone('Theme picker dismissed', { display: 'system' })}
        skipExitHandling={true}
      />
    </Pane>
  )
}

The ThemePicker 组件本身（在 components/ThemePicker.tsx）提供实时预览 - 您可以在主题之间切换并在提交之前查看 UI 重新渲染。 这可以通过一个 usePreviewTheme() 设置与保存的设置不同的临时主题状态的钩子。 按 Esc 键取消并恢复之前的主题； 按 Enter 保存它。

/color 命令

The /color 命令仅适用于子代理会话 - 它设置当前会话的提示栏颜色，在多个 Claude Code 代理同时运行时创建视觉差异：

// commands/color/color.ts
export async function call(onDone, context, args) {
  // Teammates cannot set their own color — only the team leader assigns them
  if (isTeammate()) {
    onDone('Cannot set color: This session is a swarm teammate...', { display: 'system' })
    return null
  }

  const colorArg = args.trim().toLowerCase()

  // 'default', 'reset', 'none', 'gray', 'grey' all reset to gray
  if (RESET_ALIASES.includes(colorArg)) {
    await saveAgentColor(sessionId, 'default', fullPath)
    // Updates AppState for immediate effect
    context.setAppState(prev => ({
      ...prev,
      standaloneAgentContext: { ...prev.standaloneAgentContext, color: undefined }
    }))
    return null
  }

  // Valid colors: AGENT_COLORS = ['red','blue','green','yellow','purple','orange','pink','cyan']
  await saveAgentColor(sessionId, colorArg, fullPath)
  context.setAppState(prev => ({
    ...prev,
    standaloneAgentContext: { ...prev.standaloneAgentContext, color: colorArg }
  }))
}

§8 AgentColorManager — 子代理视觉识别

在多代理（群）会话中，Claude Code 需要在视觉上区分代理。 这 agentColorManager.ts 处理从代理类型字符串到主题颜色槽的映射：

export const AGENT_COLORS: readonly AgentColorName[] = [
  'red', 'blue', 'green', 'yellow',
  'purple', 'orange', 'pink', 'cyan'
]

export const AGENT_COLOR_TO_THEME_COLOR = {
  red:    'red_FOR_SUBAGENTS_ONLY',
  blue:   'blue_FOR_SUBAGENTS_ONLY',
  // ... maps human-readable name → Theme key
} as const satisfies Record<AgentColorName, keyof Theme>

The satisfies 约束是聪明的部分 - 它确保在编译时映射中的每个条目都指向该映射的有效键 Theme 类型，而不将常量的类型扩展为 Record<AgentColorName, keyof Theme>。 如果有人添加了新的代理颜色但忘记添加相应的 _FOR_SUBAGENTS_ONLY 槽到 Theme 类型，构建失败。

The general-purpose 代理类型返回 undefined from getAgentColor - 它故意没有颜色，因为通用会话在视觉上没有区别。 只有专门的代理类型（代码审查、测试等）才会从池中获得分配的颜色。

§9 全色分辨率数据流

§10 深潜

// Create a chalk instance with 256-color level for Apple Terminal
// Apple Terminal doesn't handle 24-bit color escape sequences well
const chalkForChart =
  env.terminal === 'Apple_Terminal'
    ? new Chalk({ level: 2 }) // 256 colors
    : chalk

export function themeColorToAnsi(themeColor: string): string {
  const rgbMatch = themeColor.match(/rgb\(\s?(\d+),\s?(\d+),\s?(\d+)\s?\)/)
  if (rgbMatch) {
    const colored = chalkForChart.rgb(r, g, b)('X')
    return colored.slice(0, colored.indexOf('X'))
  }
}

if (isTeammate()) {
  onDone('Cannot set color: This session is a swarm teammate.
Teammate colors are assigned by the team leader.', { display: 'system' })
  return null
}