Skip to main content

Theme Styling Guide

Best practices for theme CSS.

CSS Architecture​

Variables First​

Define all customizable values as CSS variables:

:root {
  /* Colors */
  --color-primary: var(--theme-primary, #8b5cf6);
  --color-secondary: var(--theme-secondary, #0ea5e9);
  
  /* Typography */
  --font-heading: var(--theme-font-heading, 'Inter');
  --font-body: var(--theme-font-body, 'Inter');
  
  /* Spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  --spacing-xl: 4rem;
}

BEM Naming​

Use BEM for class names:

/* Block */
.hero {}

/* Element */
.hero__title {}
.hero__subtitle {}
.hero__cta {}

/* Modifier */
.hero--dark {}
.hero--centered {}

Utility Classes​

Provide common utilities:

.text-center { text-align: center; }
.text-left { text-align: left; }
.text-right { text-align: right; }

.mt-1 { margin-top: var(--spacing-sm); }
.mt-2 { margin-top: var(--spacing-md); }
.mt-3 { margin-top: var(--spacing-lg); }

.hidden { display: none; }
.visible { display: block; }

Responsive Design​

Mobile-First​

/* Base (mobile) */
.container {
  padding: 1rem;
}

/* Tablet */
@media (min-width: 768px) {
  .container {
    padding: 2rem;
  }
}

/* Desktop */
@media (min-width: 1024px) {
  .container {
    padding: 4rem;
    max-width: 1200px;
    margin: 0 auto;
  }
}

Breakpoints​

Standard breakpoints:

/* Mobile: default */
/* Tablet: 768px */
/* Desktop: 1024px */
/* Wide: 1280px */

Dark Mode​

Support dark mode:

:root {
  --bg-color: #ffffff;
  --text-color: #1f2937;
}

[data-theme="dark"] {
  --bg-color: #0f172a;
  --text-color: #f1f5f9;
}

body {
  background: var(--bg-color);
  color: var(--text-color);
}

Performance​

  1. Minimize specificity — Avoid deep nesting
  2. Use CSS variables — Reduce duplication
  3. Optimize selectors — Prefer classes over tags
  4. Bundle styles — Combine into single file