Skip to main content

CSS Comments and Documentation Conventions

CSS comments are more than syntax — they are your documentation system, your team communication layer, and your AI context tool. Used strategically, they transform a CSS file from a list of rules into a self-explaining codebase.

1. CSS Comment Syntax​

CSS has exactly one comment syntax: /* */

/* This is a single-line CSS comment */

/*
  This is a
  multi-line CSS comment
*/

.selector {
  property: value;   /* Inline comment explaining this value */
}

[!IMPORTANT] CSS does not support // single-line comments. // is invalid in plain CSS. Use /* */ for all CSS comments regardless of what you're commenting.

// This is NOT valid CSS ❌ (will cause parse errors in some browsers)
/* This IS valid CSS ✅ */

2. Sass Comments: // vs /* */​

If you use Sass/SCSS, you have two comment types with different behaviors:

// Sass single-line comment — NOT compiled to CSS output
/* CSS comment — IS compiled to CSS output */

// This comment disappears from the final CSS file ✅ Good for dev notes
/* This comment appears in the compiled CSS — use for docs */

// Example in a component file:
// TODO: Add dark mode variant
// HACK: Weird Safari 15 bug — padding fixes render glitch

/*
 * Component: .c-btn
 * Author: Your Name
 * Last updated: 2026-04-28
 */
.c-btn { padding: 0.7rem 1.5rem; }

3. Strategic Comment Patterns​

Pattern 1: The Component Header Block​

Every component file or component section starts with a header block:

/* ============================================================
   Component: Card
   File:      components/_card.scss
   ============================================================
   Block:      .c-card
   Elements:   .c-card__image, .c-card__body, .c-card__title,
               .c-card__text, .c-card__footer, .c-card__btn
   Modifiers:  .c-card--featured, .c-card--dark, .c-card--horizontal
   States:     .is-loading, .is-selected
   JS hooks:   .js-card-link
   ============================================================ */

Pattern 2: Section Dividers​

Divide a large CSS file into clearly labeled sections:

/* ─────────────────────────────────────────────
   RESET
───────────────────────────────────────────── */

/* ─────────────────────────────────────────────
   DESIGN TOKENS
───────────────────────────────────────────── */

/* ─────────────────────────────────────────────
   TYPOGRAPHY
───────────────────────────────────────────── */

/* ─────────────────────────────────────────────
   COMPONENTS: BUTTONS
───────────────────────────────────────────── */

Pattern 3: Property Explanation Comments​

.c-nav {
  position: sticky;
  top: 0;                          /* Sticks to top of viewport */
  z-index: var(--z-sticky);        /* Above content, below modals */
  backdrop-filter: blur(20px);     /* Glass effect — requires bg transparency */
  background: rgba(15,15,15,0.85); /* Must be semi-transparent for blur to show */
  will-change: transform;          /* Promote to GPU layer for smooth scroll */
}

Pattern 4: Warning Comments — Never Delete This​

/* !!! WARNING: This class is referenced in JavaScript
   nav.classList.toggle('is-open')
   DO NOT rename or delete without updating main.js line 47 */
.is-open { display: flex; }

/* !!! WARNING: WordPress adds .admin-bar to <body> when logged in.
   This adds 32px margin-top. The sticky nav offset accounts for this. */
.admin-bar .c-nav { top: 32px; }

Pattern 5: TODO and FIXME Comments​

/* TODO: Add .c-btn--loading state after JS integration */
.c-btn--primary { background: var(--color-primary); }

/* FIXME: Safari 16 bug — transform breaks position:sticky inside flex */
/* workaround: adding will-change: auto resolves the issue */
.c-hero { will-change: auto; }

/* HACK: WooCommerce forces 0 padding on checkout inputs — override needed */
.woocommerce .c-form__input { padding: 0.75rem 1rem !important; }

/* REVIEW: Client asked for 1.5rem gap — check mobile layout */
.c-feature-grid { gap: 1.5rem; }

Pattern 6: Source Reference Comments​

/* Technique from: https://css-tricks.com/the-trick-to-viewport-units-on-mobile/ */
.c-hero { min-height: 100dvh; }

/* Algorithm: Kevin Powell's fluid type scale — type.scale.com */
--text-xl: clamp(1.25rem, 1rem + 1.5vw, 2rem);

/* Based on: CUBE CSS by Andy Bell — cube.fyi */

4. AI-Optimized Comments​

When working with AI, comments become context signals. Well-commented CSS helps AI understand your system:

/* Design tokens — reference these in all components */
:root {
  --color-primary: hsl(245, 80%, 58%);    /* Main brand color — purple */
  --color-bg: #0f0f0f;                    /* Page background — very dark */
  --color-surface: #1a1a1a;               /* Card/component surface */
  --color-text: #f0f0f0;                  /* Primary text — near white */
  --color-text-muted: #888888;            /* Secondary text */
  --radius-lg: 1rem;                      /* Standard large border radius */
  --shadow-md: 0 4px 12px rgba(0,0,0,0.5); /* Standard card shadow */
}

/*
 * Component: .c-card
 * Pattern: BEM — Block / Element / Modifier
 * Usage: Blog cards, product cards, feature cards
 * Responsive: Stacks vertically below 640px
 * Dark mode: Automatic via CSS variables — no extra overrides needed
 */
.c-card {
  background: var(--color-surface);  /* Uses surface token not bg — one level up */
  border: 1px solid rgba(255,255,255,0.06);
  border-radius: var(--radius-lg);
}

AI Prompt that uses comments as context:

Read the comments in this CSS file — they describe the design system.
Build a new .c-testimonial component that follows the same patterns.
[PASTE COMMENTED CSS]

5. Comments in the ITCSS/7-1 Architecture​

Each file in the 7-1 Sass structure should follow this comment pattern:

// ============================================================
// COMPONENT: Button
// ============================================================
// Block:      .c-btn
// Description: Primary interactive element. Used for all CTAs,
//              form submissions, and navigation actions.
//
// Elements:
//   .c-btn__icon      - Optional leading/trailing icon
//   .c-btn__label     - Text label (use for sr-only text)
//
// Modifiers:
//   .c-btn--primary   - Main CTA style (filled, color-primary)
//   .c-btn--outline   - Secondary CTA (bordered, transparent bg)
//   .c-btn--ghost     - Tertiary (no border, hover bg)
//   .c-btn--danger    - Destructive action
//   .c-btn--sm        - Compact size
//   .c-btn--lg        - Large size
//   .c-btn--block     - Full width
//
// States:
//   .is-loading       - Shows spinner, disables pointer events
//   :disabled         - Native disabled state
//
// JS Hooks:
//   .js-submit-btn    - Bound to form submit handler
//
// Usage:
//   <button class="c-btn c-btn--primary">Click me</button>
//   <a href="#" class="c-btn c-btn--outline">Learn More</a>
// ============================================================

6. CSS Comment Anti-Patterns​

/* ❌ Useless comments — state what isn't obvious */
color: red;           /* Sets the color to red */  /* Obvious — don't do this */
margin: 0;            /* Remove margin */           /* Obvious — skip it */
display: flex;        /* Display flex */            /* Obvious — skip it */

/* ✅ Useful comments — explain WHY, not WHAT */
color: red;           /* Error state — matches brand danger color */
margin: 0 0 0 auto;   /* Push to far right in flex container */
display: flex;        /* Needed to align icon vertically with text */


/* ❌ Outdated comments — worse than no comment */
/* OLD: background: blue; */
background: var(--color-primary);   /* The old comment confuses readers */

/* ✅ Delete outdated comments — use git history if you need old values */
background: var(--color-primary);


/* ❌ Commented-out code blocks in production */
/*
.old-card {
  background: #fff;
  padding: 20px;
  border: 1px solid #ddd;
}
*/
/* ✅ Delete it — it lives in git. Commented-out code is noise. */

7. Comment Consistency Checklist​

For every component file:
□ Component header block with block/element/modifier/state/js-hook list
□ Inline comment on any non-obvious value (z-index, will-change, opacity hack)
□ WARNING comment on any class referenced by JavaScript
□ TODO comment for planned additions not yet built
□ FIXME comment for known browser bugs or workarounds
□ Reference link for any technique taken from an external source

For the main CSS file:
□ Section divider comments for each category
□ Token comments explaining each design token's purpose
□ File map comment at the top listing all section headers