在 Shopify Liquid 主题中编写…

当你在 .liquid 文件或主题资源文件中编写 CSS、JavaScript、HTML 时，用这套规范保证渐进增强、设计令牌、BEM 命名与防御性样式。

适用场景

解决思路

1. 遵循核心原则：渐进增强（语义 HTML 优先，CSS 次之，JS 最后）、不引入外部依赖（仅用原生浏览器 API）、使用设计令牌（绝不硬编码颜色/间距/字体）、统一 BEM 命名、编写防御性 CSS。
2. 按位置放置 CSS：`{% stylesheet %}` 用于组件作用域样式（每个文件一个，不处理 Liquid）；`{% style %}` 用于需要 Liquid 的动态值；`assets/*.css` 用于共享/全局样式。
3. 注意 `{% stylesheet %}` 不处理 Liquid，动态值改用内联 style 属性设置 CSS 变量，例如 `<div class="hero" style="--bg-color: {{ section.settings.bg_color }};">`。
4. 遵循 BEM 命名：`.block`、`.block__element`、`.block--modifier`、`.block__element--modifier`；用连字符分隔单词（`.product-card` 而非 `.productCard`）；只允许单层元素（`.block__element`，禁止 `.block__el1__el2`）；修饰符必须与基础类同时使用（`class="btn btn--primary"`）；当子元素可独立存在时开启新的 BEM 作用域。
5. 控制选择器特异性：尽量保持 `0 1 0`（单类），复杂父子场景最多 `0 4 0`；禁止用 ID 作选择器；禁止用 `!important`（万不得已时注释说明原因）；避免元素选择器，改用类。
6. 使用 CSS 嵌套：媒体查询写在选择器内部；用 `&` 写状态修饰符（`:hover`、`:focus-visible`、`[disabled]`）；父修饰符影响子元素只嵌套一层；禁止嵌套超过第一层。
7. 使用设计令牌：所有值用 CSS 自定义属性，绝不硬编码颜色/间距/字体；定义一致的尺度（如 `--space-2xs` 到 `--space-xl`、`--font-size-sm` 到 `--font-size-2xl`）；间距和排版用 `rem`；令牌语义化命名（`--space-sm` 而非 `--space-16`）；全局令牌定义在 `:root`，组件令牌定义在组件根。
8. CSS 变量作用域：全局变量放 `:root`；组件变量放组件根并加命名空间（如 `.facets { --facets-padding: var(--space-md); }`），避免通用名冲突；通过内联 style 覆盖 section/block 设置。
9. 按固定顺序书写 CSS 属性：1) 布局（position、display、flex-direction、grid-template-columns）；2) 盒模型（width、margin、padding、border）；3) 排版（font-family、font-size、line-height、color）；4) 视觉（background、opacity、border-radius）；5) 动画（transition、animation）。
10. 使用逻辑属性支持 RTL：用 `padding-inline`、`padding-block`、`margin-inline`、`border-inline-end`、`text-align: start`、`inset: 0`，避免 `padding-left`、`text-align: left`、`top/right/bottom/left` 等物理属性。
11. 编写防御性 CSS：`overflow-wrap: break-word` 防文本溢出；`min-width: 0` 允许 flex 项收缩；`max-width: 100%` 约束图片/媒体；`isolation: isolate` 创建层叠上下文；图片容器用 `aspect-ratio` 防布局偏移并以背景色兜底。
12. 使用现代 CSS 特性：容器查询（`container-type: inline-size` + `@container`）实现响应式组件；`clamp()` 实现流式间距；`min()` 实现内在尺寸。
13. 性能优化：只动画 `transform` 和 `opacity`（绝不动画布局属性）；谨慎使用 `will-change` 并在动画后移除；用 `contain: content` 隔离渲染；移动端用 `dvh` 替代 `vh`。
14. 支持减少动效：在 `@media (prefers-reduced-motion: reduce)` 中把动画/过渡时长设为 `0.01ms`、迭代次数设为 1、`scroll-behavior: auto`。
15. 按位置放置 JS：`{% javascript %}` 用于组件专属脚本（每个文件一个，不处理 Liquid）；`assets/*.js` 用于共享工具和 Web Components。
16. 使用 Web Component 模式：继承 `HTMLElement`，在 `connectedCallback` 中查询元素并绑定事件，在 `disconnectedCallback` 中清理监听器和 AbortController，用 `customElements.define` 注册，在 Liquid 中以自定义标签使用并传 `data-*` 属性。
17. 遵循 JavaScript 规则：循环用 `for (const item of items)` 而非 `forEach()`；异步用 `async`/`await` 而非 `.then()` 链；默认用 `const`，仅在重新赋值时用 `let`；用提前返回替代嵌套 `if/else`；URL 用 `new URL()` + `URLSearchParams` 而非字符串拼接；依赖用原生浏览器 API 而非外部库；私有方法用 `#methodName()` 而非 `_methodName()`；类型用 JSDoc `@typedef`/`@param`/`@returns`。
18. 用 AbortController 管理 fetch：每次请求前 abort 上一个控制器并新建，捕获时忽略 `AbortError`，在 `disconnectedCallback` 中 abort。
19. 组件通信：父传子调用子组件公开方法（`this.querySelector('child-component')?.publicMethod(data)`）；子传父派发冒泡的自定义事件（`new CustomEvent('child:action', { detail, bubbles: true })`）。
20. HTML 优先使用原生元素：可展开用 `<details>/<summary>` 而非自定义 JS 手风琴；对话框用 `<dialog>` 而非自定义遮罩 div；提示/弹窗用 `popover` 属性；搜索表单用 `<search>`；表单结果用 `<output>`。
21. 实现渐进增强：先用 `<details>` 等原生元素保证无 JS 可用，再用 `{% javascript %}` 增强（平滑动画、分析追踪）。
22. 图片处理：用 `image_url` + `image_tag` 过滤器；首屏以下图片加 `loading: 'lazy'`；始终设置 `width` 和 `height` 防布局偏移；写描述性 `alt`，装饰性图片用空 `alt=""`。
23. 编辑 JSON 模板与配置文件（`templates/*.json`、`sections/*.json`、`config/settings_data.json`）时用 `jq` 做外科手术式修改，比字符串查找替换更安全可靠；常见操作：添加 section、更新设置值、重排 section（`.order += [...]`）、删除 section（`del(...) | .order -= [...]`）、读取嵌套值；任何 `.json` 修改都优先用 `jq` 而非 `edit`。

适用边界 · 注意事项

• `{% stylesheet %}` 和 `{% javascript %}` 不处理 Liquid，因此不要在其中写 Liquid 变量或标签。
• 不要用 ID 作 CSS 选择器，不要用 `!important`，不要嵌套超过第一层，不要用物理属性（需支持 RTL 时）。
• 不要引入外部 JS 库或依赖，不要用 `forEach()`、`.then()` 链、`_methodName()` 私有命名等非推荐写法。