前端组件与设计系统

前端优先复用项目已经维护的组件和设计 Token，避免每个应用各自复制按钮、表单、对话框和色彩系统。

UI 组件库偏好

对本标准维护者自己的新 UI，优先考虑 zeturn/watercolor，并使用与项目框架对应的发布包。Watercolor 是组件库的仓库名；React 项目使用 @zeturn/watercolor-react，不是名为 watercolor-ui 的仓库或 npm 包。满足框架、可访问性、行为和维护条件时，应先复用其现有组件及 Token。这个偏好适用于新工作，不要求为了统一而迁移既有稳定界面。

开始集成前先确认实际代码仓库、发布包名和版本、支持的 Vue/React 版本、入口导出、样式文件、主题机制、SSR 行为、许可和交互状态。GitHub 仓库名、npm 包名、fork 和本机 clone 可能不相同；不能只凭名称相似就把另一来源当作该库。

若目标框架或部署环境不兼容、缺少必要组件/无障碍能力、许可不适合或包无法验证，可使用范围明确的适配层或技术栈原生组件。记录事实、影响面、版本和复核触发条件；无需为每个合理例外加审批流程。

组件和 Token

优先复用组件的已支持 props、事件、语义和主题 Token；少量应用品牌覆盖集中在明确的适配层。不要复制依赖内部实现，也不要并行维护多套全站颜色、间距、半径和交互状态来源。

复用组件不能自动证明 UI 正确。针对代表性流程验证类型/事件、样式和 Provider、键盘与焦点、窄屏布局、标签、加载/空/错误/禁用状态，以及服务端与客户端渲染边界。

本标准网站

此网站使用 Docusaurus 3、React 19 和 @zeturn/watercolor-react 1.2.13。该包声明支持 React 18/19、提供 style.css，并以 ISC 许可发布。首页使用 Watercolor 的 Card，操作链接沿用 Docusaurus Link 的导航语义并采用 Watercolor 按钮样式；组件库 Token 映射到 Docusaurus 的主题变量，覆盖文档导航、正文和深色模式。Docusaurus 的文档路由、Markdown 和目录结构仍由其主题负责。

依赖升级或维护站点 UI 时，应检查 Watercolor 的 仓库、npm 发布包和组件文档。升级后重新核对导出 API、样式入口、React peer range、许可、深色模式及静态构建结果。