用 theme.json 搭一套统一设计系统：颜色、字号、间距怎么定 (2)

settings 与 styles 分区

theme.json 顶层只有两个核心分区：settings 负责“能选什么”，styles 负责“默认长什么样”。2026 年 WordPress 6.7 之后，这个文件仍是块主题（Block Theme）的唯一真源，位于主题根目录 wp-content/themes/your-theme/theme.json。

在 settings 里定义调色板、字号、间距开关；在 styles 里用同样的 slug 引用它们，给 core/paragraph、core/heading 等区块写默认 typography、spacing、color。两者通过 slug 关联，而不是写死色值。

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "color": {
      "palette": [
        { "slug": "base", "color": "#ffffff", "name": "Base" },
        { "slug": "ink", "color": "#1a1a1a", "name": "Ink" }
      ]
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" }
      ]
    },
    "spacing": {
      "spacingScale": { "operator": "*", "increment": 1.5, "steps": 6, "mediumStep": 1, "unit": "rem" }
    }
  },
  "styles": {
    "color": { "background": "var(--wp--preset--color--base)", "text": "var(--wp--preset--color--ink)" },
    "typography": { "fontSize": "var(--wp--preset--font-size--small)" }
  }
}

验证方法：进站点编辑器（Appearance → Editor），新建页面，看右侧检查器里的颜色与字号是否只剩预设项；再对比前端源码，确认 --wp--preset--color--ink 等 CSS 变量已输出。若没生效，回退方式是删掉 theme.json 里的 version 改回 2 并清 wp_cache_flush() 后重试，或检查是否被子主题同名文件覆盖。

slug 命名约定

slug 是设计系统的身份证。颜色用语义名而非视觉名：写 ink、brand、surface，不要写 dark-gray、blue-500。字号用 small、medium、large、x-large；间距靠 spacingScale 自动生成 20 到 70 的步进 slug。

WordPress 会把 color.palette[].slug 编译成 CSS 变量 --wp--preset--color--{slug}，把 typography.fontSizes[].slug 编译成 --wp--preset--font-size--{slug}。所以 slug 必须全小写、连字符分词，且全站唯一。踩坑在于：如果子主题也定义同名 slug 但不同色值，父主题变量会被覆盖，导致编辑器预览和前端不一致。回退办法是子主题用不同前缀，或只在子主题 styles 里改不新增 settings。

如果你需要把这套系统接到定制区块上，可以参考我们之前写的 从零开发一个 WordPress 自定义区块：从 theme.json 到区块样式 (2)，里面讲了区块怎么消费这些预设变量。

spacingScale 与 fluid 字号

2026 年 WordPress 已原生支持 settings.spacing.spacingScale。它不再手写一堆 spacingSizes，而是用算子生成：operator 为 * 或 +，increment 是步长，steps 是档数，mediumStep 是基准偏移，unit 是单位。上面示例用乘 1.5 生成 6 档 rem 间距，slug 为 20 到 70。

fluid 字号则在 settings.typography.fontSizes 里用 fluid 对象：{ "min": "0.875rem", "max": "1.125rem" }，再配合 size 作为回退值。WordPress 会输出 clamp() 并绑定视口宽度变量。注意：fluid 需要 settings.typography.fluid 为 true（默认开），且主题要声明 appearanceTools: true 才会把间距 UI 给到编辑器。

{
  "settings": {
    "appearanceTools": true,
    "typography": {
      "fluid": true,
      "fontSizes": [
        {
          "slug": "medium",
          "size": "1rem",
          "fluid": { "min": "0.9375rem", "max": "1.125rem" },
          "name": "Medium"
        }
      ]
    },
    "spacing": {
      "spacingScale": { "operator": "*", "increment": 1.5, "steps": 6, "mediumStep": 1, "unit": "rem" }
    }
  }
}

验证：在页面插入段落，检查器里字号下拉应出现“Medium (fluid)”；浏览器 DevTools 看 font-size 是否为 clamp(...)。失败回退：把 fluid 关掉退回固定 size，或确认 appearanceTools 没被父主题设为 false。官方文档见 WordPress theme.json 参考。

禁用不需要的区块

不是所有区块都该给内容编辑用。在 settings.blocks 里对具体区块设 allowedBlocks 或全局用 removeBlockTypes 思路：更干净的做法是只开放白名单。2026 年推荐在 theme.json 的 settings 中用 blocks 映射，例如只允许核心段落、标题、图片。

更彻底的是在主题 functions.php 里挂 allowed_block_types_all 过滤器，但 theme.json 层面可用 core/* 的 allowedBlocks 限制容器区块的子项。例如限制 core/group 只能放三类：

{
  "settings": {
    "blocks": {
      "core/group": {
        "allowedBlocks": [ "core/paragraph", "core/heading", "core/image" ]
      }
    }
  }
}

验证：编辑器里拖入 Group 区块，插入器只应出现这三个。若仍出现别的，说明有插件用 register_block_type 注入了，回退是在 functions.php 用 add_filter('allowed_block_types_all', ...) 返回数组兜底。更多限制策略可看 技术栏目首页 的区块治理文章。

实施步骤

1. 在主题根目录建或改 theme.json，顶层写 version: 3 与 $schema。
2. 在 settings 填 color.palette、typography.fontSizes、spacing.spacingScale 并开 appearanceTools。
3. 在 styles 用 var(--wp--preset--...) 引用同一批 slug 做默认值。
4. 在 settings.blocks 给容器区块设 allowedBlocks 白名单。
5. 跑 wp theme list 确认主题激活，清缓存后进编辑器逐项点选验证。
6. 前端看源码变量与 clamp()，不一致就回退到固定值并排查子主题覆盖。

为什么这样能统一设计系统

因为 theme.json 被 WordPress 同时喂给编辑器和前端：编辑器读它生成 UI 选项，wp-includes/global-styles-and-settings.php 在 2026 年仍负责把 JSON 编译成内联 :root 变量。你只改一个文件，两边同步。若走传统 style.css 加 add_theme_support，编辑器不认，就会漂移。

对站点负责人来说，这意味着换人接手时不靠口头规范，而靠文件约束。若你们正在评估外包，2026年wordpress代建站服务商怎么选 里提到要看对方是否交付可维护的 theme.json，这正好是判断专业度的硬指标。

常见问题

theme.json 改了但编辑器没反应怎么办？

先清对象缓存与浏览器缓存，确认文件在激活主题根目录；用 wp eval 'print_r(WP_Theme_JSON_Resolver::get_theme_data());' 看是否解析到。若被覆盖，检查子主题。

fluid 字号在低版本主题里不支持？

2026 年核心已默认支持 version 3 的 fluid；若主题还写 version 2，把 version 升到 3 并补 fluid 对象即可，不需要插件。

间距档位太多编辑不会用？

把 spacingScale.steps 降到 4，或在 styles 里给常用区块写死 padding 预设，减少选择负担。

动作清单

• 今天就把主题根目录的 theme.json 补齐 settings 与 styles 两个分区。
• 把所有颜色 slug 改成语义命名，禁止 hex 散落在区块里。
• 开启 spacingScale 与 fluid，生成 clamp() 字号。
• 用 allowedBlocks 关掉至少一半用不到的区块。
• 进编辑器与前端双向验证变量是否一致。

需要把设计系统落进生产环境？看我们的 WordPress 主题开发与定制 服务，或回 技术栏目 继续读。

参考资料与延伸阅读

• WordPress 开发者文档
• WordPress 主题开发手册
• WordPress 插件开发手册