theme-shopify-css-guidelines

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shopify CSS Guidelines

Shopify CSS 指南

CSS naming conventions, nesting rules, and encapsulation practices for Shopify theme development.

本文介绍Shopify主题开发中的CSS命名规范、嵌套规则及封装实践。

When to Use

适用场景

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

编写Shopify主题板块的CSS代码
为CSS类命名
决定何时使用CSS嵌套
封装板块样式

CSS Naming - BEM Methodology

CSS命名 - BEM方法论

Use BEM (Block Element Modifier) methodology for structure inside a section:

css

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

在板块内部使用**BEM（Block Element Modifier，块-元素-修饰符）**方法论来构建结构：

css

.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
```

类名应简短、语义化且表意明确
避免使用通用或基于视觉效果的命名
使用BEM结构:
```
.block__element--modifier
```

Examples

示例

css

/* 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

/* 推荐 - BEM结构 */
.product-card {}
.product-card__image {}
.product-card__title {}
.product-card__price {}
.product-card__button {}
.product-card__button--primary {}

/* 不推荐 - 通用或视觉化命名 */
.red-button {}
.big-text {}
.container {}

CSS Scope & Encapsulation

CSS作用域与封装

Encapsulation is allowed:

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

Each section should have its own scoped styles to prevent conflicts.

允许进行封装的场景：

避免样式在不同板块之间泄漏
保护板块不受主题全局样式的影响
仅在板块作用域内使用

每个板块都应有自己的作用域样式，以防止样式冲突。

CSS Nesting

CSS嵌套

Native CSS nesting is allowed, but with strict rules.

允许使用原生CSS嵌套，但需遵循严格规则。

When to Use Nesting

嵌套适用场景

Use nesting only where encapsulation is required:

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 {} }
```

嵌套必须保持在板块作用域内
尽量减少嵌套深度（最多1–2层）
使用嵌套来构建BEM结构:
```
.block { .block__element {} }
```

Allowed Use Cases

允许的使用场景

css

/* 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 */
}

css

/* 板块级命名空间 */
.featured-collection {
  padding: 2rem;
}

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

.featured-collection__item {
  /* 块元素 */
}

.featured-collection__item:hover {
  /* 伪类 */
}

.featured-collection__item--featured {
  /* 修饰符 */
}

Not Allowed

不允许的情况

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

css

/* 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 */
  }
}

深层嵌套（超过2层）
跨块依赖
假设嵌套样式可全局复用

css

/* 不推荐 - 嵌套过深 */
.section {
  .block {
    .element {
      .sub-element {
        /* 3层及以上 - 避免使用 */
      }
    }
  }
}

/* 不推荐 - 跨块依赖 */
.section-a {
  .section-b__element {
    /* 不要为其他板块的元素设置样式 */
  }
}

Section CSS Structure

板块CSS结构

Each section should have its own CSS file with scoped styles:

css

/* 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 */
  }
}

每个板块都应有独立的CSS文件，包含作用域样式：

css

/* featured-collection.css */
.featured-collection {
  /* 板块容器 */
}

.featured-collection__header {
  /* 板块头部 */
}

.featured-collection__grid {
  /* 主内容区域 */
}

.featured-collection__item {
  /* 网格项 */
}

.featured-collection__item:hover {
  /* 悬停状态 */
}

@media (max-width: 749px) {
  .featured-collection__grid {
    /* 移动端样式 */
  }
}

Shopify Theme Documentation

Shopify主题官方文档

Reference these official Shopify resources:

Shopify Templates
Liquid Filters (for CSS asset handling)

参考以下Shopify官方资源：

Shopify Templates
Liquid Filters（用于CSS资源处理）

Instructions

操作指引

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

使用BEM命名板块内的所有类
保持命名语义化 - 描述用途而非外观
在板块作用域内封装样式
限制嵌套深度最多1–2层
每个板块对应一个CSS文件 - 切勿混合多个板块的样式
仅在BEM结构和伪类中使用嵌套