Rename --width-* namespace to --container-* (#14898)

This PR renames all of the `--width-*` variables to `--container-*` to
better communicate the purpose of these tokens as layout container
sizes. These are the values that were historically stored under
`maxWidth` in the v3 and earlier eras, and were also re-used by the
container queries plugin.

The name `--container-*` feels like a better match alongside the
`--breakpoint-*` namespace and since these both serve that same sort of
purpose it makes sense to me that the name should be optimized for
feeling "right" in that context.

I like that this also sort of advertises Tailwind's support for
container queries directly in the CSS variables themselves, and helps
people understand what these are really intended to be used for.

---------

Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>

CHANGELOG.md

@@ -44,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Remove `var(…)` fallbacks from theme values in utilities ([#14881](https://github.com/tailwindlabs/tailwindcss/pull/14881))
 - Remove static `font-weight` utilities and add `--font-weight-*` values to the default theme ([#14883](https://github.com/tailwindlabs/tailwindcss/pull/14883))
 - Rename `--transition-timing-function-*` variables to `--ease-*` ([#14886](https://github.com/tailwindlabs/tailwindcss/pull/14886))
+- Rename `--width-*` variables to `--container-*` ([#14898](https://github.com/tailwindlabs/tailwindcss/pull/14898))
 
 ## [4.0.0-alpha.31] - 2024-10-29
 

packages/@tailwindcss-postcss/src/__snapshots__/index.test.ts.snap

@@ -297,20 +297,20 @@ exports[`\`@import 'tailwindcss'\` is replaced with the generated CSS 1`] = `
     --drop-shadow-xl: 0 20px 13px #00000008, 0 8px 5px #00000014;
     --drop-shadow-2xl: 0 25px 25px #00000026;
     --spacing: .25rem;
-    --width-3xs: 16rem;
-    --width-2xs: 18rem;
-    --width-xs: 20rem;
-    --width-sm: 24rem;
-    --width-md: 28rem;
-    --width-lg: 32rem;
-    --width-xl: 36rem;
-    --width-2xl: 42rem;
-    --width-3xl: 48rem;
-    --width-4xl: 56rem;
-    --width-5xl: 64rem;
-    --width-6xl: 72rem;
-    --width-7xl: 80rem;
-    --width-prose: 65ch;
+    --container-3xs: 16rem;
+    --container-2xs: 18rem;
+    --container-xs: 20rem;
+    --container-sm: 24rem;
+    --container-md: 28rem;
+    --container-lg: 32rem;
+    --container-xl: 36rem;
+    --container-2xl: 42rem;
+    --container-3xl: 48rem;
+    --container-4xl: 56rem;
+    --container-5xl: 64rem;
+    --container-6xl: 72rem;
+    --container-7xl: 80rem;
+    --container-prose: 65ch;
     --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
     --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
     --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;

packages/@tailwindcss-upgrade/src/template/codemods/theme-to-var.test.ts

@@ -92,8 +92,9 @@ test.each([
   // `theme(…)` calls valid in v3, but not in v4 should still be converted.
   ['[--foo:theme(transitionDuration.500)]', '[--foo:theme(transitionDuration.500)]'],
 
-  // `screens` values
+  // Renamed theme keys
   ['max-w-[theme(screens.md)]', 'max-w-[var(--breakpoint-md)]'],
+  ['w-[theme(maxWidth.md)]', 'w-[var(--container-md)]'],
 
   // Invalid cases
   ['[--foo:theme(colors.red.500/50/50)]', '[--foo:theme(colors.red.500/50/50)]'],

packages/tailwindcss/src/__snapshots__/index.test.ts.snap

@@ -296,20 +296,20 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
   --drop-shadow-xl: 0 20px 13px #00000008, 0 8px 5px #00000014;
   --drop-shadow-2xl: 0 25px 25px #00000026;
   --spacing: .25rem;
-  --width-3xs: 16rem;
-  --width-2xs: 18rem;
-  --width-xs: 20rem;
-  --width-sm: 24rem;
-  --width-md: 28rem;
-  --width-lg: 32rem;
-  --width-xl: 36rem;
-  --width-2xl: 42rem;
-  --width-3xl: 48rem;
-  --width-4xl: 56rem;
-  --width-5xl: 64rem;
-  --width-6xl: 72rem;
-  --width-7xl: 80rem;
-  --width-prose: 65ch;
+  --container-3xs: 16rem;
+  --container-2xs: 18rem;
+  --container-xs: 20rem;
+  --container-sm: 24rem;
+  --container-md: 28rem;
+  --container-lg: 32rem;
+  --container-xl: 36rem;
+  --container-2xl: 42rem;
+  --container-3xl: 48rem;
+  --container-4xl: 56rem;
+  --container-5xl: 64rem;
+  --container-6xl: 72rem;
+  --container-7xl: 80rem;
+  --container-prose: 65ch;
   --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif;
   --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;

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

@@ -57,6 +57,10 @@ test('config values can be merged into the theme', () => {
             '100%': '100%',
           },
 
+          maxWidth: {
+            '9xs': '6rem',
+          },
+
           transitionTimingFunction: {
             fast: 'cubic-bezier(0, 0.55, 0.45, 1)',
           },
@@ -87,6 +91,7 @@ test('config values can be merged into the theme', () => {
   expect(theme.resolve('1/2', ['--width'])).toEqual('60%')
   expect(theme.resolve('0.5', ['--width'])).toEqual('60%')
   expect(theme.resolve('100%', ['--width'])).toEqual('100%')
+  expect(theme.resolve('9xs', ['--container'])).toEqual('6rem')
   expect(theme.resolve('fast', ['--ease'])).toEqual('cubic-bezier(0, 0.55, 0.45, 1)')
 })
 

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

@@ -135,6 +135,7 @@ export function keyPathToCssProperty(path: string[]) {
   if (path[0] === 'animation') path[0] = 'animate'
   if (path[0] === 'transitionTimingFunction') path[0] = 'ease'
   if (path[0] === 'fontFamily') path[0] = 'font'
+  if (path[0] === 'maxWidth') path[0] = 'container'
 
   for (let part of path) {
     if (!IS_VALID_KEY.test(part)) return null

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

@@ -1533,6 +1533,9 @@ test('old theme values are merged with their renamed counterparts in the CSS the
 
         --animate-a: 1;
         --animate-b: 2;
+
+        --container-a: 1;
+        --container-b: 2;
       }
 
       @plugin "./plugin.js";
@@ -1583,6 +1586,14 @@ test('old theme values are merged with their renamed counterparts in the CSS the
 
             expect(theme('boxShadow.a')).toEqual('1')
             expect(theme('boxShadow.b')).toEqual('2')
+
+            expect(theme('maxWidth')).toMatchObject({
+              a: '1',
+              b: '2',
+            })
+
+            expect(theme('maxWidth.a')).toEqual('1')
+            expect(theme('maxWidth.b')).toEqual('2')
           }),
         }
       },

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

@@ -13,34 +13,34 @@ export function createCompatConfig(cssTheme: Theme): UserConfig {
       // and only allow colors from the CSS theme.
       colors: ({ theme }) => theme('color', {}),
 
-      boxShadow: ({ theme }) => ({
-        ...defaultTheme.boxShadow,
-        ...theme('shadow', {}),
-      }),
-
-      animation: ({ theme }) => ({
-        ...defaultTheme.animation,
-        ...theme('animate', {}),
-      }),
-
-      borderRadius: ({ theme }) => ({
-        ...defaultTheme.borderRadius,
-        ...theme('radius', {}),
-      }),
-
-      screens: ({ theme }) => ({
-        ...defaultTheme.screens,
-        ...theme('breakpoint', {}),
-      }),
-
-      transitionDuration: {
-        ...defaultTheme.transitionDuration,
-        DEFAULT: cssTheme.get(['--default-transition-duration']) ?? null,
-      },
-
-      transitionTimingFunction: {
-        ...defaultTheme.transitionTimingFunction,
-        DEFAULT: cssTheme.get(['--default-transition-timing-function']) ?? null,
+      extend: {
+        boxShadow: ({ theme }) => ({
+          ...theme('shadow', {}),
+        }),
+
+        animation: ({ theme }) => ({
+          ...theme('animate', {}),
+        }),
+
+        borderRadius: ({ theme }) => ({
+          ...theme('radius', {}),
+        }),
+
+        screens: ({ theme }) => ({
+          ...theme('breakpoint', {}),
+        }),
+
+        transitionDuration: {
+          DEFAULT: cssTheme.get(['--default-transition-duration']) ?? null,
+        },
+
+        transitionTimingFunction: {
+          DEFAULT: cssTheme.get(['--default-transition-timing-function']) ?? null,
+        },
+
+        maxWidth: ({ theme }) => ({
+          ...theme('container', {}),
+        }),
       },
     },
   }

packages/tailwindcss/src/css-functions.test.ts

@@ -617,7 +617,7 @@ describe('theme function', () => {
           'fontFamily.sans',
           'ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',
         ],
-        ['width.xs', '20rem'],
+        ['maxWidth.xs', '20rem'],
         ['transitionTimingFunction.in-out', 'cubic-bezier(.4, 0, .2, 1)'],
         ['backgroundColor.red.500', 'oklch(.637 .237 25.331)'],
       ])('theme(%s) → %s', async (value, result) => {

packages/tailwindcss/src/utilities.test.ts

@@ -2738,7 +2738,7 @@ test('min-width', async () => {
       css`
         @theme {
           --spacing-4: 1rem;
-          --width-xl: 36rem;
+          --container-xl: 36rem;
         }
         @tailwind utilities;
       `,
@@ -2756,7 +2756,7 @@ test('min-width', async () => {
   ).toMatchInlineSnapshot(`
     ":root {
       --spacing-4: 1rem;
-      --width-xl: 36rem;
+      --container-xl: 36rem;
     }
 
     .min-w-4 {
@@ -2788,7 +2788,7 @@ test('min-width', async () => {
     }
 
     .min-w-xl {
-      min-width: var(--width-xl);
+      min-width: var(--container-xl);
     }"
   `)
   expect(
@@ -2814,7 +2814,7 @@ test('max-width', async () => {
       css`
         @theme {
           --spacing-4: 1rem;
-          --width-xl: 36rem;
+          --container-xl: 36rem;
         }
         @tailwind utilities;
       `,
@@ -2832,7 +2832,7 @@ test('max-width', async () => {
   ).toMatchInlineSnapshot(`
     ":root {
       --spacing-4: 1rem;
-      --width-xl: 36rem;
+      --container-xl: 36rem;
     }
 
     .max-w-4 {
@@ -2860,7 +2860,7 @@ test('max-width', async () => {
     }
 
     .max-w-xl {
-      max-width: var(--width-xl);
+      max-width: var(--container-xl);
     }"
   `)
   expect(
@@ -3293,15 +3293,15 @@ test('flex-basis', async () => {
     await compileCss(
       css`
         @theme {
-          --width-xl: 36rem;
+          --container-xl: 36rem;
         }
         @tailwind utilities;
       `,
       ['basis-auto', 'basis-full', 'basis-xl', 'basis-11/12', 'basis-[123px]'],
     ),
   ).toMatchInlineSnapshot(`
     ":root {
-      --width-xl: 36rem;
+      --container-xl: 36rem;
     }
 
     .basis-11\\/12 {
@@ -3321,7 +3321,7 @@ test('flex-basis', async () => {
     }
 
     .basis-xl {
-      flex-basis: var(--width-xl);
+      flex-basis: var(--container-xl);
     }"
   `)
   expect(
@@ -6451,8 +6451,8 @@ test('columns', async () => {
     await compileCss(
       css`
         @theme {
-          --width-3xs: 16rem;
-          --width-7xl: 80rem;
+          --container-3xs: 16rem;
+          --container-7xl: 80rem;
         }
         @tailwind utilities;
       `,
@@ -6468,20 +6468,20 @@ test('columns', async () => {
     ),
   ).toMatchInlineSnapshot(`
     ":root {
-      --width-3xs: 16rem;
-      --width-7xl: 80rem;
+      --container-3xs: 16rem;
+      --container-7xl: 80rem;
     }
 
     .columns-3xs {
-      columns: var(--width-3xs);
+      columns: var(--container-3xs);
     }
 
     .columns-4 {
       columns: 4;
     }
 
     .columns-7xl {
-      columns: var(--width-7xl);
+      columns: var(--container-7xl);
     }
 
     .columns-99 {

packages/tailwindcss/src/utilities.ts

@@ -909,9 +909,9 @@ export function createUtilities(theme: Theme) {
   )
 
   for (let [name, namespaces, property] of [
-    ['w', ['--width'], 'width'],
-    ['min-w', ['--min-width', '--width'], 'min-width'],
-    ['max-w', ['--max-width', '--width'], 'max-width'],
+    ['w', ['--width', '--container'], 'width'],
+    ['min-w', ['--min-width', '--container'], 'min-width'],
+    ['max-w', ['--max-width', '--container'], 'max-width'],
     ['h', ['--height'], 'height'],
     ['min-h', ['--min-height', '--height'], 'min-height'],
     ['max-h', ['--max-height', '--height'], 'max-height'],
@@ -1001,7 +1001,7 @@ export function createUtilities(theme: Theme) {
    */
   staticUtility('basis-auto', [['flex-basis', 'auto']])
   staticUtility('basis-full', [['flex-basis', '100%']])
-  spacingUtility('basis', ['--flex-basis', '--width'], (value) => [decl('flex-basis', value)], {
+  spacingUtility('basis', ['--flex-basis', '--container'], (value) => [decl('flex-basis', value)], {
     supportsFractions: true,
   })
 
@@ -1653,7 +1653,7 @@ export function createUtilities(theme: Theme) {
   staticUtility('columns-auto', [['columns', 'auto']])
 
   functionalUtility('columns', {
-    themeKeys: ['--columns', '--width'],
+    themeKeys: ['--columns', '--container'],
     handleBareValue: ({ value }) => {
       if (!isPositiveInteger(value)) return null
       return value
@@ -1664,7 +1664,7 @@ export function createUtilities(theme: Theme) {
   suggest('columns', () => [
     {
       values: Array.from({ length: 12 }, (_, i) => `${i + 1}`),
-      valueThemeKeys: ['--columns', '--width'],
+      valueThemeKeys: ['--columns', '--container'],
     },
   ])
 

packages/tailwindcss/src/variants.test.ts

@@ -1942,7 +1942,7 @@ test('container queries', async () => {
     await compileCss(
       css`
         @theme {
-          --width-lg: 1024px;
+          --container-lg: 1024px;
         }
         @tailwind utilities;
       `,
@@ -1965,7 +1965,7 @@ test('container queries', async () => {
     ),
   ).toMatchInlineSnapshot(`
     ":root {
-      --width-lg: 1024px;
+      --container-lg: 1024px;
     }
 
     @container name (width < 1024px) {