# SepComet 个人主页 UI 设计文档

> 关联文档：`REQUIREMENTS.md`、`design-system/sepcomet/MASTER.md`
>
> 本文档用于确定本项目的页面风格、信息架构、视觉规则与组件边界。
> 如与自动生成的 `design-system/sepcomet/MASTER.md` 有冲突，以本文档为准。

---

## 1. 项目定位

### 1.1 产品目标

SepComet 个人主页是一个**公开、静态、数据驱动**的个人站点，用于：

- 展示个人身份与长期输出
- 呈现开发日志与精选项目
- 提供可分享的求职/展示入口
- 通过 Markdown / JSON 数据驱动页面更新

### 1.2 用户印象目标

访问者打开首页后，应感知到：

1. 这是一个**持续记录开发过程**的工程师主页
2. 内容真实、结构清楚、便于快速浏览
3. 项目与日志都不是装饰，而是核心内容
4. 站点风格有开发者气质，但不走重特效路线

### 1.3 设计关键词

- 工程编辑部
- 内容优先
- 理性克制
- 数据驱动
- 轻技术感
- 可读性优先

---

## 2. 主题方向

### 2.1 最终方向

本项目采用：

## **工程编辑部风格 + 少量终端技术感**

即：

- 整体以**浅色、清晰、排版感强**的编辑式布局为主
- 在局部模块中引入**等宽字体、状态标签、深色数据面板**等技术感元素
- 避免做成纯作品集站点，也避免做成后台仪表盘

### 2.2 风格原则

- 首页优先表达“**我持续在做事**”，而不是“我会做炫酷页面”
- 日志与项目同等重要，不让任何一方沦为陪衬
- 动效只做轻反馈，不做强打断
- 组件层次清楚，便于后续按数据模型扩展

---

## 3. 信息架构

### 3.1 页面结构

站点包含以下页面：

- `/` 首页
- `/logs` 开发日志列表页
- `/logs/[slug]` 日志详情页
- `/projects` 项目展示页
- `/shares` 分享链接页

### 3.2 导航结构

顶部导航建议包含：

- Home
- Logs
- Projects
- Shares
- GitHub / Gitea（外链）

导航设计要求：

- 桌面端采用悬浮式头部
- 移动端折叠菜单
- 当前页面有明确激活态

---

## 4. 首页设计

## 4.1 页面目标

首页不是单纯名片，而是“**个人概览页 + 内容入口页**”。

首页负责完成三件事：

1. 快速建立人物认知
2. 把访问者引导到日志与项目
3. 展示持续产出的证据

## 4.2 模块顺序

首页建议按以下顺序排列：

1. Hero
2. Latest Logs
3. Featured Projects
4. Gitea Activity
5. Recent Shares（可选）
6. Footer

## 4.3 Hero

### 内容组成

- 头像
- 名字：SepComet
- 一句话身份说明
- 2~3 行简介
- 社交链接按钮
- 右侧状态卡 / 数据摘要

### 文案方向

建议语气：

- 客观
- 稳定
- 不装饰性夸张

示例表达方向：

- `Unity 开发者 / 正在构建数据驱动的个人主页与工具链`
- `记录开发过程，整理项目输出，把日常构建沉淀成可浏览的公开主页`

### 视觉布局

桌面端采用左右结构：

- 左：身份与文案
- 右：状态卡 / 技术摘要

移动端改为单列。

## 4.4 Latest Logs

### 目标

让访问者在首页直接看到“最近在做什么”。

### 展示策略

- 展示最近 3~5 条
- 每张卡片包含：
  - 标题
  - 日期
  - repo
  - tags
  - summary

### 设计要求

- 日期与 repo 使用等宽字体
- summary 限制在 2~3 行
- 卡片应支持整块点击
- hover 只做边框/阴影反馈

## 4.5 Featured Projects

### 目标

让访问者快速识别代表性项目与技术方向。

### 每个项目卡片包含

- 封面图
- 名称
- 描述
- 标签
- 外链按钮组
  - Gitea Repo
  - Demo（如有）
  - Download（如有）

### 设计要求

- 封面图使用固定宽高比
- Featured 项目可带小型状态标签
- 网格排版优先整齐、稳定，不使用复杂瀑布流

## 4.6 Gitea Activity

### 目标

补足“真实活跃开发中”的信号。

### 内容组成

- 贡献热力图
- 最近活动列表
- 前往 Gitea 主页链接

### 视觉策略

- 该模块允许使用**深色面板**
- 与首页浅色主背景形成对比
- 热力图必须有 legend，不允许只靠颜色传达信息

## 4.7 Recent Shares（可选）

如果首页首版内容密度过高，可不放在首页，只保留 `/shares` 页面与导航入口。

如放首页，建议仅展示最近 2~3 条。

---

## 5. 页面级设计规范

## 5.1 `/logs`

### 页面目标

提供清楚、可扫描的开发日志索引。

### 布局建议

- 顶部：页标题 + 简介
- 中部：时间倒序日志列表
- 预留筛选区域（后续可扩展）

### 推荐样式

采用“**时间线 + 卡片**”混合形式：

- 左侧：日期轨道
- 右侧：日志卡片

这样可强化“开发记录”的时间连续性。

### 日志卡必须包含

- 标题
- 日期
- tags
- summary
- repo

## 5.2 `/logs/[slug]`

### 页面目标

正文阅读体验优先。

### 内容顺序

1. 标题
2. 日期 / repo / commit links
3. tags
4. Markdown 正文
5. 返回列表入口

### 设计要求

- 正文最大宽度控制在舒适阅读范围
- Markdown 使用统一排版，不手写零散样式
- 代码块、引用、列表、标题层级需统一

## 5.3 `/projects`

### 页面目标

作为结构化项目索引页，而非花哨作品集墙。

### 页面内容

- 页头说明
- 项目卡片网格
- 可预留筛选能力

### 卡片层级

1. 名称
2. 描述
3. 标签
4. 外链操作

## 5.4 `/shares`

### 页面目标

承载 Seafile 分享资源的公开入口。

### 展示形式

更接近“资源列表页”，而非项目卡片页。

每条资源包含：

- 文件名
- 描述
- 时间
- 跳转链接

---

## 6. 视觉系统

## 6.1 色板

### 基础色

| Token | 值 | 用途 |
|------|------|------|
| `--bg` | `#FAFAFA` | 页面背景 |
| `--surface` | `#FFFFFF` | 卡片背景 |
| `--text` | `#09090B` | 主文本 |
| `--muted` | `#52525B` | 次级文本 |
| `--border` | `#E4E4E7` | 边框 |
| `--accent` | `#2563EB` | 链接 / CTA / 激活态 |

### 技术感辅助色

| Token | 值 | 用途 |
|------|------|------|
| `--success` | `#22C55E` | 活跃状态 / 统计信号 |
| `--panel-dark` | `#0F172A` | 深色数据面板背景 |
| `--panel-text` | `#F8FAFC` | 深色面板文字 |
| `--tag-bg` | `#F4F4F5` | 标签背景 |

### 用色原则

- 页面大面积只使用黑白灰
- 蓝色作为主强调色，避免泛滥
- 绿色只用于“运行/活跃/统计成功信号”
- 不使用高饱和多彩 UI

## 6.2 字体系统

| 类型 | 建议 |
|------|------|
| 标题 | Archivo |
| 正文 | Space Grotesk |
| 等宽信息 | JetBrains Mono 或 Fira Code |

### 字体使用建议

- 标题承担结构感与力量感
- 正文保持清楚耐读
- 日期、repo、commit、标签元数据可适度使用等宽字体

## 6.3 圆角、边框、阴影

- 卡片圆角：`rounded-2xl`
- 边框：`1px solid zinc-200`
- 阴影：轻微，不制造悬浮夸张感

建议层级：

- 默认：仅边框
- hover：边框稍深 + 轻阴影
- 强调卡：轻阴影 + 更清楚的边框

## 6.4 间距

建议使用统一间距系统：

- `4`
- `8`
- `12`
- `16`
- `24`
- `32`
- `48`
- `64`

区块间距应明显大于卡片内部间距，确保信息分组清楚。

---

## 7. 组件设计规范

## 7.1 建议组件树

### 布局层

- `Layout.astro`
- `Header.astro`
- `Footer.astro`
- `Container.astro`

### 首页层

- `Hero.astro`
- `StatusCard.astro`
- `SectionTitle.astro`
- `LogCard.astro`
- `ProjectCard.astro`
- `GiteaHeatmap.jsx`
- `ActivityList.astro`

### 通用层

- `TagList.astro`
- `MetaRow.astro`
- `EmptyState.astro`
- `LinkButton.astro`

## 7.2 卡片规范

所有卡片遵循：

- 内部留白统一
- 标题层级清楚
- hover 有反馈
- 可点击区域完整
- 图片与数据区分明确

### 不允许

- 卡片内容上下间距混乱
- 缺少 hover 反馈却整块可点
- hover 使用缩放导致布局抖动

## 7.3 标签规范

标签用于：

- 技术栈
- 日志主题
- 项目分类

样式建议：

- 浅灰背景
- 深灰文字
- 小号圆角胶囊
- 可选等宽字体增强技术感

---

## 8. 交互规范

### 允许的交互

- 卡片 hover 阴影/边框变化
- 链接 hover 颜色变化
- 轻量滚动入场
- 当前导航高亮
- 按钮按下状态

### 禁止的交互

- 大幅位移的 hover
- 强制滚动动画
- 复杂页面切换特效
- 大面积视差
- 自动播放且无法关闭的动态效果

### 动效原则

- 时长控制在 `150ms ~ 300ms`
- 所有动效需兼容 `prefers-reduced-motion`

---

## 9. 响应式规范

## 9.1 断点目标

至少覆盖：

- 375px
- 768px
- 1024px
- 1440px

## 9.2 各页面行为

### 首页

- Desktop：Hero 左右分栏
- Tablet：信息压缩、项目 2 列
- Mobile：Hero 单列、项目单列、日志卡单列

### Logs / Projects / Shares

- 列表在移动端必须无横向滚动
- 长标题需要合理截断
- 图片区域保留稳定尺寸，避免内容跳动

---

## 10. 可访问性规范

以下为首版必须遵守的要求：

- 使用语义 HTML：`nav`、`main`、`section`、`article`、`footer`
- 所有有意义图片必须带 `alt`
- 图标按钮必须有 `aria-label`
- 文字对比度至少达到 4.5:1
- 不能只靠颜色表达状态
- 热力图必须附带文字 legend
- 键盘可访问性完整
- 聚焦态必须清晰可见

---

## 11. 内容表现规范

## 11.1 日志

日志内容应强调：

- 做了什么
- 为什么这样做
- 关联仓库 / commit

首页摘要不需要完整展开，但要足够真实，不使用无意义占位文本。

## 11.2 项目

项目描述应突出：

- 项目目标
- 当前形态
- 技术标签
- 外部入口

## 11.3 分享

分享条目更像“公开资源索引”，语气保持中性、实用。

---

## 12. 实现建议

## 12.1 首版优先级

### Phase 1

- 全局 Layout
- Header / Footer
- Hero
- 首页基础 section

### Phase 2

- Logs 列表页
- Log 详情页
- Markdown 样式

### Phase 3

- Projects 页
- Featured Projects 接入首页

### Phase 4

- Gitea Heatmap React Island

### Phase 5

- Shares 页
- 深色模式
- 细节打磨与 SEO

## 12.2 技术实现提醒

- 内容页优先静态生成
- 交互仅在必要位置引入 React Island
- Markdown 排版尽量基于统一富文本样式
- 图片、卡片、异步数据区域要预留尺寸，避免布局抖动

---

## 13. 非目标

本项目当前不追求：

- 重交互展示型作品集
- 炫技式动画首页
- 高度拟物化或实验性视觉
- 类 SaaS 管理后台布局

---

## 14. 一句话设计结论

> SepComet 首页应当像一个“持续构建中的工程师公开工作台”：
> **结构清楚、内容真实、风格克制、带一点技术感。**