Payload ui4-review 技能详解UI4 设计令牌迁移的 CSS 审查与自动修复实践【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload本文基于 Payload 仓库中 ui4-review 技能定义 展开完整讲解这套 UI4 CSS 迁移审查工作流的四步流程定位变更文件、六类违规并行检测、按优先级自动修复、输出报告与全部违规参考手册SCSS 嵌套、间距/圆角/描边/阴影令牌、语义颜色命名、遗留变量替换。结合 packages/ui/src/css/ 下的令牌源文件与已迁移组件示例读完后你既能复现这套检测—修复—报告的审查流程也能理解 Payload 管理面板从 SCSS 硬编码值迁移到纯 CSS 设计令牌体系的底层规则。ui4-review 在工作流中的位置Payload 的管理面板 UIpackages/ui正在从 SCSS 硬编码值迁移到纯 CSS 嵌套 设计令牌的 UI4 体系。仓库为此配套了两个协作的 AI 技能ui4 技能负责单个组件的重新皮肤化SCSS → CSS 迁移、Figma 对齐、变体测试、E2E 测试其 Step 8 明确要求组件视觉确认通过后调用ui4-review技能做收尾扫描ui4-review 技能即本文主题职责是审查 CSS 变更并自动修复令牌违规Reviews CSS changes andauto-fixestoken violations它既是迁移后的质量门禁也是日常 PR 中 CSS 改动的审查工具。迁移后的全局令牌文件全部位于 packages/ui/src/css/ 目录包括colors.css、design-tokens.css、spacing.css、radius.css、theme.css、elevations.css、utilities.css等。ui4 技能明确指出packages/ui/src/scss/目录已被移除任何使用的 CSS 变量必须存在于该 css 目录中这正是 ui4-review 各条检测规则的存在前提。核心原则调色板令牌--ramp-*与语义令牌--color-*技能文档把这条原则放在最前面因为它决定了什么算违规--ramp-*令牌是原始调色板如--ramp-white-1000、--ramp-blue-500只允许在colors.css中用于定义语义令牌--color-*令牌是感知上下文的语义令牌如--color-bg、--color-text-brand它们自动处理亮/暗主题切换组件与元素永远使用--color-*语义令牌绝不直接使用--ramp-*调色板令牌。/* ❌ BAD - 使用原始调色板 */ background: var(--ramp-white-1000); /* ✅ GOOD - 使用语义令牌 */ background: var(--color-bg);从源码可以完整印证这条设计。design-tokens.css 定义了原始调色板本身按色相分命名空间--ramp-blue-*、--ramp-grey-*、--ramp-red-*、--ramp-dark-red-*等黑白系则是基于透明度的rgba值--ramp-black-100: rgba(0, 0, 0, 0.05); --ramp-white-1000: #ffffff; --ramp-blue-500: #0d99ff;而 colors.css 承担语义层角色其文件内的命名规则注释L44-L50说明了 UI4 命名约定所有语义色以--color-为前缀default类别是隐式的--color-bg-secondary而非--color-bg-default-secondarydefault变体也是隐式的--color-bg而非--color-bg-defaulton{X}算作一个词段--color-text-onbrand。该文件的结构同时解释了自动亮/暗主题的机制:root块内定义浅色主题下的--color-*默认主题例如浅色下--color-bg: var(--ramp-white-1000)、--color-text: var(--ramp-black-800)随后在 colors.css#L306-L307 的html[data-themedark], [data-themedark]选择器中只覆盖调色板引用发生变化的令牌如深色下--color-bg: var(--ramp-grey-800)、--color-text: var(--ramp-white-1000)。data-theme属性由 Theme 提供者 在页面上设置——组件只需引用语义令牌切换主题时颜色自动跟随这就是组件 CSS 里禁止出现--ramp-*的原因一旦组件直接引用调色板暗色模式下就会拿到错误的颜色。审查流程四步详解Step 1获取变更的 CSS 文件git status --porcelain | grep \.css$或者当调用者直接指定了某个文件时直接对该文件操作。Step 2六类违规的并行检测这是技能的核心——六条 grep 命令必须在同一个并行批次中一次性发出同时检测所有违规类型然后统一分析结果# 1. SCSS 嵌套违规在纯 CSS 中不生效的 BEM 拼接模式 grep -n __\|-- $FILE # 2. 硬编码间距本应使用令牌却写成 px/rem 的值 grep -nE :\s*[0-9]px|:\s*[0-9.]rem $FILE # 3. 硬编码颜色hex、rgb、rgba —— 包含 box-shadow grep -nE #[0-9a-fA-F]{3,8}|rgba?\( $FILE # 4. 遗留主题变量 grep -nE var\(--theme-|var\(--style-|var\(--base\) $FILE # 5. 旧令牌名UI4 之前的命名 grep -nE \-\-bg-default|\-\-bg-secondary|\-\-text-default|\-\-text-secondary|\-\-icon-default|\-\-icon-secondary|\-\-border-default|\-\-border-strong $FILE # 6. 原始调色板使用应改用语义令牌 # 注意colors.css 除外因为语义令牌正是在其中定义的 grep -nE var\(--ramp- $FILE需要注意的边界条件--ramp-*原始调色板违规只在组件 CSS 文件中判定colors.css 中引用--ramp-*是定义语义令牌的正常行为不告警。Step 3按优先级自动修复检测到违规后不是简单罗列而是按下面的优先级顺序立即修复SCSS 嵌套会完全破坏 CSS— 最先修遗留变量已弃用— 替换为新令牌旧令牌名UI4 之前— 转换为--color-*命名原始调色板使用组件中出现--ramp-*— 替换为语义--color-*令牌硬编码值间距、颜色、圆角— 替换为令牌。Step 4输出报告修复完成后报告三类统计检测到的违规总数、已自动修复的违规数、需要人工复核的违规数没有明确令牌匹配项的。输出格式见文末输出格式一节。违规参考手册SCSS 嵌套会直接破坏 CSS这是唯一一类语法级违规——SCSS 的拼接在纯 CSS 中是无效选择器模式问题修复方式__elementBEM 元素拼接使用扁平的.block__element选择器--modifierBEM 修饰符拼接使用扁平的.block--modifier选择器.child { .parent--mod }父级引用改写为.parent--mod .child仍然合法的 CSS 嵌套:hover、:focus、::before、 .child。ui4 技能 的 Step 1 给出了同一问题的对照示例SCSS 中.block { __element { color: red; } }能编译出.block__element但在纯 CSS 中__element是无效写法必须拆成扁平选择器。迁移规则统一为所有__与--一律转为扁平 BEM 选择器伪类、伪元素与后代嵌套空格则可保留。间距令牌与取整规则基础映射表值令牌4px / 0.25rem--spacer-18px / 0.5rem--spacer-212px / 0.75rem--spacer-2-516px / 1rem--spacer-324px / 1.5rem--spacer-432px / 2rem--spacer-540px / 2.5rem--spacer-6取整规则——永远取整到最近的令牌像素区间令牌说明0-2px--spacer-0直接用 03-6px--spacer-1(4px)5-6px 取整为 4px7-10px--spacer-2(8px)10px向下取整到 8px11-14px--spacer-2-5(12px)13.33px 取整到 12px15-20px--spacer-3(16px)15px、20px 均取整到 16px21-28px--spacer-4(24px)29-36px--spacer-5(32px)30px 取整到 32px37-48px--spacer-6(40px)总规则40px 及以下的值一律使用单个令牌禁用calc()超过 40px 的值才允许用calc()配合间距令牌。例外值0、百分比、auto、inherit、-1px用于裁剪偏移不需要令牌化。spacing.css 是这些令牌的真实定义与上表完全一致:root { --spacer-0: 0; --spacer-1: 0.25rem; /** 4px */ --spacer-1-5: 0.375rem; /** 6px */ --spacer-2: 0.5rem; /** 8px */ --spacer-2-5: 0.75rem; /** 12px */ --spacer-3: 1rem; /** 16px */ --spacer-4: 1.5rem; /** 24px */ --spacer-5: 2rem; /** 32px */ --spacer-6: 2.5rem; /** 40px */ ... }两个源码层面的补充细节spacing.css中还存在审查表未列出的--spacer-1-56px此外该文件还派生出布局级令牌--gutter-h、--spacing-field与断点令牌--breakpoint-s-width: 768px、--breakpoint-m-width: 1024px等且--gutter-h会随视口断点响应式降级≤1440px 降为--spacer-4、≤1024px 降为--spacer-3——这类布局令牌本身也全部建立在间距令牌之上。描边宽度令牌值令牌1px--stroke-width-smalltheme.css 中的实际定义还包含一个 2px 档--stroke-width-small: 1px与--stroke-width-medium: 2px。同一文件还集中定义了组件级主题令牌--field-min-height-*、--button-height、--popup-radius等其文件头注释说明用户在自己的:root块中覆盖这些变量即可整体重换组件外观普通:root规则天然胜过layer规则无需!important。圆角令牌值令牌2px / 0.125rem--radius-small5px / 0.3125rem--radius-medium13px / 0.8125rem--radius-large9999px--radius-fullradius.css 的定义与上表一一对应并额外提供--radius-none: 0与--radius-chip: 0.1875rem两档。高程令牌Box Shadows高程令牌定义在 elevations.css。box-shadow 绝不允许写硬编码rgba()应使用高程令牌令牌适用场景--elevation-300-tooltip提示框、小型浮动元素--elevation-400-menu-panel菜单、下拉、浮动面板--elevation-500-modal-window模态框、对话框、全屏遮罩/* ❌ BAD - 硬编码阴影 */ box-shadow: 0 -2px 16px -2px rgba(0, 0, 0, 0.2); /* ✅ GOOD - 高程令牌 */ box-shadow: var(--elevation-400-menu-panel);高程自动适配亮/暗主题并非空话elevations.css#L20-L36 在[data-themedark]选择器下对三个令牌给出了完全不同的暗色实现加入inset白色内描边、更深的黑色投影另外还有一个上表未列出的--elevation-100-canvas档位。因此第 3 条 greprgba?\(把 box-shadow 一并扫入正是为了保证组件不会绕过这套主题感知的高程体系。语义颜色令牌UI4 命名所有语义色使用--color-前缀default类别与变体均为隐式。完整的旧名 → UI4 新名映射旧名新名UI4--bg-default--color-bg--bg-secondary--color-bg-secondary--bg-hover--color-bg-hover--bg-selected--color-bg-selected--bg-brand--color-bg-brand--bg-danger--color-bg-danger--bg-success--color-bg-success--bg-warning--color-bg-warning--text-default--color-text--text-secondary--color-text-secondary--text-tertiary--color-text-tertiary--text-brand--color-text-brand--text-danger--color-text-danger--text-success--color-text-success--icon-default--color-icon--icon-secondary--color-icon-secondary--icon-tertiary--color-icon-tertiary--icon-brand--color-icon-brand--icon-danger--color-icon-danger--border-default--color-border--border-strong--color-border-strong--border-selected--color-border-selected--border-brand--color-border-brand这套命名规则与 colors.css 中的注释逐条吻合且实际令牌数量远多于迁移表——例如浅色主题下还有--color-bg-inverse、--color-border-danger-strong、--color-icon-onbrand等状态化令牌组件迁移时应以colors.css中的实际定义为准而不是只记住迁移表里的 23 个旧名。遗留变量立即替换遗留变量替换为--theme-elevation-0--color-bg--theme-elevation-50--color-bg-secondary--theme-elevation-100--color-border--theme-text--color-text--style-radius-m--radius-mediumvar(--base)的转换该遗留令牌的值为 20px按下表转换原式像素替换为var(--base) * 0.48pxvar(--spacer-2)var(--base) * 0.510pxcalc(var(--spacer-1) * 2.5)var(--base) * 0.612pxvar(--spacer-2-5)var(--base)20pxcalc(var(--spacer-4) * 0.833)var(--base) * 240pxvar(--spacer-6)完整的转换表见 ui4 技能 Step 1。需要说明的是两份技能文档对边界值的策略存在轻微差异ui4 技能的取整表将 10px 直接取整为--spacer-28px、20px 取整为--spacer-316px或--spacer-424px而 ui4-review 的这张表保留了精确值calc表达。从源码结构看两者都合法实际迁移时建议优先对齐 Figma 设计稿的目标尺寸并按取整规则向最近令牌靠拢。修复行为准则先修后报不确定的只标记技能文档用Behavior一节划定了明确的行动边界核心要求不要只报告违规必须立即修复使用replace_string_in_file或multi_replace_string_in_file。对每一条违规执行固定动作序列定位确切的行号与值判定正确的令牌替换项立即执行替换修复报告修复内容。只在以下情况标记而不修复不存在匹配的令牌例如 18px 的徽章尺寸该值是有意为之例如1px边框、0替换项存在歧义。空 CSS 文件处理若某个组件的 CSS 文件在迁移后变空样式已全部交给Button等共享组件处理应删除该 CSS 文件并移除组件中对它的 import。输出格式与汇总自动修复完成后报告采用已修复 / 待人工复核两段式格式## Auto-Fixed ✅ Collapsible/index.css:9 — height: 2rem → height: var(--spacer-5) ✅ Collapsible/index.css:120 — width: 2rem → width: var(--spacer-5) ## Flagged (Manual Review) ⚠️ ErrorPill/index.css:15 — height: 1.125rem (18px) — no matching token所有文件处理完毕后再输出一张按文件聚合的汇总表文件已修复待复核Collapsible/index.css21ErrorPill/index.css02实战印证迁移后的组件长什么样以 Button 组件的样式文件 为例可以看到合规产物与本文规则的对应关系背景色写作background-color: var(--color-bg)而非var(--ramp-white-1000)整个文件不含--ramp-*、不含__/--拼接、颜色与间距全部引用packages/ui/src/css/中的令牌。ui4 技能也将它列为已迁移组件参考实现并建议迁移完成后运行 Playwright 变体验证与 test/v4/ 测试套件做视觉回归。小结ui4-review 的价值在于把CSS 令牌迁移这件容易退化为口头约定的事固化成了可执行、可验证的流程git status圈定范围 → 六条 grep 并行检测 → 按语法破坏 遗留变量 旧命名 原始调色板 硬编码值的优先级自动修复 → 双段式报告加汇总表。配套的令牌体系则形成清晰的三层结构design-tokens.css 的原始调色板--ramp-*、colors.css 的主题感知语义令牌--color-*靠data-theme自动切换亮/暗以及 spacing.css、radius.css、theme.css、elevations.css 中的几何与效果令牌。组件 CSS 只允许触碰第二、三层这正是这套审查规则的全部出发点。【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考