oldboy/THEME.md

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:

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

Usage in Components

Components reference theme variables using var():

.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:

: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

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

After

.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