ballet-server/DESIGN.md

# 芭蕾岛设计规范

本文件定义芭蕾岛小程序的视觉语言，供设计与开发新页面、调整已有组件时使用。适用范围为 `miniprogram/` 中的记录、日历、成长及相关表单和管理页面。

正文中的使用规则是后续设计的默认依据；表格中的数值沿用现有实现。标为「现状」或「待验证」的内容只描述实现边界，不代表长期设计决策或已通过验收。未覆盖的新场景，先按视觉原则选择最接近的现有模式。

本文采用纯 Markdown，按 [Google Labs DESIGN.md 格式规范](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)的主题组织。色彩角色名称用于沟通设计，不表示代码中已存在同名 token。

## Overview

芭蕾岛面向希望记录和回看练习的芭蕾练习者。界面以一本温暖、安静的练习手账为视觉参考：暖白纸面、灰玫瑰重点、清楚的日期和记录，留出足够空间容纳自己的笔记。

用户应当先看见练了什么、投入了多少时间，以及下一步如何记录。装饰保持克制，主要通过文字层级、浅色容器与留白建立秩序。密集数据也保持平静，避免用排行榜或成绩评判的语气解释练习。

设计时优先遵循以下原则：

- **记录优先**：让项目名称、练习时长和笔记易于阅读；管理与更正入口放在相关内容附近。
- **温和反馈**：用明确的状态与下一步帮助用户继续操作；休息日保持中性，不制造缺勤压力。
- **一致复用**：新增页面沿用已有标题、容器和操作层级，让熟悉一个页面的用户能理解其他页面。
- **表达真实投入**：数字与图表用于回顾练习，不把时长解释为技术水平或排名。

## Colors

暖白与暖灰构成大部分画面，灰玫瑰用于需要注意的操作、选中项和练习数据。通过限制强调色的用途保持重点清楚，避免把每个标题、边框或装饰都染成品牌色。

| 角色 | 基准色值 | 使用规则 |
| --- | --- | --- |
| 页面底色 | `#faf7f3` | 页面与顶部导航的连续背景 |
| 内容表面 | `#fffdfa` | 普通面板、记录卡片与底部导航 |
| 轻描边 | `#ece3dd` | 界定普通容器，避免描边比内容更醒目 |
| 主文字 | `#3e3435` | 正文、名称和标题，承担主要阅读信息 |
| 次要文字 | `#827572` | 日期、解释与辅助说明，仍需清晰可读 |
| 主强调色（Primary） | `#9c5268` | 主要操作、选中状态、记录时长和图表聚焦项 |
| 汇总标签 | `#946d76` | 标识今天或累计练习，不替代汇总数字 |
| 汇总表面 / 描边 / 数字 | `#f1e7e3` / `#eddfda` / `#864b5e` | 承载今天或累计练习的核心汇总，与普通记录形成层级 |
| 输入表面 / 描边 / 文字 | `#f8f4ef` / `#e8dfd8` / `#44383b` | 将可填写区域与外层面板区分 |
| 普通按钮文字 / 描边 | `#655656` / `#e5dcd6` | 辅助操作，背景沿用内容表面色 |
| 错误提示背景 / 文字 | `#fae9e9` / `#9d3748` | 需要处理的错误，配合文字说明原因 |
| 成功提示背景 / 文字 | `#eaf0e7` / `#4f6b4c` | 已确认完成的操作结果 |

### 项目与图表用色

项目卡片用低饱和底色帮助区分相邻入口，名称始终是识别项目的依据。现状为按展示顺序循环配色，排序变化后颜色可能变化；这些颜色不表达项目的固定身份、等级或状态。

| 项目卡片色组 | 背景 | 描边 |
| --- | --- | --- |
| 浅玫瑰 | `#f4ece8` | `#e7ded8` |
| 灰绿色 | `#eef0e7` | `#e0e5d9` |
| 灰紫色 | `#eeeaf2` | `#e3dfea` |
| 浅麦色 | `#f4efdf` | `#eae4d5` |

趋势柱形使用 `#d8a8b2`，聚焦项使用主强调色；项目分布使用 `#f0e8e2` 轨道与 `#bc8292` 填充。图表通过日期、时长、百分比和状态文字补足含义，颜色不承担唯一的信息提示。

危险操作沿用已有组件与原生确认弹窗的危险样式，不套用普通主操作色。平台默认色及各局部样式的具体映射见文末实现入口。

## Typography

使用系统无衬线字体，字体栈为 `-apple-system, BlinkMacSystemFont, 'PingFang SC', sans-serif`。中文名称与笔记优先保证连续阅读；数字通过适度放大和加重获得重点，不采用宣传海报式的大标题。

默认正文为 `15px`、行高 `1.55`。按信息角色选取层级，同一角色跨页面保持一致。

| 角色 | 字号 / 字重 | 使用规则 |
| --- | --- | --- |
| 页面标题 | 沿用原生导航栏 | 内容区域不重复放置页面大标题 |
| 核心汇总数字 | 时长 `29px / 600`，统计 `30px / 600` | 保留已有两种汇总组件；时长行高 `1.5` |
| 区块标题与项目入口名称 | `17px / 600` | 组织内容或标识可进入的项目 |
| 正文与记录名称 | `15px`，记录名称字重 `500` | 支持较长名称和实际内容 |
| 输入内容 | `16px` | 填写时保持可读；笔记行高 `1.6` |
| 表单标签 | `14px / 500` | 清楚表达字段含义 |
| 说明、记录时长与笔记 | `13px` | 作为局部辅助层级，不与汇总数字竞争 |
| 紧凑辅助信息与单位 | `12px` | 日期、单位、帮助文字等 |
| 空状态标题 | `16px / 500` | 简短说明当前无数据；可执行的下一步使用明确按钮 |

长项目名称、笔记和汇总时长允许换行，保留笔记的原始换行，不用省略号隐藏主要信息。数字必须带上可理解的单位，例如「1 小时 30 分钟」「2 次」。

现状中汇总标签及部分辅助文字使用 `10–11px`，趋势日期标签使用周视图 `10px`、月视图 `8px`。这些局部值不作为新正文或操作标签的默认字号；小字号和图表标签的可读性仍需在目标设备验证。

## Layout

页面以纵向单栏组织一个主要任务；项目入口和管理列表均为一行一张卡片，两列仅用于简短指标，七列仅用于日历。新增页面按「主要内容或输入 → 相关操作与反馈」建立阅读顺序，避免为了填满画面增加区块。

尺寸均为 `375px` 设计宽度下的源码设计尺寸，由现有构建配置转换为小程序单位，不等同于设备截图的物理像素。页面基准内边距为上 `20px`、左右 `18px`、下 `32px` 加底部安全区。

间距按内容关系选取，先复用相同组件的间距，再选择下列范围：

| 内容关系 | 间距基准 | 典型用途 |
| --- | --- | --- |
| 紧密关联 | `4–8px` | 数字与说明、标题与副标题、快捷按钮之间 |
| 同组内容 | `10–12px` | 行内间隙、相邻记录与两列网格；网格间距 `12px` |
| 容器内部 | `16–18px` | 普通内容与容器边缘的距离，具体按组件复用 |
| 独立区块 | `22–24px` | 区块分隔、标题区下方、表单操作区之前 |

这些范围描述现有间距的用途，不要求把现有数值机械归入统一倍数。汇总卡片和紧凑控件使用各自的容器内边距。

### 导航与内容组织

页面用途由原生导航栏说明，内容直接从数据或字段开始，不放页面大标题、品牌小字、抒情标题或副标题。管理、补记等局部入口靠近所属区块，表单主操作统一固定在底部。

当前一级导航为「记录、日历、成长」，使用文字 TabBar；练习记录和项目管理为二级页面。延续这一层级，新页面不自行增加一套全局导航。

快捷按钮允许换行，长内容允许撑高。编辑页面底部固定一行两个等宽按钮，左侧「取消」、右侧「保存」，间距 `12px`。操作栏下方保留安全区，页面底部预留 `100px` 加安全区，确保末尾内容可以滚动到操作栏上方。键盘出现时的可达性属于验收事项，不能仅凭静态布局认定已适配。

## Elevation & Depth

常规页面保持平面表现，通过暖白底色、浅色容器、细描边和留白建立层级。普通内容放在浅色面板上，核心汇总使用稍深的暖玫瑰底色；相邻同级记录使用一致表面，便于连续浏览。

常规卡片沿用 `1px` 细描边，不额外叠加阴影、发光或装饰渐变。需要突出信息时，先调整信息位置、文字层级或使用已有汇总容器。原生弹窗等浮层沿用平台表现，这一规则不用于覆盖系统控件。

## Shapes

容器采用柔和圆角。圆角与留白共同表达亲和感，组件之间通过用途保持一致；新增普通面板优先复用通用面板，已有专用组件保留自己的尺寸。

| 容器角色 | 圆角 | 内边距 | 选择依据 |
| --- | --- | --- | --- |
| 通用面板 | `18px` | `18px` | 表单或成组内容的默认容器 |
| 核心汇总 | `21px` | 上下 `23px`、左右 `22px` | 承载少量重点数字，留白比普通内容更充裕 |
| 项目入口 | `17px` | 上下 `10px`、左右 `16px` | 一行一张，名称前可放 `32px` 项目图标；高度由内容决定，支持名称换行 |
| 项目管理条目 | `17px` | 上下 `8px`、左右 `16px` | 名称与操作按钮同排；高度由内容决定 |
| 练习记录 | `16px` | 上下 `16px`、左右 `18px` | 可连续浏览的独立记录 |
| 日历面板 | `18px` | 上下 `16px`、左右 `12px` | 沿用面板外形，为七列日期留出横向空间 |
| 输入区域 | `11px` | 左右 `14px`；单行输入上下 `0`，选择区域与笔记上下 `12px` | 单行原生输入依靠高度定位文字，避免垂直内边距使文字下移 |
| 状态提示条 | `12px` | 上下 `13px`、左右 `15px` | 紧贴相关操作提供短反馈 |

按钮圆角为 `12px`，日期选中区域为 `13px`。这些差异是现有组件的基准，不构成一套可按大小任意套用的全局圆角等级。需要新容器时，按用途复用上表，避免再增加近似数值。

## Components

### 操作按钮

主要提交使用灰玫瑰实心按钮；底部「取消」与快捷选项使用描边按钮；管理、更正等辅助入口使用文字按钮。危险操作使用危险文字样式，并在确认时说明后果。

表单底部两个按钮沿用中号，高度 `44px`、字号 `16px`，各填满所在的半行；行内操作和切换沿用小号按钮，高度 `32px`、字号 `13px`。提交中显示加载状态并阻止重复操作，不能只靠按钮文字变化表达等待。

复用现有按钮组件及主题；按下、禁用和加载的具体表现沿用组件行为，不在页面上另造一套状态样式。

### 表单与输入

字段采用「上方标签 + 下方完整输入区域」，占位文字仅补充示例或提示。帮助文字靠近字段，字数计数置于笔记区下方右侧。

普通输入高度 `48px`；选择区域最小高度 `48px`，允许长内容撑高；笔记区沿用 `140px` 高度。标签与字段保持清楚关联，字段组之间留出更大间距。主要提交与取消使用固定底部操作栏，删除入口留在内容区，与保存操作分开。

### 卡片与列表

项目入口卡片展示名称与用户选择的图标，不放编号或重复的操作提示，不设用于装饰留白的最小高度。图标采用灰玫瑰线描和浅色填充，以 `32px` 方形置于名称前；未选择或无法识别图标时不占位。记录卡片先展示项目名与时长，再展示日期、归档标记与更正入口；笔记置于下方，以细线和留白分隔。长名称优先获得可换行空间。

管理条目每项独立成卡，以间距区分；图标、名称、编辑和移除按钮放在同一行，不附加重复的历史记录说明。编辑表单中可选择或取消图标，底部选择面板按「基础练习、专业动作、物件」分类；名称与图标一并保存。移除的归档或删除后果在确认弹窗中说明。历史记录中的归档状态仍用文字标注。

### 日历与图表

日历从周一开始，七列等宽。选中日期使用主强调色底与暖白文字；练习日使用圆点并提供含义说明。未来日期弱化且不可选择，休息日保持空白，不显示惩罚性标记。

趋势图用柱高表达时长，零分钟保持零高度。点按后高亮对应柱形，并显示日期和时长。月视图可减少日期标签密度，但保留各日期的数据与点按入口。

项目分布按「名称与百分比 → 横向进度条 → 时长」组织。归档项目仍需明确标注；统计口径与计算规则由业务实现定义，不用装饰性长度或颜色改变数据含义。

### 状态与反馈

| 状态 | 呈现规则 |
| --- | --- |
| 加载中 | 在内容区域说明正在读取，避免暂时展示成空记录 |
| 读取失败 | 说明失败并提供重试入口，与无数据状态区分 |
| 没有数据 | 简短说明无数据；有可执行的下一步时提供明确入口 |
| 表单错误 | 保留输入，以错误提示解释需要处理的问题 |
| 操作成功 | 结果确认后再显示成功提示；反馈靠近操作或在返回后呈现 |
| 保存结果未确认 | 保留提交内容，明确说明尚未确认，并提供重试确认入口 |
| 删除或移除 | 确认前说明后果，明确区分删除记录与归档项目 |

按钮文案使用简短动作，例如「保存」「取消」「删除」。保存结果未确认时，主按钮使用「重试」，提示区说明需要确认的结果，并禁用取消以保留提交保护。空状态使用「暂无记录」等直接描述；不添加鼓励性口号、抒情说明或重复引导。保留字段限制、图表含义、错误反馈及危险操作后果等必要说明。

## Do's and Don'ts

- 新页面先确定主要阅读内容和操作，再从现有角色中选择颜色、文字层级和容器；不为每个页面新增一套视觉语言。
- 状态同时通过文字和视觉样式表达；不让颜色成为错误、选中或归档状态的唯一依据。
- 保留真实数据和完整主要内容；不通过截断、装饰性图形或夸张文案改变其含义。
- 展示休息与练习时保持中性；不新增缺勤警告、排名或技术水平暗示。

### 适配与待验证事项

后续界面验收应覆盖长名称与笔记、快捷按钮换行、加载／错误／空状态、日期选中标记，以及底部操作可达性。

现状只有小程序移动端布局，没有桌面或平板专用方案。窄屏、系统大字体、原生键盘遮挡、深色模式与完整无障碍表现仍属待验证事项；现有小字号与浅色文字也需要检查实际可读性。本文件不将设计要求当作适配完成的证据，单次设备验收结果记录在对应任务中。

### 实现与维护

实现时按需查阅以下入口，不在本文维护完整的 CSS 或组件 API 副本：

- [全局样式](miniprogram/src/app.scss)：实际颜色、字号、间距与按钮主题映射。
- [构建配置](miniprogram/config/index.ts)：设计宽度与尺寸转换配置。
- [导航配置](miniprogram/src/app.config.ts)：原生导航与底部导航。
- [公共组件](miniprogram/src/components/common.tsx)：底部表单操作栏、加载与空状态、记录卡片及按钮复用入口。

新增页面优先遵循本文件的使用规则并复用现有组件。发现文档与实现不一致时，明确差异及其原因，不直接将偶然实现提升为通用规则；有意调整视觉语言时，同步更新相关规则和对应样式。