/design-system

name: claude-devtools:design-system
description: Design system and visual language — theming, CSS variables, Tailwind config, component styling patterns, icon usage, animations, and z-index layers. Use when creating or modifying UI components, working with the dark/light theme, or debugging visual issues.

Design System & Visual Language

How the theming, color palette, component patterns, and styling conventions work.

Theme Architecture

Two themes (dark/light) driven by CSS custom properties in `src/renderer/index.css`. Toggled via `useTheme()` hook which adds/removes `light` class on `document.documentElement`.

Flash prevention: a script in `index.html` applies the cached theme before React loads.

Theme Hook

// src/renderer/hooks/useTheme.ts
const { theme, resolvedTheme, isDark, isLight } = useTheme();
// theme: 'dark' | 'light' | 'system'
// resolvedTheme: 'dark' | 'light' (after system resolution)

Styling Convention

**Colors**: Always via CSS variables (theme-aware). Use inline `style` or Tailwind classes mapped to variables. **Layout/spacing**: Tailwind utility classes. **Icons**: `lucide-react` with `size-*` Tailwind classes.

// Preferred: inline style for theme-aware colors, Tailwind for layout
<div className="flex items-center gap-2 rounded-md px-3 py-2"
     style={{ backgroundColor: 'var(--color-surface-raised)', color: 'var(--color-text)' }}>
  <Bot className="size-4 shrink-0" style={{ color: COLOR_TEXT_SECONDARY }} />
</div>

// Also valid: Tailwind classes that reference CSS variables
<div className="bg-surface text-text border-border">
<div className="bg-surface-raised text-text-secondary">

TypeScript Constants

`src/renderer/constants/cssVariables.ts` centralizes CSS variable strings:

import { COLOR_TEXT_MUTED, CARD_BG, CARD_BORDER_STYLE } from '@renderer/constants/cssVariables';

<span style={{ color: COLOR_TEXT_MUTED }}>Muted text</span>
<div style={{ backgroundColor: CARD_BG, border: CARD_BORDER_STYLE }}>Card</div>

Constants cover: text colors, surfaces, borders, code blocks, diff, cards, tags, prose.

CSS Variable Reference

All defined in `src/renderer/index.css` under `:root` (dark) and `:root.light`.

Surfaces

| Variable | Dark | Light | Usage | |----------|------|-------|-------| | `--color-surface` | `#141416` | `#f9f9f7` | Main background | | `--color-surface-raised` | `#27272a` | `#f0efed` | Elevated surfaces | | `--color-surface-overlay` | `#27272a` | `#e8e7e4` | Overlays/modals | | `--color-surface-sidebar` | `#0f0f11` | `#f1f0ee` | Sidebar background |

Text

| Variable | Dark | Light | Usage | |----------|------|-------|-------| | `--color-text` | `#fafafa` | `#1c1b19` | Primary text | | `--color-text-secondary` | `#a1a1aa` | `#4d4b46` | Secondary text | | `--color-text-muted` | `#71717a` | `#6d6b65` | Muted text |

Borders

| Variable | Dark | Light | |----------|------|-------| | `--color-border` | `rgba(255,255,255,0.05)` | `#d5d3cf` | | `--color-border-subtle` | `rgba(255,255,255,0.05)` | `#e3e1dd` | | `--color-border-emphasis` | `rgba(255,255,255,0.1)` | `#a8a5a0` |

Chat Bubbles

**User bubble** (right-aligned): | Variable | Dark | Light | |----------|------|-------| | `--chat-user-bg` | `#27272a` | `#eae9e6` | | `--chat-user-text` | `#a1a1aa` | `#5a5955` | | `--chat-user-border` | `rgba(255,255,255,0.08)` | `#d5d3cf` | | `--chat-user-shadow` | `0 1px 0 0 rgba(255,255,255,0.03)` | `0 1px 2px 0 rgba(0,0,0,0.04)` | | `--chat-user-tag-bg` | `rgba(255,255,255,0.08)` | `rgba(0,0,0,0.05)` | | `--chat-user-tag-text` | `#e4e4e7` | `#3a3935` | | `--chat-user-tag-border` | `rgba(255,255,255,0.12)` | `rgba(0,0,0,0.08)` |

**AI message**: | Variable | Dark | Light | |----------|------|-------| | `--chat-ai-border` | `rgba(255,255,255,0.05)` | `#d5d3cf` | | `--chat-ai-icon` | `#71717a` | `#6d6b65` |

**System bubble**: | Variable | Dark | Light | |----------|------|-------| | `--chat-system-bg` | `rgba(39,39,42,0.5)` | `#eae9e6` | | `--chat-system-text` | `#d4d4d8` | `#3a3935` |

Code & Syntax

| Variable | Dark | Light | |----------|------|-------| | `--code-bg` | `#1c1c1e` | `#f0efed` | | `--code-header-bg` | `#1c1c1e` | `#eae9e6` | | `--code-border` | `rgba(255,255,255,0.1)` | `#d5d3cf` | | `--code-line-number` | `#52525b` | `#a8a5a0` | | `--code-filename` | `#60a5fa` | `#2563eb` | | `--inline-code-bg` | `rgba(255,255,255,0.08)` | `rgba(0,0,0,0.05)` | | `--inline-code-text` | `#e4e4e7` | `#3a3935` |

Syntax highlighting: `--syntax-string`, `--syntax-comment`, `--syntax-number`, `--syntax-keyword`, `--syntax-type`, `--syntax-operator`, `--syntax-function`. Dark uses vibrant colors; light uses GitHub-inspired palette.

Semantic Blocks

**Thinking**: Purple tones (`--thinking-bg`, `--thinking-border`, `--thinking-text`) **Tool call**: Amber tones (`--tool-call-bg`, `--tool-call-border`, `--tool-call-text`) **Tool result success**: Green tones (`--tool-result-success-bg/border/text`) **Tool result error**: Red tones (`--tool-result-error-bg/border/text`) **Output**: Gray tones (`--output-bg`, `--output-border`, `--output-text`) **Interruption**: Red (`--interruption-bg/border/text`) **Warning**: Amber (`--warning-bg/border/text`) **Plan exit**: Green (`--plan-exit-bg/header-bg/border/text`)

Diff Viewer

| Variable | Dark | Light | |----------|------|-------| | `--diff-added-bg` | `rgba(34,197,94,0.15)` | `rgba(34,197,94,0.1)` | | `--diff-added-text` | `#4ade80` | `#166534` | | `--diff-removed-bg` | `rgba(239,68,68,0.15)` | `rgba(239,68,68,0.1)` | | `--diff-removed-text` | `#f87171` | `#991b1b` |

Cards (Subagents)

| Variable | Dark | Light | |----------|------|-------| | `--card-bg` | `#121212` | `#f9f9f7` | | `--card-border` | `#27272a` | `#d5d3cf` | | `--card-header-bg` | `#18181b` | `#f0efed` | | `--card-header-hover` | `#1f1f23` | `#eae9e6` | | `--card-icon-muted` | `#52525b` | `#a8a5a0` | | `--card-separator` | `#3f3f46` | `#d5d3cf` |

Bad