Add canonical class diagnostics (#1475)

This feature, when used with a new enough Tailwind CSS version
(v4.1.15+), allows IntelliSense to detect when a utility you've written
could be written in a more succinct / optimal fashion. These suggestions
are unique to your project so if you customize your theme that will be
taken into account.

It can suggest utilities that match arbitrary ones:
<img width="961" height="120" alt="Screenshot 2025-10-07 at 10 41 01"
src="https://github.com/user-attachments/assets/85c9b85f-56be-4476-8cfe-ce774b45dc0c"
/>

It can also match arbitrary values against values in your theme:
<img width="1081" height="142" alt="Screenshot 2025-10-07 at 10 41 45"
src="https://github.com/user-attachments/assets/75779488-1187-4d28-b1d5-5ea5cfebaf12"
/>

This includes matching against custom theme values in your project:
<img width="830" height="131" alt="Screenshot 2025-10-07 at 10 43 01"
src="https://github.com/user-attachments/assets/c96cb794-c661-43e1-9541-547590cf9299"
/>

It even works for variants:
<img width="888" height="136" alt="Screenshot 2025-10-07 at 10 44 07"
src="https://github.com/user-attachments/assets/ba7483fd-4979-4b10-8069-698f686541ed"
/>

And of course it works for both simultaneously:
<img width="1078" height="174" alt="Screenshot 2025-10-07 at 10 44 27"
src="https://github.com/user-attachments/assets/ba2b6022-417a-4cb9-b171-726623116fb5"
/>

When presented with one of these diagnostics it will also have an
accompanying code action that lets you replace the class:

<img width="659" height="130" alt="Screenshot 2025-10-07 at 10 45 40"
src="https://github.com/user-attachments/assets/00e91b0d-68ee-42fc-babb-ebc02ddafbe9"
/>

Note: Matching is done with mostly exact values to your theme so colors
that _parse to the same value_ but don't match won't necessarily be
suggested. This is a possible future improvement but requires some
design work in Tailwind CSS itself.

Author: thecrypticace

packages/tailwindcss-language-server/tests/diagnostics/diagnostics.test.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises'
 import { expect, test } from 'vitest'
 import { withFixture } from '../common'
-import { css, defineTest } from '../../src/testing'
+import { css, defineTest, json } from '../../src/testing'
 import { createClient } from '../utils/client'
 
 withFixture('basic', (c) => {
@@ -425,3 +425,61 @@ defineTest({
     ])
   },
 })
+
+defineTest({
+  name: 'Shows warning when using non-canonical classes',
+  fs: {
+    // TODO: Drop this when the embedded version of tailwindcss is v4.1.15
+    'package.json': json`
+      {
+        "dependencies": {
+          "tailwindcss": "0.0.0-insiders.efe084b"
+        }
+      }
+    `,
+    'app.css': css`
+      @import 'tailwindcss';
+    `,
+  },
+  prepare: async ({ root }) => ({
+    client: await createClient({
+      root,
+      settings: {
+        tailwindCSS: {
+          lint: { suggestCanonicalClasses: 'warning' },
+        },
+      },
+    }),
+  }),
+  handle: async ({ client }) => {
+    let doc = await client.open({
+      lang: 'html',
+      text: '<div class="[@media_print]:flex [color:red]/50">',
+    })
+
+    let diagnostics = await doc.diagnostics()
+
+    expect(diagnostics).toEqual([
+      {
+        code: 'suggestCanonicalClasses',
+        message: 'The class `[@media_print]:flex` can be written as `print:flex`',
+        range: {
+          start: { line: 0, character: 12 },
+          end: { line: 0, character: 31 },
+        },
+        severity: 2,
+        suggestions: ['print:flex'],
+      },
+      {
+        code: 'suggestCanonicalClasses',
+        message: 'The class `[color:red]/50` can be written as `text-[red]/50`',
+        range: {
+          start: { line: 0, character: 32 },
+          end: { line: 0, character: 46 },
+        },
+        severity: 2,
+        suggestions: ['text-[red]/50'],
+      },
+    ])
+  },
+})

packages/tailwindcss-language-service/src/codeActions/codeActionProvider.ts

@@ -13,6 +13,7 @@ import {
   isInvalidScreenDiagnostic,
   isInvalidVariantDiagnostic,
   isRecommendedVariantOrderDiagnostic,
+  isSuggestCanonicalClasses,
 } from '../diagnostics/types'
 import { flatten, dedupeBy } from '../util/array'
 import { provideCssConflictCodeActions } from './provideCssConflictCodeActions'
@@ -74,7 +75,8 @@ export async function doCodeActions(
         isInvalidTailwindDirectiveDiagnostic(diagnostic) ||
         isInvalidScreenDiagnostic(diagnostic) ||
         isInvalidVariantDiagnostic(diagnostic) ||
-        isRecommendedVariantOrderDiagnostic(diagnostic)
+        isRecommendedVariantOrderDiagnostic(diagnostic) ||
+        isSuggestCanonicalClasses(diagnostic)
       ) {
         return provideSuggestionCodeActions(state, params, diagnostic)
       }

packages/tailwindcss-language-service/src/codeActions/provideSuggestionCodeActions.ts

@@ -6,6 +6,7 @@ import type {
   InvalidScreenDiagnostic,
   InvalidVariantDiagnostic,
   RecommendedVariantOrderDiagnostic,
+  SuggestCanonicalClassesDiagnostic,
 } from '../diagnostics/types'
 
 export function provideSuggestionCodeActions(
@@ -16,7 +17,8 @@ export function provideSuggestionCodeActions(
     | InvalidTailwindDirectiveDiagnostic
     | InvalidScreenDiagnostic
     | InvalidVariantDiagnostic
-    | RecommendedVariantOrderDiagnostic,
+    | RecommendedVariantOrderDiagnostic
+    | SuggestCanonicalClassesDiagnostic,
 ): CodeAction[] {
   return diagnostic.suggestions.map((suggestion) => ({
     title: `Replace with '${suggestion}'`,

packages/tailwindcss-language-service/src/diagnostics/canonical-classes.ts

@@ -0,0 +1,59 @@
+import type { TextDocument } from 'vscode-languageserver-textdocument'
+import type { State, Settings } from '../util/state'
+import { type SuggestCanonicalClassesDiagnostic, DiagnosticKind } from './types'
+import { findClassListsInDocument, getClassNamesInClassList } from '../util/find'
+
+export async function getSuggestCanonicalClassesDiagnostics(
+  state: State,
+  document: TextDocument,
+  settings: Settings,
+): Promise<SuggestCanonicalClassesDiagnostic[]> {
+  if (!state.v4) return []
+  if (!state.designSystem.canonicalizeCandidates) return []
+
+  let severity = settings.tailwindCSS.lint.suggestCanonicalClasses
+  if (severity === 'ignore') return []
+
+  let diagnostics: SuggestCanonicalClassesDiagnostic[] = []
+
+  let classLists = await findClassListsInDocument(state, document)
+
+  for (let classList of classLists) {
+    let classNames = getClassNamesInClassList(classList, [])
+
+    // NOTES:
+    //
+    // A planned enhancement to `canonicalizeCandidates` is to operate on class *lists* which would
+    // allow `[font-size:0.875rem] [line-height:0.25rem]` to turn into a single `text-sm/3` class.
+    //
+    // To account for this future we process class names individually. At some future point we can
+    // then take the list of individual classes and pass it in *again* to issue a diagnostic for the
+    // class list as a whole.
+    //
+    // This may not allow you to see *which classes* got combined since the inputs/outputs map to
+    // entire lists but this seems fine to do
+    //
+    // We'd probably want to only issue a class list diagnostic once there are no individual class
+    // diagnostics in a given class list.
+
+    for (let className of classNames) {
+      let canonicalized = state.designSystem.canonicalizeCandidates([className.className])[0]
+      let isCanonical = canonicalized === className.className
+
+      if (isCanonical) continue
+
+      diagnostics.push({
+        code: DiagnosticKind.SuggestCanonicalClasses,
+        range: className.range,
+        severity:
+          severity === 'error'
+            ? 1 /* DiagnosticSeverity.Error */
+            : 2 /* DiagnosticSeverity.Warning */,
+        message: `The class \`${className.className}\` can be written as \`${canonicalized}\``,
+        suggestions: [canonicalized],
+      })
+    }
+  }
+
+  return diagnostics
+}

packages/tailwindcss-language-service/src/diagnostics/diagnosticsProvider.ts

@@ -10,6 +10,7 @@ import { getInvalidTailwindDirectiveDiagnostics } from './getInvalidTailwindDire
 import { getRecommendedVariantOrderDiagnostics } from './getRecommendedVariantOrderDiagnostics'
 import { getInvalidSourceDiagnostics } from './getInvalidSourceDiagnostics'
 import { getUsedBlocklistedClassDiagnostics } from './getUsedBlocklistedClassDiagnostics'
+import { getSuggestCanonicalClassesDiagnostics } from './canonical-classes'
 
 export async function doValidate(
   state: State,
@@ -24,6 +25,7 @@ export async function doValidate(
     DiagnosticKind.InvalidSourceDirective,
     DiagnosticKind.RecommendedVariantOrder,
     DiagnosticKind.UsedBlocklistedClass,
+    DiagnosticKind.SuggestCanonicalClasses,
   ],
 ): Promise<AugmentedDiagnostic[]> {
   const settings = await state.editor.getConfiguration(document.uri)
@@ -57,6 +59,9 @@ export async function doValidate(
         ...(only.includes(DiagnosticKind.UsedBlocklistedClass)
           ? await getUsedBlocklistedClassDiagnostics(state, document, settings)
           : []),
+        ...(only.includes(DiagnosticKind.SuggestCanonicalClasses)
+          ? await getSuggestCanonicalClassesDiagnostics(state, document, settings)
+          : []),
       ]
     : []
 }

packages/tailwindcss-language-service/src/diagnostics/types.ts

@@ -11,6 +11,7 @@ export enum DiagnosticKind {
   InvalidSourceDirective = 'invalidSourceDirective',
   RecommendedVariantOrder = 'recommendedVariantOrder',
   UsedBlocklistedClass = 'usedBlocklistedClass',
+  SuggestCanonicalClasses = 'suggestCanonicalClasses',
 }
 
 export type CssConflictDiagnostic = Diagnostic & {
@@ -111,6 +112,17 @@ export function isUsedBlocklistedClass(
   return diagnostic.code === DiagnosticKind.UsedBlocklistedClass
 }
 
+export type SuggestCanonicalClassesDiagnostic = Diagnostic & {
+  code: DiagnosticKind.SuggestCanonicalClasses
+  suggestions: string[]
+}
+
+export function isSuggestCanonicalClasses(
+  diagnostic: AugmentedDiagnostic,
+): diagnostic is SuggestCanonicalClassesDiagnostic {
+  return diagnostic.code === DiagnosticKind.SuggestCanonicalClasses
+}
+
 export type AugmentedDiagnostic =
   | CssConflictDiagnostic
   | InvalidApplyDiagnostic
@@ -121,3 +133,4 @@ export type AugmentedDiagnostic =
   | InvalidSourceDirectiveDiagnostic
   | RecommendedVariantOrderDiagnostic
   | UsedBlocklistedClassDiagnostic
+  | SuggestCanonicalClassesDiagnostic

packages/tailwindcss-language-service/src/util/state.ts

@@ -66,6 +66,7 @@ export type TailwindCssSettings = {
     invalidSourceDirective: DiagnosticSeveritySetting
     recommendedVariantOrder: DiagnosticSeveritySetting
     usedBlocklistedClass: DiagnosticSeveritySetting
+    suggestCanonicalClasses: DiagnosticSeveritySetting
   }
   experimental: {
     classRegex: string[] | [string, string][]
@@ -205,6 +206,7 @@ export function getDefaultTailwindSettings(): Settings {
         invalidSourceDirective: 'error',
         recommendedVariantOrder: 'warning',
         usedBlocklistedClass: 'warning',
+        suggestCanonicalClasses: 'warning',
       },
       showPixelEquivalents: true,
       includeLanguages: {},

packages/tailwindcss-language-service/src/util/v4/design-system.ts

@@ -38,9 +38,14 @@ export interface DesignSystem {
   getClassList(): ClassEntry[]
   getVariants(): VariantEntry[]
 
-  // Optional because it did not exist in earlier v4 alpha versions
+  // Added in v4.0.0-alpha.24
   resolveThemeValue?(path: string, forceInline?: boolean): string | undefined
+
+  // Added in v4.0.0-alpha.26
   invalidCandidates?: Set<string>
+
+  // Added in v4.1.15
+  canonicalizeCandidates?(classes: string[]): string[]
 }
 
 export interface DesignSystem {

packages/vscode-tailwindcss/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Fix infinite recursion in theme variable lookups ([#1473](https://github.com/tailwindlabs/tailwindcss-intellisense/pull/1473))
 - Fix infinite recursion when replacing unbalanced calc expressions ([#1473](https://github.com/tailwindlabs/tailwindcss-intellisense/pull/1473))
+- Add diagnostic to suggest canonical classes by default ([#1475](https://github.com/tailwindlabs/tailwindcss-intellisense/pull/1475))
 
 ## 0.14.27
 

packages/vscode-tailwindcss/README.md

@@ -183,6 +183,17 @@ Class variants not in the recommended order (applies in [JIT mode](https://tailw
 
 Usage of class names that have been blocklisted via `@source not inline(…)`. **Default: `warning`**
 
+#### `tailwindCSS.lint.suggestCanonicalClasses`
+
+Detect usage of class names that are not in the most optimal form. **Default: `warning`**
+
+Some examples of the changes this makes:
+
+| Class                           | Canonical Form |
+| ------------------------------- | -------------- |
+| `[color:red]/100`               | `text-[red]`   |
+| `[@media_print]:[display:flex]` | `print:flex`   |
+
 ### `tailwindCSS.inspectPort`
 
 Enable the Node.js inspector agent for the language server and listen on the specified port. **Default: `null`**