lab/ts/web/nextjs/polaris/docs/design/Polaris 首页设计文档.md

# Polaris 首页设计文档

> 关联文档：
> [Polaris 项目说明文档](./Polaris%20项目说明文档.md) —— 项目定位、技术选型、数据结构、开发阶段
> [Polaris 分类页设计文档](./Polaris%20分类页设计文档.md) —— 分类页布局与交互
>
> 配套设计图：[Polaris 页面设计图](../assets/Polaris页面设计图.png)（示意图，视觉细节以本文档文字规范为准）

## 1. 页面定位

Polaris 首页是一个**浏览器起始页**，不是后台管理系统，也不是信息密集型 Dashboard。

> 一个具有个人审美、可自定义背景、可快速搜索和访问常用链接的浏览器起始页。

首页应给人的感觉是：

```text
私人入口
浏览器首页
轻量工具启动页
个人网址导航
安静、高效、有氛围感
```

而不是：

```text
后台系统
资源管理平台
复杂书签管理器
信息看板
数据仪表盘
```

---

## 2. 整体视觉风格

首页推荐采用：

> 轻量玻璃感 + 极简浏览器起始页 + 柔和个人空间感

设计关键词：

```text
极简
半透明
玻璃感
柔和阴影
大留白
低饱和
可换背景
个人化
安静
高级感
```

整体视觉应避免过重的管理系统风格。

首页不应常驻展示以下元素：

```text
设置按钮
编辑按钮
管理按钮
新增按钮
统计数据
用户头像
访问次数
站点域名副标题
复杂分类卡片
```

这些能力在后续阶段通过隐藏入口、独立配置页或快捷键面板实现。

---

## 3. 首页整体布局

首页采用左右结构：

```text
┌──────────────────┬────────────────────────────────────────────┐
│ 左侧边栏          │ 主内容区域                                  │
│                  │                                            │
│ Logo + 折叠按钮   │ 问候语 + 当前时间                            │
│ 首页              │ 日期 / 星期                                  │
│ AI 工具           │ 搜索框                                      │
│ 开发工具          │ 常用链接                                    │
│ 设计资源          │                                            │
│ 学习资料          │                                            │
│ 效率工具          │                                            │
│ 娱乐媒体          │                                            │
│ 生活服务          │                                            │
└──────────────────┴────────────────────────────────────────────┘
```

布局原则：

1. 左侧边栏负责分类导航；
2. 主内容区域只展示最高频内容；
3. 首页不展示分类卡片；
4. 首页不展示编辑、设置、管理类按钮；
5. 常用链接只做轻量展示。

主内容整体居中，视觉重心位于页面中上方。

推荐信息层级：

```text
1. 当前时间 / 问候语
2. 搜索框
3. 常用链接
4. 左侧分类导航
5. 背景氛围
```

---

## 4. 左侧边栏设计

### 4.1 边栏内容

左侧边栏从上到下依次展示：

```text
Logo
折叠按钮
首页
AI 工具
开发工具
设计资源
学习资料
效率工具
娱乐媒体
生活服务
```

「首页」指向 `/`，各分类指向 `/categories/{categoryId}`。当前路由对应的导航项处于选中态，选中样式见[分类页设计文档](./Polaris%20分类页设计文档.md) 6.2 节。

暂时不展示：

```text
设置
关于
编辑
管理
新增分类
账户信息
```

### 4.2 折叠按钮位置

折叠按钮放在侧边栏顶部右侧，与 Logo 位于同一行。

示意：

```text
┌──────────────────────┐
│ Logo            ≪    │
└──────────────────────┘
```

不采用侧边栏中间悬浮按钮。

原因：

1. 中间悬浮按钮视觉上突兀；
2. 容易产生后台管理系统的感觉；
3. 会破坏页面边界的干净感；
4. 顶部右侧更符合用户对全局控制按钮的认知。

### 4.3 边栏宽度

展开状态：

```text
推荐宽度：240px
可选范围：220px - 260px
```

折叠状态：

```text
推荐宽度：72px
可选范围：68px - 80px
```

展开时显示图标和文字。

折叠时只显示图标。

折叠状态持久化到 `localStorage`，刷新后保持。

### 4.4 边栏视觉样式

推荐样式：

```css
background: rgba(255, 255, 255, 0.68);
backdrop-filter: blur(24px);
border: 1px solid rgba(255, 255, 255, 0.45);
box-shadow: 0 24px 80px rgba(15, 23, 42, 0.1);
border-radius: 24px;
```

边栏与页面边缘保持一定距离，形成悬浮玻璃面板感。

推荐边距：

```text
left: 20px;
top: 20px;
bottom: 20px;
```

---

## 5. 时间与问候语

首页顶部展示问候语和当前时间。

示例：

```text
晚上好，21:56
2026 年 8 月 20 日 星期四
```

问候语规则：

```text
05:00 - 11:59  早上好
12:00 - 13:59  中午好
14:00 - 17:59  下午好
18:00 - 23:59  晚上好
00:00 - 04:59  夜深了
```

推荐样式：

```css
font-size: 56px;
font-weight: 700;
color: #0f172a;
```

日期样式：

```css
font-size: 16px;
color: #64748b;
```

时间为客户端实时时钟，每分钟更新。

---

## 6. 搜索框设计

### 6.1 搜索框定位

搜索框是 Polaris 首页最核心的交互组件。

搜索框位于时间与日期下方，居中展示，首页加载后**自动聚焦**。

### 6.2 搜索范围

首页搜索框支持以下四种搜索方式：

```text
Google 搜索
Bing 搜索
GitHub 搜索
本地搜索
```

其中：

1. **Google 搜索**：使用 Google 搜索引擎搜索输入内容；
2. **Bing 搜索**：使用 Bing 搜索引擎搜索输入内容；
3. **GitHub 搜索**：在 GitHub 中搜索输入内容；
4. **本地搜索**：搜索 Polaris 本地配置中的链接、分类和名称。

第一版不支持：

```text
直接输入 URL 跳转
自定义搜索引擎
多搜索引擎聚合结果
AI 搜索
站外爬取搜索
全文索引搜索
```

这些能力作为后续扩展。

### 6.3 搜索框尺寸

桌面端推荐：

```text
width: 760px;
height: 68px;
```

可选范围：

```text
宽度：720px - 860px
高度：64px - 72px
```

> 移动端尺寸第一版不定义，移动端整体适配为后续阶段工作。

### 6.4 搜索框视觉样式

推荐样式：

```css
background: rgba(255, 255, 255, 0.72);
backdrop-filter: blur(22px);
border: 1px solid rgba(255, 255, 255, 0.65);
border-radius: 24px;
box-shadow: 0 20px 60px rgba(15, 23, 42, 0.12);
```

placeholder 统一为：

```text
搜索网站、书签或关键词...
```

右侧展示快捷键提示，**按平台检测显示**：

```text
macOS：⌘K
Windows / Linux：Ctrl K
```

快捷键行为：按下后聚焦搜索框（详见 7.4）。

### 6.5 搜索模式切换

搜索模式可以通过以下方式切换：

```text
搜索框左侧下拉选择
快捷键切换
命令面板中选择
默认使用上一次选择的搜索方式
```

第一版采用简单方案：

```text
搜索框左侧或右侧提供当前搜索模式标识
点击后可切换 Google / Bing / GitHub / 本地
```

### 6.6 本地搜索范围

本地搜索的数据来自本地数据配置。

搜索范围包括：

```text
链接标题
链接关键词
链接描述
分类名称
分类 ID
```

链接数据预留 `keywords` 字段，完整数据结构见[项目说明文档](./Polaris%20项目说明文档.md)。

---

## 7. 搜索功能设计

### 7.1 搜索 Provider

支持四个 provider：

```ts
export type SearchProvider = "google" | "bing" | "github" | "local"
```

### 7.2 搜索行为

Google：

```text
https://www.google.com/search?q={keyword}
```

Bing：

```text
https://www.bing.com/search?q={keyword}
```

GitHub：

```text
https://github.com/search?q={keyword}
```

Local：

```text
在本地 links / categories 数据中搜索
```

### 7.3 本地搜索匹配规则

本地搜索匹配字段：

```text
title
keywords
categoryId
category title
```

推荐匹配逻辑（权重从高到低）：

```text
完全匹配优先
标题匹配其次
关键词匹配再次
分类匹配最后
```

搜索结果展示：

```text
图标
标题
所属分类
```

搜索行为**按模式严格分离**：选择使用哪个搜索引擎，就只用它搜索。

```text
Google / Bing / GitHub 模式：回车直接跳转对应引擎搜索，不显示任何下拉
Local 模式：输入时实时显示本地结果下拉（见 7.5）
```

Local 模式回车行为：

```text
如果只有一个高匹配本地结果，回车打开该链接
如果有多个结果，↑ / ↓ 选择后回车打开选中项（默认选中第一项）
如果没有结果，展示空状态
```

### 7.4 快捷键

```text
Ctrl K（macOS 为 ⌘K）：聚焦搜索框
Esc：清空输入 / 关闭结果列表
```

快捷键仅在首页生效，分类页不响应。

---

### 7.5 结果下拉面板（仅 Local 模式）

面板出现在搜索框正下方，与搜索框同宽，间距 8px，视觉上与搜索框衔接为一体。

面板样式：

```css
background: rgba(255, 255, 255, 0.72);
backdrop-filter: blur(22px);
border: 1px solid rgba(255, 255, 255, 0.65);
border-radius: 20px;
box-shadow: 0 20px 60px rgba(15, 23, 42, 0.12);
```

列表项内容：

```text
图标（遵循统一图标方案）
标题
所属分类
```

交互：

```text
↑ / ↓ 在结果间移动选中项
回车打开选中项（新标签页）
Esc 关闭面板
鼠标点击直接打开
选中项背景 rgba(59, 130, 246, 0.10)
```

结果数量上限 8 条；无匹配时面板内展示空状态「没有匹配的网站」。

---

## 8. 常用链接区域

### 8.1 区域定位

常用链接用于展示用户最高频访问的网站。

首页不展示分类卡片，以保持页面干净。

第一版展示 8 个常用链接：

```text
GitHub
ChatGPT
Gmail
Notion
Figma
YouTube
Vercel
Bilibili
```

实际项目中根据个人习惯调整。

数据来源：`pinned: true` 的链接，按 `pinnedSort` 排序取前 8 个；超出 8 个时按 4 列网格换行展示。`sort` 仅用于分类内排序，避免首页顺序与分类页顺序相互约束。

第一版数据构成（8 条 pinned 分布于各分类，归入真实分类）：

```text
GitHub    → 开发工具（dev）
Vercel    → 开发工具（dev）
Figma     → 开发工具（dev）
ChatGPT   → AI 工具（ai）
Gmail     → 效率工具（efficiency）
Notion    → 效率工具（efficiency）
YouTube   → 娱乐媒体（media）
Bilibili  → 娱乐媒体（media）
```

其中 ChatGPT、Gmail、Notion、YouTube、Bilibili 5 条是为首页常用链接补入的跨分类条目。受此影响，AI 工具、效率工具、娱乐媒体三个分类页会展示少量链接而非空状态；纯空状态分类为设计资源、学习资料、生活服务。

### 8.2 链接卡片内容

常用链接卡片只展示：

```text
图标
名称
```

不展示：

```text
域名
描述
编辑按钮
更多按钮
拖拽按钮
访问统计
```

图标来源遵循统一图标方案（见[项目说明文档](./Polaris%20项目说明文档.md)）：自定义图标 → Simple Icons / 本地图标库 → favicon 自动抓取 → 文字占位兜底。

### 8.3 链接卡片样式

推荐样式：

```css
background: rgba(255, 255, 255, 0.62);
backdrop-filter: blur(20px);
border: 1px solid rgba(255, 255, 255, 0.56);
border-radius: 20px;
box-shadow: 0 14px 40px rgba(15, 23, 42, 0.1);
```

推荐尺寸：

```text
width: 200px;
height: 76px;
```

推荐布局：

```text
两行四列
```

示意：

```text
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ GitHub │ │ChatGPT │ │ Gmail  │ │ Notion │
└────────┘ └────────┘ └────────┘ └────────┘

┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ Figma  │ │YouTube │ │ Vercel │ │Bilibili│
└────────┘ └────────┘ └────────┘ └────────┘
```

Hover 效果：

```css
transform: translateY(-2px);
background: rgba(255, 255, 255, 0.78);
box-shadow: 0 18px 50px rgba(15, 23, 42, 0.14);
transition: all 180ms ease;
```

点击卡片在新标签页打开链接。

---

## 9. 背景设计

### 9.1 背景类型

Polaris 支持背景自定义的设计预留。

**第一版默认背景为 CSS 低饱和青蓝渐变**（模拟晨雾 / 天空氛围），不依赖图片资产。

后续支持：

```text
静态图片背景
渐变背景
纯色背景
本地上传背景
远程图片背景
深色背景
```

图片背景建议：

```text
湖面
雪山
晨雾
天空
抽象渐变
低对比度风景图
```

背景类型通过 `settings.background.type`（`gradient` / `image`）配置。

### 9.2 背景遮罩

由于用户未来可能更换任意背景，因此需要增加背景遮罩层，保证内容可读。

浅色主题：

```css
background-overlay: rgba(255, 255, 255, 0.32);
backdrop-filter: blur(8px);
```

深色主题（后续阶段预留）：

```css
background-overlay: rgba(15, 23, 42, 0.42);
backdrop-filter: blur(8px);
```

---

## 10. 配色系统

默认采用浅色玻璃主题。

推荐 CSS 变量：

```css
:root {
  --color-text-primary: #0f172a;
  --color-text-secondary: #64748b;
  --color-text-muted: #94a3b8;

  --color-primary: #3b82f6;
  --color-primary-hover: #2563eb;
  --color-primary-soft: rgba(59, 130, 246, 0.1);

  --color-surface-sidebar: rgba(255, 255, 255, 0.68);
  --color-surface-card: rgba(255, 255, 255, 0.62);
  --color-surface-search: rgba(255, 255, 255, 0.72);

  --color-border-light: rgba(255, 255, 255, 0.56);
  --color-border-subtle: rgba(15, 23, 42, 0.08);

  --shadow-soft: 0 14px 40px rgba(15, 23, 42, 0.1);
  --shadow-medium: 0 20px 60px rgba(15, 23, 42, 0.12);
}
```

变量按双主题友好方式组织：第一版只实现浅色值；深色玻璃主题为后续阶段，届时以 `[data-theme="dark"]` 覆盖同名变量，组件无需改动。

---

## 11. 字体建议

推荐字体栈：

```css
font-family:
  Inter,
  "SF Pro Display",
  "SF Pro Text",
  -apple-system,
  BlinkMacSystemFont,
  "Segoe UI",
  "PingFang SC",
  "Hiragino Sans GB",
  "Microsoft YaHei",
  sans-serif;
```

字体原则：

```text
标题清晰
正文轻盈
导航可读
不要使用过度装饰性字体
```

---

## 12. 首页线框

```text
┌──────────────────────┬────────────────────────────────────────────────────┐
│                      │                                                    │
│   LOGO          ≪    │                                                    │
│                      │                                                    │
│   ⌂  首页            │                                                    │
│   ✦  AI 工具         │                 晚上好，21:56                      │
│   <> 开发工具        │              2026 年 8 月 20 日 星期四              │
│   ◌  设计资源        │                                                    │
│   📖 学习资料        │       ┌────────────────────────────────────┐       │
│   ⚡ 效率工具        │       │  🔍 搜索网站、书签或关键词... Ctrl K │       │
│   ▶  娱乐媒体        │       └────────────────────────────────────┘       │
│   ☕ 生活服务        │                                                    │
│                      │                 常用链接                           │
│                      │       ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│                      │       │ GitHub │ │ChatGPT │ │ Gmail  │ │ Notion │ │
│                      │       └────────┘ └────────┘ └────────┘ └────────┘ │
│                      │       ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│                      │       │ Figma  │ │YouTube │ │ Vercel │ │Bilibili│ │
│                      │       └────────┘ └────────┘ └────────┘ └────────┘ │
│                      │                                                    │
└──────────────────────┴────────────────────────────────────────────────────┘
```

---

## 13. 设计原则总结

首页遵循以下原则：

```text
首页只放最高频内容
搜索框是核心入口
搜索范围保持克制
常用链接轻量展示
分类入口放在左侧边栏
首页不展示分类卡片
首页不展示编辑和设置按钮
背景可换，但内容必须始终清晰
玻璃感要轻，不要炫技
交互动效要柔和，不要夸张
整体像浏览器起始页，不像后台系统
第一版数据本地配置，后续平滑切换到 Go 后端
第一版仅实现浅色主题、仅适配桌面端
```

最终目标：

> 打开 Polaris 后，用户可以立刻搜索、立刻访问常用网站，也可以通过侧边栏进入分类页面。页面具有个人氛围，但保持干净、高效、克制。