CSS Overhaul #1241
Description
Because the website was started ~12-14 years ago, we have compiled significant technical debt—including a hodgepodge CSS handling and outdated practices. This impacts maintainability and the accessibility of our site (we are failing access checks; see #1240).
I had Claude run an analysis of our CSS infrastructure, specifically. And here's the report:
Makeability Lab CSS Architecture Analysis & Redesign Recommendation
Executive Summary
After analyzing all 29 CSS files (totaling ~10,500 lines), I've identified significant opportunities for consolidation, modernization, and accessibility improvement. The current architecture has accumulated technical debt over 12 years, resulting in inconsistent patterns, duplicated code, and accessibility failures.
Key Findings:
- 22 custom CSS files (~2,700 lines of custom code)
- 7 third-party files (Bootstrap 3.3.6, jQuery UI)
- 40+ unique color values with no centralized palette
- 20+ different media query breakpoints
- Only 1 file uses CSS custom properties (design tokens)
- Multiple accessibility violations (color contrast, missing focus states)
Current State Analysis
File Inventory
| Category | Files | Lines | Notes |
|---|---|---|---|
| Third-party | 7 | ~7,800 | Bootstrap 3.3.6, jQuery UI (keep as-is) |
| Layout/Structure | 4 | ~1,100 | base.css, footer.css, top-navbar.css, carousel_fade.css |
| Page-specific | 11 | ~1,350 | index, project, publications, people, news, etc. |
| Components | 5 | ~280 | faq, talks, backtop, autocomplete, etc. |
| Unused/Legacy | 2 | ~240 | project_old.css, bootstrap-modifications.css |
Long-term Recommendations
1. Consider CSS Framework Migration
Bootstrap 3 is end-of-life. Options:
- Bootstrap 5 - Familiar, CSS variables built-in
- Tailwind CSS - Utility-first, great for consistency
- Custom + Modern CSS - CSS Grid/Flexbox, custom properties
2. Implement CSS Linting
Add Stylelint to your build process:
{
"extends": "stylelint-config-standard",
"rules": {
"color-no-hex": true, // Force use of CSS variables
"declaration-no-important": true,
"selector-max-specificity": "0,3,0"
}
}
3. Document Component Patterns
Create a simple style guide page showing:
- Color palette with accessibility notes
- Typography scale
- Button variants
- Card patterns
- Form elements
Summary: Recommended Approach
For your situation, I recommend Phase 1 + selective Phase 2:
- Today: Create
a11y-overrides.css→ Fixes all 1,064 accessibility errors - This week: Create
design-tokens.css→ Foundation for consistency - Next sprint: Consolidate news files and project files
- Ongoing: Replace hardcoded values with variables as you touch files
This approach:
- ✅ Fixes accessibility immediately
- ✅ Doesn't break existing functionality
- ✅ Establishes patterns for new code
- ✅ Can be done incrementally
- ✅ Doesn't require full rewrite