class_hour_record/design_guidelines.md

轻课记事小程序设计指南

1. 品牌定位

• 应用定位：轻量级移动端课时管理工具
• 设计风格：简洁、实用、专业
• 目标用户：培训机构、个人教师
• 核心功能：登录验证、课时记录、学员管理、数据统计、按时间查看

2. 配色方案

主色调

• 主色 (Primary)：#1890ff - 蓝色，用于主要按钮、标题强调
• 次要色 (Secondary)：#f5f5f5 - 浅灰，用于卡片背景、输入框背景
• 强调色 (Accent)：#52c41a - 绿色，用于成功状态
• 警告色 (Destructive)：#ff4d4f - 红色，用于错误、删除等操作

中性色

• 文字主色：#333333 - 深灰
• 文字次要：#666666 - 中灰
• 文字辅助：#999999 - 浅灰
• 边框色：#e5e5e5 - 边框、分割线
• 背景色：#ffffff - 页面背景

Tailwind 类名映射

/* 颜色变量 */
--primary: #1890ff;
--primary-foreground: #ffffff;
--secondary: #f5f5f5;
--secondary-foreground: #333333;
--muted: #f5f5f5;
--muted-foreground: #999999;
--accent: #52c41a;
--accent-foreground: #ffffff;
--destructive: #ff4d4f;
--destructive-foreground: #ffffff;
--border: #e5e5e5;
--input: #e5e5e5;
--background: #ffffff;
--foreground: #333333;

3. 字体规范

• 标题：text-lg (18px)，font-semibold (600)
• 正文：text-sm (14px)，font-normal (400)
• 辅助文字：text-xs (12px)，text-muted-foreground
• 数字金额：font-mono，等宽显示

4. 间距系统

• 页面边距：px-4 (16px)
• 卡片内边距：p-4 (16px)
• 组件间距：gap-4 (16px) 或 mb-4
• 按钮高度：h-11 (44px) - 适配触摸操作
• 输入框高度：h-12 (48px)

5. 组件使用原则

组件选型约束

• 通用组件优先：按钮、输入框、弹窗、Tabs、Toast、Card 等通用组件必须优先使用 @/components/ui/*
• 禁止手搓通用组件：禁止使用 View/Text 手搓按钮、输入框、卡片等通用 UI
• 业务组件按需：页面结构容器使用 @tarojs/components

页面组件选型

创建或重写页面前，必须先判断页面里哪些区域应优先复用 @/components/ui/*：

• 表单输入 → Input, Field
• 提交按钮 → Button
• 信息展示 → Card, Badge
• 提示信息 → Toast, Alert
• 日期选择 → Calendar
• 空状态 → 自定义空状态组件（图标+文案）

6. 导航结构

页面路由

pages/login/index      - 登录页面（默认）
pages/index/index      - 首页（功能入口）
pages/student/index    - 学员管理
pages/record/index     - 课时录入
pages/report/index     - 数据查看

页面跳转

• TabBar 内跳转：Taro.switchTab()
• 普通页面跳转：Taro.navigateTo()
• 返回上一页：Taro.navigateBack()

7. 容器样式原则

卡片样式

<Card className="rounded-xl shadow-sm border border-border">
  <CardContent className="p-4">
    {/* 内容 */}
  </CardContent>
</Card>

页面容器

<View className="min-h-screen bg-background">
  <View className="px-4 py-4">
    {/* 内容 */}
  </View>
</View>

8. 状态展示

加载态

• 使用 Skeleton 组件
• 骨架屏替代 loading 文字

空状态

• 居中显示图标
• 主文案 + 副文案
• 可选操作按钮

错误状态

• 红色警示图标
• 错误描述
• 重试按钮

9. 小程序约束

包体积

• 控制代码包在 2MB 以内
• 图片资源使用 TOS 对象存储

性能优化

• 列表使用 onEndReached 加载更多
• 避免频繁 setData
• 使用 scroll-view 优化长列表

兼容处理

• Text 组件添加 className="block"
• Input 组件外层 View 包裹
• Fixed 定位使用 inline style