Rename --aspect-ratio-* theme key to --aspect-* (#15365)

This PR renames the `--aspect-ratio` theme key to `--aspect`. This is to
match what we've done with other theme keys where they match the utility
names, like `--ease` and `--leading`.

```diff
  @theme {
-   --aspect-ratio-retro: 4 / 3;
+   --aspect-retro: 4 / 3;
  }
```

Additionally, I've also converted the existing `aspect-video` static
utility to a theme value. This will allow people to override this
utility in their own projects—something that's not possible with static
utilities. This change feels appropriate since the video aspect ratio is
subjective, unlike other static utilities like `aspect-square`.

```css
@theme {
  --aspect-video: 4 / 3; /* N64 baby! */
}
```

CHANGELOG.md

@@ -18,6 +18,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix missing `shadow-none` suggestion in IntelliSense ([#15342](https://github.com/tailwindlabs/tailwindcss/pull/15342))
 - Optimize AST before printing for IntelliSense ([#15347](https://github.com/tailwindlabs/tailwindcss/pull/15347))
 
+### Changed
+
+- Rename `--aspect-ratio-*` theme key to `--aspect-*` ([#15365](https://github.com/tailwindlabs/tailwindcss/pull/15365))
+- Derive `aspect-video` utility from theme ([#15365](https://github.com/tailwindlabs/tailwindcss/pull/15365))
+
 ## [4.0.0-beta.6] - 2024-12-06
 
 ### Fixed
@@ -752,4 +757,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Move the CLI into a separate `@tailwindcss/cli` package ([#13095](https://github.com/tailwindlabs/tailwindcss/pull/13095))
 
 ## [4.0.0-alpha.1] - 2024-03-06
-

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

@@ -359,6 +359,7 @@ exports[`\`@import 'tailwindcss'\` is replaced with the generated CSS 1`] = `
     --perspective-normal: 500px;
     --perspective-midrange: 800px;
     --perspective-distant: 1200px;
+    --aspect-video: 16 / 9;
     --default-transition-duration: .15s;
     --default-transition-timing-function: cubic-bezier(.4, 0, .2, 1);
     --default-font-family: var(--font-sans);

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

@@ -358,6 +358,7 @@ exports[`compiling CSS > \`@tailwind utilities\` is replaced by utilities using
   --perspective-normal: 500px;
   --perspective-midrange: 800px;
   --perspective-distant: 1200px;
+  --aspect-video: 16 / 9;
   --default-transition-duration: .15s;
   --default-transition-timing-function: cubic-bezier(.4, 0, .2, 1);
   --default-font-family: var(--font-sans);

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

@@ -23,6 +23,10 @@ test('config values can be merged into the theme', () => {
             sm: '1234px',
           },
 
+          aspectRatio: {
+            retro: '4 / 3',
+          },
+
           boxShadow: {
             normal: '0 1px 3px black',
           },
@@ -75,6 +79,7 @@ test('config values can be merged into the theme', () => {
         },
       },
       base: '/root',
+      reference: false,
     },
   ])
   applyConfigToTheme(design, resolvedConfig, replacedThemeKeys)
@@ -82,6 +87,7 @@ test('config values can be merged into the theme', () => {
   expect(theme.resolve('primary', ['--color'])).toEqual('#c0ffee')
   expect(theme.resolve('sm', ['--breakpoint'])).toEqual('1234px')
   expect(theme.resolve('normal', ['--shadow'])).toEqual('0 1px 3px black')
+  expect(theme.resolve('retro', ['--aspect'])).toEqual('4 / 3')
   expect(theme.resolve('sm', ['--radius'])).toEqual('0.33rem')
   expect(theme.resolve('blink', ['--animate'])).toEqual('blink 1s linear infinite')
   expect(theme.resolve('red-500', ['--color'])).toEqual('red')

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

@@ -148,6 +148,7 @@ export function keyPathToCssProperty(path: string[]) {
   path = structuredClone(path)
 
   if (path[0] === 'animation') path[0] = 'animate'
+  if (path[0] === 'aspectRatio') path[0] = 'aspect'
   if (path[0] === 'borderRadius') path[0] = 'radius'
   if (path[0] === 'boxShadow') path[0] = 'shadow'
   if (path[0] === 'colors') path[0] = 'color'

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

@@ -1534,6 +1534,9 @@ test('old theme values are merged with their renamed counterparts in the CSS the
         --animate-a: 1;
         --animate-b: 2;
 
+        --aspect-a: 1;
+        --aspect-b: 2;
+
         --container-a: 1;
         --container-b: 2;
 
@@ -1585,6 +1588,14 @@ test('old theme values are merged with their renamed counterparts in the CSS the
             expect(theme('animation.a')).toEqual('1')
             expect(theme('animation.b')).toEqual('2')
 
+            expect(theme('aspectRatio')).toMatchObject({
+              a: '1',
+              b: '2',
+            })
+
+            expect(theme('aspectRatio.a')).toEqual('1')
+            expect(theme('aspectRatio.b')).toEqual('2')
+
             expect(theme('boxShadow')).toMatchObject({
               a: '1',
               b: '2',

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

@@ -26,6 +26,10 @@ export function createCompatConfig(cssTheme: Theme): UserConfig {
           ...theme('animate', {}),
         }),
 
+        aspectRatio: ({ theme }) => ({
+          ...theme('aspect', {}),
+        }),
+
         borderRadius: ({ theme }) => ({
           ...theme('radius', {}),
         }),

packages/tailwindcss/src/intellisense.test.ts

@@ -11,6 +11,7 @@ function loadDesignSystem() {
   theme.add('--colors-red-500', 'red')
   theme.add('--colors-blue-500', 'blue')
   theme.add('--breakpoint-sm', '640px')
+  theme.add('--aspect-video', '16 / 9')
   theme.add('--font-sans', 'sans-serif')
   theme.add('--font-weight-superbold', '900')
   theme.add('--text-xs', '0.75rem')

packages/tailwindcss/src/utilities.test.ts

@@ -2485,8 +2485,22 @@ test('field-sizing', async () => {
 })
 
 test('aspect-ratio', async () => {
-  expect(await run(['aspect-video', 'aspect-[10/9]', 'aspect-4/3'])).toMatchInlineSnapshot(`
-    ".aspect-4\\/3 {
+  expect(
+    await compileCss(
+      css`
+        @theme {
+          --aspect-video: 16 / 9;
+        }
+        @tailwind utilities;
+      `,
+      ['aspect-video', 'aspect-[10/9]', 'aspect-4/3'],
+    ),
+  ).toMatchInlineSnapshot(`
+    ":root {
+      --aspect-video: 16 / 9;
+    }
+
+    .aspect-4\\/3 {
       aspect-ratio: 4 / 3;
     }
 
@@ -2495,7 +2509,7 @@ test('aspect-ratio', async () => {
     }
 
     .aspect-video {
-      aspect-ratio: 16 / 9;
+      aspect-ratio: var(--aspect-video);
     }"
   `)
   expect(

packages/tailwindcss/src/utilities.ts

@@ -828,9 +828,8 @@ export function createUtilities(theme: Theme) {
    */
   staticUtility('aspect-auto', [['aspect-ratio', 'auto']])
   staticUtility('aspect-square', [['aspect-ratio', '1 / 1']])
-  staticUtility('aspect-video', [['aspect-ratio', '16 / 9']])
   functionalUtility('aspect', {
-    themeKeys: ['--aspect-ratio'],
+    themeKeys: ['--aspect'],
     handleBareValue: ({ fraction }) => {
       if (fraction === null) return null
       let [lhs, rhs] = segment(fraction, '/')

packages/tailwindcss/theme.css

@@ -429,6 +429,8 @@
   --perspective-midrange: 800px;
   --perspective-distant: 1200px;
 
+  --aspect-video: 16 / 9;
+
   --default-transition-duration: 150ms;
   --default-transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
   --default-font-family: var(--font-sans);