597 lines
10 KiB
Markdown
597 lines
10 KiB
Markdown
# 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 首页应当像一个“持续构建中的工程师公开工作台”：
|
||
> **结构清楚、内容真实、风格克制、带一点技术感。**
|
||
|