Reset default @theme values for non extend JS theme config (#14672)

Imagine the following setup:

```css
/* src/input.css */
@import "tailwindcss";
@config "../tailwind.config.ts";
@theme {
  --color-red-500: #ef4444;
}
```

```ts
/* tailwind.config.ts */
export default {
  theme: {
    colors: {
      red: {
        600: '#dc2626'
      } 
    },
    extend: {
      colors: {
        400: '#f87171'
      }
    }
  }
}
```

Since the theme object in the JS config contains `colors` in the
non-`extends` block, you would expect this to _not pull in all the
default colors imported via `@import "tailwindcss";`_. This, however,
wasn't the case right now since all theme options were purely _additive_
to the CSS.

This PR makes it so that non-`extend` theme keys _overwrite default CSS
theme values_. The emphasis is on `default` here since you still want to
be able to overwrite your options via `@theme {}` in user space.

This now generates the same CSS that our upgrade codemods would also
generate as this would apply the new CSS right after the `@import
"tailwindcss";` rule resulting in:

```css
@import "tailwindcss";
@theme {
  --color-*: initial;
  --color-red-400: #f87171;
  --color-red-600: #dc2626;
}
@theme {
  --color-red-500: #ef4444;
}
```

## Keyframes

This PR also adds a new core API to unset keyframes the same way. We
previously had no option of doing that but while working on the above
codemods we noticed that keyframes should behave the same way:

```css
@import "tailwindcss";
@theme {
  --keyframes-*: initial;
  @Keyframes spin {
    to {
      transform: rotate(361deg);
    }
  }
}
```

To do this, the keyframes bookeeping was moved from the main Tailwind
CSS v4 file into the `Theme` class.


_I’m not sure super of the API yet but we would need a way for the
codemods to behave the same as out interop layer here. Option B is that
we don't reset keyframes the same way we reset other theme variables_.

Author: philipp-spiess

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Ensure `theme` values defined outside of `extend` in JS configuration files overwrite all existing values for that namespace ([#14672](https://github.com/tailwindlabs/tailwindcss/pull/14672))
 - _Upgrade (experimental)_: Speed up template migrations ([#14679](https://github.com/tailwindlabs/tailwindcss/pull/14679))
 
 ## [4.0.0-alpha.27] - 2024-10-15

packages/@tailwindcss-upgrade/src/codemods/migrate-media-screen.ts

@@ -15,8 +15,8 @@ export function migrateMediaScreen({
   function migrate(root: Root) {
     if (!designSystem || !userConfig) return
 
-    let resolvedUserConfig = resolveConfig(designSystem, [{ base: '', config: userConfig }])
-    let screens = resolvedUserConfig?.theme?.screens || {}
+    let { resolvedConfig } = resolveConfig(designSystem, [{ base: '', config: userConfig }])
+    let screens = resolvedConfig?.theme?.screens || {}
 
     let mediaQueries = new DefaultMap<string, string | null>((name) => {
       let value = designSystem?.resolveThemeValue(`--breakpoint-${name}`) ?? screens?.[name]

packages/@tailwindcss-upgrade/src/migrate-js-config.ts

@@ -9,7 +9,7 @@ import {
   keyPathToCssProperty,
   themeableValues,
 } from '../../tailwindcss/src/compat/apply-config-to-theme'
-import { applyKeyframesToAst } from '../../tailwindcss/src/compat/apply-keyframes-to-ast'
+import { keyframesToRules } from '../../tailwindcss/src/compat/apply-keyframes-to-theme'
 import { deepMerge } from '../../tailwindcss/src/compat/config/deep-merge'
 import { mergeThemeExtension } from '../../tailwindcss/src/compat/config/resolve-config'
 import type { ThemeConfig } from '../../tailwindcss/src/compat/config/types'
@@ -249,7 +249,6 @@ function onlyUsesAllowedTopLevelKeys(theme: ThemeConfig): boolean {
 }
 
 function keyframesToCss(keyframes: Record<string, unknown>): string {
-  let ast: AstNode[] = []
-  applyKeyframesToAst(ast, { theme: { keyframes } })
+  let ast: AstNode[] = keyframesToRules({ theme: { keyframes } })
   return toCss(ast).trim() + '\n'
 }

packages/@tailwindcss-upgrade/src/template/prepare-config.ts

@@ -83,7 +83,7 @@ async function createResolvedUserConfig(fullConfigPath: string): Promise<Config>
 
   return resolveConfig(noopDesignSystem, [
     { base: dirname(fullConfigPath), config: unresolvedUserConfig },
-  ]) as any
+  ]).resolvedConfig as any
 }
 
 const DEFAULT_CONFIG_FILES = [

packages/tailwindcss/src/compat/apply-compat-hooks.ts

@@ -2,7 +2,7 @@ import { rule, toCss, walk, WalkAction, type AstNode } from '../ast'
 import type { DesignSystem } from '../design-system'
 import { segment } from '../utils/segment'
 import { applyConfigToTheme } from './apply-config-to-theme'
-import { applyKeyframesToAst } from './apply-keyframes-to-ast'
+import { applyKeyframesToTheme } from './apply-keyframes-to-theme'
 import { createCompatConfig } from './config/create-compat-config'
 import { resolveConfig } from './config/resolve-config'
 import type { UserConfig } from './config/types'
@@ -215,12 +215,15 @@ function upgradeToFullPluginSupport({
 
   let userConfig = [...pluginConfigs, ...configs]
 
-  let resolvedConfig = resolveConfig(designSystem, [
+  let { resolvedConfig } = resolveConfig(designSystem, [
     { config: createCompatConfig(designSystem.theme), base },
     ...userConfig,
     { config: { plugins: [darkModePlugin] }, base },
   ])
-  let resolvedUserConfig = resolveConfig(designSystem, userConfig)
+  let { resolvedConfig: resolvedUserConfig, replacedThemeKeys } = resolveConfig(
+    designSystem,
+    userConfig,
+  )
 
   let pluginApi = buildPluginApi(designSystem, ast, resolvedConfig)
 
@@ -231,8 +234,8 @@ function upgradeToFullPluginSupport({
   // Merge the user-configured theme keys into the design system. The compat
   // config would otherwise expand into namespaces like `background-color` which
   // core utilities already read from.
-  applyConfigToTheme(designSystem, resolvedUserConfig)
-  applyKeyframesToAst(ast, resolvedUserConfig)
+  applyConfigToTheme(designSystem, resolvedUserConfig, replacedThemeKeys)
+  applyKeyframesToTheme(designSystem, resolvedUserConfig, replacedThemeKeys)
 
   registerThemeVariantOverrides(resolvedUserConfig, designSystem)
   registerScreensConfig(resolvedUserConfig, designSystem)

packages/tailwindcss/src/compat/apply-config-to-theme.test.ts

@@ -1,14 +1,14 @@
 import { expect, test } from 'vitest'
 import { buildDesignSystem } from '../design-system'
-import { Theme } from '../theme'
+import { Theme, ThemeOptions } from '../theme'
 import { applyConfigToTheme } from './apply-config-to-theme'
 import { resolveConfig } from './config/resolve-config'
 
-test('Config values can be merged into the theme', () => {
+test('config values can be merged into the theme', () => {
   let theme = new Theme()
   let design = buildDesignSystem(theme)
 
-  let resolvedUserConfig = resolveConfig(design, [
+  let { resolvedConfig, replacedThemeKeys } = resolveConfig(design, [
     {
       config: {
         theme: {
@@ -54,7 +54,7 @@ test('Config values can be merged into the theme', () => {
       base: '/root',
     },
   ])
-  applyConfigToTheme(design, resolvedUserConfig)
+  applyConfigToTheme(design, resolvedConfig, replacedThemeKeys)
 
   expect(theme.resolve('primary', ['--color'])).toEqual('#c0ffee')
   expect(theme.resolve('sm', ['--breakpoint'])).toEqual('1234px')
@@ -75,11 +75,60 @@ test('Config values can be merged into the theme', () => {
   ])
 })
 
-test('Invalid keys are not merged into the theme', () => {
+test('will reset default theme values with overwriting theme values', () => {
   let theme = new Theme()
   let design = buildDesignSystem(theme)
 
-  let resolvedUserConfig = resolveConfig(design, [
+  theme.add('--color-blue-400', 'lightblue', ThemeOptions.DEFAULT)
+  theme.add('--color-blue-500', 'blue', ThemeOptions.DEFAULT)
+  theme.add('--color-red-400', '#f87171')
+  theme.add('--color-red-500', '#ef4444')
+
+  let { resolvedConfig, replacedThemeKeys } = resolveConfig(design, [
+    {
+      config: {
+        theme: {
+          colors: {
+            blue: {
+              500: '#3b82f6',
+            },
+            red: {
+              500: 'red',
+            },
+          },
+          extend: {
+            colors: {
+              blue: {
+                600: '#2563eb',
+              },
+              red: {
+                600: '#dc2626',
+              },
+            },
+          },
+        },
+      },
+      base: '/root',
+    },
+  ])
+  applyConfigToTheme(design, resolvedConfig, replacedThemeKeys)
+
+  expect(theme.namespace('--color')).toMatchInlineSnapshot(`
+    Map {
+      "red-400" => "#f87171",
+      "red-500" => "#ef4444",
+      "blue-500" => "#3b82f6",
+      "blue-600" => "#2563eb",
+      "red-600" => "#dc2626",
+    }
+  `)
+})
+
+test('invalid keys are not merged into the theme', () => {
+  let theme = new Theme()
+  let design = buildDesignSystem(theme)
+
+  let { resolvedConfig, replacedThemeKeys } = resolveConfig(design, [
     {
       config: {
         theme: {
@@ -92,7 +141,7 @@ test('Invalid keys are not merged into the theme', () => {
     },
   ])
 
-  applyConfigToTheme(design, resolvedUserConfig)
+  applyConfigToTheme(design, resolvedConfig, replacedThemeKeys)
 
   let entries = Array.from(theme.entries())
 

packages/tailwindcss/src/compat/apply-config-to-theme.ts

@@ -19,7 +19,18 @@ function resolveThemeValue(value: unknown, subValue: string | null = null): stri
   return null
 }
 
-export function applyConfigToTheme(designSystem: DesignSystem, { theme }: ResolvedConfig) {
+export function applyConfigToTheme(
+  designSystem: DesignSystem,
+  { theme }: ResolvedConfig,
+  replacedThemeKeys: Set<string>,
+) {
+  for (let resetThemeKey of replacedThemeKeys) {
+    let name = keyPathToCssProperty([resetThemeKey])
+    if (!name) continue
+
+    designSystem.theme.clearNamespace(`--${name}`, ThemeOptions.DEFAULT)
+  }
+
   for (let [path, value] of themeableValues(theme)) {
     if (typeof value !== 'string' && typeof value !== 'number') {
       continue