CSS Best Practices Skill

CSS Best Practices

Production-grade CSS development with architectural principles, proper specificity management, and maintainable patterns.

Core Principles

Single Responsibility - Each class handles one concern only
Open/Closed - Open for extension, closed for modification
Immutable CSS - Utilities and objects never change after creation
Behavior over implementation - Focus on what the code does, not how
Accessibility first - Semantic HTML before ARIA, proper contrast and sizing

Quick Reference

| Topic | Guide | | -------------------------------------------------------- | ----------------------------------------------------------------------- | | Specificity hierarchy, safe techniques, !important rules | specificity.md | | rem vs px, margins, layout algorithms | units-margins.md | | @extend vs mixins, refactoring workflow, code smells | preprocessors-refactoring.md | | Architectural principles and common code patterns | patterns.md |

When to Use Each Guide

Specificity

Use specificity.md when you need:

Specificity hierarchy and calculations
Safe techniques (self-chaining, attribute selectors)
Anti-patterns (IDs, deep nesting, qualified selectors)
!important rules (proactive vs reactive)
Shorthand property gotchas
Alternatives to reactive !important

Units and Margins

Use units-margins.md when you need:

rem vs px decision framework
Line-height best practices
Margin encapsulation rules
Single-direction margin patterns
Margin collapse behavior
Layout algorithm awareness (Flow, Flexbox, Grid)
Common gotchas (z-index, magic space under images)

Preprocessors and Refactoring

Use preprocessors-refactoring.md when you need:

@extend vs mixins guidance
Avoiding & concatenation
CSS @import performance issues
Finding dead CSS with beacons
The Three I's refactoring workflow
Code smell reference tables

Patterns

Use patterns.md when you need:

Single Responsibility Principle examples
Open/Closed Principle patterns
Immutable CSS patterns and prefixes
Component without margin examples
Utility class patterns
Self-chaining for specificity
CSS custom properties for design scales

Quick Reference: Decision Trees

Should I use !important?

Is this a utility class that must be immutable?
├── Yes → Use !important (proactive)
└── No → Is there a specificity conflict?
    ├── Yes → Try: self-chain, attribute selector, or restructure cascade
    └── No → Don't use !important

Should I use px or rem?

Should this scale with user font preferences?
├── Yes → Use rem
│   Examples: font-size, vertical text margins, media queries
└── No → Use px
    Examples: borders, box-shadows, horizontal padding

Should I use shorthand?

Am I intentionally setting ALL related properties?
├── Yes → Shorthand is fine
└── No → Use longhand to avoid unintentional resets

Should component have margin?

Is this a layout component (grid, stack, container)?
├── Yes → Margin/gap is appropriate
└── No → Move spacing to parent or use utility classes

@extend or mixin?

Are these selectors thematically related (same component)?
├── Yes → @extend might be acceptable
└── No → Use mixin (safer, doesn't disrupt source order)

How should I refactor this CSS?

Step 1: Identify - Is this frequently used and problematic?
├── Yes → Continue
└── No → Skip refactoring, focus elsewhere

Step 2: Isolate - Build new version separately
├── Use CodePen/jsFiddle
└── Don't build on top of existing CSS

Step 3: Implement - Reintegrate carefully
├── Component fixes → component's partial
└── Legacy conflicts → shame.css

Summary Checklist

Before committing CSS, verify:

[ ] Classes follow single responsibility (structure separate from cosmetics)
[ ] No ID selectors for styling
[ ] No reactive !important (only proactive for utilities)
[ ] Components have no margin (spacing controlled by parent)
[ ] Using rem for font-size and scalable spacing
[ ] Using px for borders, shadows, and fixed visual elements
[ ] Longhand properties when only setting one value
[ ] No deep nesting (4+ levels)
[ ] No qualified selectors (e.g., ul.nav)
[ ] Layout algorithm appropriate for context (Flow, Flex, Grid)
[ ] Accessible color contrast ratios
[ ] Semantic HTML before adding ARIA

Agent Skills: CSS Best Practices

Install this agent skill to your local

Skill Files