Tailwind v4 dark mode: the @theme vs @theme inline gotcha that broke my contrast tests

Short summary

Tailwind v4 offers two ways to declare color tokens: @theme inline (compiles hex values directly into utilities) and @theme (uses CSS variables for dynamic cascading). Only @theme supports wrapper-class overrides, essential for complex dark-mode theming with always-light and always-dark containers. The author discovered this after shipping six surfaces with invisible text due to baked-in hex values failing accessibility contrast tests.

• •@theme vs @theme inline have different cascade behavior in Tailwind v4
• •Only @theme supports wrapper-class overrides needed for multi-layer dark mode
• •Inline hex values break accessibility when contrast overrides are required

Generated with AI, which can make mistakes.