labmem/lab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(polaris): 同步设计与部署文档现状

Browse Source 
对齐深色玻璃样式、响应式布局、数据规模与配置生效范围。
明确仅由 polaris-v* 标签触发发布，并保留历史规格说明。
This commit is contained in:
labmem
2026-10-14 16:38:07 +08:00
parent d53dbac88e
commit 86f6eb39b2
6 changed files with 287 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ts/web/nextjs/polaris/docs/design/Polaris 首页设计文档.md
+65 -4
View File
@@ -6,6 +6,43 @@
>
> 配套设计图：[Polaris 页面设计图](../assets/Polaris页面设计图.png)（示意图，视觉细节以本文档文字规范为准）
## 0. 当前实现状态（2026-10-14 校对）
本章为现状说明。第 1–13 章保留立项时的历史设计意图，其中「浅色玻璃」「CSS 渐变背景」「仅适配桌面端」等表述均为历史方案，不代表当前实现；样式细节以本章与 `src/app/globals.css` 为准。
**视觉主题**：当前为深色玻璃主题（`color-scheme: dark`），没有浅色/深色切换。稳定的设计 tokens：
```css
--background: #101a2a;
--text-primary: #f4f7fc;
--text-secondary: #d7e2f0;
--text-muted: #bfd0e4;
--primary: #a9c9ff;
--primary-hover: #d3e3ff;
--primary-soft: rgba(147, 190, 255, 0.15);
--border-glass: rgba(222, 234, 255, 0.17);
--radius-card: 20px;
--radius-panel: 24px;
```
**玻璃表面**：侧边栏、搜索框、常用链接卡片均为深色半透明渐变（`--surface-sidebar` / `--surface-search` / `--surface-card` / `--surface-card-hover`），配合 `backdrop-filter: blur(16px - 20px) saturate(108% - 134%)` 与带内描边高光的软阴影，形成悬浮玻璃面板感。
**背景**：背景素材可整体替换（用户会不定期更换），背景层的显示与遮罩样式由现有 CSS 管理——`body` 背景层（fixed + cover）之上叠加一层固定的深色渐变遮罩保证前景可读；素材的类型、路径与画面内容**不属于设计规范**。`settings.theme` 与 `settings.background` 目前仅有数据模型与校验逻辑，不驱动任何样式。
**响应式（已实现）**：
```text
桌面默认：侧栏展开 240px / 折叠 72px，常用链接 4 列
≤1199px：侧栏展开宽度 220px，常用链接 2 列
≤767px：侧边栏变为顶部横栏（Logo + 横向滚动导航，折叠按钮隐藏），
首页与分类页改为顶部横栏下方的常规滚动布局
≤420px：常用链接 1 列，搜索快捷键提示隐藏
```
另已支持 `prefers-reduced-motion` 降低动效。
**数据现状**：8 个分类（含后增的「游戏资料」）、51 条链接、6 条 pinned 常用链接。
## 1. 页面定位
Polaris 首页是一个**浏览器起始页**，不是后台管理系统，也不是信息密集型 Dashboard。
@@ -40,6 +77,8 @@ Polaris 首页是一个**浏览器起始页**，不是后台管理系统，也
> 轻量玻璃感 + 极简浏览器起始页 + 柔和个人空间感
> 2026-10-14 实现状态：该方向已落地，但配色从浅色玻璃改为**深色玻璃**（深蓝底、冷白文字，见第 0 章）；关键词中「玻璃感、低饱和、可换背景、安静」依然成立。
设计关键词：
```text
@@ -136,6 +175,8 @@ AI 工具
生活服务
```
> 2026-10-14 实现状态：当前侧边栏为「首页 + 8 个分类」，新增了「游戏资料」分类，上表为立项时的 7 分类历史列表；折叠时导航项只显示图标并提供 Tooltip，移动端顶部横栏下不显示折叠按钮。
「首页」指向 `/`，各分类指向 `/categories/{categoryId}`。当前路由对应的导航项处于选中态，选中样式见[分类页设计文档](./Polaris%20分类页设计文档.md) 6.2 节。
暂时不展示：
@@ -204,6 +245,8 @@ box-shadow: 0 24px 80px rgba(15, 23, 42, 0.1);
border-radius: 24px;
```
> 2026-10-14 实现状态：上方浅色样式为历史方案。当前侧边栏为深色渐变玻璃（`--surface-sidebar`，blur(20px) saturate(108%)，`--shadow-panel` 阴影），悬浮边距仍为 20px；宽度见第 0 章响应式。
边栏与页面边缘保持一定距离，形成悬浮玻璃面板感。
推荐边距：
@@ -245,6 +288,8 @@ font-weight: 700;
color: #0f172a;
```
> 2026-10-14 实现状态：当前问候语字号为 clamp(44px, 4.2vw, 56px)、冷白色（rgba(248, 250, 252, 0.98)）并带文字投影，日期为 rgba(241, 245, 249, 0.86)；上方 #0f172a / #64748b 为历史浅色方案。
日期样式：
```css
@@ -311,7 +356,7 @@ height: 68px;
高度：64px - 72px
```
> 移动端尺寸第一版不定义，移动端整体适配为后续阶段工作。
> 历史说明：立项时移动端尺寸未定义。当前移动端已适配：搜索框宽度随容器收缩，≤420px 时隐藏快捷键提示（见第 0 章）。
### 6.4 搜索框视觉样式
@@ -325,6 +370,8 @@ border-radius: 24px;
box-shadow: 0 20px 60px rgba(15, 23, 42, 0.12);
```
> 2026-10-14 实现状态：上方浅色样式为历史方案。当前搜索框为深色玻璃（`--surface-search` 渐变 + blur(20px) saturate(108%)），聚焦时出现 rgba(147, 197, 253, 0.17) 的 focus 环；尺寸仍为最大 760px × 68px。
placeholder 统一为：
```text
@@ -480,6 +527,8 @@ border-radius: 20px;
box-shadow: 0 20px 60px rgba(15, 23, 42, 0.12);
```
> 2026-10-14 实现状态：上方浅色样式为历史方案。当前结果面板为更实的深色玻璃 rgba(19, 31, 49, 0.95)，最大高度 min(520px, 100vh − 220px)，选中项使用 `--primary-soft` 底色。
列表项内容：
```text
@@ -525,6 +574,8 @@ Bilibili
实际项目中根据个人习惯调整。
> 2026-10-14 实现状态：当前 pinned 链接为 6 条，按 `pinnedSort` 排序展示：GitHub、ChatGPT、Gmail、Notion、YouTube、Bilibili；服务层默认上限仍为 8 条（`getPinnedLinks(limit = 8)`）。下文「第一版展示 8 个常用链接」及 8 条 pinned 的数据构成为立项时的历史方案。
数据来源：`pinned: true` 的链接，按 `pinnedSort` 排序取前 8 个；超出 8 个时按 4 列网格换行展示。`sort` 仅用于分类内排序，避免首页顺序与分类页顺序相互约束。
第一版数据构成（8 条 pinned 分布于各分类，归入真实分类）：
@@ -576,6 +627,8 @@ border-radius: 20px;
box-shadow: 0 14px 40px rgba(15, 23, 42, 0.1);
```
> 2026-10-14 实现状态：上方浅色样式为历史方案。当前卡片为深色玻璃（`--surface-card` + blur(16px) saturate(134%)），高 76px、圆角 20px，hover 上浮与过渡不变。
推荐尺寸：
```text
@@ -622,6 +675,8 @@ Polaris 支持背景自定义的设计预留。
**第一版默认背景为 CSS 低饱和青蓝渐变**（模拟晨雾 / 天空氛围），不依赖图片资产。
> **2026-10-14 实现状态（重要）**：背景已不再是 CSS 渐变，改为可替换的背景素材层 + 深色遮罩（由 `body` 背景层加载，见第 0 章）；背景层显示与遮罩样式由现有 CSS 管理，素材的类型、路径、画面与题材由用户自行选择、不定期更换，**不写入设计规范**。下方「图片背景建议」仅作当时的设计联想，不构成约束。`settings.background.type` 目前仅有数据模型与校验，未接入渲染；「CSS 低饱和青蓝渐变」为历史方案。
后续支持：
```text
@@ -650,6 +705,8 @@ Polaris 支持背景自定义的设计预留。
由于用户未来可能更换任意背景，因此需要增加背景遮罩层，保证内容可读。
> 2026-10-14 实现状态：遮罩已实现，但形态与下方两侧历史值不同——当前为固定深色渐变（顶部 rgba(5, 12, 25, 0.43) → 中部 0.37 → 底部 0.47，无 backdrop blur）；浅色遮罩值为历史方案，「深色主题（后续阶段预留）」未按该形式落地。
浅色主题：
```css
@@ -668,9 +725,9 @@ backdrop-filter: blur(8px);
## 10. 配色系统
默认采用浅色玻璃主题。
> 2026-10-14 实现状态：当前默认为**深色玻璃主题**（无主题切换），tokens 直接定义在 `globals.css` 的 `:root`，未使用 `[data-theme]` 覆盖；`settings.theme` 未接入样式。现行值见第 0 章；下方「推荐 CSS 变量」为立项时的浅色方案，仅作历史参考。
推荐 CSS 变量：
历史方案（浅色玻璃）推荐 CSS 变量：
```css
:root {
@@ -694,7 +751,7 @@ backdrop-filter: blur(8px);
}
```
变量按双主题友好方式组织：第一版只实现浅色值；深色玻璃主题为后续阶段，届时以 `[data-theme="dark"]` 覆盖同名变量，组件无需改动。
> 历史说明：上段为立项时的双主题规划。实际实现未走 `[data-theme]` 覆盖路线，深色值自当前版本起直接作为默认主题（见第 0 章与 `globals.css`）。
---
@@ -716,6 +773,8 @@ font-family:
sans-serif;
```
> 2026-10-14 实现状态：当前字体栈以 Avenir Next / Avenir 开头，未引入 Inter；中文回退与上方一致。
字体原则：
```text
@@ -775,6 +834,8 @@ font-family:
第一版仅实现浅色主题、仅适配桌面端
```
> 历史说明：末行「仅浅色主题、仅适配桌面端」为第一版约束，已被后续实现取代——当前为深色玻璃默认主题，移动端适配已完成。
最终目标：
> 打开 Polaris 后，用户可以立刻搜索、立刻访问常用网站，也可以通过侧边栏进入分类页面。页面具有个人氛围，但保持干净、高效、克制。