# Theme System

## Overview

The application uses a centralized CSS custom properties (variables) system defined in `src/theme.css`. This provides a consistent design language across all components and makes theme switching possible in the future.

## Architecture

### Theme Variables

All theme variables are defined at the `:root` level in `theme.css` and use the `--` prefix:

```css
:root {
  --color-accent-primary: #646cff;
  --space-md: 0.75rem;
  --font-base: 0.875rem;
}
```

### Usage in Components

Components reference theme variables using `var()`:

```css
.my-component {
  color: var(--color-text-primary);
  padding: var(--space-md);
  font-size: var(--font-base);
}
```

## Variable Categories

### Colors

#### Base & Surface
- `--color-bg-base`: Main background
- `--color-surface-0` through `--color-surface-3`: Elevated surfaces

#### Text Hierarchy
- `--color-text-primary`: Main text (87% opacity)
- `--color-text-secondary`: Secondary text (60% opacity)
- `--color-text-tertiary`: Labels and hints (40% opacity)
- `--color-text-disabled`: Disabled state (25% opacity)

#### Accent
- `--color-accent-primary`: Primary brand color (#646cff)
- `--color-accent-primary-hover`: Hover state
- `--color-accent-primary-subtle`: Transparent accent for backgrounds

#### Semantic
- `--color-success`: Success states (#10b981)
- `--color-warning`: Warning states (#fbbf24)
- `--color-error`: Error states (#ef4444)
- `--color-info`: Informational elements (#60a5fa)

#### Borders
- `--color-border-subtle`: Very subtle borders (6% opacity)
- `--color-border-default`: Standard borders (10% opacity)
- `--color-border-strong`: Emphasized borders (20% opacity)

#### Interactive States
- `--color-hover-overlay`: Hover effect
- `--color-active-overlay`: Active/pressed effect
- `--color-selected-overlay`: Selection background

### Spacing

Uses a consistent scale from `--space-xs` (0.25rem) to `--space-2xl` (2rem):

```
xs:  0.25rem
sm:  0.5rem
md:  0.75rem
lg:  1rem
xl:  1.5rem
2xl: 2rem
```

### Typography

#### Font Sizes
- `--font-xs` through `--font-lg` for consistent sizing
- Base size is `--font-base: 0.875rem`

#### Font Families
- `--font-mono`: Monospace font for code
- `--font-sans`: System UI font

#### Line Heights
- `--leading-tight`: 1.4
- `--leading-normal`: 1.5
- `--leading-relaxed`: 1.6

### Visual Effects

- `--radius-sm/md/lg`: Border radius values
- `--shadow-sm/md/lg`: Box shadow presets
- `--transition-fast/base/slow`: Animation durations

### Component-Specific

Specialized tokens for specific use cases:
- `--accordion-*`: Accordion styling
- `--input-*`: Form inputs
- `--tooltip-*`: Tooltip components
- `--code-*`: Code blocks

## Design Principles

### Color Usage

1. **Use accent colors sparingly**: Primary accent (#646cff) for:
   - Interactive elements
   - Primary actions
   - Highlighted content (e.g., opcode names)

2. **Semantic colors for meaning**:
   - Blue (`--color-info`) for informational data (e.g., rates)
   - Green (`--color-success`) for success states
   - Yellow (`--color-warning`) for warnings
   - Red (`--color-error`) for errors

3. **Text hierarchy through opacity**:
   - Use `--color-text-*` variables instead of custom opacity values
   - Maintains consistency and improves readability

### Spacing

- Use the spacing scale consistently
- Avoid magic numbers - use defined spacing tokens
- Vertical rhythm: prefer consistent spacing between elements

### Borders

- Most borders should use `--color-border-subtle` for minimal visual weight
- Use `--color-border-default` for more emphasis
- Reserve `--color-border-strong` for important separators

## Adding a New Theme

To add a new theme (e.g., light mode):

1. Create a new CSS file (e.g., `theme-light.css`)
2. Override the root variables:

```css
:root {
  --color-bg-base: #ffffff;
  --color-text-primary: rgba(0, 0, 0, 0.87);
  /* ... other overrides */
}
```

3. Conditionally import based on theme preference
4. All components automatically adapt to the new values

## Migration Guide

When updating existing components to use the theme system:

### Before
```css
.component {
  background-color: #1a1a1a;
  color: rgba(255, 255, 255, 0.87);
  padding: 0.75rem;
  border: 1px solid #3a3a3a;
}
```

### After
```css
.component {
  background-color: var(--color-bg-base);
  color: var(--color-text-primary);
  padding: var(--space-md);
  border: 1px solid var(--color-border-default);
}
```

## Benefits

1. **Consistency**: Single source of truth for design tokens
2. **Maintainability**: Change once, apply everywhere
3. **Theme switching**: Easy to add light/dark mode or custom themes
4. **Readability**: Semantic names instead of magic values
5. **Scalability**: Add new tokens without touching components