The CSS Scaling Problem
CSS starts simple but becomes unwieldy at scale. Architecture decisions made early have a massive impact on maintainability. Here's how we handle CSS in large codebases.
Design Token System
Design tokens are the single source of truth for your visual design. They abstract away raw values into meaningful names.
:root {
--color-primary-500: #6366f1;
--space-1: 0.25rem;
--space-4: 1rem;
--text-base: 1rem;
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
--transition-fast: 150ms ease;
}
[data-theme="dark"] {
--color-primary-500: #818cf8;
}Component CSS Architecture
Use CSS Modules or Tailwind for component-scoped styles. Avoid global CSS except for design tokens and resets.
/* Button.module.css */
.button {
display: inline-flex;
padding: var(--space-2) var(--space-4);
border-radius: var(--radius-lg);
transition: all var(--transition-fast);
}
.primary { background: var(--color-primary-500); color: white; }
.secondary { background: transparent; border: 1px solid var(--color-primary-500); }Best Practices
- Keep specificity low. Avoid nesting beyond 2 levels
- Only animate transform and opacity for 60fps performance
- Respect prefers-reduced-motion for accessibility
- Monitor CSS bundle size: unused CSS is dead weight
- Use logical properties (margin-inline) for RTL support
Conclusion
Good CSS architecture is about consistency and constraints. Design tokens + utility-first CSS + component styles is a proven formula for scaling.
