Comments ( and /* */)

How to write comments when working with Tailwind CSS. Tailwind is a framework, so comment syntax follows the language in use. HTML templates use , CSS files use /* */, and JavaScript configuration files such as tailwind.config.js use // or /* */. Because Tailwind utility classes are concise, comments that explain the intent behind long class lists are particularly useful.

Syntax

<!-- HTML comment. Written in Tailwind markup. -->

<!--
  Multi-line HTML comment.
  Used when commenting out an entire component block.
-->

The same logic can also be written as:

/* CSS file comment.
   Written in custom CSS that uses @layer or @apply. */

The same logic can also be written as:

// JavaScript comment in tailwind.config.js.
// Used to document theme extensions and plugin configuration.

/* Block comments also work as JavaScript. */

Comment Types (Three Layers)

Layer	File	Syntax	Description
HTML template	.html / .php / *.jsx, etc.	<!-- text -->	Used to mark component boundaries or to clarify the intent behind long class attribute values.
CSS (custom)	input.css / globals.css, etc.	/* text */	Used to annotate `@layer`, `@apply`, and custom class definitions.
Config file (JS)	tailwind.config.js	// text / /* text */	Used to document theme extensions, color palettes, and plugin configuration.

Patterns for Placing Comments

Decision	Situation	Reason
Write a comment	Grouping and explaining a long class list	When utility classes are stacked, a comment indicating which group handles layout versus which handles visual styling improves readability.
Write a comment	Start and end of a component	In deeply nested HTML, comments at component boundaries help locate your position in the file.
Write a comment	Theme extensions in the config file	When adding color palettes or spacing values in `tailwind.config.js`, recording the design system specification (e.g., brand color name, link to design document) is useful.
Write a comment	The reason for using @apply	`@apply` deviates from the Tailwind-recommended utility-first approach. Leaving a note explaining why utility classes were not used directly helps with future maintenance.
No comment needed	When the class name makes the purpose obvious	The meaning of `flex`, `items-center`, and `gap-4` is clear from Tailwind documentation. Adding a comment to each class becomes noise.
No comment needed	Change history or deleted code	Because version control (git) is available, there is no need to keep old code or change dates in comments.

Sample Code

Component boundaries in HTML and comments on long class attributes.

page.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Tailwind Comment Sample</title>
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body class="bg-gray-100 min-h-screen">

  <!-- Header -->
  <header class="bg-white shadow">
    <div class="max-w-7xl mx-auto px-4 py-4 flex items-center justify-between">
      <span class="text-xl font-bold text-gray-800">Brand</span>
      <nav class="flex gap-6">
        <a href="#" class="text-gray-600 hover:text-gray-900">Home</a>
        <a href="#" class="text-gray-600 hover:text-gray-900">About</a>
      </nav>
    </div>
  </header>
  <!-- /Header -->

  <!-- Main content -->
  <main class="max-w-7xl mx-auto px-4 py-8">

    <!-- Card grid (responsive: sm=1 col, md=2 cols, lg=3 cols) -->
    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

      <!-- Card -->
      <div class="bg-white rounded-lg shadow p-6">
        <h2 class="text-lg font-semibold text-gray-800 mb-2">Item A</h2>
        <p class="text-gray-600 text-sm">Description text goes here.</p>
        <!-- Footer: styles to pin the button to the bottom of the card -->
        <div class="mt-4">
          <a href="#"
            class="inline-block bg-blue-600 text-white text-sm font-medium
                   px-4 py-2 rounded hover:bg-blue-700 transition-colors">
            Learn more
          </a>
        </div>
      </div>
      <!-- /Card -->

    </div>
    <!-- /Card grid -->

  </main>
  <!-- /Main content -->

</body>
</html>

Comments in the configuration file.

tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{html,js,php}",
  ],
  theme: {
    extend: {
      // Brand color palette (follows Design System v2)
      // Reference: https://example.com/design-system/colors
      colors: {
        brand: {
          50:  "#e6f0ff",
          100: "#cce1ff",
          500: "#0066cc", // Primary button and link color
          600: "#0052a3", // Hover state for primary color
          900: "#001433",
        },
      },
      // Custom spacing (aligned with design token values)
      spacing: {
        "18": "4.5rem", // Adding 4.5rem which is not in the default scale
        "72": "18rem",
        "84": "21rem",
      },
      // Custom font family (loaded via Google Fonts)
      fontFamily: {
        sans: ["Noto Sans JP", "sans-serif"],
      },
    },
  },
  plugins: [
    // Forms reset plugin (normalizes the appearance of input elements)
    require("@tailwindcss/forms"),
  ],
};

Comments in a CSS file using @layer and @apply.

input.css

@tailwind base;
@tailwind components;
@tailwind utilities;

/* ==========================================================================
   Custom components
   ========================================================================== */

@layer components {
  /* Base button style.
     @apply is used here to share this style across multiple button variants.
     Combine with a variant class (btn-primary / btn-secondary). */
  .btn {
    @apply inline-block font-medium px-4 py-2 rounded transition-colors;
  }

  /* Primary button variant. */
  .btn-primary {
    @apply bg-blue-600 text-white hover:bg-blue-700;
  }

  /* Secondary button variant. */
  .btn-secondary {
    @apply bg-gray-200 text-gray-800 hover:bg-gray-300;
  }
}

/* ==========================================================================
   Custom utilities
   ========================================================================== */

@layer utilities {
  /* Utility to display text in the brand color. */
  .text-brand {
    color: #0066cc;
  }
}

Overview

Tailwind CSS comments follow the rules of each language:  in HTML, /* */ in CSS, and // or /* */ (JavaScript syntax) in configuration files.

Tailwind utility classes have concise names with clear functions, so individual class names often act as their own documentation. Information such as the layout structure intended by a combination of classes, the reasoning behind responsive breakpoints, or references to design tokens in the configuration file — in other words, "why this combination was chosen" — is the kind of context comments tend to capture well.

If you find any errors or copyright issues, please contact us.

Home

Tailwind CSS Dictionary