CSS Best Practices

Writing clean, maintainable CSS improves collaboration, performance, and scalability.

Code Organization

File Structure

css/
├── base/
│   ├── reset.css
│   ├── typography.css
│   └── variables.css
├── components/
│   ├── button.css
│   ├── card.css
│   └── modal.css
├── layout/
│   ├── header.css
│   ├── footer.css
│   └── grid.css
├── pages/
│   ├── home.css
│   └── about.css
└── main.css

CSS Order

/* 1. Reset/Normalize */
* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

/* 2. Custom Properties */
:root {
  --primary-color: #3498db;
}

/* 3. Base Styles */
body {
  font-family: Arial, sans-serif;
  line-height: 1.6;
}

/* 4. Layout Styles */
.container {
  max-width: 1200px;
  margin: 0 auto;
}

/* 5. Component Styles */
.button {
  padding: 10px 20px;
}

/* 6. Utility Classes */
.text-center {
  text-align: center;
}

Naming Conventions

BEM (Block Element Modifier)

/* Block */
.card { }

/* Element */
.card__title { }
.card__content { }
.card__button { }

/* Modifier */
.card--primary { }
.card__title--large { }

Functional Naming

/* Functional approach */
.container { }
.flex { }
.grid { }
.hidden { }
.visible { }
.text-center { }
.bg-primary { }
.mt-1 { }
.mb-2 { }

Avoid

/* Bad naming */
.blue { }
.small { }
.left { }
.div-wrapper { }

/* Good naming */
.button-primary { }
.text-small { }
.align-left { }
.card-wrapper { }

Responsive Design

Mobile-First

/* Base styles for mobile */
.container {
  padding: 1rem;
}

/* Add styles for larger screens */
@media (min-width: 768px) {
  .container {
    padding: 2rem;
  }
}

Use Relative Units

/* Good: Relative units */
h1 {
  font-size: 2rem;
}

.container {
  width: min(100%, 1200px);
}

/* Bad: Fixed units */
h1 {
  font-size: 32px;
}

.container {
  width: 1200px;
}

Performance

Minimize Reflows

/* Bad: Triggers layout */
.element {
  width: 100px;
  margin-left: 50px;
}

/* Good: Use transform */
.element {
  transform: translateX(50px);
}

Use Efficient Selectors

/* Bad: Specificity too high */
#main > div > ul > li > a { }

/* Good: Simple class */
.nav-link { }

Avoid Expensive Properties

/* Bad: Expensive */
.element {
  box-shadow: 0 0 100px rgba(0, 0, 0, 0.5);
}

/* Good: Simpler */
.element {
  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
}

Maintainability

Use CSS Variables

:root {
  --primary-color: #3498db;
  --spacing: 1rem;
}

.button {
  background-color: var(--primary-color);
  padding: var(--spacing);
}

Use Consistent Spacing

:root {
  --space-xs: 0.25rem;
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  --space-xl: 2rem;
}

.card {
  padding: var(--space-lg);
  margin-bottom: var(--space-md);
}

Keep Specificity Low

/* Bad: High specificity */
#main .card .title { }

/* Good: Low specificity */
.card-title { }

Complete Example: Button Component

/* Button base */
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: var(--space-sm) var(--space-md);
  font-size: var(--text-base);
  font-weight: 500;
  text-decoration: none;
  border: none;
  border-radius: var(--radius-md);
  cursor: pointer;
  transition: background-color 0.2s, transform 0.1s;
}

.button:hover {
  transform: translateY(-1px);
}

.button:active {
  transform: translateY(0);
}

.button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  transform: none;
}

/* Button variants */
.button--primary {
  background-color: var(--primary-color);
  color: white;
}

.button--primary:hover {
  background-color: var(--primary-dark);
}

.button--secondary {
  background-color: var(--secondary-color);
  color: white;
}

.button--outline {
  background-color: transparent;
  border: 2px solid var(--primary-color);
  color: var(--primary-color);
}

.button--outline:hover {
  background-color: var(--primary-color);
  color: white;
}

/* Button sizes */
.button--small {
  padding: var(--space-xs) var(--space-sm);
  font-size: var(--text-sm);
}

.button--large {
  padding: var(--space-md) var(--space-lg);
  font-size: var(--text-lg);
}

/* Button with icon */
.button__icon {
  margin-right: var(--space-sm);
}

Complete Example: Card Component

/* Card base */
.card {
  background-color: var(--bg-secondary);
  border-radius: var(--radius-lg);
  box-shadow: var(--shadow-sm);
  overflow: hidden;
  transition: box-shadow 0.2s, transform 0.2s;
}

.card:hover {
  box-shadow: var(--shadow-md);
  transform: translateY(-2px);
}

/* Card elements */
.card__image {
  width: 100%;
  height: 200px;
  object-fit: cover;
}

.card__content {
  padding: var(--space-lg);
}

.card__title {
  font-size: var(--text-xl);
  font-weight: 600;
  margin-bottom: var(--space-sm);
}

.card__text {
  color: var(--text-secondary);
  margin-bottom: var(--space-md);
}

.card__footer {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: var(--space-md) var(--space-lg);
  border-top: 1px solid var(--border-color);
}

/* Card modifier */
.card--featured {
  border: 2px solid var(--primary-color);
}

.card--horizontal {
  display: flex;
  flex-direction: row;
}

.card--horizontal .card__image {
  width: 300px;
  height: auto;
}

Complete Example: Utility Classes

/* Display */
.hidden { display: none; }
.block { display: block; }
.inline { display: inline; }
.inline-block { display: inline-block; }
.flex { display: flex; }
.grid { display: grid; }

/* Flexbox */
.flex-row { flex-direction: row; }
.flex-col { flex-direction: column; }
.items-center { align-items: center; }
.justify-center { justify-content: center; }
.justify-between { justify-content: space-between; }

/* Spacing */
.m-0 { margin: 0; }
.m-1 { margin: var(--space-sm); }
.m-2 { margin: var(--space-md); }
.m-3 { margin: var(--space-lg); }
.p-0 { padding: 0; }
.p-1 { padding: var(--space-sm); }
.p-2 { padding: var(--space-md); }
.p-3 { padding: var(--space-lg); }

/* Text */
.text-left { text-align: left; }
.text-center { text-align: center; }
.text-right { text-align: right; }
.text-sm { font-size: var(--text-sm); }
.text-base { font-size: var(--text-base); }
.text-lg { font-size: var(--text-lg); }
.font-bold { font-weight: 700; }

/* Colors */
.text-primary { color: var(--primary-color); }
.text-secondary { color: var(--text-secondary); }
.bg-primary { background-color: var(--primary-color); }
.bg-secondary { background-color: var(--bg-secondary); }

Checklist

Organization:

Logical file structure
Consistent CSS order
Grouped related styles

Naming:

BEM or consistent naming
Meaningful class names
No presentation-based names

Responsive:

Mobile-first approach
Relative units
Tested on multiple devices

Performance:

Efficient selectors
Minimal reflows
Optimized properties

Maintainability:

CSS variables
Consistent spacing
Low specificity

Common Mistakes

Over-specific selectors — Hard to override
Inconsistent naming — Confusing for team
Desktop-first approach — Less maintainable
Not using variables — Repetitive values
Overusing !important — Overrides everything
Ignoring performance — Slow animations
Not organizing code — Hard to find styles
Overusing utility classes — Clutters HTML