Template migrations: Migrate bg-gradient-* utilities to bg-linear-* (#14537)

In v4, we're making room for more gradient primitives with the addition
of [gradient and conic gradient
utilities](https://github.com/tailwindlabs/tailwindcss/pull/14467). To
make this clearer, we are renaming all v3 `bg-gradient-*` utilities to
`bg-linear-*` to make it clear that these refer to linear gradients.

This PR adds a migration that will automatically update the class names
based on this migration.

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add support for prefixes ([#14501](https://github.com/tailwindlabs/tailwindcss/pull/14501))
+- _Experimental_: Add template codemods for migrating `bg-gradient-*` utilities to `bg-linear-*` ([#14537](https://github.com/tailwindlabs/tailwindcss/pull/14537]))
 
 ### Fixed
 

packages/@tailwindcss-upgrade/src/template/codemods/bg-gradient.test.ts

@@ -0,0 +1,24 @@
+import { __unstable__loadDesignSystem } from '@tailwindcss/node'
+import { expect, test } from 'vitest'
+import { printCandidate } from '../candidates'
+import { bgGradient } from './bg-gradient'
+
+test.each([
+  ['bg-gradient-to-t', 'bg-linear-to-t'],
+  ['bg-gradient-to-tr', 'bg-linear-to-tr'],
+  ['bg-gradient-to-r', 'bg-linear-to-r'],
+  ['bg-gradient-to-br', 'bg-linear-to-br'],
+  ['bg-gradient-to-b', 'bg-linear-to-b'],
+  ['bg-gradient-to-bl', 'bg-linear-to-bl'],
+  ['bg-gradient-to-l', 'bg-linear-to-l'],
+  ['bg-gradient-to-tl', 'bg-linear-to-tl'],
+
+  ['max-lg:hover:bg-gradient-to-t', 'max-lg:hover:bg-linear-to-t'],
+])('%s => %s', async (candidate, result) => {
+  let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
+    base: __dirname,
+  })
+
+  let migrated = bgGradient(designSystem.parseCandidate(candidate)[0]!)
+  expect(migrated ? printCandidate(migrated) : migrated).toEqual(result)
+})

packages/@tailwindcss-upgrade/src/template/codemods/bg-gradient.ts

@@ -0,0 +1,17 @@
+import type { Candidate } from '../../../../tailwindcss/src/candidate'
+
+const DIRECTIONS = ['t', 'tr', 'r', 'br', 'b', 'bl', 'l', 'tl']
+
+export function bgGradient(candidate: Candidate): Candidate | null {
+  if (candidate.kind === 'static' && candidate.root.startsWith('bg-gradient-to-')) {
+    let direction = candidate.root.slice(15)
+
+    if (!DIRECTIONS.includes(direction)) {
+      return null
+    }
+
+    candidate.root = `bg-linear-to-${direction}`
+    return candidate
+  }
+  return null
+}