Mark break-words as deprecated, and upgrade to wrap-break-word (#19157)

This PR marks `break-words` as deprecated (such that intellisense
doesn't suggest it anymore). Updates the upgrade tooling to prefer
`wrap-break-word` instead.

Note: `break-words` will still work as expected.

## Test plan

1. `break-words` still generates the correct CSS.
2. Intellisense doesn't suggest `break-words` anymore.
3. Upgrade tooling suggests `wrap-break-word` instead of `break-words`.

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Don’t index into strings with the `theme(…)` function ([#19111](https://github.com/tailwindlabs/tailwindcss/pull/19111))
 - Fix parsing issue when `\t` is used in at-rules ([#19130](https://github.com/tailwindlabs/tailwindcss/pull/19130))
 - Upgrade: Canonicalize utilities containing `0` values ([#19095](https://github.com/tailwindlabs/tailwindcss/pull/19095))
+- Upgrade: Migrate deprecated `break-words` to `wrap-break-word` ([#19157](https://github.com/tailwindlabs/tailwindcss/pull/19157))
 
 ## [4.1.14] - 2025-10-01
 

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

@@ -3606,7 +3606,6 @@ exports[`getClassList 1`] = `
   "break-inside-avoid-page",
   "break-keep",
   "break-normal",
-  "break-words",
   "brightness-0",
   "brightness-50",
   "brightness-75",

packages/tailwindcss/src/canonicalize-candidates.test.ts

@@ -531,6 +531,32 @@ describe.each([['default'], ['with-variant'], ['important'], ['prefix']])('%s',
 
       await expectCanonicalization(input, candidate, expected)
     })
+
+    test('`break-words` → `wrap-break-word`', async () => {
+      let candidate = 'break-words'
+      let expected = 'wrap-break-word'
+
+      let input = css`
+        @import 'tailwindcss';
+      `
+
+      await expectCanonicalization(input, candidate, expected)
+    })
+
+    test('`break-words` → `break-words` with custom implementation', async () => {
+      let candidate = 'break-words'
+      let expected = 'break-words'
+
+      let input = css`
+        @import 'tailwindcss';
+
+        @utility break-words {
+          break: words; /* imagine this exists */
+        }
+      `
+
+      await expectCanonicalization(input, candidate, expected)
+    })
   })
 
   describe('arbitrary variants', () => {

packages/tailwindcss/src/canonicalize-candidates.ts

@@ -878,7 +878,10 @@ function bareValueUtilities(candidate: Candidate, options: SignatureOptions): Ca
 
 // ----
 
-const DEPRECATION_MAP = new Map([['order-none', 'order-0']])
+const DEPRECATION_MAP = new Map([
+  ['order-none', 'order-0'],
+  ['break-words', 'wrap-break-word'],
+])
 
 function deprecatedUtilities(candidate: Candidate, options: SignatureOptions): Candidate {
   let designSystem = options.designSystem

packages/tailwindcss/src/compat/legacy-utilities.ts

@@ -92,4 +92,5 @@ export function registerLegacyUtilities(designSystem: DesignSystem) {
   })
 
   designSystem.utilities.static('order-none', () => [decl('order', '0')])
+  designSystem.utilities.static('break-words', () => [decl('overflow-wrap', 'break-word')])
 }

packages/tailwindcss/src/utilities.ts

@@ -2156,7 +2156,6 @@ export function createUtilities(theme: Theme) {
     ['overflow-wrap', 'normal'],
     ['word-break', 'normal'],
   ])
-  staticUtility('break-words', [['overflow-wrap', 'break-word']])
   staticUtility('break-all', [['word-break', 'break-all']])
   staticUtility('break-keep', [['word-break', 'keep-all']])