UI 改进建议

基于对 Innate Playground 项目代码的全面审查，以下是按优先级和模块分类的 UI 改进建议。

1. 布局与导航（高优先级）

1.1 修复 Sidebar 分组状态不一致的 Bug

文件：components/layout/app-sidebar.tsx:192-195

问题：系列分组的标签文字是"系列"，但状态键使用的是 collapsedGroups["courses"]，与标签组 ID 不统一。这会导致切换"系列"分组时，实际检查的是不存在的 "courses" 键。

建议修复：

// 第 192-195 行
<SidebarGroupLabel
  className="cursor-pointer select-none"
  onClick={() => toggleGroup("series")}  // 改为 "series" 与标签一致
>
  系列
  <ChevronRight className={`ml-auto size-3 transition-transform duration-200 ${collapsedGroups["series"] ? "" : "rotate-90"}`} />
</SidebarGroupLabel>
{!collapsedGroups["series"] && (   // 改为 "series"

1.2 Sidebar 系列列表滚动优化

问题：当系列和教程数量增多时，Sidebar 的可展开系列列表会超出视口，但目前没有独立的滚动区域，会导致整个 Sidebar 被撑高。

建议：为系列分组的内容区域添加 max-height 和 overflow-y-auto，使其独立滚动：

<SidebarGroupContent className="max-h-[calc(100vh-400px)] overflow-y-auto">

1.3 MenuBar 搜索交互增强

文件：components/layout/menu-bar.tsx

问题：搜索栏仅支持 Enter 跳转，没有实时搜索建议或搜索结果预览。

建议：

添加搜索下拉面板，实时显示匹配的教程和系列（最多 5-8 条）
使用 Command 组件（来自 shadcn/ui）实现类似 Spotlight 的搜索体验
支持键盘上下导航（↑↓）选择结果，Enter 确认

1.4 面包屑导航缺失

问题：除 /learn 页面外，其他页面（教程详情、系列详情）没有面包屑导航，用户无法快速了解当前位置和返回上级。

建议：在教程详情页和系列详情页顶部添加面包屑：

首页 > 系列中心 > Node.js 基础 > 安装 Node.js

2. 终端面板（高优先级）

2.1 终端标签页支持

文件：components/terminal-panel.tsx

问题：当前只有一个终端实例，用户无法同时运行多个命令或查看不同会话的输出。

建议：

添加标签页系统，支持创建/关闭多个终端标签
每个标签独立维护一个 PTY 会话
在终端头部添加标签栏（类似 VS Code）

2.2 终端空状态提示

问题：终端首次打开时只显示欢迎文本，对于新用户不够友好。

建议：在终端头部添加快捷命令面板（可折叠），展示常用命令模板，如：

快速运行：node -v | npm install | git status | pwd

2.3 终端搜索功能

问题：终端输出增多后，难以查找特定内容。

建议：集成 @xterm/addon-search，通过 Ctrl+Shift+F 呼出搜索框，支持高亮匹配项。

2.4 终端字体大小调节

问题：不同用户对终端字体大小需求不同，当前固定 fontSize: 13。

建议：在终端头部添加字号放大/缩小按钮（Ctrl++ / Ctrl+-），并将偏好存入 localStorage。

3. 首页与内容展示（中优先级）

3.1 空状态视觉优化

文件：app/page.tsx

问题：当暂无系列或教程时，空状态页面较为简陋（仅图标 + 文字 + 按钮）。

建议：

设计更有吸引力的插图空状态（可使用 Lottie 动画或 SVG 插画）
添加引导文案，如"第一次使用？查看示例教程 →"
空状态卡片使用渐变色背景增加视觉层次

3.2 统计卡片动态化

文件：app/page.tsx:57-61

问题：学习时长为硬编码的 "120+"，没有实际计算。

建议：基于 progress 数据计算实际学习时长：

const totalMinutes = Object.values(progress).reduce((sum, p) => sum + (p.duration || 0), 0);

3.3 教程卡片信息密度

文件：app/page.tsx（最近教程部分）

问题：教程卡片缺少系列归属信息，用户不知道某个教程属于哪个学习路径。

建议：在教程卡片底部添加所属系列标签（带图标链接）：

{courseInfo && (
  <div className="flex items-center gap-1 text-xs text-primary mt-2">
    <FolderOpen size={12} />
    <span>{courseInfo.title}</span>
  </div>
)}

4. 教程详情页（中优先级）

4.1 右侧目录导航（TOC）

文件：app/tutorial/[id]/TutorialContent.tsx

问题：长教程页面缺少目录导航，用户难以快速跳转到特定章节。

建议：

解析 MDX 内容中的 h2/h3 标题，生成右侧悬浮目录
当前阅读章节高亮（通过 Intersection Observer 监听滚动位置）
点击目录项平滑滚动到对应位置

4.2 代码块增强

问题：代码块缺少行号、复制成功反馈、以及全屏展开功能。

建议：

为代码块添加左侧行号（使用 Shiki 的 lineNumbers 选项）
复制按钮点击后显示"已复制!" Tooltip 反馈（1.5 秒后恢复）
添加全屏按钮，将代码块以模态框展开（适合长脚本）

4.3 步骤式进度指示器

问题：教程详情页没有展示当前在系列中的位置（如"第 3 课，共 8 课"）。

建议：在页面顶部添加系列内进度指示器：

Node.js 基础  ───────○──○──●──○──○──○──○──○───────  3/8

（带左右导航箭头，可跳转到上一课/下一课）

4.4 完成庆祝动效

问题：点击"标记完成"后仅静态更新按钮状态，缺乏正向反馈。

建议：完成时触发庆祝动效：

使用 canvas-confetti 或 CSS 动画撒花效果
按钮变为"已完成"状态时有缩放脉冲动画
显示 Toast 通知："恭喜完成《xxx》！"

5. 学习工作台 `/learn`（高优先级）

5.1 从原型到实际功能

文件：components/workspace/tutorial-workspace-sketch.tsx

问题：当前为纯 mock 数据，没有连接真实教程数据。

建议：这是最需要投入的方向：

将 mock 数据替换为 useAppStore 中的真实教程数据
实现步骤与教程内容的关联（从 MDX 的 {executable} 块提取命令）
步骤执行状态与 progress store 同步

5.2 步骤执行状态可视化

建议：每个步骤添加更丰富的状态指示：

成功步骤显示绿色对勾 + 执行时间
运行中步骤显示旋转加载器 + 终端输出实时预览
错误步骤显示红色警告 + 错误输出摘要
支持步骤重试

5.3 输出日志面板

建议：右侧面板从纯终端改为"步骤日志 + 终端"双模式切换：

步骤日志：结构化显示每个步骤的命令、输出、状态、耗时
终端：保留完整的交互式终端

6. 设置页（中优先级）

6.1 API Keys 持久化

文件：app/settings/page.tsx

问题：API Key 输入框是纯展示性的，没有保存/加载逻辑。

建议：

使用 Tauri 的 secureStore 或 localStorage 加密存储 API Keys
添加显示/隐藏切换按钮
添加验证按钮（测试 API Key 是否有效）

6.2 终端偏好设置

建议：添加终端设置卡片：

默认位置（右侧/底部）
默认字体大小
默认高度/宽度
光标样式（Block/Line/Bar）
滚动缓冲区大小

6.3 快捷键一览

建议：添加快捷键参考面板，列出所有可用快捷键：

Ctrl+Shift+T — 切换终端
Ctrl+Shift+F — 搜索
Ctrl+B — 切换侧边栏
Ctrl+J — 切换终端位置

7. 动画与交互（低优先级）

7.1 页面过渡动画

问题：页面切换时生硬，没有过渡效果。

建议：使用 Next.js App Router 的 template.tsx 或 Framer Motion 添加页面切换动画：

淡入 + 轻微上移（opacity: 0→1, translateY: 10px→0）
过渡时长 200-300ms，使用 ease-out

7.2 卡片悬停动效统一

问题：不同页面的卡片悬停效果略有差异（有的有阴影，有的没有）。

建议：统一卡片交互规范：

悬停：translateY(-2px) + shadow-lg + border-primary/30
过渡时长：duration-200
点击：scale-[0.98] 微缩反馈

7.3 骨架屏加载

问题：多个页面使用简单的旋转动画作为加载状态（animate-spin），不够现代。

建议：使用 shadcn/ui 的 Skeleton 组件实现骨架屏：

首页：3 个统计卡片骨架 + 4 个教程卡片骨架
教程列表：6 个卡片骨架网格
系列列表：4 个卡片骨架网格

8. 响应式与移动端（中优先级）

8.1 移动端侧边栏体验

问题：移动端侧边栏直接显示，占据大量屏幕空间。

建议：

移动端默认折叠侧边栏为图标模式或完全隐藏
通过汉堡菜单按钮触发 Sheet/Drawer 样式的侧边栏覆盖层
侧边栏打开时添加背景遮罩 + 点击外部关闭

8.2 终端面板移动端适配

问题：终端在移动端右侧模式下宽度不可接受。

建议：移动端强制使用底部模式，高度限制为屏幕的 30-40%，支持手势上下滑动调整高度。

8.3 触控友好的按钮尺寸

问题：部分按钮（如终端头部按钮 size="icon"）尺寸过小，触控困难。

建议：移动端触控目标至少 44×44px，可通过 Tailwind 的 min-touch-target 或增大按钮尺寸实现。

9. 无障碍与细节（低优先级）

9.1 焦点状态优化

问题：部分交互元素（如教程列表中的自定义按钮）缺少明显的焦点指示器。

建议：统一使用 focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:ring-offset-2 样式。

9.2 ARIA 标签补全

问题：部分图标按钮缺少 aria-label。

建议：为所有 Button variant="ghost" size="icon" 添加 aria-label 或 title 属性。

9.3 颜色对比度检查

问题：text-muted-foreground 在部分背景上的对比度可能不足。

建议：使用 @radix-ui/colors 或 APCA 工具检查关键文本的对比度，确保符合 WCAG AA 标准。

10. 性能优化（低优先级）

10.1 虚拟滚动

问题：当教程数量超过 50 时，网格渲染性能下降。

建议：使用 react-window 或 @tanstack/react-virtual 实现教程列表虚拟滚动。

10.2 图片/图标优化

问题：系列图标使用 emoji（c.icon || "📚"），在不同平台显示不一致。

建议：使用自定义 SVG 图标或 lucide-react 图标替代 emoji，保持跨平台一致性。可为每个系列分配一个图标名（如 "BookOpen", "Terminal", "Code"），从图标映射表渲染。

10.3 代码分割

问题：TutorialContent.tsx 同步导入 next-mdx-remote 和 serialize，首屏加载较重。

建议：使用 React.lazy() 或动态导入 next-mdx-remote，将 MDX 序列化逻辑推迟到需要时。

实施路线图建议

阶段	内容	预计工时
Phase 1	修复 Sidebar Bug、添加面包屑、终端标签页	2-3 天
Phase 2	学习工作台实现、教程 TOC、完成动效	4-5 天
Phase 3	搜索增强、设置持久化、移动端适配	3-4 天
Phase 4	动画优化、骨架屏、无障碍改进	2-3 天

总结

当前 UI 已经具备了良好的视觉基础和组件体系（shadcn/ui + Radix），主要改进方向集中在：

Bug 修复（Sidebar 状态键不一致）
功能补全（学习工作台、终端标签、TOC）
体验打磨（搜索、动画、空状态、反馈）
多端适配（移动端响应式）

建议优先处理 Phase 1 的高优先级项，它们能显著提升日常使用的稳定性和效率。

Uh oh!

FilesExpand file tree

UI_IMPROVEMENTS.md

Latest commit

History