claude-devtools:design-system
This Claude Code item provides the complete design system documentation for a themed UI component library built with Tailwind CSS and lucide-react icons. Use it when building or modifying UI components, implementing dark/light theme switching, debugging visual inconsistencies, or referencing the centralized CSS variable names and color palette conventions. It covers the theme architecture driven by CSS custom properties, styling patterns that mix Tailwind utilities with theme-aware inline styles, and the TypeScript constants file that centralizes variable references across the codebase.
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/matt1398/claude-devtools/HEAD/.claude/commands/devtools/design-system.md -o ~/.claude/commands/claude-devtools-design-system.mddesign-system.md
# 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
```typescript
// 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.
```tsx
// 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:
```typescript
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` |
### Badges
Status badges: `--badge-error-bg/text`, `--badge-warning-bg/text`, `--badge-success-bg/text`, `--badge-info-bg/text`, `--badge-neutral-bg/text`.
Tags: `--tag-bg`, `--tag-text`, `--tag-border`.
### Search Highlights
| Variable | Dark | Light |
|----------|------|-------|
| `--highlight-bg` | `rgba(202,138,4,Use this agent when CLAUDE.md files or .claude/rules/ files may have drifted from the actual codebase state. This includes after significant refactors, feature additions, file renames, directory restructuring, or when you suspect documentation no longer matches reality. Use proactively after any large code change.\\n\\nExamples:\\n\\n- Example 1:\\n user: \"Refactor the services directory to split analysis into separate modules\"\\n assistant: \"I've completed the refactoring of the services directory. Let me now launch the claude-md-auditor agent to ensure all CLAUDE.md files reflect these structural changes.\"\\n <commentary>\\n Since a significant refactor was performed that likely changed file paths, exports, and directory structure documented in CLAUDE.md files, use the Task tool to launch the claude-md-auditor agent.\\n </commentary>\\n\\n- Example 2:\\n user: \"Add a new notifications feature with hooks, components, and a store slice\"\\n assistant: \"The notifications feature is now implemented. I'll use the claude-md-auditor agent to update the documentation to include the new files and patterns.\"\\n <commentary>\\n A new feature was added with multiple new files across components, hooks, and store slices. The CLAUDE.md files likely need updating to document these additions. Use the Task tool to launch the claude-md-auditor agent.\\n </commentary>\\n\\n- Example 3:\\n user: \"Rename isRealUserMessage to isParsedRealUserMessage across the codebase\"\\n assistant: \"The rename is complete across all source and test files. Now I'll launch the claude-md-auditor agent to update any documentation references to the old function name.\"\\n <commentary>\\n A function was renamed which is likely documented in CLAUDE.md type guard tables and conventions sections. Use the Task tool to launch the claude-md-auditor agent to fix stale references.\\n </commentary>\\n\\n- Example 4:\\n user: \"Can you audit the CLAUDE.md files to make sure they're up to date?\"\\n assistant: \"I'll launch the claude-md-auditor agent to systematically verify all documentation against the actual codebase.\"\\n <commentary>\\n The user explicitly requested a documentation audit. Use the Task tool to launch the claude-md-auditor agent.\\n </commentary>
Use this agent when the user wants to fix all code quality issues in the project, including linting, formatting, and unused code detection. This agent runs `pnpm fix` followed by `pnpm quality` in a loop, delegating each iteration to a subagent, until all issues are resolved.\\n\\nExamples:\\n\\n- User: \"Fix all the quality issues\"\\n Assistant: \"I'll launch the quality-fixer agent to iteratively fix all linting, formatting, and quality issues.\"\\n (Uses Task tool to launch quality-fixer agent)\\n\\n- User: \"Run quality checks and fix everything\"\\n Assistant: \"Let me use the quality-fixer agent to handle that.\"\\n (Uses Task tool to launch quality-fixer agent)\\n\\n- User: \"Make sure the code passes all checks\"\\n Assistant: \"I'll use the quality-fixer agent to ensure all quality checks pass.\"\\n (Uses Task tool to launch quality-fixer agent)\\n\\n- After completing a large refactor or feature implementation:\\n Assistant: \"Now that the changes are complete, let me launch the quality-fixer agent to ensure everything passes quality checks.\"\\n (Uses Task tool to launch quality-fixer agent)
ChatGroup architecture — how conversation data flows from raw JSONL to rendered chat groups. Use when working on UserGroup, AIGroup, SystemGroup, display items, tool linking, chunks, or the rendering hierarchy.
Explains what "Visible Context" is — the 6 trackable token categories, what falls outside tracking, how it's displayed, and why it matters. Use when someone asks about visible context, token attribution, or context window usage.
Markdown search logic — how in-session and cross-session search works. Use when working on SearchBar, search highlighting, searchHighlightUtils, markdownTextSearch, or SessionSearcher.
Navigation and scroll orchestration — tab navigation, error highlights, search scrolling, auto-scroll coordination, and common bug patterns. Use when working on useTabNavigationController, scroll restore, or navigation requests.