文档优化 TODO 清单

目标：把 Nova UI 文档从“可用”升级到“高效查阅 + 易维护 + 可度量改进”。

P0（优先处理）

1) 统一页面信息架构（IA）

[ ] 为所有组件页统一结构：介绍 -> 何时使用 -> 示例 -> API -> 可访问性 -> 常见问题。
[ ] 每个组件页新增 何时使用 / 何时不建议使用 小节，减少误用。
[ ] API 表字段统一（属性 / 说明 / 类型 / 默认值 / 版本）。

验收标准

任意抽查 10 个组件页面，目录结构一致。
新同学 5 分钟内能定位到组件 API 与示例。

2) 提升组件示例质量

[ ] 每个组件至少提供 3 类示例：基础、进阶、边界场景（空值/禁用/错误态）。
[ ] 补齐“真实业务组合示例”（如 Form + Select + Upload 联动）。
[ ] 对复杂示例增加“关键点说明”，避免仅展示代码。

验收标准

组件示例覆盖率 >= 90%（有基础 + 进阶示例）。
用户无需查看源码即可理解关键交互。

3) API 文档自动化（减少手工维护）

[ ] 评估从 TypeScript 类型自动生成 API 表（props / events / methods）。
[ ] 约定注释规范（如 @default, @since, @deprecated）。
[ ] 建立“变更即更新 API 文档”的 CI 检查。

验收标准

新增/修改 props 后，文档可自动同步或触发 CI 提示。
API 表手工更新工作量明显下降。

4) 导航与检索优化

[ ] 在组件总览页增加“按场景筛选”（表单录入/反馈提示/数据展示等）。
[ ] 为高频组件增加“快速入口”区块（Button / Form / Table / Modal）。
[ ] 优化页面标题与关键词，提升站内搜索命中率。

验收标准

站内搜索前 3 条结果命中用户意图。
常用组件平均点击深度下降（更快抵达）。

P1（次优先级）

[ ] 每类组件补充键盘操作说明（Tab/Enter/Esc 等）。
[ ] 标注 ARIA 使用建议与常见误区。
[ ] 增加“屏幕阅读器体验”注意事项。

6) 国际化与术语规范

[ ] 建立中英文术语表（如 Drawer/抽屉、Popover/气泡卡片）。
[ ] 统一按钮文案与状态文案风格（确定/取消/保存中）。
[ ] 预留英文文档结构（先不全量翻译也可）。

7) 版本与迁移文档

[ ] 建立 Changelog 阅读入口与“升级指引”页面。
[ ] 对破坏性变更提供“迁移前后代码对比”。
[ ] 标注组件/属性的引入版本与废弃计划。

8) FAQ 与故障排查

[ ] 汇总高频问题：样式覆盖、暗黑模式、SSR、按需引入。
[ ] 每个 FAQ 给出“最小复现 + 解决方案 + 原因”。
[ ] 在组件页底部增加“相关 FAQ”跳转。

P2（持续优化）

9) 文档体验增强

[ ] 提供“复制代码成功提示”和“展开/折叠代码”。
[ ] 示例支持切换主题（亮色/暗色）并保持状态。
[ ] 优化移动端阅读样式（表格横向滚动、代码折行策略）。

10) 文档质量度量看板

[ ] 定义指标：页面访问、停留时长、跳出率、搜索无结果词。
[ ] 每月输出一次“文档优化报告”。
[ ] 将无结果高频词反向驱动文档补齐。

11) 贡献流程与规范

[ ] 新增“文档贡献指南”（写作模板、提交流程、Review 清单）。
[ ] 增加 PR 模板：示例截图、变更影响、验证步骤。
[ ] 约定“组件发布必须附文档更新”的门禁。

可立即执行的两周计划（建议）

Week 1

[ ] 统一 10 个高频组件页面结构（Button / Input / Select / Form / Table...）。
[ ] 为上述页面补齐“何时使用 + 边界示例 + FAQ”。
[ ] 确认 API 表字段规范并完成首批试点。

Week 2

[ ] 落地总览页筛选与快速入口。
[ ] 完成 A11y 说明模板并接入 10 个页面。
[ ] 建立基础度量（搜索无结果词 + 高访问低停留页面）。

负责人建议（可选）

文档 owner：负责信息架构与验收。
组件 owner：负责示例与 API 正确性。
设计/体验 owner：负责术语、视觉一致性与可读性。