fix(website): comprehensive light mode CSS fixes for Tailwind v4

[ajitpratap0]

Summary

Fixes the broken light mode that was introduced in #514. The light mode CSS overrides weren't working because:

1. Tailwind v4 cascade layers — utilities compile inside @layer which beats unlayered selectors regardless of specificity. Fixed with !important.
2. Arbitrary value classes — bg-[#09090b] on the playground root container couldn't be matched by any named-class selector. Added escaped arbitrary value selector.
3. Slash-encoded opacities — bg-white/[0.06], border-white/10, bg-slate-900/50 etc. use Tailwind v4 class encoding that attribute selectors ([class*="..."]) can't reliably match. Added direct class selectors.

Changes

Single file: website/src/app/globals.css (+83, -20)

• Add !important to all html.light text, background, border overrides
• Add direct class selectors for all bg-white/[x], border-white/[x] variants
• Add bg-[#09090b] and bg-[#0F172A] playground container overrides
• Add bg-slate-900/50, bg-slate-900/30, bg-slate-700/50 direct overrides
• Darken slate text overrides (text-slate-400 → #475569) for playground contrast
• Override all select elements in light mode
• Add playground-specific overrides (blue tabs, emerald code, dividers, skeletons)

Test Plan

• next build passes (51 pages, 0 errors)
• Homepage light mode: hero, trust, performance, features, dialects, code, MCP, footer
• Docs index + article light mode
• Playground light mode (editor stays dark via CodeMirror oneDark)
• Benchmarks, Compare, Blog light mode
• Dark mode regression check (no changes to dark mode)
• Lighthouse accessibility >= 0.95

Breaking Changes

None.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
gosqlx-website	Ready	Preview, Comment	Apr 13, 2026 5:12pm

[github-actions]

Claude finished @ajitpratap0's task —— View job

---

Code Review Complete ✅

I've thoroughly reviewed this light mode CSS fix. Here's my comprehensive feedback:

Todo List:

• Analyze PR context and requirements
• Read the modified CSS file to understand changes
• Review CSS code quality and best practices
• Check for potential bugs and issues
• Assess performance considerations
• Look for security concerns
• Evaluate test coverage approach
• Provide comprehensive review feedback

Review Summary

Overall Assessment: ✅ Approved with minor suggestions

This is a well-executed fix for the light mode issues introduced by the Tailwind v4 upgrade. The approach is pragmatic and technically sound.

Code Quality & Best Practices

✅ Strengths:

1. Strategic Use of !important: Correctly addresses Tailwind v4's @layer cascade precedence issue (website/src/app/globals.css:141)
2. Comprehensive Coverage: Addresses all major UI components systematically (lines 117-454)
3. CSS Organization: Well-structured with clear section comments and logical grouping
4. Escaped Arbitrary Values: Proper CSS escaping for complex Tailwind classes like bg-[#09090b] (line 316)
5. Accessibility: Maintains prefers-reduced-motion support (lines 456-463)

🔄 Suggestions for Improvement:

1. CSS Custom Properties Enhancement (website/src/app/globals.css:118-131):

   /* Consider extending design tokens for better maintainability */
   html.light {
     --color-light-text: #1A1A2E;
     --color-light-border: rgba(0, 0, 0, 0.08);
     /* Use these variables throughout instead of hardcoded values */
   }

2. Selector Specificity Optimization (lines 183-216):

   /* Current approach works but could be consolidated */
   html.light [class*="bg-slate-"][class*="/"] { 
     background-color: var(--light-subtle-bg) !important; 
   }

Potential Issues & Bugs

⚠️ Minor Concerns:

1. Selector Reliability (website/src/app/globals.css:189,213-216):

   • Attribute selectors like [class*="bg-white\\/"] may not match all variations reliably
   • Consider adding specific fallback classes if needed

2. Code Block Consistency (lines 348-381):

   • Mixed approaches between keeping dark theme vs. light theme for code blocks
   • Ensure CodeMirror integration maintains expected dark theme

✅ Well Handled:

1. Cascade Conflicts: Proper use of !important where necessary
2. Component Isolation: Accent containers maintain white text appropriately (lines 144-149)
3. Playground Integration: Handles arbitrary background colors correctly (lines 316-317)

Performance Considerations

✅ Positive Impact:

1. Single File Change: Minimal bundle size impact
2. CSS-Only Solution: No JavaScript overhead
3. Efficient Selectors: Most selectors are reasonably performant

💡 Optimization Opportunities:

1. CSS Custom Properties: Using CSS variables more extensively would reduce repetition and improve paint performance
2. Selector Count: 100+ new selectors - consider consolidation where possible

Security Assessment

✅ No Security Concerns:

• Pure CSS changes with no user input handling
• No XSS vectors introduced
• No external resources or imports

Test Coverage Evaluation

✅ Adequate for CSS Changes:

• Build verification confirms no compilation errors
• Visual testing plan covers all major components
• Regression testing for dark mode included

💡 Testing Enhancements:

// Consider adding automated visual regression tests
// E.g., with Playwright or Chromatic for critical pages

Technical Deep Dive

Tailwind v4 Compatibility Issues Addressed:

1. CSS Cascade Layers (line 141): Tailwind v4 utilities compile in @layer, requiring !important to override
2. Arbitrary Value Encoding (line 316): bg-[#09090b] requires escaped CSS selectors
3. Opacity Slash Syntax (lines 183-216): New bg-white/[0.06] format needs specific handling

Architecture Decision Analysis:

The CSS-override approach vs. component-level changes:

• ✅ Pros: Faster implementation, no JSX changes, centralized theming
• ⚠️ Tradeoffs: Higher specificity, maintenance overhead, some coupling to class names

Recommendations

1. Ship as-is - This is production-ready and addresses the critical light mode issues
2. Consider follow-up: Gradual migration to CSS custom properties for better maintainability
3. Monitor: Watch for edge cases in production, particularly with dynamically generated classes

Summary

This PR effectively solves the Tailwind v4 light mode breaking changes with a well-researched, technically sound approach. The code quality is high, performance impact is minimal, and security is not a concern. The comprehensive coverage and proper handling of CSS cascade issues makes this ready for production deployment.

Recommendation: ✅ Approve and merge

---