Standardizing Component Styling: Lessons in CSS Consistency
Rethinking Our Approach
For a long time, the styling in the humaya project grew organically—which is developer-speak for "inconsistent and hard to maintain." As the project expanded, we found ourselves fighting against specific overrides and increasingly bloated stylesheets. We needed a shift towards a more predictable design structure.
The Shift to Modular CSS
Our primary goal was to move away from deeply nested selectors that were difficult to override. By adopting a more modular approach, we focused on breaking down styles into reusable blocks, significantly reducing the complexity of our CSS hierarchy.
Simplifying Selectors
Instead of broad, global definitions, we transitioned to scoped components. This change allows us to define styles locally without worrying about side effects elsewhere in the application. For instance, we moved from:
/* The Old Way */
main div .sidebar > ul li a { color: blue; }
/* The New Way */
.nav-link--active {
color: var(--primary-brand-color);
font-weight: bold;
}
Key Improvements
Maintainability
By decoupling styles from the DOM structure, updates to a component's appearance no longer require auditing distant stylesheets. The code is now self-contained, and the reliance on specific HTML structures is gone.
Developer Experience
New developers can now understand how a specific component is styled without needing to trace styles back to a massive, global file. Everything related to a button, navigation, or card component now lives within its intended scope.
Future Considerations
- Adopt Design Tokens. We are looking into migrating hard-coded values into variables for consistent theming.
- Automated Linting. Introducing tools to enforce naming conventions (BEM) to ensure our new modular structure remains intact as the project grows.
Actionable Takeaway
If your stylesheets are becoming unmanageable, stop writing styles tied to your HTML structure. Start by refactoring your most-used components into isolated modules today. Your future self will thank you.
Generated with Gitvlg.com