VSCode CSS `unknownAtRule` warning fix

#tailwindcss #vscode #css

Have you experienced unknownAtRule linter warning?

For recap, here are common CSS at-rules that will not result in CSS lint warning.

@import
@media
@supports
@layer
@font-face
@keyframes
@property
@page
@counter-style
@container

Most likely, you’re working with Tailwind CSS, which uses directives for special functionality and can cause the linter to complain.

A custom at-rules are allowed in CSS Syntax Module Level 3, but the linter will not know about them without your help.

That would be the case for Tailwind @theme, @apply directives, for example.

Rather than ignoring the unkonwnAtRules lint error by adding the following to the .vscode/settings.json:

{
  "css.lint.unknownAtRules": "ignore", // ignore | warning | error
}

here are two better alternatives:

1) First, if you use Tailwind CSS 4.x, install Tailwind CSS Intellisence and set the files.associations (I omitted the second step, the main reason this post exists 😆)
2) Second, have own whitelist of allowed at-rules.

1. Tailwind CSS 4.x, TW Intellisense plugin

Most likely you've encountered the unknownAtRule when working with the latest Tailwind CSS 4.x directives. Despite having Tailwind CSS Intellisence activated, you still see squiggly lint warnings. Most likely because you have not read the full docs for Recommended Settings. Don't forget to set your .vscode/settings.json:

  "files.associations": {
    "*.css": "tailwindcss"
  }

2. at-rules whitelist with own descriptions

You can create own whitelist of custom at-rules by adding their definitions into Custom Data.

(related: schema, custom-data-sample, custom-data-extension in package.json)

Inside .vscode/settings.json:

{
  "css.customData": [".vscode/css-custom-data.json"],
}

And add css-custom-data.json file with specific Tailwind directives:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vscode-css-languageservice/main/docs/customData.schema.json",
  "version": 1.1,
  "atDirectives": [
    {
      "name": "@apply",
      "description": "Tailwind CSS directive for applying utility classes within custom CSS.",
      "references": [
        {
          "name": "@apply",
          "url": "https://tailwindcss.com/docs/functions-and-directives#apply"
        }
      ]
    },
    {
      "name": "@config",
      "description": "Tailwind CSS directive to load a legacy JavaScript-based configuration file.",
      "references": [
        {
          "name": "@config",
          "url": "https://tailwindcss.com/docs/functions-and-directives#config"
        }
      ]
    },
    {
      "name": "@custom-variant",
      "description": "Tailwind CSS directive for defining custom variants.",
      "references": [
        {
          "name": "@custom-variant",
          "url": "https://tailwindcss.com/docs/plugins#adding-variants"
        }
      ]
    },
    {
      "name": "@layer",
      "description": "Tailwind CSS directive for organizing custom styles into cascade layers.",
      "references": [
        {
          "name": "@layer",
          "url": "https://tailwindcss.com/docs/functions-and-directives#layer"
        }
      ]
    },
    {
      "name": "@plugin",
      "description": "Tailwind CSS directive to load a legacy JavaScript-based plugin.",
      "references": [
        {
          "name": "@plugin",
          "url": "https://tailwindcss.com/docs/plugins"
        }
      ]
    },
    {
      "name": "@source",
      "description": "Tailwind CSS directive to specify source files for content detection or to safelist utilities.",
      "references": [
        {
          "name": "@source",
          "url": "https://tailwindcss.com/docs/content-configuration"
        }
      ]
    },
    {
      "name": "@theme",
      "description": "Tailwind CSS directive for defining custom design tokens like fonts, colors, and breakpoints.",
      "references": [
        {
          "name": "@theme",
          "url": "https://tailwindcss.com/docs/theme"
        }
      ]
    },
    {
      "name": "@utility",
      "description": "Tailwind CSS directive to add custom utilities to the framework.",
      "references": [
        {
          "name": "@utility",
          "url": "https://tailwindcss.com/docs/plugins#adding-utilities"
        }
      ]
    },
    {
      "name": "@variant",
      "description": "Tailwind CSS directive to apply a variant to styles in your CSS.",
      "references": [
        {
          "name": "@variant",
          "url": "https://tailwindcss.com/docs/plugins#adding-variants"
        }
      ]
    }
  ]
}