How do I enforce Idiomatic CSS rules in my team?

Use CSS linters like Stylelint with custom configurations based on the guide, integrate EditorConfig for basic formatting, and establish code review processes. This requires manual setup but ensures consistency across contributions.

Idiomatic CSS or BEM: which should I use?

Idiomatic CSS is a style guide for code formatting and structure, while BEM is a naming convention for CSS classes. They serve different purposes and can be combined; use Idiomatic CSS for consistent code layout and BEM for scalable selector naming.

Can I use Idiomatic CSS with React and CSS-in-JS?

The core principles of consistency and readability can apply, but specific formatting rules might not directly translate to CSS-in-JS syntax like Styled Components. You may need to adapt guidelines for inline styles or template literals.

What's the best way to comment CSS code?

Following Idiomatic CSS, use section comment blocks for major components, Doxygen-style for detailed descriptions, and keep comments concise and on new lines above the subject, as detailed in the Comments section with practical examples.

How to adapt Idiomatic CSS for a Sass project?

Extend the guidelines with the preprocessor considerations provided, such as limiting nesting depth to 1-2 levels and placing @extend statements first in declaration blocks, as shown in the 'Preprocessors' subsection.

Is Idiomatic CSS still relevant with modern CSS frameworks?

Yes, for foundational code consistency, but it may need supplementation for framework-specific practices. Its principles on readability and maintainability are timeless, though some details might require updates for new CSS features.

Idiomatic CSS — CSS Style Guide

What is Idiomatic CSS?

Idiomatic CSS is a style guide that provides principles and conventions for writing consistent, maintainable CSS code. It solves the problem of inconsistent CSS styles across teams by establishing sensible patterns that ensure code readability and uniformity. The guide covers everything from whitespace and formatting to commenting practices and preprocessor considerations.

Target Audience

Frontend developers, CSS authors, and development teams who need to establish or follow consistent CSS coding standards. It's particularly valuable for teams with multiple contributors working on the same codebase.

Value Proposition

Developers choose Idiomatic CSS because it provides a comprehensive, battle-tested foundation for CSS style guides that emphasizes clarity over cleverness. Its practical examples and detailed formatting rules make it easy to implement, while its focus on team consistency helps prevent style fragmentation.

Principles of writing consistent, idiomatic CSS.

Use Cases

Best For

Establishing team-wide CSS coding standards
Creating a consistent style guide for new projects
Improving CSS code readability and maintainability
Training junior developers on CSS best practices
Standardizing CSS across large codebases with multiple contributors
Extending style guidelines to include Sass or other preprocessors

Not Ideal For

Projects using CSS-in-JS or utility-first frameworks like Tailwind CSS, where inline styles or utility classes dominate
Solo developers or very small teams where enforcing a comprehensive style guide adds unnecessary overhead
Codebases already committed to a specific CSS methodology like BEM or SMACSS with conflicting formatting rules
Teams seeking automated linting and formatting tools without manual style guide integration

Pros & Cons

Pros

Comprehensive Formatting Rules

Provides detailed guidelines on whitespace, indentation, declaration order, and selector formatting, as shown in sections 2 and 4, ensuring uniform code across teams.

Detailed Commenting Standards

Includes standards for comments, such as Doxygen-style descriptions and section blocks, which enhance code documentation and clarity, illustrated in the Comments section.

Preprocessor Adaptability

Extends conventions to Sass with rules for nesting limits, @extend and @include placement, making it suitable for modern preprocessor workflows, as detailed in the Format section.

Practical Implementation Examples

Offers complete code examples, like the grid layout, demonstrating how to apply all principles in real-world scenarios for easier adoption.

Cons

No Built-in Automation

Requires teams to set up external tools like linters or formatters for enforcement, as it's purely a documentation-based style guide without integrated tooling.

Potentially Overly Rigid

The strict rules, such as preferences for spaces over tabs or specific declaration orders, might not flexibly accommodate all team preferences or modern CSS practices.

Limited Modern CSS Coverage

Focuses on foundational formatting but doesn't extensively address newer CSS features like Grid, Flexbox, or CSS Custom Properties, requiring supplementary guidelines.

What is Idiomatic CSS?

Target Audience

Value Proposition

Use Cases

Best For

Establishing team-wide CSS coding standards
Creating a consistent style guide for new projects
Improving CSS code readability and maintainability
Training junior developers on CSS best practices
Standardizing CSS across large codebases with multiple contributors
Extending style guidelines to include Sass or other preprocessors

Not Ideal For

Projects using CSS-in-JS or utility-first frameworks like Tailwind CSS, where inline styles or utility classes dominate
Solo developers or very small teams where enforcing a comprehensive style guide adds unnecessary overhead
Codebases already committed to a specific CSS methodology like BEM or SMACSS with conflicting formatting rules
Teams seeking automated linting and formatting tools without manual style guide integration

Pros & Cons

Pros

Comprehensive Formatting Rules

Provides detailed guidelines on whitespace, indentation, declaration order, and selector formatting, as shown in sections 2 and 4, ensuring uniform code across teams.

Detailed Commenting Standards

Includes standards for comments, such as Doxygen-style descriptions and section blocks, which enhance code documentation and clarity, illustrated in the Comments section.

Preprocessor Adaptability

Extends conventions to Sass with rules for nesting limits, @extend and @include placement, making it suitable for modern preprocessor workflows, as detailed in the Format section.

Practical Implementation Examples

Offers complete code examples, like the grid layout, demonstrating how to apply all principles in real-world scenarios for easier adoption.

Cons

No Built-in Automation

Requires teams to set up external tools like linters or formatters for enforcement, as it's purely a documentation-based style guide without integrated tooling.

Potentially Overly Rigid

The strict rules, such as preferences for spaces over tabs or specific declaration orders, might not flexibly accommodate all team preferences or modern CSS practices.

Limited Modern CSS Coverage

Focuses on foundational formatting but doesn't extensively address newer CSS features like Grid, Flexbox, or CSS Custom Properties, requiring supplementary guidelines.

Idiomatic CSS

What is Idiomatic CSS?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Idiomatic CSS

What is Idiomatic CSS?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?