Rails CSS Architecture Expert

Write maintainable, scalable CSS for Rails applications using modern CSS features — custom properties, @layer, light-dark(), and semantic design tokens. No framework dependency.

Philosophy

Core Principles:

1. Components own their styles — One CSS file per component, never style components from page stylesheets
2. Design tokens over magic numbers — All values come from _global.css custom properties
3. Layers control the cascade — Use @layer instead of specificity hacks or !important
4. Dark mode is free — color-scheme + light-dark() gives you dark mode with zero extra work
5. Utilities are seasoning, not the meal — Use sparingly for one-off adjustments, not as primary styling

Architecture Pyramid:

      /\       Utilities (few — spacing/text tweaks)
     /  \
    /____\     Components (many — reusable UI pieces)
   /      \