CSS · CSS Best Practices

CSS Documentation

Document your CSS for better maintainability and team collaboration

Find videos you like?

Save to resource drawer for future reference!

What is CSS Documentation?

Comments and explanations in your CSS that help others (and future you) understand the code

Explain complex or unusual CSS

Document component purposes

Note browser hacks and workarounds

Help team members understand code

Essential for large projects

Saves time during maintenance

Why Document CSS?

In 6 months, you won't remember why you wrote that complex CSS. Good documentation is like leaving notes for future you and your team - it explains the "why" behind the code, not just the "what"!

When to Add CSS Comments

What deserves documentation

🔧 Complex Solutions

Tricky CSS that's not obvious

Z-index management, flex hacks

🐛 Browser Workarounds

Fixes for specific browsers

IE11 fixes, Safari bugs

📦 Component Purpose

What the section does

Header, navigation, footer

⚠️ Important Notes

Warnings and gotchas

Don't change this value!

CSS Comment Styles

Different ways to document

1. Section Headers (Large Sections)

CSS

/**
 * ================================================
 * HEADER COMPONENT
 * ================================================
 * Main site header with logo, navigation, and search.
 * Used on all pages.
 * 
 * @author Design Team
 * @date 2024-12-13
 */

.header {
  /* styles here */
}

2. Block Comments (Components/Groups)

CSS

/* =================================
   Navigation Component
   ================================= */

.nav {
  display: flex;
  justify-content: space-between;
}

/* Navigation items */
.nav__item {
  padding: 10px 20px;
}

/* Active navigation state */
.nav__item--active {
  background: #3b82f6;
  color: white;
}

3. Inline Comments (Single Properties)

CSS

.element {
  /* Fix for IE11 flexbox bug */
  flex: 1 1 auto;
  
  /* Force hardware acceleration */
  transform: translateZ(0);
  
  /* Prevent text selection */
  user-select: none;
  
  /* Magic number - matches design spec */
  padding: 23px;
}

4. TODO Comments (Reminders)

CSS

/* TODO: Optimize this for mobile */
.gallery {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
}

/* FIXME: Safari rendering issue - investigate */
.card {
  backdrop-filter: blur(10px);
}

/* NOTE: Don't change this - it breaks the layout */
.sidebar {
  width: 250px;
}

Documentation Best Practices

How to write good CSS comments

✅ DO: Good Comments

Explain WHY

/* Z-index: 1000 to appear above modal */

Document Hacks

/* IE11 flexbox fix */

Section Headers

/* === HEADER SECTION === */

Warnings

/* WARNING: Don't modify */

❌ DON'T: Bad Comments

State the Obvious

/* Make text blue */ color: blue;

Redundant Comments

/* Set padding to 10px */ padding: 10px;

Outdated Comments

/* Works in all browsers */ -webkit-transform: ...

Commented-Out Code

/* .old-style { ... } */

Golden Rules for CSS Comments

✓ Explain WHY, not WHAT (code shows what it does)
✓ Document browser hacks and workarounds
✓ Use section headers for major components
✓ Keep comments up to date with code changes
✓ Delete outdated or commented-out code
✓ Be concise but clear

File Organization with TOC

Table of Contents for large CSS files

CSS File with Table of Contents

CSS

/**
 * ================================================
 * MAIN STYLESHEET
 * ================================================
 * 
 * Table of Contents:
 * 
 * 1. CSS Variables
 * 2. Reset & Base Styles
 * 3. Typography
 * 4. Layout
 *    4.1 Header
 *    4.2 Navigation
 *    4.3 Main Content
 *    4.4 Sidebar
 *    4.5 Footer
 * 5. Components
 *    5.1 Buttons
 *    5.2 Cards
 *    5.3 Forms
 *    5.4 Modals
 * 6. Utilities
 * 7. Media Queries
 * 
 * ================================================
 */


/* ================================================
   1. CSS VARIABLES
   ================================================ */

:root {
  --color-primary: #3b82f6;
  --color-secondary: #6b7280;
  --spacing-unit: 8px;
}


/* ================================================
   2. RESET & BASE STYLES
   ================================================ */

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

When Documentation is Essential

Critical scenarios

Team Projects

Multiple developers need to understand code

Large Codebases

Thousands of lines of CSS to maintain

Complex Layouts

Intricate CSS that needs explanation

Long-Term Projects

Code maintained for years

CSS Documentation Checklist

Section Headers: Use clear headers for major components and sections
Explain Complex CSS: Document tricky solutions and why they're needed
Browser Hacks: Always note browser-specific workarounds
Magic Numbers: Explain why specific values are used
TOC for Large Files: Add table of contents if file is 500+ lines
Update Comments: Keep documentation in sync with code changes
Remove Old Code: Delete commented-out CSS - use version control instead
Be Concise: Write clear, brief comments - avoid essays

Documentation Tools

StyleDocco: Generates style guides from CSS comments

KSS: Living style guide methodology

Storybook: Component explorer with documentation

Pattern Lab: Creates pattern libraries from code

Previous Topic

Best Practices

Coding standards, maintainability, scalability, team workflows, and professional CSS.

Next Topic

Refactoring

Cleaning up CSS, removing technical debt, improving structure, and maintenance strategies.

Ask a Question

Have a question about Documentation? Ask our AI assistant.

🔐 Login to use AI Assistant

CSS · CSS Best Practices

CSS Documentation

Document your CSS for better maintainability and team collaboration

Find videos you like?

Save to resource drawer for future reference!

What is CSS Documentation?

Comments and explanations in your CSS that help others (and future you) understand the code

Explain complex or unusual CSS

Document component purposes

Note browser hacks and workarounds

Help team members understand code

Essential for large projects

Saves time during maintenance

Why Document CSS?

In 6 months, you won't remember why you wrote that complex CSS. Good documentation is like leaving notes for future you and your team - it explains the "why" behind the code, not just the "what"!

When to Add CSS Comments

What deserves documentation

🔧 Complex Solutions

Tricky CSS that's not obvious

Z-index management, flex hacks

🐛 Browser Workarounds

Fixes for specific browsers

IE11 fixes, Safari bugs

📦 Component Purpose

What the section does

Header, navigation, footer

⚠️ Important Notes

Warnings and gotchas

Don't change this value!

CSS Comment Styles

Different ways to document

1. Section Headers (Large Sections)

CSS

/**
 * ================================================
 * HEADER COMPONENT
 * ================================================
 * Main site header with logo, navigation, and search.
 * Used on all pages.
 * 
 * @author Design Team
 * @date 2024-12-13
 */

.header {
  /* styles here */
}

2. Block Comments (Components/Groups)

CSS

/* =================================
   Navigation Component
   ================================= */

.nav {
  display: flex;
  justify-content: space-between;
}

/* Navigation items */
.nav__item {
  padding: 10px 20px;
}

/* Active navigation state */
.nav__item--active {
  background: #3b82f6;
  color: white;
}

3. Inline Comments (Single Properties)

CSS

.element {
  /* Fix for IE11 flexbox bug */
  flex: 1 1 auto;
  
  /* Force hardware acceleration */
  transform: translateZ(0);
  
  /* Prevent text selection */
  user-select: none;
  
  /* Magic number - matches design spec */
  padding: 23px;
}

4. TODO Comments (Reminders)

CSS

/* TODO: Optimize this for mobile */
.gallery {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
}

/* FIXME: Safari rendering issue - investigate */
.card {
  backdrop-filter: blur(10px);
}

/* NOTE: Don't change this - it breaks the layout */
.sidebar {
  width: 250px;
}

Documentation Best Practices

How to write good CSS comments

✅ DO: Good Comments

Explain WHY

/* Z-index: 1000 to appear above modal */

Document Hacks

/* IE11 flexbox fix */

Section Headers

/* === HEADER SECTION === */

Warnings

/* WARNING: Don't modify */

❌ DON'T: Bad Comments

State the Obvious

/* Make text blue */ color: blue;

Redundant Comments

/* Set padding to 10px */ padding: 10px;

Outdated Comments

/* Works in all browsers */ -webkit-transform: ...

Commented-Out Code

/* .old-style { ... } */

Golden Rules for CSS Comments

✓ Explain WHY, not WHAT (code shows what it does)
✓ Document browser hacks and workarounds
✓ Use section headers for major components
✓ Keep comments up to date with code changes
✓ Delete outdated or commented-out code
✓ Be concise but clear

File Organization with TOC

Table of Contents for large CSS files

CSS File with Table of Contents

CSS

/**
 * ================================================
 * MAIN STYLESHEET
 * ================================================
 * 
 * Table of Contents:
 * 
 * 1. CSS Variables
 * 2. Reset & Base Styles
 * 3. Typography
 * 4. Layout
 *    4.1 Header
 *    4.2 Navigation
 *    4.3 Main Content
 *    4.4 Sidebar
 *    4.5 Footer
 * 5. Components
 *    5.1 Buttons
 *    5.2 Cards
 *    5.3 Forms
 *    5.4 Modals
 * 6. Utilities
 * 7. Media Queries
 * 
 * ================================================
 */


/* ================================================
   1. CSS VARIABLES
   ================================================ */

:root {
  --color-primary: #3b82f6;
  --color-secondary: #6b7280;
  --spacing-unit: 8px;
}


/* ================================================
   2. RESET & BASE STYLES
   ================================================ */

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

When Documentation is Essential

Critical scenarios

Team Projects

Multiple developers need to understand code

Large Codebases

Thousands of lines of CSS to maintain

Complex Layouts

Intricate CSS that needs explanation

Long-Term Projects

Code maintained for years

CSS Documentation Checklist

Section Headers: Use clear headers for major components and sections
Explain Complex CSS: Document tricky solutions and why they're needed
Browser Hacks: Always note browser-specific workarounds
Magic Numbers: Explain why specific values are used
TOC for Large Files: Add table of contents if file is 500+ lines
Update Comments: Keep documentation in sync with code changes
Remove Old Code: Delete commented-out CSS - use version control instead
Be Concise: Write clear, brief comments - avoid essays

Documentation Tools

StyleDocco: Generates style guides from CSS comments

KSS: Living style guide methodology

Storybook: Component explorer with documentation

Pattern Lab: Creates pattern libraries from code

Coder Pod - Learn Programming Online | AI Coding Tutor & Interview Practice

Best Practices

Refactoring

Building Your Learning Module...

CSS Documentation

Why Document CSS?

🔧 Complex Solutions

🐛 Browser Workarounds

📦 Component Purpose

⚠️ Important Notes

1. Section Headers (Large Sections)

2. Block Comments (Components/Groups)

3. Inline Comments (Single Properties)

4. TODO Comments (Reminders)

✅ DO: Good Comments

❌ DON'T: Bad Comments

Golden Rules for CSS Comments

CSS File with Table of Contents

Team Projects

Large Codebases

Complex Layouts

Long-Term Projects

CSS Documentation Checklist

Documentation Tools

Best Practices

Refactoring

CSS Documentation

Why Document CSS?

🔧 Complex Solutions

🐛 Browser Workarounds

📦 Component Purpose

⚠️ Important Notes

1. Section Headers (Large Sections)

2. Block Comments (Components/Groups)

3. Inline Comments (Single Properties)

4. TODO Comments (Reminders)

✅ DO: Good Comments

❌ DON'T: Bad Comments

Golden Rules for CSS Comments

CSS File with Table of Contents

Team Projects

Large Codebases

Complex Layouts

Long-Term Projects

CSS Documentation Checklist

Documentation Tools