设计系统介绍
列出了其基础包和组合包。本指南重点关注@wordpress/components、@wordpress/ui 和 @wordpress/theme，这些是贡献者在当前组件过渡期间必须比较的公开
包。
尽管介绍中将其与较新的设计系统包区分开来，但 @wordpress/components 仍然受支持。
选择工作边界
在构建 Gutenberg 功能、插件或独立应用程序时，请使用公共包。应用程序消费者可以使用公共包入口点、已记录的属性、语义化 --wpds-* 令牌以及公共主题/设置 API。它不得依赖包私有源路径、CSS 模块、Base UI 实现细节、私有 API 桥接或 Gutenberg 检出代码库。
不要仅仅因为名称以 __experimental 开头就将 API 视为私有的。WordPress 发布的遗留实验性 API 可能承担公共兼容性义务。请根据规范 API 边界指南验证其状态。
在更改 packages/components、packages/ui 或 packages/theme 时，请使用包贡献工作流程。包变更必须考虑其发布的 API 以及 Gutenberg 调用站点之外的用户。当变更同时包含包代码和应用代码时，请检查两者的契约。将特定于产品的行为保留在使用方包中；仅当共享行为属于可复用组件或令牌时，才将其添加到设计系统中。
如果公共界面无法满足产品需求，请记录该行为、受影响的使用者、尝试过的组合方式以及提议的公共契约。不要通过导入包私有内容来绕过这一决策。
检查目标版本
对于 Gutenberg 变更，请使用提议的源代码及其依赖项。当消费的应用程序运行不同的包或 WordPress 发布版本时，请检查其他版本：
- 如果应用程序捆绑了该软件包，请检查安装的软件包版本。
- 如果 WordPress 在运行时提供该软件包，请检查应用程序支持的最低 WordPress 版本。验证该版本是否提供了所需的导出项以及脚本或样式句柄。
构建工具将第二种情况称为“外部化”：包不包含在应用程序捆绑包中。当运行时依赖项的来源不明确时，请检查构建配置和生成的资产元数据。默认的 @wordpress/dependency-extraction-webpack-plugin 会将许多 WordPress 包外部化。
使用包文档作为持久事实的来源：
针对证据实际描述的状态使用证据：
- 部署的检出代码库或运行时环境对于可用的导出项、样式和运行时行为具有权威性。已安装的包证明了编译时类型，而不是外部化的运行时 API。
- 在审查中，确定检出代码库是基线、提议的头版本还是另一个修订版。结合相应的源代码阅读差异。未应用的差异并不是其新 API 缺失的证据，头版本检出也不是旧行为的证据。
- 设计系统 MCP 服务器和当前的 Storybook 描述了当前的建议。它们不能证明较旧的目标版本导出了某个 API。
使用公共包构建
在引入应用本地的自定义控件之前，请先选择一个现有的公共组件和组合。
选择推荐组件
@wordpress/components 仍然受支持。向 @wordpress/ui 的过渡是按组件逐个进行的，因此请为每个组件选择推荐的包。不要将任一包的年龄视为通用的选择规则，也不要机械地从一个包迁移到另一个包。
对于当前的包版本，请使用维护良好的推荐来源，而不是将组件映射复制到文档或代理指令中：
- 可用时，使用
get_components查询 WordPress 设计系统 MCP 服务器，然后对相关组件使用get_component_details。其组件目录由精心整理的 Storybook 清单生成，并返回当前推荐的包和导入。 - 否则，请检查
use-recommended-componentsESLint 规则源代码中维护的ALLOWLIST和DENYLIST。其文档解释了规则行为并链接了迁移指南。 - 当规则未涵盖某个组件时，请在目标检出代码库中检查该组件的
*.story.*源文件。使用其componentStatus和注释。渲染后的 Storybook 是一个人类可读的伴侣，但源文件可供代理访问，并且可以根据目标版本进行检查。该状态比experimental标签或组件前缀更具权威性。
对于使用较旧包版本的应用程序，请使用这些来源的相应版本，并根据其安装的导出项、类型和文档验证选择。迁移现有组件时，请保持行为、样式、无障碍性和兼容性的对等。
对于编辑数据集的表单，请考虑 DataForm。对于内联验证，请阅读经过验证的表单控件概述，包括其状态和限制，并验证目标版本的导出项。根据表单的状态和验证需求进行选择，而不是在不检查整个表单的情况下替换单个控件。
使用语义化 --wpds-* 自定义属性进行设计系统接口样式设置。使用 --wp--preset--* 自定义属性进行 theme.json 预设和面向块的样式设置。令牌名称和值会随时间变化，因此请勿将令牌清单复制到指南、应用程序约定或技能中。
当组件属性已经表达了样式意图时，优先使用它们。对于自定义样式，如有可用，请使用设计系统 MCP 服务器的 get_design_tokens。如果没有 MCP，请使用设计令牌参考。根据语义目的和状态选择令牌，而不是匹配其当前的原始值。并非每个 CSS 字面量都需要一个令牌。在为块或内容预览（包括编辑器内的预览）设置样式时，请使用活动主题的 theme.json 预设。
设置取决于文档
标准的 WordPress 编辑器屏幕集中管理共享样式。单独的应用程序、iframe 或弹出窗口可能需要自己的样式表和主题设置。清点每个文档中渲染哪些公共包，然后遵循适用的包设置指南：
仅为在该处渲染的包应用设置，而不是将合并的配置复制到处个文档中。
React portal 改变了 DOM 放置位置，但可以留在同一文档中。在添加文档设置之前，请检查其实际的容器和 ownerDocument。CSS 选择器和继承的自定义属性遵循 DOM 树，因此工具栏上的类或嵌套的主题提供者可能无法到达门户到该子树外部的弹出窗口。通过记录的属性或弹出窗口本身的类应用特定于产品的弹出窗口样式。验证其样式表是否存在于目标文档中。
当覆盖层需要主题覆盖时，请遵循 ThemeProvider 嵌套与根节点指南。不要为每个覆盖层都添加一个 isRoot provider；这会改变文档级别的令牌，且每个文档仅支持一个根 provider。
当应用程序直接打包了 @wordpress/components 和@wordpress/ui 时，请遵循 @wordpress/ui README 中记录的覆盖层兼容性设置。在实际渲染的文档中测试覆盖层和焦点。
安全地更改包
识别受影响的消费者以及相关的组件或令牌先例。对于新功能，需阐明为何现有的公共组合方式不足。对于错误修复或内部重构，需确定要恢复或保留的契约。请遵循被更改包的源码指南：
将实现细节与公共 API 区分开来。对于公共变更，
需决定并记录兼容性、迁移、发布、生成输出以及
对消费者的影响。在浏览器中验证 CSS 和交互行为，因为单元测试无法确立级联顺序、焦点几何形状或 portal 行为。
当更改捆绑的设计系统包与由 WordPress 单独提供的依赖项之间的契约时，请遵循跨 WordPress 版本测试已发布的包。检查受该契约影响的受支持的入口点和版本配对。无关的内部编辑不需要此矩阵。
在声明包工作完成之前，请检查受变更影响的要求：
- 公共导出和类型，包括通过包声明的依赖解析的定义。
- 语义、状态、交互、refs、兼容性和迁移。
- 当状态或导出发生变化时，专注的测试和故事（stories）、公共文档以及组件推荐元数据。
- 生成的输出以及包政策要求的更新日志。
内部重构并不自动意味着需要新的故事或公共文档。解释未解决的需求，而不要为每次贡献都添加一份不相关表面的清单。
在替换 API 前比较契约
在移除、重命名或替换组件、prop、令牌或扩展点之前，比较受影响的新旧行为。包括接受的值和默认值、受控和非受控状态、回调参数、渲染语义、ref 目标、样式钩子，以及适用的键盘或焦点行为。对于多部分迁移，紧凑的比较表会有所帮助。
搜索更改包之外的消费者。迁移所有仓库调用站点并不能证明插件或其他 npm 消费者的兼容性。检查文档化的扩展点（如 SlotFill 子元素和 render 回调），看它们是否符合以前接受的值和组合。处理内置调用者的适配器可能无法处理第三方输入。如果无法确定外部使用情况，请说明这一限制，并明确宣布任何受支持行为的退役。
在移除或更改公共 API 之前，使用 Veloria 查找其在 WordPress.org 插件和主题中的用法。搜索相关的标识符、hooks、样式钩子和常见访问模式，然后在上下文中检查匹配项。记录搜索范围和相关结果。匹配项可以演示兼容性影响；没有匹配项并不能证明移除是安全的。私有代码、在其他地方分发的商业产品，以及因编译或动态访问而被掩盖的用法可能仍未被发现。将此证据与 API 的支持政策和迁移选项结合使用。
对于令牌，除了默认值外，还要比较语义目的和受影响的模式。遵循令牌源指南和构建流程，然后检查受变更影响的生成资产和消费者。在一个主题中具有相等值的两个令牌不一定可以互换。
验证受影响的行为
从更改的契约和测试概览中选择验证方法。在现有覆盖率能证明行为的地方加以利用。将状态和结构检查保留在 jsdom 中；对于计算样式、布局、原生焦点、滚动和过渡，请使用 Browser Mode 或可复现的浏览器检查。加载真实消费者使用的样式。仅靠类断言、模拟几何形状和快照并不能证明视觉一致性。
不要因为缺乏覆盖率就添加或要求测试。对于第三方依赖项拥有的且变更保持完整的行为，依靠其自身的测试。将本地覆盖率集中在我们的转换、覆盖、状态处理和集成上，因为它们引入了具体的回归风险。在添加测试之前，确定受支持的用例、可能的失败及其后果，然后选择尚未覆盖的最小检查。避免重复依赖套件、枚举每个 prop 组合，或为推测性的边缘情况构建固定装置。综合考虑现实的可能性和影响；即使是不常见的受支持用例，当其失败具有严重后果时仍然很重要。
对于交互变更，检查我们的更改可能影响的键盘和指针路径、无障碍名称、状态转换、关闭操作或焦点返回。使用针对未变更行为的现有覆盖率。根据适用的 ARIA Authoring Practices、ARIA 规范或 WCAG 比较无障碍要求。通过的自动化检查是其检查规则的有力证据，而非完全无障碍的证明。
对于样式或令牌变更，根据正在更改的定义或令牌模式选择条件。相关案例可能包括浅色和深色主题、嵌套 providers、密度、RTL、强制颜色、减少动效、长内容或翻译内容、缩放或受限容器；这不是必需的测试矩阵。在组合消费者处进行检查，因为它们的覆盖或布局可能会改变结果。在选择断点或测量 API 之前，检查响应式决策是依赖于视口还是组件的容器。
运行仓库适用的 lint、类型、生成和构建检查。区分已验证的结果和尚未运行的手动步骤。受阻的浏览器检查限制了关于一致性的主张；它本身并不能证明存在缺陷。