Upgrade: Migrate ring to ring-3 (#15063)

This PR adds a codemod for migrating `ring` to `ring-3` if it is safe to
do so.


# Test plan

Added a `ring` to the Catalyst project and then migrated it:
<img width="864" alt="image"
src="https://github.com/user-attachments/assets/163d9faa-c712-494e-b9d7-106508157915">

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add consistent base styles for buttons and form controls ([#15036](https://github.com/tailwindlabs/tailwindcss/pull/15036))
 - _Upgrade (experimental)_: Convert `group-[]:flex` to `in-[.group]:flex` ([#15054](https://github.com/tailwindlabs/tailwindcss/pull/15054))
 - _Upgrade (experimental)_: Add form reset styles to CSS files for compatibility with v3 ([#15036](https://github.com/tailwindlabs/tailwindcss/pull/15036))
+- _Upgrade (experimental)_: Migrate `ring` to `ring-3` ([#15063](https://github.com/tailwindlabs/tailwindcss/pull/15063))
 
 ### Fixed
 

integrations/upgrade/index.test.ts

@@ -78,6 +78,9 @@ test(
 
         <!-- Migrate to 2xs -->
         <div class="shadow-xs inset-shadow-xs"></div>
+
+        <!-- Migrate to -3 -->
+        <div class="ring"></div>
       `,
       'src/input.css': css`
         @tailwind base;
@@ -111,6 +114,9 @@ test(
       <!-- Migrate to 2xs -->
       <div class="shadow-2xs inset-shadow-2xs"></div>
 
+      <!-- Migrate to -3 -->
+      <div class="ring-3"></div>
+
       --- ./src/input.css ---
       @import 'tailwindcss';
 
@@ -2512,6 +2518,10 @@ test(
               DEFAULT: '0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)',
             },
 
+            ringWidth: {
+              DEFAULT: '4px',
+            },
+
             extend: {
               // Changes the "before" class definition. 'blur' -> 'blur-sm' is
               // not safe because 'blur' has a custom value.
@@ -2541,6 +2551,7 @@ test(
           <div class="shadow shadow-sm shadow-xs"></div>
           <div class="blur blur-sm"></div>
           <div class="rounded rounded-sm"></div>
+          <div class="ring"></div>
         </div>
       `,
     },
@@ -2558,6 +2569,9 @@ test(
         --shadow-*: initial;
         --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
 
+        --ring-width-*: initial;
+        --ring-width: 4px;
+
         --blur: var(--custom-default-blur);
 
         --radius-sm: var(--custom-rounded-sm);
@@ -2601,14 +2615,15 @@ test(
         <div class="shadow shadow-sm shadow-xs"></div>
         <div class="blur blur-xs"></div>
         <div class="rounded rounded-sm"></div>
+        <div class="ring"></div>
       </div>
       "
     `)
   },
 )
 
 test(
-  'make suffix-less migrations safe (e.g.: `blur`, `rounded`, `shadow`)',
+  'make suffix-less migrations safe (e.g.: `blur`, `rounded`, `shadow`, `ring`)',
   {
     fs: {
       'package.json': json`
@@ -2633,7 +2648,7 @@ test(
         @tailwind utilities;
       `,
       'index.html': html`
-        <div class="rounded blur shadow"></div>
+        <div class="rounded blur shadow ring"></div>
       `,
       'example-component.tsx': ts`
         type Star = [
@@ -2643,10 +2658,11 @@ test(
           blur?: boolean,
           rounded?: boolean,
           shadow?: boolean,
+          ring?: boolean,
         ]
 
-        function Star({ point: [cx, cy, dim, blur, rounded, shadow] }: { point: Star }) {
-          return <svg class="rounded shadow blur" filter={blur ? 'url(…)' : undefined} />
+        function Star({ point: [cx, cy, dim, blur, rounded, shadow, ring] }: { point: Star }) {
+          return <svg class="rounded shadow blur ring" filter={blur ? 'url(…)' : undefined} />
         }
       `,
     },
@@ -2694,7 +2710,7 @@ test(
       }
 
       --- index.html ---
-      <div class="rounded-sm blur-sm shadow-sm"></div>
+      <div class="rounded-sm blur-sm shadow-sm ring-3"></div>
 
       --- example-component.tsx ---
       type Star = [
@@ -2704,10 +2720,11 @@ test(
         blur?: boolean,
         rounded?: boolean,
         shadow?: boolean,
+        ring?: boolean,
       ]
 
-      function Star({ point: [cx, cy, dim, blur, rounded, shadow] }: { point: Star }) {
-        return <svg class="rounded-sm shadow-sm blur-sm" filter={blur ? 'url(…)' : undefined} />
+      function Star({ point: [cx, cy, dim, blur, rounded, shadow, ring] }: { point: Star }) {
+        return <svg class="rounded-sm shadow-sm blur-sm ring-3" filter={blur ? 'url(…)' : undefined} />
       }
       "
     `)

packages/@tailwindcss-upgrade/src/template/codemods/legacy-classes.test.ts

@@ -20,14 +20,16 @@ test.each([
   ['blur', 'blur-sm'],
   ['blur-sm', 'blur-xs'],
 
+  ['ring', 'ring-3'],
+
   ['blur!', 'blur-sm!'],
   ['hover:blur', 'hover:blur-sm'],
   ['hover:blur!', 'hover:blur-sm!'],
 
   ['hover:blur-sm', 'hover:blur-xs'],
   ['blur-sm!', 'blur-xs!'],
   ['hover:blur-sm!', 'hover:blur-xs!'],
-])('%s => %s', async (candidate, result) => {
+])('%s => %s (%#)', async (candidate, result) => {
   let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
     base: __dirname,
   })

packages/@tailwindcss-upgrade/src/template/codemods/legacy-classes.ts

@@ -28,6 +28,8 @@ const LEGACY_CLASS_MAP = new Map([
 
   ['blur', 'blur-sm'],
   ['blur-sm', 'blur-xs'],
+
+  ['ring', 'ring-3'],
 ])
 
 const THEME_KEYS = new Map([
@@ -47,6 +49,9 @@ const THEME_KEYS = new Map([
   ['blur', '--blur'],
   ['blur-sm', '--blur-sm'],
   ['blur-xs', '--blur-xs'],
+
+  ['ring', '--ring-width'],
+  ['ring-3', '--ring-width-3'],
 ])
 
 const DESIGN_SYSTEMS = new DefaultMap((base) => {
@@ -134,7 +139,7 @@ export async function legacyClasses(
 
       // The new theme value is not defined, which means we can't safely
       // migrate the utility.
-      if (customTo === undefined) {
+      if (customTo === undefined && defaultTo !== undefined) {
         continue
       }