Tired
This commit is contained in:
189
THEME.md
Normal file
189
THEME.md
Normal file
@ -0,0 +1,189 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user