grvpanchal Theme
What is a Theme?
Themes are systematic design languages implemented through CSS—design tokens covering colors, typography, spacing, shadows, and interactions that ensure visual consistency across your entire application.
Key Principles
Design Tokens: Use named tokens (
--color-primary,--spacing-md) not raw values. Tokens are the contract between designers and developers.CSS Custom Properties: Prefer CSS variables over preprocessor variables for runtime flexibility (dark mode, user preferences) without recompilation.
Semantic Naming: Use purpose-based names (
--color-error) not value-based (--color-red). Allows theme changes without renaming.
Best Practices
✅ DO:
- Define all design decisions as tokens
- Use CSS custom properties (variables)
- Support light/dark mode via token switching
- Create semantic color names (primary, error, surface)
- Document token usage and values
- Organize tokens by category (color, spacing, typography)
❌ DON'T:
- Hardcode colors/spacing in components
- Use magic numbers (
padding: 17px) - Create one-off values outside token system
- Mix token naming conventions
- Forget accessibility (contrast ratios)
Code Patterns
Recommended
/* tokens.css - Design token definitions */
:root {
/* Color tokens - semantic names */
--color-primary: #3b82f6;
--color-primary-hover: #2563eb;
--color-error: #ef4444;
--color-success: #22c55e;
/* Surface colors */
--color-surface: #ffffff;
--color-surface-elevated: #f8fafc;
--color-text: #1e293b;
--color-text-muted: #64748b;
/* Spacing scale */
--spacing-xs: 0.25rem;
--spacing-sm: 0.5rem;
--spacing-md: 1rem;
--spacing-lg: 1.5rem;
--spacing-xl: 2rem;
/* Typography */
--font-family: system-ui, sans-serif;
--font-size-sm: 0.875rem;
--font-size-base: 1rem;
--font-size-lg: 1.25rem;
}
/* Dark mode via token override */
[data-theme="dark"] {
--color-surface: #0f172a;
--color-text: #f1f5f9;
}
// Component using tokens
const Button = ({ variant }) => (
<button style={{
backgroundColor: `var(--color-${variant})`,
padding: 'var(--spacing-sm) var(--spacing-md)',
fontFamily: 'var(--font-family)'
}}>
Click
</button>
);
Avoid
/* ❌ WRONG - Hardcoded values */
.button {
background: #3b82f6; /* Magic color */
padding: 8px 16px; /* Magic numbers */
}
/* ✅ CORRECT - Use tokens */
.button {
background: var(--color-primary);
padding: var(--spacing-sm) var(--spacing-md);
}
Related Terminologies
- Atom (UI) - Atoms consume theme tokens
- Component (UI) - All components reference theme
- Accessibility (UI) - Theme must meet contrast requirements
- Props (UI) - Theme can be passed as prop context
Quality Gates
- All colors defined as tokens
- All spacing uses scale tokens
- Semantic naming (not value-based)
- Dark mode supported
- Meets WCAG contrast requirements
- Documented token catalog
Source: /docs/ui/theme.md