PureChatNext 样式迁移方案

将 PureChatNext 业务组件渐进迁移到 Tailwind CSS 的阶段与验收标准。

目标

逐步将业务层从 LobeHub 风格的 createStaticStyles 迁移到 Tailwind CSS，同时保留复杂 CSS 的表达能力，避免视觉回归和一次性大规模重构。

迁移完成后的边界：

新业务组件默认使用 Tailwind，但格式化后的单个静态 className 不得超过 120 字符。
简单静态样式不再新增 createStaticStyles。
复杂、动态、动画、超长 className 和基础 UI 样式允许继续使用 createStaticStyles。
@pure/ui 的主题和组件桥接在业务迁移稳定后再单独评估。

当前基线

当前仓库已经在 src/styles/globals.css 接入 Tailwind v4，并通过 postcss.config.mjs 构建。

迁移前的代码扫描基线：

约 90 个生产代码文件使用 createStaticStyles。
约 85 个生产代码文件直接使用 cssVar。
主要分布在 chat、settings、home、resources、community。
Tailwind class 已在 dev 页面、认证页和少量基础组件中使用。

这些数字用于衡量进度，不应作为一次性迁移清单。每次迁移后可用以下命令重新统计：

rg -l "createStaticStyles" src packages --glob '*.{ts,tsx}' --glob '!**/*.test.*' | wc -l
rg -l "cssVar" src packages --glob '*.{ts,tsx}' --glob '!**/*.test.*' | wc -l

阶段 0：先统一 token 和边界

在迁移业务页面前完成：

确认 ThemeProvider 产生的运行时 CSS 变量命名和暗色模式行为。
在 src/styles/globals.css 的 @theme inline 中建立语义化 Tailwind token，或在 src/styles/utilities.css 中建立少量稳定的语义 utility。
明确文字、背景、边框、主色、成功、警告、错误、阴影和圆角的映射。
约定业务组件不得直接复制 dev 页面中的展示色作为主应用主题。
保留 antd-style 和 StyleProvider，因为 @pure/ui 仍依赖它们。

推荐的 token 方向：

@theme inline {
  --color-app-text: var(--ant-color-text);
  --color-app-text-secondary: var(--ant-color-text-secondary);
  --color-app-surface: var(--ant-color-bg-container);
  --color-app-border: var(--ant-color-border-secondary);
}

ThemeProvider 的 theme={{ cssVar: { key: 'pure-vars' } }} 只设置 CSS 变量作用域 key，不会把 key 作为变量名前缀。当前 antd-style 的 cssVar 实际对应 kebab-case 的 --ant-* 变量，例如：

cssVar.colorTextSecondary → var(--ant-color-text-secondary)
cssVar.colorError → var(--ant-color-error)
cssVar.colorErrorBg → var(--ant-color-error-bg)

上面的 app-* 仅表示后续可新增的语义映射方向。新增前必须确认变量在实际 Provider 作用域内存在，并验证浅色、深色主题；业务 JSX 只能使用已经提交到 globals.css 的语义 token，不得自行拼接变量名。

阶段 1：新代码设闸

从规则生效开始：

新组件默认写 Tailwind class。
少量样式修改不创建 styles 常量。
格式化后单个静态 className 超过 120 字符时，先复用 Tailwind 内置工具和 utilities.css 组合；仍超限则必须使用 createStaticStyles。
createStaticStyles 可用于复杂样式、动态几何值和无法合理压缩到 120 字符以内的组件级样式。
新增例外时，在代码附近写一句保留原因。
@pure/ui 组件继续使用，但业务布局优先用 className 或已有 props 组合。

这一步不要求立即减少存量，只防止迁移过程中继续增加债务。

阶段 2：试点迁移

优先选择简单、边界清晰、视觉影响可控的文件，例如：

src/features/settings/provider/styles.ts
settings 中的 row、label、hint、shell
简单的 card、empty state、页面容器
只包含布局、间距、颜色、border、radius 的 createStaticStyles

每个试点按以下顺序完成：

把 styles.xxx 用 Tailwind class 替换。
检查静态 className 是否超过 120 字符；优先复用 Tailwind 内置工具和已有公共 utility。
只有跨组件重复且语义稳定时才新增 @utility；单组件样式仍超限则保留或恢复 createStaticStyles。
将 cssVar 使用转为 globals.css 已存在的语义 token；不存在映射时继续通过 createStaticStyles 使用 cssVar。
删除无用的 antd-style import、样式常量和测试 mock。
检查响应式、暗色模式和交互状态。
运行 lint/typecheck，并进行页面视觉检查。