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

一、settings 与 styles 分区：谁定义令牌，谁负责输出

theme.json 的顶层只认两个关键分区：settings 和 styles。settings 负责“生成什么能力”，它是设计令牌的注册表，决定编辑器里出现哪些颜色、字号、间距档位；styles 负责“实际用什么值”，把令牌应用到元素或区块上，最终编译成 CSS 变量和选择器。

2026 年 WordPress 6.8+ 的 theme.json 已经支持 schema v3，主题根目录放 theme.json，需要按区块覆盖时放到 styles/ 目录。核心机制是：settings 里的每一组 color.palette、typography.fontSizes、spacing.spacingSizes 都会生成 CSS 自定义属性，例如 --wp--preset--color--brand，blocks 通过 var() 引用，所以改一处即可全局生效。

验证方法：在站点根目录执行 wp theme.json validate（需要 WP-CLI 2.11+），或用浏览器访问 /wp-json/wp/v2/themes?status=active 看返回结构里是否含你的预设。踩坑点是把该放 settings 的值直接写进 styles，导致编辑器里无法选择，也无法被区块复用。回退方法是保留旧 theme.json 备份，用 wp theme activate 切回上一个主题版本。

{
  '$schema': 'https://schemas.wp.org/wp/6.8/theme.json',
  'version': 3,
  'settings': {
    'color': {
      'palette': [
        { 'slug': 'brand', 'color': '#1f6feb', 'name': 'Brand' },
        { 'slug': 'ink', 'color': '#111827', 'name': 'Ink' }
      ]
    },
    'typography': {
      'fluid': true,
      'fontSizes': [
        { 'slug': 'body', 'size': '1rem', 'name': 'Body' },
        { 'slug': 'h2', 'size': 'clamp(1.5rem, 3vw, 2.25rem)', 'name': 'H2' }
      ]
    },
    'spacing': {
      'spacingScale': { 'steps': 6, 'operator': '*', 'increment': 1.5, 'mediumStep': 1.5, 'unit': 'rem' }
    }
  },
  'styles': {
    'color': { 'background': 'var(--wp--preset--color--ink)', 'text': 'var(--wp--preset--color--brand)' },
    'elements': { 'h2': { 'typography': { 'fontSize': 'var(--wp--preset--font-size--h2)' } } }
  }
}

二、slug 命名约定：让令牌可预测

slug 是不可变契约，一旦上线被区块引用，改名等于全站样式断裂。建议约定：颜色用“用途”而非“色相”，如 brand、ink、surface；字号用“角色”，如 body、h1、caption；间距用 space-10 到 space-80 或纯数字档位。全部小写、连字符分隔、禁止驼峰。

常见踩坑是 primary 与 brand 并存、blue-500 这种把色相写死，导致换色时必须改代码。回退策略是保留旧 slug 作为别名，新增语义 slug，逐步迁移。验证方式：在 wp-content/themes/your-theme/theme.json 里对所有 slug 做一次 grep，确认没有重复与保留字冲突。

三、spacingScale 与 fluid 字号：把响应式交给令牌

间距不要手写 1.2rem，用 spacingScale 生成 6 档；WordPress 会按 operator、increment、mediumStep 自动算出 --wp--preset--spacing--10 等变量。字号打开 typography.fluid 后，WordPress 会把固定值自动转成 clamp()；若想精确控制，直接写 clamp 表达式也行。

验证方法：打开浏览器 DevTools，检查 :root 下是否生成 spacing 与 font-size 变量，再把窗口从 360px 拉到 1440px，观察标题字号是否平滑变化。踩坑点是 spacingScale 档位太多导致编辑器下拉臃肿，或 fluid 最小值过小造成移动端可读性差。回退方法是先把 fluid 关掉，确认基础字号没问题后再逐段开启。

四、禁用不需要的区块：白名单比黑名单稳

用 settings.blocks 下的区块配置逐个禁用，例如 settings.blocks['core/cover'].color.custom = false 关闭自定义色，或直接通过 PHP 钩子 allowed_block_types_all 做白名单。2026 年推荐用过滤器集中管理，便于按角色控制。

add_filter( 'allowed_block_types_all', function( $allowed, $editor_context ) {
  return array(
    'core/paragraph',
    'core/heading',
    'core/image',
    'core/group'
  );
}, 10, 2 );

验证方法：进入编辑器，打开区块插入器，确认列表只剩白名单项。踩坑是白名单过窄导致旧文章里已存在的区块无法编辑。回退方法是临时移除该过滤器，恢复默认，再逐块放行。

常见问题

theme.json 改完不生效怎么办？

先清站点缓存与 CDN，再确认文件路径与 JSON 语法；WordPress 6.8+ 对 schema 校验更严格，缺逗号会整体回退到默认。用 wp theme.json validate 定位行号。

slug 可以中途改名吗？

不建议。改名会让已保存的区块样式引用失效。正确做法是新增 slug、保留旧值作别名，在下一版主题里清理旧引用。

fluid 字号和固定字号能混用吗？

可以。打开 fluid 后仍可对个别字号写死值，WordPress 只对未加 clamp 的尺寸自动处理。混用时务必在移动端回归检查最小字号。

下一步行动

1. 备份现有 theme.json，用 WP-CLI 校验当前结构。
2. 按“用途 slug”重写颜色、字号、间距三组预设。
3. 开启 fluid 与 spacingScale，在 DevTools 验证 CSS 变量生成。
4. 用 allowed_block_types_all 收敛区块白名单并回归旧文章。
5. 把 theme.json 纳入 Git，每次改动用预览环境验证后再合并。

需要把这套设计系统落到你的主题里？查看我们的主题开发服务，或先浏览 技术栏目 的更多实战拆解。

参考资料与延伸阅读

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