docs(ts): 重组 Polaris 设计文档体系并迁移至 nextjs 目录

- 拆分为项目说明/首页设计/分类页设计三份文档，职责分离 - 新增项目说明文档：14 条决策记录、技术选型（Next.js 静态导出）、数据结构、Go API 草案、通用语法表结构、五阶段规划 - 融入决策：JSON 数据载体、Ctrl+K 仅首页生效、统一图标方案（si:/local:/url: 前缀 + 四级 fallback）、搜索按模式严格分离、首页补足 8 个常用链接（跨分类归属） - 目录 ts/web/astro/polaris → ts/web/nextjs/polaris，删除过时 README，更新 ts/README.md 框架描述
2026-08-21 22:08:14 +08:00
parent 86182ce5d7
commit 95c3da0f71
7 changed files with 1896 additions and 794 deletions
@@ -0,0 +1,780 @@
+# Polaris 首页设计文档
+
+> 关联文档：
+> [Polaris 项目说明文档](./Polaris%20项目说明文档.md) —— 项目定位、技术选型、数据结构、开发阶段
+> [Polaris 分类页设计文档](./Polaris%20分类页设计文档.md) —— 分类页布局与交互
+>
+> 配套设计图：`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.10);
+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` 的链接，按 `sort` 排序取前 8 个；超出 8 个时按 4 列网格换行展示。
+
+第一版数据构成（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.10);
+```
+
+推荐尺寸：
+
+```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.10);
+
+  --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.10);
+  --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 后，用户可以立刻搜索、立刻访问常用网站，也可以通过侧边栏进入分类页面。页面具有个人氛围，但保持干净、高效、克制。