v2-refactor-temp/docs/ui/ui-library-current-issues.md
更新日期：2026-04-16 范围：
packages/ui目的：记录@cherrystudio/ui当前已识别出的架构问题，作为后续 v2 UI 收口与拆分的依据。状态：历史快照。 本文保留当时的问题背景，不再作为当前主题架构的事实来源。现行契约请以
packages/ui/docs/design-token-system.md和packages/ui/docs/variable-catalog.md为准。
packages/ui 当前同时承担了多种职责：
这让它在 monorepo 内部可以继续承担“迁移缓冲区”的角色，但也导致对外边界、发布契约和技术栈约束都不够稳定。
当前最核心的问题不是某一个组件实现有缺陷，而是 @cherrystudio/ui 还没有从“内部迁移目录”真正收敛为“边界稳定的 UI 库”。
packages/ui/package.json 当前只发布：
distREADME.md但 exports 仍然把样式子路径导向 src/styles/*：
./styles./styles/tokens.css./styles/theme.css./styles/index.css这意味着：
类似地，./icons export 指向 dist/components/icons/index.*，但当前构建产物并没有对应目录，说明 export 设计与构建配置之间也没有完全对齐。
结论：
@cherrystudio/ui 现在更像“源码别名入口”，而不是“可独立发布的包”。
虽然 v2 的方向是：
@cherrystudio/ui但当前包里仍存在旧依赖残留：
EditableNumber 直接依赖 antdEditableNumber、Scrollbar、Sortable、HorizontalScrollContainer 等仍在使用 styled-componentstsdown.config.ts 仍将 styled-components 作为 external 保留package.json 的 devDependencies 中仍包含 antd、styled-components、@types/styled-components这类残留的风险不是“包暂时还能跑”，而是：
如果一个公共 UI 包还默认允许旧技术栈存活，那么它就很难成为 v2 UI 重构的真正收口点。
这份快照记录的问题已经由 Shadcn v2 变量契约收口。当前依赖方向为：
tokens/** 提供 foundation 值theme-input.css 声明受控运行时输入shadcn.css 提供无前缀的官方语义变量product.css 提供经过审核的无前缀产品语义theme.css 只负责 Tailwind @theme inline 适配Renderer 的 tailwind.css 只接入共享生成适配器，不再维护第二套主题变量。运行时主题逻辑只写
--cs-theme-* 输入；手写 CSS 直接消费官方语义变量或稳定产品变量，不消费 --color-*。完整现行规则见
本文开头链接的规范文档。
当前 packages/ui/README.md 与真实状态不一致，典型表现包括：
HeroUIProvider这种漂移会带来两个问题：
packages/ui 当前把以下内容放在同一个包里：
这会导致：
体量大本身不是问题，职责不收口才是问题。
包内部大量通过 @cherrystudio/ui/lib/utils 引用 cn 等内部工具。
这类自引用在 monorepo 中短期可用，但会带来几个问题：
更合理的方式应该是：
当前 packages/ui 的测试主要集中在：
但该包实际承载的公开能力远多于当前测试覆盖，包括：
这会导致一个典型风险：
包的对外表面积已经很大，但“哪些行为是受保护 contract”仍然不清楚。
antd / styled-components 迁移债务这些问题会直接阻碍 UI 包独立演进，也会影响后续 v2 收口。
这些问题不一定立刻导致功能故障，但会持续抬高维护成本。
这两项可以在完成边界收口后继续推进。
先统一发布契约：
exports 只能指向真实会发布的产物icons、styles 等子路径 export 需要和构建产物一一对应这一层不解决，后续所有“组件设计系统化”都仍然建立在不稳定基础上。
需要明确哪些组件属于：
原则上：
antdstyled-components需要收敛主题系统的三层边界：
同时约定：
packages/ui 的定位从“迁移缓冲区”改成“稳定边界”长期看，packages/ui 应只保留与运行时 UI 强相关的内容：
而以下内容可以继续评估是否拆离：
本方案不追求一次性“大拆大改”，而是按“先稳边界，再减耦合，最后做结构优化”的顺序推进。
这样做的原因很简单：
因此更合理的路径是先把 contract 固定下来，再逐步清理迁移债务。
这轮优化的目标不是立刻把 packages/ui 变成一个完美的独立 design system，而是先完成以下四件事：
目标：
让 @cherrystudio/ui 先成为一个“入口稳定、对外契约清晰”的包。
主要工作：
package.json 中的 exports、files 和真实构建产物styles、icons 等子路径 export 指向packages/ui/src/*建议原则：
阶段产出：
目标：
把 antd / styled-components 从“正式 UI 层”中剥离出去。
主要工作：
建议优先处理的组件：
EditableNumberScrollbarHorizontalScrollContainerSortable组件治理规则：
antd 依赖styled-components 依赖阶段产出：
目标：
明确 token、theme、runtime override 三层职责。
建议分层：
tokens: 负责设计令牌theme: 负责语义映射与 Tailwind 对接runtime override: 负责用户主题与运行时覆写主要工作：
useUserTheme 只能覆写明确允许覆写的变量建议规则：
实际落地约定：
@cherrystudio/ui/styles/theme.css，并优先使用语义 Tailwind 工具类--color-* 是生成的 Tailwind 适配层，不是运行时消费 API--cs-theme-* 是 runtime override input，只允许主题宿主写入@cherrystudio/ui/styles/tokens.css阶段产出：
目标：
在边界稳定后，再判断哪些内容应该继续留在 packages/ui，哪些应该拆出。
可评估拆离的内容：
长期期望：
packages/ui 只保留运行时强相关内容阶段产出：
推荐顺序如下：
src/* 的直接依赖这样做的好处是：
如果要真正落地，建议把这件事拆成 5 个 workstream 并行推进：
负责：
package.jsontsdown.config.ts验收重点：
负责：
验收重点：
负责：
验收重点：
负责：
验收重点：
负责：
验收重点：
达到以下条件即可视为第一阶段完成：
packages/ui/src/*达到以下条件即可视为第二阶段完成：
antdstyled-components达到以下条件即可视为第三阶段完成：
达到以下条件即可视为长期治理进入稳定期：
packages/ui 的运行时职责清晰优化完成后，至少应满足以下标准：
@cherrystudio/ui 的所有公开入口都具备稳定 contractantd / styled-components在推进过程中，应避免以下方案：
这些做法看似能短期推进，实际会让 UI 包继续停留在“迁移缓冲区”状态。
packages/ui 当前最大的问题不是“还有一些旧代码”，而是它仍然同时扮演：
在 v2 继续推进之前，必须先把它收敛成一个边界稳定、发布契约明确、技术栈一致的 UI 包，否则它很难成为后续 UI 重构的基础设施。