Shopify CSS Guidelines

When to Use

• Writing CSS for Shopify theme sections
• Naming CSS classes
• Deciding when to use CSS nesting
• Encapsulating section styles

CSS Naming - BEM Methodology

.block {}
.block__element {}
.block__element--modifier {}

Naming Rules

• Class names should be short, semantic, and intentional
• Avoid generic or visual-based naming
• Use BEM structure:

  .block__element--modifier

Examples

/* Good - BEM structure */
.product-card {}
.product-card__image {}
.product-card__title {}
.product-card__price {}
.product-card__button {}
.product-card__button--primary {}

/* Bad - generic or visual naming */
.red-button {}
.big-text {}
.container {}

CSS Scope & Encapsulation

• To avoid style leakage between sections
• To protect a section from theme-level styles
• Only inside a section scope

CSS Nesting

When to Use Nesting

• Section-level namespacing
• Block → element structure inside a section
• Pseudo-classes and state modifiers

Nesting Rules

• Nesting must stay inside a section scope
• Keep nesting depth minimal (1–2 levels max)
• Use nesting for BEM structure:

  .block { .block__element {} }

Allowed Use Cases

/* Section-level namespacing */
.featured-collection {
  padding: 2rem;
}

.featured-collection__grid {
  display: grid;
  gap: 1rem;
}

.featured-collection__item {
  /* Block element */
}

.featured-collection__item:hover {
  /* Pseudo-class */
}

.featured-collection__item--featured {
  /* Modifier */
}

Not Allowed

• Deep nesting (more than 2 levels)
• Cross-block dependencies
• Assuming nested styles are globally reusable

/* Bad - too deep */
.section {
  .block {
    .element {
      .sub-element {
        /* 3+ levels - avoid */
      }
    }
  }
}

/* Bad - cross-block dependency */
.section-a {
  .section-b__element {
    /* Don't style other sections' elements */
  }
}

Section CSS Structure

/* featured-collection.css */
.featured-collection {
  /* Section wrapper */
}

.featured-collection__header {
  /* Section header */
}

.featured-collection__grid {
  /* Main content area */
}

.featured-collection__item {
  /* Grid item */
}

.featured-collection__item:hover {
  /* Hover state */
}

@media (max-width: 749px) {
  .featured-collection__grid {
    /* Mobile styles */
  }
}

Shopify Theme Documentation

• Shopify Templates
• Liquid Filters (for CSS asset handling)

Instructions

1. Use BEM naming for all classes inside sections
2. Keep names semantic - describe purpose, not appearance
3. Encapsulate styles within section scope
4. Limit nesting to 1–2 levels maximum
5. One CSS file per section - never mix multiple sections
6. Use nesting only for BEM structure and pseudo-classes