테마와 시각 스타일링 시스템

§1 큰 그림

Claude Code의 터미널 스타일링은 chalk를 얇게 감싼 래퍼가 아닙니다. 색상 지원을 잘못 보고하는 VS Code 내장 터미널, truecolor 배경을 조용히 버리는 tmux, 24비트 SGR 시퀀스를 제대로 처리하지 못하는 Apple Terminal까지, 적어도 세 가지 까다로운 환경을 버텨야 하도록 의도적으로 층을 나눈 시스템입니다. 각 레이어는 하나의 일만 맡고, 서로 깔끔하게 조합됩니다.

§2 테마 타입 시스템

핵심 데이터 구조는 utils/theme.ts에 있습니다. Theme 타입은 이름 붙은 문자열 슬롯 약 70개를 평평하게 나열한 레코드입니다. 각 슬롯에는 원시 색상값이 들어갑니다. 중첩도 없고, 토큰 안에 토큰도 없습니다. 이런 평평한 구조는 의도된 선택입니다. 어떤 컴포넌트든 어디서든 O(1)로 색상을 조회할 수 있고, 무한 해석 루프에 빠질 위험도 없습니다.

export type Theme = {
  // 브랜드 정체성
  claude: string          // rgb(215,119,87), "Claude 오렌지"
  claudeShimmer: string  // shimmer 애니메이션용 더 밝은 버전

  // UI 표면 역할
  promptBorder: string
  userMessageBackground: string
  selectionBg: string    // Alt-screen 텍스트 선택 강조

  // 시맨틱 역할
  success: string
  error: string
  warning: string

  // Diff 색상(작업당 4개 변형)
  diffAdded: string
  diffAddedDimmed: string
  diffAddedWord: string

  // 에이전트 색상, 범용 사용을 막기 위한 네이밍
  red_FOR_SUBAGENTS_ONLY: string
  blue_FOR_SUBAGENTS_ONLY: string
  // ... 6개 더

  // ultrathink 키워드 강조용 무지개 색상
  rainbow_red: string
  rainbow_red_shimmer: string
  // ... 무지개 슬롯 12개 더
}

이 네이밍 규칙은 많은 것을 말해 줍니다. _FOR_SUBAGENTS_ONLY 접미사는 린트 단계의 가드레일처럼 작동해, 오용을 눈으로 grep 하듯 쉽게 찾을 수 있습니다. Shimmer 접미사는 그 색상이 정적 텍스트용이 아니라 펄스 애니메이션에서 더 밝은 단계로만 존재함을 뜻합니다. _FOR_SYSTEM_SPINNER 접미사는 Claude 자체 스피너에 쓰이는 파란색을, 사용자에게 보이는 권한 프롬프트와 분리합니다.

여섯 가지 테마

ThemeName 유니온에 매핑되는 구체적인 테마 객체는 정확히 여섯 개입니다.

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은 config에 저장되고, ThemeName은 런타임에 해석된다

auto 설정은 config 저장소에서만 유효합니다. 런타임에 시스템의 다크/라이트 모드를 따라 dark 또는 light로 해석되고, 어떤 컴포넌트가 색상 토큰을 만지기 전에 구체적인 ThemeName으로 치환됩니다.

§3 Dark, Light, Daltonized에서 실제로 바뀌는 것

세 가지 계열(dark, light, daltonized)은 밝기만 다른 것이 아닙니다. daltonized 변형은 녹색과 빨간색의 구분을 체계적으로 파란색과 빨간색의 구분으로 바꿉니다. 가장 흔한 색각 이상인 deuteranopia가 녹색 채널에 영향을 주기 때문입니다. 아래는 세 가지 dark 변형에서 몇몇 핵심 토큰이 어떻게 바뀌는지 보여 줍니다.

dark-daltonized의 success는 녹색이 아니라 밝은 파란색이라는 점에 주목해 보세요. deuteranopia가 있는 사람은 녹색을 보고 "좋음"을 안정적으로 판단할 수 없기 때문에, daltonized 테마는 완전히 다른 채널의 색인 파란색으로 대체합니다. diffAdded 토큰이 짙은 녹색에서 짙은 파란색으로 바뀌는 이유도 같습니다.

§4 colorize.ts, 터미널 환경 문제

여기서부터 엔지니어링이 흥미로워집니다. 이 파일은 서로 다른 두 터미널 환경 버그를 설명하는 긴 블록 주석 두 개로 시작하고, 어떤 색상도 렌더링되기 전에 모듈 로드 시점에서 둘 다 바로 수정합니다.

문제 1, VS Code는 색상 지원을 잘못 보고한다

function boostChalkLevelForXtermJs(): boolean {
  // xterm.js는 2017년부터 truecolor를 지원했지만, code-server/Coder
  // 컨테이너는 종종 COLORTERM=truecolor를 설정하지 않는다. chalk의 supports-color는
  // TERM_PROGRAM=vscode를 인식하지 못한다(iTerm.app/Apple_Terminal만 안다).
  // 그래서 -256color 정규식 경로로 떨어져 level 2가 된다.
  // level 2에서는 chalk.rgb()가 가장 가까운 6×6×6 큐브 색상으로 강등된다.
  // rgb(215,119,87)(Claude 오렌지) → idx 174 rgb(215,135,135), 바랜 연어색.
  if (process.env.TERM_PROGRAM === 'vscode' && chalk.level === 2) {
    chalk.level = 3
    return true
  }
  return false
}

export const CHALK_BOOSTED_FOR_XTERMJS = boostChalkLevelForXtermJs()

이 주석은 자세히 읽을 가치가 있습니다. Claude의 브랜드 오렌지 rgb(215,119,87)는 256색 모드에서 큐브 양자화가 엉뚱한 방향으로 반올림되기 때문에 바랜 연어색 rgb(215,135,135)으로 변합니다. 이 코드는 VS Code에서 브랜드 색이 망가지는 것을 받아들이지 않고, TERM_PROGRAM=vscode를 감지하면 chalk를 수동으로 level 3(truecolor)로 올립니다.

문제 2, tmux는 truecolor 배경을 버린다

function clampChalkLevelForTmux(): boolean {
  // tmux는 truecolor SGR (\e[48;2;r;g;bm)를 셀 버퍼에 올바르게 파싱하지만,
  // 바깥 터미널이 Tc/RGB 기능을 광고할 때만 클라이언트 쪽 emitter가 truecolor를
  // 외부 터미널로 다시 내보낸다. 기본 tmux 설정은 이것을 켜지 않는다.
  // 이 설정이 없으면 배경은 그냥 버려지고, bg=default가 되어
  // 다크 프로필에서는 검은색으로 보인다.
  // level 2로 제한하면 chalk가 256색(\e[48;5;Nm)을 내보내고,
  // 이 값은 tmux가 문제없이 통과시킨다. grey93(255)는 시각적으로 거의 같다.
  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이며, 이는 tmux 설정에서 terminal-overrides ,*:Tc를 제대로 잡아 둔 사용자가 클램프를 건너뛰게 해 줍니다.

colorize() 디스패치 테이블

chalk 레벨이 올바르게 맞춰지고 나면, 실제 색상 디스패치는 단순한 파서입니다.

export const colorize = (
  str: string,
  color: string | undefined,
  type: ColorType,  // 'foreground' | 'background'
): string => {
  if (color.startsWith('ansi:')) {
    // chalk.red / chalk.bgRed 등으로 보낸다
    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')) {
    // ansi256(N)을 파싱해 chalk.ansi256(N)으로 보낸다
  }
  if (color.startsWith('rgb')) {
    // rgb(r,g,b)를 파싱해 chalk.rgb(r,g,b)로 보낸다
  }
}

문자열 접두사 기반 디스패치라는 점 덕분에 색상 포맷은 자기 설명적입니다. 테마 토큰을 해석한 모든 컴포넌트는 colorize에게 그 색상이 어떤 종류인지 바로 알려 주는 문자열을 받습니다. 별도의 타입 태그가 필요 없습니다.

§5 styles.ts, TypeScript 타입으로 표현한 터미널 레이아웃

ink/styles.ts의 Styles 타입은 터미널 렌더링용 Claude Code식 CSS 속성 객체라고 볼 수 있습니다. 레이아웃(Yoga 기반 flexbox), 크기, 테두리, overflow, 텍스트 래핑, 색상까지 모두 readonly TypeScript 속성으로 다룹니다.

export type TextStyles = {
  readonly color?: Color            // 테마 키가 아닌 원시 색상값
  readonly backgroundColor?: Color
  readonly dim?: boolean
  readonly bold?: boolean
  readonly italic?: boolean
  readonly underline?: boolean
  readonly strikethrough?: boolean
  readonly inverse?: boolean
}

// Color는 지원되는 모든 포맷의 판별 유니온이다:
export type Color = RGBColor | HexColor | Ansi256Color | AnsiColor
// 여기서 RGBColor = `rgb(${number},${number},${number})`
// 그리고 AnsiColor = 'ansi:black' | 'ansi:red' | ... (ANSI 이름 16개)

여기서 핵심적인 아키텍처 결정은 이것입니다. TextStyles.color는 언제나 원시 Color 값이지, 테마 키가 아닙니다. 소스 주석도 분명하게 말합니다. "색상은 원시 값이며, 테마 해석은 컴포넌트 레이어에서 일어난다." 따라서 styles.ts와 colorize.ts는 테마를 전혀 알지 못합니다. 이 둘은 순수한 메커니즘 계층입니다. 테마 토큰과 원시 색상을 잇는 다리는 컴포넌트 레이어의 design-system/color.ts뿐입니다.

Styles → Yoga 매핑

styles.ts의 default export는 Styles 객체를 LayoutNode(Yoga 레이아웃 엔진)에 적용하는 함수입니다. Ink에서 <Box flexDirection="row" padding={2}>를 작성할 때 실제로 호출되는 것이 이것입니다.

const styles = (
  node: LayoutNode,
  style: Styles = {},
  resolvedStyle?: Styles,  // diff 적용을 위한 현재 전체 스타일
): 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)
}

resolvedStyle 파라미터는 특히 applyBorderStyles를 위해 존재합니다. 스타일 업데이트가 diff 형태로 적용될 때, 바뀐 속성만 들어가므로 borderStyle은 diff에 있어도 borderTop은 없을 수 있습니다. 이전 값이 바뀌지 않았기 때문입니다. resolved style은 이전의 전체 값을 함께 들고 와서, diff가 부분적이어도 함수가 네 방향 테두리를 모두 올바르게 설정할 수 있게 합니다.

눈에 띄는 속성 하나가 noSelect입니다. 풀스크린 모드에서 박스의 셀이 텍스트 선택에서 제외될지를 제어합니다. 'from-left-edge' 변형은 모든 행에서 0열부터 박스의 오른쪽 끝까지 제외 범위를 확장합니다. diff 패널 위를 클릭한 채 드래그할 때 줄 번호 접두사나 diff 기호가 실수로 클립보드에 복사되지 않게 하려는 설계입니다.

§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

    // 원시 색상값은 테마 조회를 완전히 건너뛴다
    if (
      c.startsWith('rgb(') || c.startsWith('#') ||
      c.startsWith('ansi256(') || c.startsWith('ansi:')
    ) {
      return colorize(text, c, type)
    }

    // 테마 키 → 원시 색상 → chalk 출력
    return colorize(text, getTheme(theme)[c as keyof Theme], type)
  }
}

반환값은 문자열이 아니라 커링된 함수입니다. 그래서 컴포넌트는 컬러라이저를 한 번만 만들어 두고, 예를 들어 렌더 함수 상단에서, 여러 텍스트 문자열에 재사용할 수 있습니다. 문자열마다 테마를 반복 조회하지 않아도 됩니다. 또한 원시 색상 접두사를 검사하기 때문에 "claude" 같은 테마 키를 넘겨도 되고, "rgb(215,119,87)" 같은 원시 색상을 넘겨도 됩니다. 둘 다 자연스럽게 동작합니다.

§7 /theme와 /color 명령어

/theme 명령어

/theme 명령어는 Pane 안에 완전한 대화형 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(`테마가 ${setting}(으)로 설정되었습니다`)
        }}
        onCancel={() => onDone('테마 선택기를 닫았습니다', { display: 'system' })}
        skipExitHandling={true}
      />
    </Pane>
  )
}

ThemePicker 컴포넌트 자체는(components/ThemePicker.tsx) 라이브 프리뷰를 제공합니다. 방향키로 테마를 넘겨 보면서 확정하기 전에 UI가 다시 렌더링되는 모습을 볼 수 있습니다. 이는 저장된 설정과 구분되는 임시 테마 상태를 잡는 usePreviewTheme() 훅으로 동작합니다. Escape를 누르면 취소하고 이전 테마를 복원하며, Enter를 누르면 저장합니다.

/color 명령어

/color 명령어는 서브 에이전트 세션 전용입니다. 현재 세션의 프롬프트 바 색상을 설정해서 여러 Claude Code 에이전트가 동시에 실행될 때 시각적으로 구분해 줍니다.

// commands/color/color.ts
export async function call(onDone, context, args) {
  // 팀원은 자기 색상을 직접 설정할 수 없고, 팀 리더만 할당할 수 있다
  if (isTeammate()) {
    onDone('색상을 설정할 수 없습니다. 이 세션은 swarm 팀원 세션입니다...', { display: 'system' })
    return null
  }

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

  // 'default', 'reset', 'none', 'gray', 'grey'는 모두 회색으로 리셋한다
  if (RESET_ALIASES.includes(colorArg)) {
    await saveAgentColor(sessionId, 'default', fullPath)
    // 즉시 반영되도록 AppState를 업데이트한다
    context.setAppState(prev => ({
      ...prev,
      standaloneAgentContext: { ...prev.standaloneAgentContext, color: undefined }
    }))
    return null
  }

  // 유효한 색상: 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, 서브 에이전트의 시각적 식별성

멀티 에이전트(swarm) 세션에서 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',
  // ... 사람이 읽는 이름을 Theme 키로 매핑한다
} as const satisfies Record<AgentColorName, keyof Theme>

satisfies 제약이 핵심입니다. 상수 타입을 Record<AgentColorName, keyof Theme>으로 넓혀 버리지 않으면서도, 맵의 모든 항목이 Theme 타입의 유효한 키를 가리키는지 컴파일 타임에 보장합니다. 누군가 새 에이전트 색상을 추가하면서 Theme 타입에 해당 _FOR_SUBAGENTS_ONLY 슬롯을 넣는 것을 잊으면 빌드가 실패합니다.

general-purpose 에이전트 타입은 getAgentColor에서 undefined를 반환합니다. 의도적으로 색을 주지 않는 것입니다. 범용 세션은 시각적으로 따로 구분하지 않기 때문입니다. 코드 리뷰, 테스팅 같은 특화된 에이전트 타입만 색상 풀에서 값을 할당받습니다.

§9 전체 색상 해석 데이터 흐름

§10 심층 분석

// Apple Terminal용으로 256색 레벨의 chalk 인스턴스를 만든다
// Apple Terminal은 24비트 색상 이스케이프 시퀀스를 잘 처리하지 못한다
const chalkForChart =
  env.terminal === 'Apple_Terminal'
    ? new Chalk({ level: 2 }) // 256색
    : 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('색상을 설정할 수 없습니다. 이 세션은 swarm 팀원 세션입니다.
팀원 색상은 팀 리더가 할당합니다.', { display: 'system' })
  return null
}