190 lines
4.6 KiB
Markdown
190 lines
4.6 KiB
Markdown
# 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
|