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 模板
Liquid 过滤器（用于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结构和伪类使用嵌套