10 KiB

Raw Blame History

SepComet 个人主页 UI 设计文档

关联文档：REQUIREMENTS.md、design-system/sepcomet/MASTER.md

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

1. 项目定位

1.1 产品目标

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

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

1.2 用户印象目标

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

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

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 页面目标

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

首页负责完成三件事：

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

4.2 模块顺序

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

Hero
Latest Logs
Featured Projects
Gitea Activity
Recent Shares（可选）
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]`

页面目标

正文阅读体验优先。

内容顺序

标题
日期 / repo / commit links
tags
Markdown 正文
返回列表入口

设计要求

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

5.3 `/projects`

页面目标

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

页面内容

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

卡片层级

名称
描述
标签
外链操作

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

10 KiB Raw Blame History Unescape Escape

SepComet 个人主页 UI 设计文档

1. 项目定位

1.1 产品目标

1.2 用户印象目标

1.3 设计关键词

2. 主题方向

2.1 最终方向

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

2.2 风格原则

3. 信息架构

3.1 页面结构

3.2 导航结构

4. 首页设计

4.1 页面目标

4.2 模块顺序

4.3 Hero

内容组成

文案方向

视觉布局

4.4 Latest Logs

目标

展示策略

设计要求

4.5 Featured Projects

目标

每个项目卡片包含

设计要求

4.6 Gitea Activity

目标

内容组成

视觉策略

4.7 Recent Shares（可选）

5. 页面级设计规范

5.1 /logs

页面目标

布局建议

推荐样式

日志卡必须包含

5.2 /logs/[slug]

页面目标

内容顺序

设计要求

5.3 /projects

页面目标

页面内容

卡片层级

5.4 /shares

页面目标

展示形式

6. 视觉系统

6.1 色板

基础色

技术感辅助色

用色原则

6.2 字体系统

字体使用建议

6.3 圆角、边框、阴影

6.4 间距

7. 组件设计规范

7.1 建议组件树

布局层

首页层

通用层

7.2 卡片规范

不允许

7.3 标签规范

8. 交互规范

允许的交互

禁止的交互

动效原则

9. 响应式规范

9.1 断点目标

9.2 各页面行为

首页

Logs / Projects / Shares

10. 可访问性规范

11. 内容表现规范

11.1 日志

11.2 项目

10 KiB

Raw Blame History

5.1 `/logs`

5.2 `/logs/[slug]`

5.3 `/projects`

5.4 `/shares`