Add support for the theme() function in the plugin API (#14207)

This PR adds support for the [`theme()`
function](https://tailwindcss.com/docs/plugins#dynamic-utilities) from
the v3 plugin API, used for configuring which values functional
utilities support:

```js
plugin(function({ matchUtilities, theme }) {
  matchUtilities(
    {
      tab: (value) => ({
        tabSize: value
      }),
    },
    { values: theme('tabSize') }
  )
})
```

Things this handles:

- "Upgrading" theme keys to their v4 names, so if you do
`theme('colors')` that will correctly retrieve all the colors from the
`--color-*` namespace with the new CSS variable based configuration
- Polyfilling dependent keys, so `theme('backgroundColor')` will still
pull everything in `--color-*` even though there is no values in the
`backgroundColor` namespace in v4 by default
- Polyfilling theme values that are now handled by "bare values"
internally, so even though there is no `flexShrink` theme values in v4,
`theme('flexShrink')` will still configure your plugin to properly
support any value that the built-in `shrink-*` utilities support

Things that aren't handled:

- Theme values that have been replaced by static utilities can't be
retrieved yet, so for example `theme('cursor')` returns nothing right
now because there are no values for the `cursor-*` utilities in the
theme anymore, they are all just baked in to the framework.

This will be handled in a future PR.

---------

Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add support for `addBase` plugins using the `@plugin` directive ([#14172](https://github.com/tailwindlabs/tailwindcss/pull/14172))
 - Add support for the `tailwindcss/plugin` export ([#14173](https://github.com/tailwindlabs/tailwindcss/pull/14173))
+- Add support for the `theme()` function in plugins ([#14207](https://github.com/tailwindlabs/tailwindcss/pull/14207))
 
 ### Fixed
 

packages/tailwindcss/src/ast.ts

@@ -42,30 +42,6 @@ export function comment(value: string): Comment {
   }
 }
 
-export type CssInJs = { [key: string]: string | CssInJs }
-
-export function objectToAst(obj: CssInJs): AstNode[] {
-  let ast: AstNode[] = []
-
-  for (let [name, value] of Object.entries(obj)) {
-    if (typeof value === 'string') {
-      if (!name.startsWith('--') && value === '@slot') {
-        ast.push(rule(name, [rule('@slot', [])]))
-      } else {
-        // Convert camelCase to kebab-case:
-        // https://github.com/postcss/postcss-js/blob/b3db658b932b42f6ac14ca0b1d50f50c4569805b/parser.js#L30-L35
-        name = name.replace(/([A-Z])/g, '-$1').toLowerCase()
-
-        ast.push(decl(name, value))
-      }
-    } else {
-      ast.push(rule(name, objectToAst(value)))
-    }
-  }
-
-  return ast
-}
-
 export enum WalkAction {
   /** Continue walking, which is the default */
   Continue,

packages/tailwindcss/src/compat/config/create-compat-config.ts

@@ -0,0 +1,179 @@
+import type { NamedUtilityValue } from '../../candidate'
+import type { Theme } from '../../theme'
+import { segment } from '../../utils/segment'
+import type { UserConfig } from './types'
+
+function bareValues(fn: (value: NamedUtilityValue) => string | undefined) {
+  return {
+    // Ideally this would be a Symbol but some of the ecosystem assumes object with
+    // string / number keys for example by using `Object.entries()` which means that
+    // the function that handles the bare value would be lost
+    __BARE_VALUE__: fn,
+  }
+}
+
+let bareIntegers = bareValues((value) => {
+  if (!Number.isNaN(Number(value.value))) {
+    return value.value
+  }
+})
+
+let barePercentages = bareValues((value: NamedUtilityValue) => {
+  if (!Number.isNaN(Number(value.value))) {
+    return `${value.value}%`
+  }
+})
+
+let barePixels = bareValues((value: NamedUtilityValue) => {
+  if (!Number.isNaN(Number(value.value))) {
+    return `${value.value}px`
+  }
+})
+
+let bareMilliseconds = bareValues((value: NamedUtilityValue) => {
+  if (!Number.isNaN(Number(value.value))) {
+    return `${value.value}ms`
+  }
+})
+
+let bareDegrees = bareValues((value: NamedUtilityValue) => {
+  if (!Number.isNaN(Number(value.value))) {
+    return `${value.value}deg`
+  }
+})
+
+export function createCompatConfig(theme: Theme): UserConfig {
+  return {
+    theme: {
+      colors: ({ theme }) => theme('color', {}),
+      accentColor: ({ theme }) => theme('colors'),
+      aspectRatio: bareValues((value) => {
+        if (value.fraction === null) return
+        let [lhs, rhs] = segment(value.fraction, '/')
+        if (!Number.isInteger(Number(lhs)) || !Number.isInteger(Number(rhs))) return
+        return value.fraction
+      }),
+      backdropBlur: ({ theme }) => theme('blur'),
+      backdropBrightness: ({ theme }) => ({
+        ...theme('brightness'),
+        ...barePercentages,
+      }),
+      backdropContrast: ({ theme }) => ({
+        ...theme('contrast'),
+        ...barePercentages,
+      }),
+      backdropGrayscale: ({ theme }) => ({
+        ...theme('grayscale'),
+        ...barePercentages,
+      }),
+      backdropHueRotate: ({ theme }) => ({
+        ...theme('hueRotate'),
+        ...bareDegrees,
+      }),
+      backdropInvert: ({ theme }) => ({
+        ...theme('invert'),
+        ...barePercentages,
+      }),
+      backdropOpacity: ({ theme }) => ({
+        ...theme('opacity'),
+        ...barePercentages,
+      }),
+      backdropSaturate: ({ theme }) => ({
+        ...theme('saturate'),
+        ...barePercentages,
+      }),
+      backdropSepia: ({ theme }) => ({
+        ...theme('sepia'),
+        ...barePercentages,
+      }),
+      backgroundColor: ({ theme }) => theme('colors'),
+      backgroundOpacity: ({ theme }) => theme('opacity'),
+      border: barePixels,
+      borderColor: ({ theme }) => theme('colors'),
+      borderOpacity: ({ theme }) => theme('opacity'),
+      borderSpacing: ({ theme }) => theme('spacing'),
+      boxShadowColor: ({ theme }) => theme('colors'),
+      brightness: barePercentages,
+      caretColor: ({ theme }) => theme('colors'),
+      columns: bareIntegers,
+      contrast: barePercentages,
+      divideColor: ({ theme }) => theme('borderColor'),
+      divideOpacity: ({ theme }) => theme('borderOpacity'),
+      divideWidth: ({ theme }) => ({
+        ...theme('borderWidth'),
+        ...barePixels,
+      }),
+      fill: ({ theme }) => theme('colors'),
+      flexBasis: ({ theme }) => theme('spacing'),
+      flexGrow: bareIntegers,
+      flexShrink: bareIntegers,
+      gap: ({ theme }) => theme('spacing'),
+      gradientColorStopPositions: barePercentages,
+      gradientColorStops: ({ theme }) => theme('colors'),
+      grayscale: barePercentages,
+      gridRowEnd: bareIntegers,
+      gridRowStart: bareIntegers,
+      gridTemplateColumns: bareValues((value) => {
+        if (!Number.isNaN(Number(value.value))) {
+          return `repeat(${value.value}, minmax(0, 1fr))`
+        }
+      }),
+      gridTemplateRows: bareValues((value) => {
+        if (!Number.isNaN(Number(value.value))) {
+          return `repeat(${value.value}, minmax(0, 1fr))`
+        }
+      }),
+      height: ({ theme }) => theme('spacing'),
+      hueRotate: bareDegrees,
+      inset: ({ theme }) => theme('spacing'),
+      invert: barePercentages,
+      lineClamp: bareIntegers,
+      margin: ({ theme }) => theme('spacing'),
+      maxHeight: ({ theme }) => theme('spacing'),
+      maxWidth: ({ theme }) => theme('spacing'),
+      minHeight: ({ theme }) => theme('spacing'),
+      minWidth: ({ theme }) => theme('spacing'),
+      opacity: barePercentages,
+      order: bareIntegers,
+      outlineColor: ({ theme }) => theme('colors'),
+      outlineOffset: barePixels,
+      outlineWidth: barePixels,
+      padding: ({ theme }) => theme('spacing'),
+      placeholderColor: ({ theme }) => theme('colors'),
+      placeholderOpacity: ({ theme }) => theme('opacity'),
+      ringColor: ({ theme }) => theme('colors'),
+      ringOffsetColor: ({ theme }) => theme('colors'),
+      ringOffsetWidth: barePixels,
+      ringOpacity: ({ theme }) => theme('opacity'),
+      ringWidth: barePixels,
+      rotate: bareDegrees,
+      saturate: barePercentages,
+      scale: barePercentages,
+      scrollMargin: ({ theme }) => theme('spacing'),
+      scrollPadding: ({ theme }) => theme('spacing'),
+      sepia: barePercentages,
+      size: ({ theme }) => theme('spacing'),
+      skew: bareDegrees,
+      space: ({ theme }) => theme('spacing'),
+      stroke: ({ theme }) => theme('colors'),
+      strokeWidth: barePixels,
+      textColor: ({ theme }) => theme('colors'),
+      textDecorationColor: ({ theme }) => theme('colors'),
+      textDecorationThickness: barePixels,
+      textIndent: ({ theme }) => theme('spacing'),
+      textOpacity: ({ theme }) => theme('opacity'),
+      textUnderlineOffset: barePixels,
+      transitionDelay: bareMilliseconds,
+      transitionDuration: {
+        DEFAULT: theme.get(['--default-transition-duration']) ?? null,
+        ...bareMilliseconds,
+      },
+      transitionTimingFunction: {
+        DEFAULT: theme.get(['--default-transition-timing-function']) ?? null,
+      },
+      translate: ({ theme }) => theme('spacing'),
+      width: ({ theme }) => theme('spacing'),
+      zIndex: bareIntegers,
+    },
+  }
+}

packages/tailwindcss/src/compat/config/deep-merge.ts

@@ -0,0 +1,37 @@
+export function isPlainObject<T>(value: T): value is T & Record<keyof T, unknown> {
+  if (Object.prototype.toString.call(value) !== '[object Object]') {
+    return false
+  }
+
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === null || Object.getPrototypeOf(prototype) === null
+}
+
+export function deepMerge<T extends object>(
+  target: T,
+  sources: (Partial<T> | null | undefined)[],
+  customizer: (a: any, b: any) => any,
+) {
+  type Key = keyof T
+  type Value = T[Key]
+
+  for (let source of sources) {
+    if (source === null || source === undefined) {
+      continue
+    }
+
+    for (let k of Reflect.ownKeys(source) as Key[]) {
+      let merged = customizer(target[k], source[k])
+
+      if (merged !== undefined) {
+        target[k] = merged
+      } else if (!isPlainObject(target[k]) || !isPlainObject(source[k])) {
+        target[k] = source[k] as Value
+      } else {
+        target[k] = deepMerge({}, [target[k], source[k]], customizer) as Value
+      }
+    }
+  }
+
+  return target
+}

packages/tailwindcss/src/compat/config/resolve-config.test.ts

@@ -0,0 +1,196 @@
+import { test } from 'vitest'
+import { buildDesignSystem } from '../../design-system'
+import { Theme } from '../../theme'
+import { resolveConfig } from './resolve-config'
+
+test('top level theme keys are replaced', ({ expect }) => {
+  let design = buildDesignSystem(new Theme())
+
+  let config = resolveConfig(design, [
+    {
+      theme: {
+        colors: {
+          red: 'red',
+        },
+
+        fontFamily: {
+          sans: 'SF Pro Display',
+        },
+      },
+    },
+    {
+      theme: {
+        colors: {
+          green: 'green',
+        },
+      },
+    },
+    {
+      theme: {
+        colors: {
+          blue: 'blue',
+        },
+      },
+    },
+  ])
+
+  expect(config).toMatchObject({
+    theme: {
+      colors: {
+        blue: 'blue',
+      },
+      fontFamily: {
+        sans: 'SF Pro Display',
+      },
+    },
+  })
+})
+
+test('theme can be extended', ({ expect }) => {
+  let design = buildDesignSystem(new Theme())
+
+  let config = resolveConfig(design, [
+    {
+      theme: {
+        colors: {
+          red: 'red',
+        },
+
+        fontFamily: {
+          sans: 'SF Pro Display',
+        },
+      },
+    },
+    {
+      theme: {
+        extend: {
+          colors: {
+            blue: 'blue',
+          },
+        },
+      },
+    },
+  ])
+
+  expect(config).toMatchObject({
+    theme: {
+      colors: {
+        red: 'red',
+        blue: 'blue',
+      },
+      fontFamily: {
+        sans: 'SF Pro Display',
+      },
+    },
+  })
+})
+
+test('theme keys can reference other theme keys using the theme function regardless of order', ({
+  expect,
+}) => {
+  let design = buildDesignSystem(new Theme())
+
+  let config = resolveConfig(design, [
+    {
+      theme: {
+        colors: {
+          red: 'red',
+        },
+        placeholderColor: {
+          green: 'green',
+        },
+      },
+    },
+    {
+      theme: {
+        extend: {
+          colors: ({ theme }) => ({
+            ...theme('placeholderColor'),
+            blue: 'blue',
+          }),
+        },
+      },
+    },
+    {
+      theme: {
+        extend: {
+          caretColor: ({ theme }) => theme('accentColor'),
+          accentColor: ({ theme }) => theme('backgroundColor'),
+          backgroundColor: ({ theme }) => theme('colors'),
+        },
+      },
+    },
+  ])
+
+  expect(config).toMatchObject({
+    theme: {
+      colors: {
+        red: 'red',
+        green: 'green',
+        blue: 'blue',
+      },
+      accentColor: {
+        red: 'red',
+        green: 'green',
+        blue: 'blue',
+      },
+      backgroundColor: {
+        red: 'red',
+        green: 'green',
+        blue: 'blue',
+      },
+      caretColor: {
+        red: 'red',
+        green: 'green',
+        blue: 'blue',
+      },
+    },
+  })
+})
+
+test('theme keys can read from the CSS theme', ({ expect }) => {
+  let theme = new Theme()
+  theme.add('--color-green', 'green')
+
+  let design = buildDesignSystem(theme)
+
+  let config = resolveConfig(design, [
+    {
+      theme: {
+        colors: ({ theme }) => ({
+          // Reads from the --color-* namespace
+          ...theme('color'),
+          red: 'red',
+        }),
+        accentColor: ({ theme }) => ({
+          // Reads from the --color-* namespace through `colors`
+          ...theme('colors'),
+        }),
+        placeholderColor: ({ theme }) => ({
+          // Reads from the --color-* namespace through `colors`
+          primary: theme('colors.green'),
+
+          // Reads from the --color-* namespace directly
+          secondary: theme('color.green'),
+        }),
+      },
+    },
+  ])
+
+  expect(config).toMatchObject({
+    theme: {
+      colors: {
+        red: 'red',
+        green: 'var(--color-green, green)',
+      },
+      accentColor: {
+        red: 'red',
+        green: 'var(--color-green, green)',
+      },
+      placeholderColor: {
+        primary: 'var(--color-green, green)',
+        secondary: 'var(--color-green, green)',
+      },
+    },
+  })
+})

packages/tailwindcss/src/compat/config/resolve-config.ts

@@ -0,0 +1,121 @@
+import type { DesignSystem } from '../../design-system'
+import { createThemeFn } from '../../theme-fn'
+import { deepMerge, isPlainObject } from './deep-merge'
+import {
+  type ResolvedConfig,
+  type ResolvedThemeValue,
+  type ThemeValue,
+  type UserConfig,
+} from './types'
+
+interface ResolutionContext {
+  design: DesignSystem
+  configs: UserConfig[]
+  theme: Record<string, ThemeValue>
+  extend: Record<string, ThemeValue[]>
+  result: ResolvedConfig
+}
+
+let minimal: ResolvedConfig = {
+  theme: {},
+}
+
+export function resolveConfig(design: DesignSystem, configs: UserConfig[]): ResolvedConfig {
+  let ctx: ResolutionContext = {
+    design,
+    configs,
+    theme: {},
+    extend: {},
+
+    // Start with a minimal valid, but empty config
+    result: structuredClone(minimal),
+  }
+
+  // Merge themes
+  mergeTheme(ctx)
+
+  return {
+    theme: ctx.theme as ResolvedConfig['theme'],
+  }
+}
+
+function mergeThemeExtension(
+  themeValue: ThemeValue | ThemeValue[],
+  extensionValue: ThemeValue | ThemeValue[],
+) {
+  // When we have an array of objects, we do want to merge it
+  if (Array.isArray(themeValue) && isPlainObject(themeValue[0])) {
+    return themeValue.concat(extensionValue)
+  }
+
+  // When the incoming value is an array, and the existing config is an object,
+  // prepend the existing object
+  if (
+    Array.isArray(extensionValue) &&
+    isPlainObject(extensionValue[0]) &&
+    isPlainObject(themeValue)
+  ) {
+    return [themeValue, ...extensionValue]
+  }
+
+  // Override arrays (for example for font-families, box-shadows, ...)
+  if (Array.isArray(extensionValue)) {
+    return extensionValue
+  }
+
+  // Execute default behaviour
+  return undefined
+}
+
+export interface PluginUtils {
+  theme(keypath: string, defaultValue?: any): any
+}
+
+function mergeTheme(ctx: ResolutionContext) {
+  let api: PluginUtils = {
+    theme: createThemeFn(ctx.design, () => ctx.theme, resolveValue),
+  }
+
+  function resolveValue(value: ThemeValue | null | undefined): ResolvedThemeValue {
+    if (typeof value === 'function') {
+      return value(api) ?? null
+    }
+
+    return value ?? null
+  }
+
+  for (let config of ctx.configs) {
+    let theme = config.theme ?? {}
+    let extend = theme.extend ?? {}
+
+    // Shallow merge themes so latest "group" wins
+    Object.assign(ctx.theme, theme)
+
+    // Collect extensions by key so each
+    // group can be lazily deep merged
+    for (let key in extend) {
+      ctx.extend[key] ??= []
+      ctx.extend[key].push(extend[key])
+    }
+  }
+
+  // Remove the `extend` key from the theme It's only used for merging and
+  // should not be present in the resolved theme
+  delete ctx.theme.extend
+
+  // Deep merge every `extend` key into the theme
+  for (let key in ctx.extend) {
+    let values = [ctx.theme[key], ...ctx.extend[key]]
+
+    ctx.theme[key] = () => {
+      let v = values.map(resolveValue)
+
+      let result = deepMerge({}, v, mergeThemeExtension)
+      return result
+    }
+  }
+
+  for (let key in ctx.theme) {
+    ctx.theme[key] = resolveValue(ctx.theme[key])
+  }
+}

packages/tailwindcss/src/compat/config/types.ts

@@ -0,0 +1,18 @@
+import type { PluginUtils } from './resolve-config'
+
+export type ResolvableTo<T> = T | ((utils: PluginUtils) => T)
+
+export interface UserConfig {
+  theme?: ThemeConfig
+}
+
+export type ThemeValue = ResolvableTo<Record<string, unknown>> | null | undefined
+export type ResolvedThemeValue = Record<string, unknown> | null
+
+export type ThemeConfig = Record<string, ThemeValue> & {
+  extend?: Record<string, ThemeValue>
+}
+
+export interface ResolvedConfig {
+  theme: Record<string, Record<string, unknown>>
+}

packages/tailwindcss/src/plugin-api.test.ts

@@ -0,0 +1,815 @@
+import { describe, test, vi } from 'vitest'
+import { compile } from '.'
+import plugin from './plugin'
+
+const css = String.raw
+
+describe('theme', async () => {
+  test('plugin theme can contain objects', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ addBase, theme }) {
+            addBase({
+              '@keyframes enter': theme('keyframes.enter'),
+              '@keyframes exit': theme('keyframes.exit'),
+            })
+          },
+          {
+            theme: {
+              extend: {
+                keyframes: {
+                  enter: {
+                    from: {
+                      opacity: 'var(--tw-enter-opacity, 1)',
+                      transform:
+                        'translate3d(var(--tw-enter-translate-x, 0), var(--tw-enter-translate-y, 0), 0) scale3d(var(--tw-enter-scale, 1), var(--tw-enter-scale, 1), var(--tw-enter-scale, 1)) rotate(var(--tw-enter-rotate, 0))',
+                    },
+                  },
+                  exit: {
+                    to: {
+                      opacity: 'var(--tw-exit-opacity, 1)',
+                      transform:
+                        'translate3d(var(--tw-exit-translate-x, 0), var(--tw-exit-translate-y, 0), 0) scale3d(var(--tw-exit-scale, 1), var(--tw-exit-scale, 1), var(--tw-exit-scale, 1)) rotate(var(--tw-exit-rotate, 0))',
+                    },
+                  },
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build([])).toMatchInlineSnapshot(`
+      "@layer base {
+        @keyframes enter {
+          from {
+            opacity: var(--tw-enter-opacity, 1);
+            transform: translate3d(var(--tw-enter-translate-x, 0), var(--tw-enter-translate-y, 0), 0) scale3d(var(--tw-enter-scale, 1), var(--tw-enter-scale, 1), var(--tw-enter-scale, 1)) rotate(var(--tw-enter-rotate, 0));
+          }
+        }
+        @keyframes exit {
+          to {
+            opacity: var(--tw-exit-opacity, 1);
+            transform: translate3d(var(--tw-exit-translate-x, 0), var(--tw-exit-translate-y, 0), 0) scale3d(var(--tw-exit-scale, 1), var(--tw-exit-scale, 1), var(--tw-exit-scale, 1)) rotate(var(--tw-exit-rotate, 0));
+          }
+        }
+      }
+      "
+    `)
+  })
+
+  test('plugin theme can extend colors', async ({ expect }) => {
+    let input = css`
+      @theme reference {
+        --color-red-500: #ef4444;
+      }
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                scrollbar: (value) => ({ 'scrollbar-color': value }),
+              },
+              {
+                values: theme('colors'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                colors: {
+                  'russet-700': '#7a4724',
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['scrollbar-red-500', 'scrollbar-russet-700'])).toMatchInlineSnapshot(`
+      ".scrollbar-red-500 {
+        scrollbar-color: var(--color-red-500, #ef4444);
+      }
+      .scrollbar-russet-700 {
+        scrollbar-color: #7a4724;
+      }
+      "
+    `)
+  })
+
+  test('plugin theme values can reference legacy theme keys that have been replaced with bare value support', async ({
+    expect,
+  }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                'animate-duration': (value) => ({ 'animation-duration': value }),
+              },
+              {
+                values: theme('animationDuration'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                animationDuration: ({ theme }: { theme: (path: string) => any }) => {
+                  return {
+                    ...theme('transitionDuration'),
+                  }
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['animate-duration-316'])).toMatchInlineSnapshot(`
+      ".animate-duration-316 {
+        animation-duration: 316ms;
+      }
+      "
+    `)
+  })
+
+  test('plugin theme values that support bare values are merged with other values for that theme key', async ({
+    expect,
+  }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                'animate-duration': (value) => ({ 'animation-duration': value }),
+              },
+              {
+                values: theme('animationDuration'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                transitionDuration: {
+                  slow: '800ms',
+                },
+
+                animationDuration: ({ theme }: { theme: (path: string) => any }) => ({
+                  ...theme('transitionDuration'),
+                }),
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['animate-duration-316', 'animate-duration-slow']))
+      .toMatchInlineSnapshot(`
+      ".animate-duration-316 {
+        animation-duration: 316ms;
+      }
+      .animate-duration-slow {
+        animation-duration: 800ms;
+      }
+      "
+    `)
+  })
+
+  test('theme value functions are resolved correctly regardless of order', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                'animate-delay': (value) => ({ 'animation-delay': value }),
+              },
+              {
+                values: theme('animationDelay'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                animationDuration: ({ theme }: { theme: (path: string) => any }) => ({
+                  ...theme('transitionDuration'),
+                }),
+
+                animationDelay: ({ theme }: { theme: (path: string) => any }) => ({
+                  ...theme('animationDuration'),
+                }),
+
+                transitionDuration: {
+                  slow: '800ms',
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['animate-delay-316', 'animate-delay-slow'])).toMatchInlineSnapshot(`
+      ".animate-delay-316 {
+        animation-delay: 316ms;
+      }
+      .animate-delay-slow {
+        animation-delay: 800ms;
+      }
+      "
+    `)
+  })
+
+  test('plugins can override the default key', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                'animate-duration': (value) => ({ 'animation-delay': value }),
+              },
+              {
+                values: theme('transitionDuration'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                transitionDuration: {
+                  DEFAULT: '1500ms',
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['animate-duration'])).toMatchInlineSnapshot(`
+      ".animate-duration {
+        animation-delay: 1500ms;
+      }
+      "
+    `)
+  })
+
+  test('plugins can read CSS theme keys using the old theme key notation', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+      @theme reference {
+        --animation: pulse 1s linear infinite;
+        --animation-spin: spin 1s linear infinite;
+      }
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(function ({ matchUtilities, theme }) {
+          matchUtilities(
+            {
+              animation: (value) => ({ animation: value }),
+            },
+            {
+              values: theme('animation'),
+            },
+          )
+
+          matchUtilities(
+            {
+              animation2: (value) => ({ animation: value }),
+            },
+            {
+              values: {
+                DEFAULT: theme('animation.DEFAULT'),
+                twist: theme('animation.spin'),
+              },
+            },
+          )
+        })
+      },
+    })
+
+    expect(compiler.build(['animation-spin', 'animation', 'animation2', 'animation2-twist']))
+      .toMatchInlineSnapshot(`
+        ".animation {
+          animation: var(--animation, pulse 1s linear infinite);
+        }
+        .animation-spin {
+          animation: var(--animation-spin, spin 1s linear infinite);
+        }
+        .animation2 {
+          animation: var(--animation, pulse 1s linear infinite);
+        }
+        .animation2-twist {
+          animation: var(--animation-spin, spin 1s linear infinite);
+        }
+        "
+      `)
+  })
+
+  test('CSS theme values are mreged with JS theme values', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+      @theme reference {
+        --animation: pulse 1s linear infinite;
+        --animation-spin: spin 1s linear infinite;
+      }
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                animation: (value) => ({ '--animation': value }),
+              },
+              {
+                values: theme('animation'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                animation: {
+                  bounce: 'bounce 1s linear infinite',
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['animation', 'animation-spin', 'animation-bounce']))
+      .toMatchInlineSnapshot(`
+        ".animation {
+          --animation: var(--animation, pulse 1s linear infinite);
+        }
+        .animation-bounce {
+          --animation: bounce 1s linear infinite;
+        }
+        .animation-spin {
+          --animation: var(--animation-spin, spin 1s linear infinite);
+        }
+        "
+      `)
+  })
+
+  test('CSS theme defaults take precedence over JS theme defaults', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+      @theme reference {
+        --animation: pulse 1s linear infinite;
+        --animation-spin: spin 1s linear infinite;
+      }
+    `
+
+    let compiler = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ matchUtilities, theme }) {
+            matchUtilities(
+              {
+                animation: (value) => ({ '--animation': value }),
+              },
+              {
+                values: theme('animation'),
+              },
+            )
+          },
+          {
+            theme: {
+              extend: {
+                animation: {
+                  DEFAULT: 'twist 1s linear infinite',
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(compiler.build(['animation'])).toMatchInlineSnapshot(`
+      ".animation {
+        --animation: var(--animation, pulse 1s linear infinite);
+      }
+      "
+    `)
+  })
+
+  test('CSS theme values take precedence even over non-object JS values', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+      @theme reference {
+        --animation-simple-spin: spin 1s linear infinite;
+        --animation-simple-bounce: bounce 1s linear infinite;
+      }
+    `
+
+    let fn = vi.fn()
+
+    await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          function ({ theme }) {
+            fn(theme('animation.simple'))
+          },
+          {
+            theme: {
+              extend: {
+                animation: {
+                  simple: 'simple 1s linear',
+                },
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(fn).toHaveBeenCalledWith({
+      spin: 'var(--animation-simple-spin, spin 1s linear infinite)',
+      bounce: 'var(--animation-simple-bounce, bounce 1s linear infinite)',
+    })
+  })
+
+  test('all necessary theme keys support bare values', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let { build } = await compile(input, {
+      loadPlugin: async () => {
+        return plugin(function ({ matchUtilities, theme }) {
+          function utility(name: string, themeKey: string) {
+            matchUtilities(
+              { [name]: (value) => ({ '--value': value }) },
+              { values: theme(themeKey) },
+            )
+          }
+
+          utility('my-aspect', 'aspectRatio')
+          utility('my-backdrop-brightness', 'backdropBrightness')
+          utility('my-backdrop-contrast', 'backdropContrast')
+          utility('my-backdrop-grayscale', 'backdropGrayscale')
+          utility('my-backdrop-hue-rotate', 'backdropHueRotate')
+          utility('my-backdrop-invert', 'backdropInvert')
+          utility('my-backdrop-opacity', 'backdropOpacity')
+          utility('my-backdrop-saturate', 'backdropSaturate')
+          utility('my-backdrop-sepia', 'backdropSepia')
+          utility('my-border', 'border')
+          utility('my-brightness', 'brightness')
+          utility('my-columns', 'columns')
+          utility('my-contrast', 'contrast')
+          utility('my-divide-width', 'divideWidth')
+          utility('my-flex-grow', 'flexGrow')
+          utility('my-flex-shrink', 'flexShrink')
+          utility('my-gradient-color-stop-positions', 'gradientColorStopPositions')
+          utility('my-grayscale', 'grayscale')
+          utility('my-grid-row-end', 'gridRowEnd')
+          utility('my-grid-row-start', 'gridRowStart')
+          utility('my-grid-template-columns', 'gridTemplateColumns')
+          utility('my-grid-template-rows', 'gridTemplateRows')
+          utility('my-hue-rotate', 'hueRotate')
+          utility('my-invert', 'invert')
+          utility('my-line-clamp', 'lineClamp')
+          utility('my-opacity', 'opacity')
+          utility('my-order', 'order')
+          utility('my-outline-offset', 'outlineOffset')
+          utility('my-outline-width', 'outlineWidth')
+          utility('my-ring-offset-width', 'ringOffsetWidth')
+          utility('my-ring-width', 'ringWidth')
+          utility('my-rotate', 'rotate')
+          utility('my-saturate', 'saturate')
+          utility('my-scale', 'scale')
+          utility('my-sepia', 'sepia')
+          utility('my-skew', 'skew')
+          utility('my-stroke-width', 'strokeWidth')
+          utility('my-text-decoration-thickness', 'textDecorationThickness')
+          utility('my-text-underline-offset', 'textUnderlineOffset')
+          utility('my-transition-delay', 'transitionDelay')
+          utility('my-transition-duration', 'transitionDuration')
+          utility('my-z-index', 'zIndex')
+        })
+      },
+    })
+
+    let output = build([
+      'my-aspect-2/5',
+      'my-backdrop-brightness-1',
+      'my-backdrop-contrast-1',
+      'my-backdrop-grayscale-1',
+      'my-backdrop-hue-rotate-1',
+      'my-backdrop-invert-1',
+      'my-backdrop-opacity-1',
+      'my-backdrop-saturate-1',
+      'my-backdrop-sepia-1',
+      'my-border-1',
+      'my-brightness-1',
+      'my-columns-1',
+      'my-contrast-1',
+      'my-divide-width-1',
+      'my-flex-grow-1',
+      'my-flex-shrink-1',
+      'my-gradient-color-stop-positions-1',
+      'my-grayscale-1',
+      'my-grid-row-end-1',
+      'my-grid-row-start-1',
+      'my-grid-template-columns-1',
+      'my-grid-template-rows-1',
+      'my-hue-rotate-1',
+      'my-invert-1',
+      'my-line-clamp-1',
+      'my-opacity-1',
+      'my-order-1',
+      'my-outline-offset-1',
+      'my-outline-width-1',
+      'my-ring-offset-width-1',
+      'my-ring-width-1',
+      'my-rotate-1',
+      'my-saturate-1',
+      'my-scale-1',
+      'my-sepia-1',
+      'my-skew-1',
+      'my-stroke-width-1',
+      'my-text-decoration-thickness-1',
+      'my-text-underline-offset-1',
+      'my-transition-delay-1',
+      'my-transition-duration-1',
+      'my-z-index-1',
+    ])
+
+    expect(output).toMatchInlineSnapshot(`
+      ".my-aspect-2\\/5 {
+        --value: 2/5;
+      }
+      .my-backdrop-brightness-1 {
+        --value: 1%;
+      }
+      .my-backdrop-contrast-1 {
+        --value: 1%;
+      }
+      .my-backdrop-grayscale-1 {
+        --value: 1%;
+      }
+      .my-backdrop-hue-rotate-1 {
+        --value: 1deg;
+      }
+      .my-backdrop-invert-1 {
+        --value: 1%;
+      }
+      .my-backdrop-opacity-1 {
+        --value: 1%;
+      }
+      .my-backdrop-saturate-1 {
+        --value: 1%;
+      }
+      .my-backdrop-sepia-1 {
+        --value: 1%;
+      }
+      .my-border-1 {
+        --value: 1px;
+      }
+      .my-brightness-1 {
+        --value: 1%;
+      }
+      .my-columns-1 {
+        --value: 1;
+      }
+      .my-contrast-1 {
+        --value: 1%;
+      }
+      .my-divide-width-1 {
+        --value: 1px;
+      }
+      .my-flex-grow-1 {
+        --value: 1;
+      }
+      .my-flex-shrink-1 {
+        --value: 1;
+      }
+      .my-gradient-color-stop-positions-1 {
+        --value: 1%;
+      }
+      .my-grayscale-1 {
+        --value: 1%;
+      }
+      .my-grid-row-end-1 {
+        --value: 1;
+      }
+      .my-grid-row-start-1 {
+        --value: 1;
+      }
+      .my-grid-template-columns-1 {
+        --value: repeat(1, minmax(0, 1fr));
+      }
+      .my-grid-template-rows-1 {
+        --value: repeat(1, minmax(0, 1fr));
+      }
+      .my-hue-rotate-1 {
+        --value: 1deg;
+      }
+      .my-invert-1 {
+        --value: 1%;
+      }
+      .my-line-clamp-1 {
+        --value: 1;
+      }
+      .my-opacity-1 {
+        --value: 1%;
+      }
+      .my-order-1 {
+        --value: 1;
+      }
+      .my-outline-offset-1 {
+        --value: 1px;
+      }
+      .my-outline-width-1 {
+        --value: 1px;
+      }
+      .my-ring-offset-width-1 {
+        --value: 1px;
+      }
+      .my-ring-width-1 {
+        --value: 1px;
+      }
+      .my-rotate-1 {
+        --value: 1deg;
+      }
+      .my-saturate-1 {
+        --value: 1%;
+      }
+      .my-scale-1 {
+        --value: 1%;
+      }
+      .my-sepia-1 {
+        --value: 1%;
+      }
+      .my-skew-1 {
+        --value: 1deg;
+      }
+      .my-stroke-width-1 {
+        --value: 1px;
+      }
+      .my-text-decoration-thickness-1 {
+        --value: 1px;
+      }
+      .my-text-underline-offset-1 {
+        --value: 1px;
+      }
+      .my-transition-delay-1 {
+        --value: 1ms;
+      }
+      .my-transition-duration-1 {
+        --value: 1ms;
+      }
+      .my-z-index-1 {
+        --value: 1;
+      }
+      "
+    `)
+  })
+
+  test('theme keys can derive from other theme keys', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+      @theme {
+        --color-primary: red;
+        --color-secondary: blue;
+      }
+    `
+
+    let fn = vi.fn()
+
+    await compile(input, {
+      loadPlugin: async () => {
+        return plugin(
+          ({ theme }) => {
+            // The compatability config specifies that `accentColor` spreads in `colors`
+            fn(theme('accentColor.primary'))
+
+            // This should even work for theme keys specified in plugin configs
+            fn(theme('myAccentColor.secondary'))
+          },
+          {
+            theme: {
+              extend: {
+                myAccentColor: ({ theme }) => theme('accentColor'),
+              },
+            },
+          },
+        )
+      },
+    })
+
+    expect(fn).toHaveBeenCalledWith('var(--color-primary, red)')
+    expect(fn).toHaveBeenCalledWith('var(--color-secondary, blue)')
+  })
+
+  test('nested theme key lookups work even for flattened keys', async ({ expect }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+      @theme {
+        --color-red-100: red;
+        --color-red-200: orangered;
+        --color-red-300: darkred;
+      }
+    `
+
+    let fn = vi.fn()
+
+    await compile(input, {
+      loadPlugin: async () => {
+        return plugin(({ theme }) => {
+          fn(theme('color.red.100'))
+          fn(theme('colors.red.200'))
+          fn(theme('backgroundColor.red.300'))
+        })
+      },
+    })
+
+    expect(fn).toHaveBeenCalledWith('var(--color-red-100, red)')
+    expect(fn).toHaveBeenCalledWith('var(--color-red-200, orangered)')
+    expect(fn).toHaveBeenCalledWith('var(--color-red-300, darkred)')
+  })
+
+  test('keys that do not exist return the default value (or undefined if none)', async ({
+    expect,
+  }) => {
+    let input = css`
+      @tailwind utilities;
+      @plugin "my-plugin";
+    `
+
+    let fn = vi.fn()
+
+    await compile(input, {
+      loadPlugin: async () => {
+        return plugin(({ theme }) => {
+          fn(theme('i.do.not.exist'))
+          fn(theme('color'))
+          fn(theme('color', 'magenta'))
+          fn(theme('colors'))
+        })
+      },
+    })
+
+    expect(fn).toHaveBeenCalledWith(undefined) // Not present in CSS or resolved config
+    expect(fn).toHaveBeenCalledWith(undefined) // Not present in CSS or resolved config
+    expect(fn).toHaveBeenCalledWith('magenta') // Not present in CSS or resolved config
+    expect(fn).toHaveBeenCalledWith({}) // Present in the resolved config
+  })
+})

packages/tailwindcss/src/plugin-api.ts

@@ -1,13 +1,17 @@
 import { substituteAtApply } from './apply'
-import { objectToAst, rule, type AstNode, type CssInJs } from './ast'
+import { decl, rule, type AstNode } from './ast'
+import type { NamedUtilityValue } from './candidate'
+import { createCompatConfig } from './compat/config/create-compat-config'
+import { resolveConfig } from './compat/config/resolve-config'
+import type { UserConfig } from './compat/config/types'
 import type { DesignSystem } from './design-system'
+import { createThemeFn } from './theme-fn'
 import { withAlpha, withNegative } from './utilities'
 import { inferDataType } from './utils/infer-data-type'
 
-export type Config = Record<string, any>
-
+export type Config = UserConfig
 export type PluginFn = (api: PluginAPI) => void
-export type PluginWithConfig = { handler: PluginFn; config?: Partial<Config> }
+export type PluginWithConfig = { handler: PluginFn; config?: UserConfig }
 export type PluginWithOptions<T> = {
   (options?: T): PluginWithConfig
   __isOptionsFunction: true
@@ -24,15 +28,22 @@ export type PluginAPI = {
     options?: Partial<{
       type: string | string[]
       supportsNegativeValues: boolean
-      values: Record<string, string>
+      values: Record<string, string> & {
+        __BARE_VALUE__?: (value: NamedUtilityValue) => string | undefined
+      }
       modifiers: 'any' | Record<string, string>
     }>,
   ): void
+  theme(path: string, defaultValue?: any): any
 }
 
 const IS_VALID_UTILITY_NAME = /^[a-z][a-zA-Z0-9/%._-]*$/
 
-export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): PluginAPI {
+function buildPluginApi(
+  designSystem: DesignSystem,
+  ast: AstNode[],
+  resolvedConfig: { theme?: Record<string, any> },
+): PluginAPI {
   return {
     addBase(css) {
       ast.push(rule('@layer base', objectToAst(css)))
@@ -61,6 +72,11 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug
 
     addUtilities(utilities) {
       for (let [name, css] of Object.entries(utilities)) {
+        if (name.startsWith('@keyframes ')) {
+          ast.push(rule(name, objectToAst(css)))
+          continue
+        }
+
         if (name[0] !== '.' || !IS_VALID_UTILITY_NAME.test(name.slice(1))) {
           throw new Error(
             `\`addUtilities({ '${name}' : … })\` defines an invalid utility selector. Utilities must be a single class name and start with a lowercase letter, eg. \`.scrollbar-none\`.`,
@@ -120,7 +136,8 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug
           let isColor = types.includes('color')
 
           // Resolve the candidate value
-          let value: string | null
+          let value: string | null = null
+          let isFraction = false
 
           {
             let values = options?.values ?? {}
@@ -128,24 +145,30 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug
             if (isColor) {
               // Color utilities implicitly support `inherit`, `transparent`, and `currentColor`
               // for backwards compatibility but still allow them to be overridden
-              values = {
-                inherit: 'inherit',
-                transparent: 'transparent',
-                current: 'currentColor',
-                ...values,
-              }
+              values = Object.assign(
+                {
+                  inherit: 'inherit',
+                  transparent: 'transparent',
+                  current: 'currentColor',
+                },
+                values,
+              )
             }
 
             if (!candidate.value) {
               value = values.DEFAULT ?? null
             } else if (candidate.value.kind === 'arbitrary') {
               value = candidate.value.value
-            } else {
-              value = values[candidate.value.value] ?? null
+            } else if (values[candidate.value.value]) {
+              value = values[candidate.value.value]
+            } else if (values.__BARE_VALUE__) {
+              value = values.__BARE_VALUE__(candidate.value) ?? null
+
+              isFraction = (candidate.value.fraction !== null && value?.includes('/')) ?? false
             }
           }
 
-          if (!value) return
+          if (value === null) return
 
           // Resolve the modifier value
           let modifier: string | null
@@ -167,12 +190,12 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug
           }
 
           // A modifier was provided but is invalid
-          if (candidate.modifier && !modifier) {
+          if (candidate.modifier && modifier === null && !isFraction) {
             // For arbitrary values, return `null` to avoid falling through to the next utility
             return candidate.value?.kind === 'arbitrary' ? null : undefined
           }
 
-          if (isColor && modifier) {
+          if (isColor && modifier !== null) {
             value = withAlpha(value, modifier)
           }
 
@@ -186,27 +209,70 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug
         })
       }
     },
+
+    theme: createThemeFn(
+      designSystem,
+      () => resolvedConfig.theme ?? {},
+      (value) => value,
+    ),
   }
 }
 
+export type CssInJs = { [key: string]: string | CssInJs }
+
+function objectToAst(obj: CssInJs): AstNode[] {
+  let ast: AstNode[] = []
+
+  for (let [name, value] of Object.entries(obj)) {
+    if (typeof value !== 'object') {
+      if (!name.startsWith('--') && value === '@slot') {
+        ast.push(rule(name, [rule('@slot', [])]))
+      } else {
+        // Convert camelCase to kebab-case:
+        // https://github.com/postcss/postcss-js/blob/b3db658b932b42f6ac14ca0b1d50f50c4569805b/parser.js#L30-L35
+        name = name.replace(/([A-Z])/g, '-$1').toLowerCase()
+
+        ast.push(decl(name, String(value)))
+      }
+    } else if (value !== null) {
+      ast.push(rule(name, objectToAst(value)))
+    }
+  }
+
+  return ast
+}
+
 export function registerPlugins(plugins: Plugin[], designSystem: DesignSystem, ast: AstNode[]) {
-  let pluginApi = buildPluginApi(designSystem, ast)
+  let pluginObjects = []
 
   for (let plugin of plugins) {
     if ('__isOptionsFunction' in plugin) {
       // Happens with `plugin.withOptions()` when no options were passed:
       // e.g. `require("my-plugin")` instead of `require("my-plugin")(options)`
-      plugin().handler(pluginApi)
+      pluginObjects.push(plugin())
     } else if ('handler' in plugin) {
       // Happens with `plugin(…)`:
       // e.g. `require("my-plugin")`
       //
       // or with `plugin.withOptions()` when the user passed options:
       // e.g. `require("my-plugin")(options)`
-      plugin.handler(pluginApi)
+      pluginObjects.push(plugin)
     } else {
       // Just a plain function without using the plugin(…) API
-      plugin(pluginApi)
+      pluginObjects.push({ handler: plugin, config: {} as UserConfig })
     }
   }
+
+  // Now merge all the configs and make all that crap work
+  let resolvedConfig = resolveConfig(designSystem, [
+    createCompatConfig(designSystem.theme),
+    ...pluginObjects.map(({ config }) => config ?? {}),
+  ])
+
+  let pluginApi = buildPluginApi(designSystem, ast, resolvedConfig)
+
+  // Loop over the handlers and run them all with the resolved config + CSS theme probably somehow
+  for (let { handler } of pluginObjects) {
+    handler(pluginApi)
+  }
 }

packages/tailwindcss/src/theme-fn.ts

@@ -0,0 +1,156 @@
+import { deepMerge } from './compat/config/deep-merge'
+import type { UserConfig } from './compat/config/types'
+import type { DesignSystem } from './design-system'
+import type { Theme } from './theme'
+import { DefaultMap } from './utils/default-map'
+import { toKeyPath } from './utils/to-key-path'
+
+export function createThemeFn(
+  designSystem: DesignSystem,
+  configTheme: () => UserConfig['theme'],
+  resolveValue: (value: any) => any,
+) {
+  return function theme(path: string, defaultValue?: any) {
+    let keypath = toKeyPath(path)
+    let cssValue = readFromCss(designSystem.theme, keypath)
+
+    if (typeof cssValue !== 'object') {
+      return cssValue
+    }
+
+    let configValue = resolveValue(get(configTheme() ?? {}, keypath) ?? null)
+
+    if (configValue !== null && typeof configValue === 'object') {
+      return deepMerge({}, [configValue, cssValue], (_, b) => b)
+    }
+
+    // Values from CSS take precedence over values from the config
+    return cssValue ?? configValue ?? defaultValue
+  }
+}
+
+function readFromCss(theme: Theme, path: string[]) {
+  type ThemeValue =
+    // A normal string value
+    | string
+
+    // A nested tuple with additional data
+    | [main: string, extra: Record<string, string>]
+
+  let themeKey = path
+    // Escape dots used inside square brackets
+    // Replace camelCase with dashes
+    .map((part) =>
+      part.replaceAll('.', '_').replace(/([a-z])([A-Z])/g, (_, a, b) => `${a}-${b.toLowerCase()}`),
+    )
+
+    // Remove the `DEFAULT` key at the end of a path
+    // We're reading from CSS anyway so it'll be a string
+    .filter((part, index) => part !== 'DEFAULT' || index !== path.length - 1)
+    .join('-')
+
+  let map = new Map<string | null, ThemeValue>()
+  let nested = new DefaultMap<string | null, Map<string, string>>(() => new Map())
+
+  let ns = theme.resolveNamespace(`--${themeKey}` as any)
+
+  if (ns.size === 0) {
+    return null
+  }
+
+  for (let [key, value] of ns) {
+    // Non-nested values can be set directly
+    if (!key || !key.includes('--')) {
+      map.set(key, value)
+      continue
+    }
+
+    // Nested values are stored separately
+    let nestedIndex = key.indexOf('--')
+
+    let mainKey = key.slice(0, nestedIndex)
+    let nestedKey = key.slice(nestedIndex + 2)
+
+    // Make `nestedKey` camel case:
+    nestedKey = nestedKey.replace(/-([a-z])/g, (_, a) => a.toUpperCase())
+
+    nested.get(mainKey === '' ? null : mainKey).set(nestedKey, value)
+  }
+
+  for (let [key, extra] of nested) {
+    let value = map.get(key)
+    if (typeof value !== 'string') continue
+
+    map.set(key, [value, Object.fromEntries(extra)])
+  }
+
+  // We have to turn the map into object-like structure for v3 compatibility
+  let obj = {}
+  let useNestedObjects = false // paths.some((path) => nestedKeys.has(path))
+
+  for (let [key, value] of map) {
+    key = key ?? 'DEFAULT'
+
+    let path: string[] = []
+    let splitIndex = key.indexOf('-')
+
+    if (useNestedObjects && splitIndex !== -1) {
+      path.push(key.slice(0, splitIndex))
+      path.push(key.slice(splitIndex + 1))
+    } else {
+      path.push(key)
+    }
+
+    set(obj, path, value)
+  }
+
+  if ('DEFAULT' in obj) {
+    // The request looked like `theme('animation.DEFAULT')` and was turned into
+    // a lookup for `--animation-*` and we should extract the value for the
+    // `DEFAULT` key from the list of possible values
+    if (path[path.length - 1] === 'DEFAULT') {
+      return obj.DEFAULT
+    }
+
+    // The request looked like `theme('animation.spin')` and was turned into a
+    // lookup for `--animation-spin-*` which had only one entry which means it
+    // should be returned directly
+    if (Object.keys(obj).length === 1) {
+      return obj.DEFAULT
+    }
+  }
+
+  return obj
+}
+
+function get(obj: any, path: string[]) {
+  for (let i = 0; i < path.length; ++i) {
+    let key = path[i]
+
+    // The key does not exist so concatenate it with the next key
+    if (obj[key] === undefined) {
+      if (path[i + 1] === undefined) {
+        return undefined
+      }
+
+      path[i + 1] = `${key}-${path[i + 1]}`
+      continue
+    }
+
+    obj = obj[key]
+  }
+
+  return obj
+}
+
+function set(obj: any, path: string[], value: any) {
+  for (let key of path.slice(0, -1)) {
+    if (obj[key] === undefined) {
+      obj[key] = {}
+    }
+
+    obj = obj[key]
+  }
+
+  obj[path[path.length - 1]] = value
+}

packages/tailwindcss/src/theme.ts

@@ -144,6 +144,21 @@ export class Theme {
 
     return values
   }
+
+  resolveNamespace(namespace: string) {
+    let values = new Map<string | null, string>()
+    let prefix = `${namespace}-`
+
+    for (let [key, value] of this.values) {
+      if (key === namespace) {
+        values.set(null, value.isInline ? value.value : this.#var(key)!)
+      } else if (key.startsWith(prefix)) {
+        values.set(key.slice(prefix.length), value.isInline ? value.value : this.#var(key)!)
+      }
+    }
+
+    return values
+  }
 }
 
 export type ThemeKey =
@@ -255,6 +270,7 @@ export type ThemeKey =
   | '--translate'
   | '--width'
   | '--z-index'
+  | `--default-${string}`
 
 export type ColorThemeKey =
   | '--color'

packages/tailwindcss/src/utilities.test.ts

@@ -16092,7 +16092,7 @@ describe('legacy: matchUtilities', () => {
     `)
   })
 
-  test('functional utilities with type: color and explicit modifiers', async () => {
+  test('functional utilities with explicit modifiers', async () => {
     async function run(candidates: string[]) {
       let compiled = await compile(
         css`

packages/tailwindcss/src/utils/to-key-path.bench.ts

@@ -0,0 +1,12 @@
+import { bench } from 'vitest'
+import { toKeyPath } from './to-key-path'
+
+bench('toKeyPath', () => {
+  toKeyPath('fontSize.xs')
+  toKeyPath('fontSize.xs[1].lineHeight')
+  toKeyPath('colors.red.500')
+  toKeyPath('colors[red].500')
+  toKeyPath('colors[red].[500]')
+  toKeyPath('colors[red]500')
+  toKeyPath('colors[red][500]')
+})

packages/tailwindcss/src/utils/to-key-path.test.ts

@@ -0,0 +1,13 @@
+import { expect, it } from 'vitest'
+import { toKeyPath } from './to-key-path'
+
+it('can convert key paths to arrays', () => {
+  expect(toKeyPath('fontSize.xs')).toEqual(['fontSize', 'xs'])
+  expect(toKeyPath('fontSize.xs[1].lineHeight')).toEqual(['fontSize', 'xs', '1', 'lineHeight'])
+  expect(toKeyPath('colors.red.500')).toEqual(['colors', 'red', '500'])
+  expect(toKeyPath('colors[red].500')).toEqual(['colors', 'red', '500'])
+  expect(toKeyPath('colors[red].[500]')).toEqual(['colors', 'red', '500'])
+  expect(toKeyPath('colors[red]500')).toEqual(['colors', 'red', '500'])
+  expect(toKeyPath('colors[red][500]')).toEqual(['colors', 'red', '500'])
+  expect(toKeyPath('colors[red]500[50]5')).toEqual(['colors', 'red', '500', '50', '5'])
+})

packages/tailwindcss/src/utils/to-key-path.ts

@@ -0,0 +1,54 @@
+import { segment } from './segment'
+
+/**
+ * Parse a path string into an array of path segments
+ *
+ * Square bracket notation `a[b]` may be used to "escape" dots that would
+ * otherwise be interpreted as path separators.
+ *
+ * Example:
+ * a -> ['a']
+ * a.b.c -> ['a', 'b', 'c']
+ * a[b].c -> ['a', 'b', 'c']
+ * a[b.c].e.f -> ['a', 'b.c', 'e', 'f']
+ * a[b][c][d] -> ['a', 'b', 'c', 'd']
+ *
+ * @param {string} path
+ **/
+export function toKeyPath(path: string) {
+  let keypath: string[] = []
+
+  for (let part of segment(path, '.')) {
+    if (!part.includes('[')) {
+      keypath.push(part)
+      continue
+    }
+
+    let currentIndex = 0
+
+    while (true) {
+      let bracketL = part.indexOf('[', currentIndex)
+      let bracketR = part.indexOf(']', bracketL)
+
+      if (bracketL === -1 || bracketR === -1) {
+        break
+      }
+
+      // Add the part before the bracket as a key
+      if (bracketL > currentIndex) {
+        keypath.push(part.slice(currentIndex, bracketL))
+      }
+
+      // Add the part inside the bracket as a key
+      keypath.push(part.slice(bracketL + 1, bracketR))
+      currentIndex = bracketR + 1
+    }
+
+    // Add the part after the last bracket as a key
+    if (currentIndex <= part.length - 1) {
+      keypath.push(part.slice(currentIndex))
+    }
+  }
+
+  return keypath
+}