按设计规则构建并更新 UI 组件库

## 按任务类型先读对应规范，源码与文档不一致时以源码为准 编辑前先对任务分类，并阅读对该任务具有约束力的来源。 - 涉及组件行为或API时，阅读公共API指南、具体实现以及附近已获批准的组件。 - 涉及样式时，阅读详细样式规范、编译时令牌文件、运行时主题文件以及相邻的作用域样式。 - 涉及构建变更时，在修改流水线前阅读构建配置和每份自定义插件契约。 - 涉及测试时，阅读专用测试配置和附近的测试；涉及文档时，阅读同步矩阵。 - 按以下顺序解决冲突：源代码和当前生效的配置、仓库规则、专项文档、一般经验。 - 当源代码与文档不一致时，以源代码为准，并在同一获批范围内修复过时文档。 - 将速查表视为指向权威章节的索引，而不是规则的独立副本。 - 绝不虚构API，也不凭记忆判断受版本影响的行为；应核实已安装版本及其随附文档。 实现前，列出受影响的导出、样式、测试、演示注册表、文档和构建不变量。 ## 每个组件一个文件夹，放好代码、样式和测试 为每个组件设置一个专属文件夹，其中包含实现、作用域样式文件、导出入口以及同目录单元测试。分别添加公开值导出和类型导出，并注册所有必需的演示界面。 - 使用带类型的函数组件，在参数解构中定义默认值，并设置稳定的显示名称。 - 扩展适当的原生元素属性，只排除发生冲突的字段。 - 组件名和类型名遵循仓库规定的大小写形式，样式文件遵循配置的文件名格式，作用域类名遵循配置的类命名约定。 - 保持严格null检查和独立模块规则；避免绕过类型检查，并显式使用仅类型导出。 - 将import置于文件顶部，使用配置的项目别名，不要在组件作用域样式中放置全局选择器。 - 通过作用域样式映射或获准的类名辅助函数组合类名，不要硬编码生成后的类名。 - 让可复用辅助函数保持单一职责，并将其放在仓库约定的位置。 更改组件的公共接口时，必须同时更新其导出、测试、示例和API文档。 ## 颜色和圆角使用统一的设计值，不写零散的原始数值 为不同用途维护彼此独立的令牌层：编译时变量用于计算和mixin，运行时CSS自定义属性则允许使用方覆盖主题。不得将这两层视为可互换的机制。 - 确保构建配置与测试配置中的CSS Modules命名和令牌注入方式一致。 - 在组件样式中优先使用运行时语义令牌；只有需要预处理时才使用编译时变量。 - 使用系统中的语义角色表达颜色、焦点、圆角、层级、排版、字重和动效，而不是使用孤立的原始值。 - 当设计语言定义了带色调的表面、温暖的文本颜色或品牌化焦点状态时，避免纯粹的极值和通用的冷色默认值。 - 保留有意设计的组件轮廓、状态表现和阴影规则，不要把它们压平为单一的通用模式。 - 将全局字体、主题变量和重置样式统一置于一个全局样式入口之后。 - 尊重减少动态效果的偏好，并维持清晰可见的焦点、键盘操作、可读对比度以及文档规定的无障碍角色。 精确值和组件特有的例外必须取自权威设计规范和当前源代码，绝不能凭记忆决定。 ## 为每个组件测试键盘操作和无障碍能力 使用仓库专用的测试配置，其中应包含已声明的DOM环境、设置文件、匹配器、别名和CSS Modules处理方式。不得把测试设置移入当前测试运行器会忽略的构建配置。 - 将组件测试与组件放在同一位置，并使用获准的渲染、查询和用户交互工具。 - 覆盖渲染、由prop驱动的类、回调、禁用状态行为、状态变化以及相关的无障碍角色。 - 使用组件模式所要求的按键测试键盘行为，包括焦点移动、激活、关闭和方向控制。 - 通过import的样式映射断言作用域类，不要使用生成后的字符串字面量。 - 测试命令式API时，应在测试框架的状态边界内调用它，并等待其挂载结果；不要把非组件API当作JSX渲染。 - 集中维护共享测试工具，并使用符合真实情况的用户交互，而不是较低层级的事件快捷方式。 - 达到配置的覆盖率阈值，并记录任何有意排除项；不要用低价值用例虚增覆盖率。 修复缺陷时，先运行一项聚焦且会失败的测试，再运行受影响的测试套件，最后在完成前运行全部必需测试套件。 ## 保持模块化构建，让使用方只加载用到的组件 将自定义构建插件、包导出和资源规则视为与使用方之间的契约。 - 分别保留ES-module和CommonJS产物，并维持模块边界，使未使用的组件仍可通过tree shaking排除。 - 当框架和获准的辅助包属于peer dependency时，应将它们保持为external；没有明确要求时，不得添加runtime dependency。 - 保持CSS代码拆分，以及将每个组件的样式关联到其JavaScript入口的机制。 - 保持全局样式表入口完整，同时防止未使用组件的资源进入使用方bundle。 - 遵循仓库的资源复制与内联策略，包括字体格式和public path要求。 - 使包的export map、发布文件和side effect声明与生成后的结构一致。 - 只有在阅读自定义插件契约后才能更改构建逻辑，之后还要验证组件级import和全局样式入口。 生成的分发、演示构建和覆盖率目录属于产物，而不是源文件编辑区域；除非仓库策略明确要求，否则不得提交。 ## 组件一改，就同步更新文档和演示页面 更新受组件变更影响的每个权威界面。 - API或prop发生变化时，根据源代码更新API手册；样式发生变化时，更新详细样式规范。 - 视觉语言发生变化时，更新设计概要；新增组件时，更新面向用户的提示或目录规范。 - 组件数量或覆盖率发生变化时，通过获准的生成器更新所有镜像readme。 - 演示注册可能分布在路由元数据、渲染器映射和主页目录中；应更新每个独立注册表。 - 让机器可读的计数派生自权威元数据，不要手工重复记录。 - 运行文档同步检查器，并明确它不会检查哪些演示界面或生成界面。 - 通过获准的命令重新生成受版本控制的产物，不要直接编辑生成内容。 更改注册后，验证选择演示路由时会渲染预期页面；如果菜单已高亮而主区域为空，通常说明缺少某项注册表条目。 ## 防止批量替换出错、演示页空白等已知失败 对于可能在不易察觉的情况下破坏大量文件的变更，应使用范围狭窄且可验证的操作。 - 使用脚本替换时，立即验证每个目标，考虑字符串操作不会原地修改，并避免使用跨带引号标记时会失败的模式。 - 当测试工具写入结构化结果时，应提供其要求的保存路径，不要假定存在默认文件。 - 进行DOM转图像捕获时，如果渲染引擎无法读取文档字体注册表，应将所需字体声明嵌入捕获根节点。 - 不要仅为改善表面的tree shaking指标而重构有意保留的组件内部依赖关系。 - 通过维持按需import，并防止未使用的大型资源、字体和组件进入使用方bundle，优化包大小。 - 排查空白演示页面时，应先检查每个独立页面注册表，再更改组件实现。 如果仓库中有稳定的安置位置，应将每个已确认会反复出现的故障转化为一项聚焦的自动检查。 ## 交付更改前，跑完全部 CI 检查 按照仓库要求的顺序运行文档规定的格式化检查、lint、单元测试和库构建。在提出贡献前，运行完整CI命令。 确认： - 所有发生变化的组件、导出、测试、文档和演示注册表均已同步； - 当覆盖率或组件数量徽章的输入发生变化时，已重新生成相应徽章； - 没有未经批准的runtime dependency或生成产物进入此次变更； - 模块化产物、CSS拆分和资源加载契约仍然有效； - 视觉变更符合当前令牌规范和组件规范； - 最终差异仅包含预期的源代码和文档变更。 如果任何必需检查失败，应修复失败并重新运行相关门禁，之后才能展示差异。采用仓库的贡献格式，并且只有任务明确包含发布工作时，才运行发布流程。准确报告已运行的检查，以及有意排除在范围之外的任何更广泛检查。