1 篇博文 含有标签「theme.json」

在为客户开发 WordPress FSE 企业主题时，发现 Footer 区块在多个 Style Variation 下文字几乎不可见。本文记录从 WCAG 对比度诊断到引入语义色、处理全局样式覆盖的完整修复过程。

TL;DR​

问题：FSE 主题的 contrast 颜色 token 语义混乱，浅色主题中 contrast ≈ 浅灰 ≈ base（白色），导致 Footer 对比度仅 1.05:1。

解法：

1. 引入 surface 语义色，专用于深色区块背景
2. 删除 wp_global_styles 中的覆盖样式
3. 所有 Style Variations 同步添加 surface 定义

结果：对比度从 1.05:1 提升至 15.8:1（WCAG AAA 级）。

问题现象​

Footer 区块使用 backgroundColor="contrast" + textColor="base"：

<!-- wp:group {"backgroundColor":"contrast","textColor":"base"} -->
<div class="has-base-color has-contrast-background-color">
  Footer 内容
</div>

在默认主题下，Footer 文字几乎不可见：

WCAG AA 标准要求普通文字对比度 ≥ 4.5:1，当前状态远不达标。

根因分析​

1. contrast 语义混乱​

contrast 的设计意图是"与 base 形成对比的背景色"，但在不同主题模式下语义矛盾：

Footer Pattern 假设 contrast 是深色背景，但 5/6 的 Style Variations 中它是浅色。

2. 颜色语义缺乏明确用途定义​

原设计系统只有 contrast 一个"对比色"，没有区分：

• 浅色对比区块（CTA Banner 等强调区域）
• 深色对比区块（Footer、暗色 Hero 等）

解决方案​

Step 1：引入 surface 语义色​

在 theme.json 中新增 surface token，专用于深色区块背景：

{
  "slug": "surface",
  "color": "#0f172a",
  "name": "Surface"
}

Step 2：更新所有 Style Variations​

每个 variation 定义自己的 surface 色（通常等于 primary）：

// styles/commerce.json
{ "slug": "surface", "color": "#1f2937", "name": "Surface" }

// styles/nature.json
{ "slug": "surface", "color": "#14532d", "name": "Surface" }

// styles/tech.json（深色主题）
{ "slug": "surface", "color": "#1e1e2e", "name": "Surface" }

Step 3：修改 Footer 模板​

<!-- wp:group {"backgroundColor":"surface","textColor":"base"} -->
<div class="has-base-color has-surface-background-color">
  Footer 内容
</div>

Step 4：删除全局样式覆盖​

修改 theme.json 后颜色仍不生效？检查全局样式：

# 检查是否存在全局样式
docker exec wp_cli wp post list --post_type=wp_global_styles --fields=ID,post_title --allow-root

# 删除全局样式
docker exec wp_cli wp post delete <ID> --force --allow-root
docker exec wp_cli wp cache flush --allow-root

原因：wp_global_styles 中的 color.palette 会完全覆盖（非合并）theme.json 的调色板。

修复结果​

颜色语义总结​

对类似需求感兴趣？联系合作