一套代码，五端齐飞；一套工作流，人机共建。

🎯 背景

NutUI-React 是京东风格的移动端 React 组件库，覆盖 80+ 高质量组件，支持 H5、微信/京东/支付宝小程序、鸿蒙/iOS/安卓等多端运行。自 v3 发布以来，NutUI-React 已服务于京东 APP、京东商家B端、科技、物流等众多业务场景，特别是在 2025 年重点支持了多个 S级/一级 项目，如订单一码五端、结算/购物车/商详等一码五端项目，累计为数千名开发者提供了生产级 UI 解决方案。

随着京东 APP 全面升级至 v16 设计规范，组件库面临一次系统性的视觉重构。这不是简单的"换个颜色、调个间距"——我们需要在保持 100% 向下兼容 的前提下，将 80+ 组件全面对齐到新设计语言，同时补齐暗黑模式、无障碍体验、多语言支持和等比缩放适配四大核心保障。

这是 NutUI-React 从 v3 迈向 v4（4.0.0-beta.1）的关键一步。

🏗️ 升级全景工作流：五层管线，逐层交付

面对如此大规模的升级，我们没有选择"一把梭"，而是设计了一套 五层管线式工作流，确保每个组件的升级都经过标准化、可复现的流程：

每一层都有明确的输入和输出，后一层依赖前一层的交付物。这套工作流已经被固化为 Agent Skill（AI 技能指令集），不仅指导人类开发者，也让 AI 编程助手能够精确执行升级任务。

💎 v16 设计规范：都升级了什么

v16 设计规范不是简单的"调色板"更新，而是覆盖了组件尺寸、间距、材质、状态反馈等多个维度的系统性升级。以下是几个典型变化：

• 尺寸与热区：按钮、选择器等交互组件的最小点击热区统一到 32×32px，确保触控友好
• 间距体系：内外边距对齐到新的 Spacing Token（4/8/12/16px 档位），整体更紧凑
• 材质与光影：引入液态玻璃（Liquid Glass）等新材质定义，悬浮按钮等组件使用 backdrop-filter + 渐变背景 + 3D 折射边框模拟质感
• 状态矩阵：每个组件覆盖常态、按下、选中、禁用等完整交互状态，配套设计稿标注
• 暗黑模式：所有色彩变量提供亮/暗双套色值，通过 CSS 变量无缝切换

以 HoverButton 的液态玻璃材质为例：光照方向 315°，通过 135° 白色渐变背景 + 上/左高光边框 + 下/右暗影边框 + blur(7px) 磨砂效果还原设计稿，暗黑模式自动反转为深色渐变。

🔧 实战案例

案例一：Radio — 热区扩展与无文本居中

问题：当 Radio 组件没有文字标签时，图标偏心，点击热区不足 32px。

解法：

• 条件渲染优化：children 为空时完全不渲染 Label 节点，消除 margin-left 挤压
• 动态绑定 .nut-radio-nolabel 修饰类，扩充热区至 32×32px 并居中对齐

.nut-radio {
  min-height: scale-px(32px);

  &.nut-radio-nolabel {
    min-width: scale-px(32px);
    justify-content: center; // 图标完美居中
  }
}

案例二：Toast — 设计 Token 精确对齐

变动点：

• 默认显示时长 2s → 3s
• 引入绝对宽度限制（文本型 88_{200px，状态型 97}225px）替代百分比
• 清理历史遗留拼写错误类名 .nut-toast-inner-descrption
• 所有物理尺寸包裹 scale-px() 实现等比适配

案例三：BackTop / HoverButton — 变体继承架构

设计理念：BackTop（返回顶部）是 HoverButton（悬浮按钮）的一种变体。

实现：

• 液态玻璃材质、3D 折射边框、投影等所有视觉属性在 hoverbuttonitem.scss 中统一实现
• BackTop 的 backtop.scss 仅控制显隐切换（display: none / flex），零冗余覆盖
• 无障碍标签通过 Locale 系统动态获取（支持 8 种语言），而非硬编码中英文

// BackTop 通过 Locale 获取无障碍标签
const { locale } = useConfig()
const finalAriaLabel = ariaLabel || locale.backtop.backToTop
// zh-CN: "回到顶部" | en-US: "Back to top" | ja-JP: "トップに戻る" ...

🛡️ 四大核心保障

每个组件升级，我们都严格执行以下四项保障检查：

🌙 暗黑模式

• 所有颜色变量在 theme-dark.scss 中注册暗黑色值
• 禁止物理硬编码色值，必须引用 CSS 变量并设置语义化兜底
• 亮/暗模式切换通过 .nut-theme-dark 类名或系统媒体查询无缝衔接

🌐 国际化（8 种语言）

• 组件内置文案接入统一 Locale 翻译机制
• 翻译字典覆盖：简中、繁中、英文、日语、印尼语、土耳其语、越南语、维吾尔语
• 严禁在 TSX 中硬编码任何语言文案

♿ 无障碍

• 交互元素补齐 role、aria-label、aria-checked、aria-disabled
• 键盘焦点导航支持（tabIndex={0}）
• 屏幕阅读器友好的语义化 DOM 结构

📐 等比适配

• 所有物理 px 值（除 1px 边框外）包裹 scale-px() 函数
• 通过 --nut-scale-f CSS 变量实现全局缩放因子控制
• 确保组件在不同视口宽度、小程序端和 Harmony/iOS/Android 端保持比例一致

🤖 AI 辅助开发：人机共建的新范式

这次 v4 升级中，我们积极探索了 AI 辅助组件开发 的新工作模式：

Agent Skill 技能库

我们将组件升级工作流固化为 Agent Skill（.agents/skills/component-upgrade-workflow/SKILL.md），这是一份 233 行的结构化指令文档。AI 编程助手读取这份技能后，能够：

1. 自动审计：扫描组件现有 Props、类型定义和 Demo 用例
2. 精确重构：按照设计稿标注修改 SCSS 变量默认值，保持变量名不变
3. 双端对齐：同步修改 H5（.tsx）和 Taro（.taro.tsx）实现
4. 保障补齐：自动为新增文案补齐 8 种语言翻译，添加 ARIA 属性
5. 文档同步：更新 4 份语言文档的主题定制表格
6. QA 验证：运行单元测试、类型检查并输出 Checklist 比对表

实际体验

在 BackTop 组件升级中，从设计稿输入到通过所有自动化验证，AI 助手完成了：

• 24 个文件的同步修改
• 9 种语言的 Locale 字典补齐
• 暗黑模式变量注册
• 单元测试通过 + TypeScript 双端编译零错误

人类开发者的角色从"逐行编码"转变为"审阅与把关"——提供设计稿、确认方案、验收结果。

📊 当前进展

📣 共建邀约：和我们一起打磨 v4

NutUI-React 4.0 是一个庞大的工程，我们真诚地邀请社区开发者加入共建。

你可以做什么？

快速上手

# 1. Fork & Clone
git clone https://github.com/jdf2e/nutui-react.git
cd nutui-react && git checkout feat_v4.x

# 2. 安装依赖
pnpm install

# 3. 启动开发服务
pnpm run dev          # H5 端
pnpm run dev:taro:h5  # Taro H5 端

# 4. 阅读升级工作流
cat .agents/skills/component-upgrade-workflow/SKILL.md

# 5. 选择一个组件，开始升级！

参考资料

• 📖 组件升级工作流 SKILL.md 【参看评论区~】
• 📋 共建待办清单
• 🏠 NutUI-React 官网
• 💬 GitHub Issues

写在最后

NutUI-React 4.0 不只是一次设计规范的升级，更是一次工程能力的全面进化。我们用 五层管线工作流 驯服了大规模组件升级的复杂度，用 AI Agent Skill 实现了人机协作的新范式，用 四大核心保障 确保了每个组件的品质底线。

这条路还很长，70+ 组件正在逐一升级中。我们相信，开源的力量在于共建。如果你也认同"移动端 UI 组件库应该同时具备视觉美感、无障碍体验和工程严谨性"，那么——

欢迎加入 NutUI-React v4 共建，让我们一起把组件做到极致。 🚀

NutUI-React 团队 · 2026 年 6 月