lab/ts/web/nextjs/polaris/Polaris 分类页设计文档.md

# Polaris 分类页设计文档

> 关联文档：
> [Polaris 项目说明文档](./Polaris%20项目说明文档.md) —— 项目定位、技术选型、数据结构、开发阶段
> [Polaris 首页设计文档](./Polaris%20首页设计文档.md) —— 首页布局与搜索交互

## 1. 页面定位

Polaris 的分类页用于展示某一类导航资源，例如：

```text
开发工具
AI 工具
设计资源
学习资料
效率工具
娱乐媒体
生活服务
```

分类页不是后台管理页，也不是资源管理面板，而是首页的延伸页面。

它的核心目标是：

1. 清晰展示当前分类下的所有链接；
2. 保持和首页一致的轻玻璃视觉风格；
3. 让用户可以快速浏览并打开目标网站；
4. 不引入过多管理、筛选、编辑类元素；
5. 保持页面干净、安静、克制。

分类页应给人的感觉是：

> 我进入了某一类个人收藏资源，可以直接浏览和访问，而不是进入了一个复杂的管理系统。

---

## 2. 页面示例

本文档以 **开发工具页** 为例进行说明。

页面标题：

```text
开发工具
```

页面描述：

```text
高效的开发工具和资源集合，提升你的开发体验和效率。
```

展示内容示例：

```text
GitHub
GitLab
Bitbucket
VS Code
JetBrains
GoLand
Postman
Docker
Kubernetes
Vercel
Netlify
Render
npm
pnpm
Figma
```

其他分类页面复用相同结构，只需要替换分类名称、描述和链接数据。

---

## 3. 与首页的关系

首页负责最高频入口：

```text
时间 / 日期
全局搜索框
常用链接
左侧分类导航
```

分类页负责分类浏览：

```text
分类标题
分类说明
链接数量
该分类下的网站卡片
```

首页有全局搜索框，分类页默认不展示搜索框。

这样可以避免功能重复，也能让分类页更像一个干净的资源浏览页面。

---

## 4. 分类页不保留搜索框

当前分类页不展示顶部搜索框。

原因：

1. 首页已经存在全局搜索框；
2. 分类页主要任务是浏览当前分类资源；
3. 再放搜索框会让页面变得像后台或资源管理器；
4. 搜索框会削弱分类标题和内容列表的视觉层级；
5. 用户可能困惑搜索范围是全站、当前分类，还是外部搜索引擎。

因此分类页第一版只保留内容展示，不放搜索框。

如果未来某个分类链接数量非常多，例如超过 30 个，可以考虑增加一个轻量的分类内筛选输入框，但它不应该是首页那种大搜索框，也不应该支持 Google、Bing、GitHub 等外部搜索。

未来可选方案：

```text
仅当前分类内筛选
小尺寸输入框
弱视觉权重
不放在第一视觉中心
```

当前阶段不实现。

---

## 5. 页面整体布局

分类页整体仍采用左右结构：

```text
┌──────────────────┬────────────────────────────────────────────┐
│ 左侧边栏          │ 分类内容区域                                │
│                  │                                            │
│ Logo + 折叠按钮   │ 分类标题                                    │
│ 首页              │ 分类描述                                    │
│ AI 工具           │                                            │
│ 开发工具          │ 全部工具  共 15 个                           │
│ 设计资源          │                                            │
│ 学习资料          │ 工具卡片网格                                 │
│ 效率工具          │                                            │
│ 娱乐媒体          │                                            │
│ 生活服务          │                                            │
└──────────────────┴────────────────────────────────────────────┘
```

布局原则：

1. 左侧边栏保持和首页一致；
2. 主内容区域使用玻璃面板承载；
3. 页面顶部展示分类标题和说明；
4. 内容区展示链接卡片；
5. 不展示搜索框；
6. 不展示排列切换；
7. 不展示编辑按钮；
8. 不展示设置按钮。

---

## 6. 左侧边栏

### 6.1 边栏内容

左侧边栏和首页保持一致。

展开状态下包含：

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

开发工具页中，左侧边栏的 **开发工具** 项处于选中状态。

---

### 6.2 选中态

开发工具项选中时，使用浅蓝紫色玻璃背景。

推荐样式：

```css
background: rgba(99, 102, 241, 0.10);
color: #2563EB;
```

图标和文字同时高亮。

选中项圆角：

```css
border-radius: 16px;
```

选中态不要使用高饱和、大面积实色块，否则会破坏轻玻璃风格。

---

### 6.3 折叠按钮

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

示意：

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

不使用侧边栏中间悬浮折叠按钮。

按钮样式应低调：

```css
width: 32px;
height: 32px;
border-radius: 10px;
background: transparent;
color: #334155;
```

Hover 状态：

```css
background: rgba(15, 23, 42, 0.06);
```

---

## 7. 主内容容器

### 7.1 容器定位

分类页主内容区域使用一个大的玻璃面板承载内容。

该面板与首页视觉风格一致，但内容密度略高。

推荐布局：

```text
┌────────────────────────────────────────────┐
│                                            │
│  开发工具                                  │
│  高效的开发工具和资源集合，提升你的开发体验... │
│                                            │
│  全部工具   共 15 个                        │
│                                            │
│  工具卡片网格                               │
│                                            │
└────────────────────────────────────────────┘
```

---

### 7.2 容器样式

推荐样式：

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

容器与页面边距：

```css
margin: 24px 30px 24px 0;
```

如果左侧边栏悬浮在页面内，主容器左侧应与边栏保持间距：

```css
gap: 24px;
```

---

### 7.3 容器内部间距

推荐内边距：

```css
padding: 56px 64px;
```

小屏幕可降低为：

```css
padding: 32px 24px;
```

内容区域不应贴边，玻璃面板内部需要足够留白。

---

## 8. 分类标题区域

### 8.1 标题

开发工具页标题为：

```text
开发工具
```

标题是页面主视觉之一，但不需要像首页时间那样巨大。

推荐样式：

```css
font-size: 40px;
font-weight: 700;
color: #0F172A;
letter-spacing: -0.02em;
```

大屏幕可使用：

```css
font-size: 44px;
```

---

### 8.2 描述

标题下方展示分类描述。

示例：

```text
高效的开发工具和资源集合，提升你的开发体验和效率。
```

推荐样式：

```css
font-size: 16px;
line-height: 1.7;
color: #64748B;
margin-top: 12px;
```

描述文字应简洁，不要写太长。

不同分类可使用类似描述：

```text
AI 工具：精选常用 AI 工具与服务，辅助创作、开发和效率提升。
设计资源：常用设计工具、素材与灵感资源集合。
学习资料：整理常用学习平台、文档、课程和知识资源。
效率工具：提升日常工作流效率的工具入口。
娱乐媒体：常用影音、社区和内容平台。
生活服务：日常生活、服务查询和实用网站入口。
```

---

## 9. 分组标题区域

分类描述下方展示内容分组标题。

开发工具页第一版只需要一个分组：

```text
全部工具
```

旁边展示数量：

```text
共 15 个
```

示意：

```text
全部工具    共 15 个
```

推荐样式：

```css
.section-title {
  font-size: 18px;
  font-weight: 700;
  color: #0F172A;
}

.section-count {
  font-size: 14px;
  color: #94A3B8;
  background: rgba(255, 255, 255, 0.42);
  border-radius: 999px;
  padding: 4px 10px;
}
```

分组标题和工具卡片网格之间保持间距：

```css
margin-top: 36px;
margin-bottom: 20px;
```

---

## 10. 工具卡片网格

### 10.1 网格布局

开发工具页推荐使用三列网格。

桌面端：

```text
三列网格
每行 3 个
共 5 行
```

示意：

```text
┌──────────┐ ┌──────────┐ ┌──────────┐
│ GitHub   │ │ GitLab   │ │ Bitbucket│
└──────────┘ └──────────┘ └──────────┘

┌──────────┐ ┌──────────┐ ┌──────────┐
│ VS Code  │ │ JetBrains│ │ GoLand   │
└──────────┘ └──────────┘ └──────────┘

┌──────────┐ ┌──────────┐ ┌──────────┐
│ Postman  │ │ Docker   │ │Kubernetes│
└──────────┘ └──────────┘ └──────────┘
```

推荐 CSS：

```css
display: grid;
grid-template-columns: repeat(3, minmax(0, 1fr));
gap: 20px 24px;
```

---

### 10.2 响应式网格

不同屏幕下的网格建议：

```text
大屏幕（>= 1280px）：3 列
中等屏幕（768px - 1279px）：2 列
```

推荐实现：

```css
grid-template-columns: repeat(2, minmax(0, 1fr));

@media (min-width: 1280px) {
  grid-template-columns: repeat(3, minmax(0, 1fr));
}
```

> 移动端单列布局为后续阶段工作，第一版仅适配桌面端与桌面窗口缩窄场景。

---

## 11. 工具卡片设计

### 11.1 卡片内容

每个工具卡片展示：

```text
工具图标
工具名称
简短描述
外链图标
```

示例：

```text
GitHub
全球最大的代码托管平台
```

不展示：

```text
编辑按钮
删除按钮
拖拽按钮
访问统计
创建时间
更新时间
域名副标题
复杂标签
```

外链图标可以保留，因为它表达“点击后打开外部网站”，但要足够轻，不要像编辑按钮。

---

### 11.2 卡片结构

推荐结构：

```text
┌────────────────────────────────────┐
│ 图标    GitHub                 ↗   │
│        全球最大的代码托管平台        │
└────────────────────────────────────┘
```

图标左侧对齐。

文字区域位于图标右侧。

外链图标位于右上角。

---

### 11.3 卡片尺寸

推荐桌面端尺寸：

```css
height: 96px;
min-width: 0;
```

卡片不需要太高，避免页面显得笨重。

推荐内边距：

```css
padding: 24px 28px;
```

---

### 11.4 卡片样式

推荐样式：

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

Hover 状态：

```css
transform: translateY(-2px);
background: rgba(255, 255, 255, 0.74);
box-shadow: 0 18px 50px rgba(15, 23, 42, 0.12);
border-color: rgba(255, 255, 255, 0.72);
```

过渡：

```css
transition:
  transform 180ms ease,
  background 180ms ease,
  box-shadow 180ms ease,
  border-color 180ms ease;
```

---

### 11.5 图标尺寸

工具图标推荐尺寸：

```css
width: 40px;
height: 40px;
```

对于复杂图标，可使用：

```css
width: 44px;
height: 44px;
```

图标区域应统一对齐，不同来源图标大小要视觉统一。

图标来源遵循统一图标方案（见[项目说明文档](./Polaris%20项目说明文档.md)）：

```text
自定义图标 → Simple Icons / 本地图标库 → favicon 自动抓取 → 文字占位兜底
```

推荐包裹容器：

```css
.icon-wrapper {
  width: 44px;
  height: 44px;
  display: flex;
  align-items: center;
  justify-content: center;
  flex-shrink: 0;
}
```

---

### 11.6 文字样式

工具名称：

```css
font-size: 17px;
font-weight: 700;
color: #0F172A;
```

工具描述：

```css
font-size: 14px;
line-height: 1.5;
color: #64748B;
margin-top: 4px;
```

描述建议控制在 8 到 16 个中文字之间。

示例：

```text
全球最大的代码托管平台
一体化 DevOps 平台
代码托管和协作开发
强大的代码编辑器
智能开发工具套件
Go 语言 IDE
API 开发和测试工具
容器化平台
容器编排平台
前端部署与托管平台
现代化的开发平台
云应用托管平台
JavaScript 包管理器
快速的包管理器
界面设计协作工具
```

---

## 12. 开发工具页数据示例

### 12.1 分类数据

```json
{
  "id": "dev",
  "title": "开发工具",
  "description": "高效的开发工具和资源集合，提升你的开发体验和效率。",
  "icon": "code",
  "sort": 20
}
```

---

### 12.2 链接数据

```json
[
  {
    "id": "github",
    "title": "GitHub",
    "description": "全球最大的代码托管平台",
    "url": "https://github.com",
    "icon": "si:github",
    "categoryId": "dev",
    "pinned": true,
    "keywords": ["代码", "仓库", "开源", "git"],
    "sort": 10
  },
  {
    "id": "gitlab",
    "title": "GitLab",
    "description": "一体化 DevOps 平台",
    "url": "https://gitlab.com",
    "icon": "si:gitlab",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["代码", "仓库", "devops", "ci", "cd"],
    "sort": 20
  },
  {
    "id": "bitbucket",
    "title": "Bitbucket",
    "description": "代码托管和协作开发",
    "url": "https://bitbucket.org",
    "icon": "si:bitbucket",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["代码", "仓库", "git"],
    "sort": 30
  },
  {
    "id": "vscode",
    "title": "VS Code",
    "description": "强大的代码编辑器",
    "url": "https://code.visualstudio.com",
    "icon": "si:vscode",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["编辑器", "ide", "代码"],
    "sort": 40
  },
  {
    "id": "jetbrains",
    "title": "JetBrains",
    "description": "智能开发工具套件",
    "url": "https://www.jetbrains.com",
    "icon": "si:jetbrains",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["ide", "开发工具", "编辑器"],
    "sort": 50
  },
  {
    "id": "goland",
    "title": "GoLand",
    "description": "Go 语言 IDE",
    "url": "https://www.jetbrains.com/go/",
    "icon": "si:goland",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["go", "golang", "ide"],
    "sort": 60
  },
  {
    "id": "postman",
    "title": "Postman",
    "description": "API 开发和测试工具",
    "url": "https://www.postman.com",
    "icon": "si:postman",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["api", "接口", "测试"],
    "sort": 70
  },
  {
    "id": "docker",
    "title": "Docker",
    "description": "容器化平台",
    "url": "https://www.docker.com",
    "icon": "si:docker",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["容器", "部署", "镜像"],
    "sort": 80
  },
  {
    "id": "kubernetes",
    "title": "Kubernetes",
    "description": "容器编排平台",
    "url": "https://kubernetes.io",
    "icon": "si:kubernetes",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["k8s", "容器", "编排", "云原生"],
    "sort": 90
  },
  {
    "id": "vercel",
    "title": "Vercel",
    "description": "前端部署与托管平台",
    "url": "https://vercel.com",
    "icon": "si:vercel",
    "categoryId": "dev",
    "pinned": true,
    "keywords": ["部署", "前端", "托管"],
    "sort": 100
  },
  {
    "id": "netlify",
    "title": "Netlify",
    "description": "现代化的开发平台",
    "url": "https://www.netlify.com",
    "icon": "si:netlify",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["部署", "前端", "托管"],
    "sort": 110
  },
  {
    "id": "render",
    "title": "Render",
    "description": "云应用托管平台",
    "url": "https://render.com",
    "icon": "si:render",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["部署", "后端", "托管", "云服务"],
    "sort": 120
  },
  {
    "id": "npm",
    "title": "npm",
    "description": "JavaScript 包管理器",
    "url": "https://www.npmjs.com",
    "icon": "si:npm",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["javascript", "node", "包管理"],
    "sort": 130
  },
  {
    "id": "pnpm",
    "title": "pnpm",
    "description": "快速的包管理器",
    "url": "https://pnpm.io",
    "icon": "si:pnpm",
    "categoryId": "dev",
    "pinned": false,
    "keywords": ["javascript", "node", "包管理"],
    "sort": 140
  },
  {
    "id": "figma",
    "title": "Figma",
    "description": "界面设计协作工具",
    "url": "https://www.figma.com",
    "icon": "si:figma",
    "categoryId": "dev",
    "pinned": true,
    "keywords": ["设计", "ui", "协作"],
    "sort": 150
  }
]
```

---

## 13. 交互行为

### 13.1 点击卡片

点击工具卡片后，在新标签页打开对应链接。

推荐行为：

```ts
window.open(url, "_blank", "noopener,noreferrer")
```

---

### 13.2 外链图标

每个卡片右上角可以保留一个轻量外链图标。

作用：

```text
提示该卡片会打开外部网站
```

外链图标不代表编辑，不是更多操作。

推荐样式：

```css
width: 16px;
height: 16px;
color: #64748B;
opacity: 0.75;
```

Hover 时：

```css
color: #2563EB;
opacity: 1;
```

---

### 13.3 卡片 hover

Hover 时只做轻微反馈：

```text
轻微上浮
背景更亮
阴影稍增强
外链图标高亮
```

不要使用夸张动画。

---

### 13.4 快捷键

分类页不注册任何快捷键。

`Ctrl K`（macOS 为 ⌘K）仅在首页生效；用户需要搜索时，通过侧边栏「首页」回到首页。

---

## 14. 响应式设计

### 14.1 桌面端

桌面端布局：

```text
左侧边栏固定
右侧主内容玻璃面板
工具卡片三列网格
```

推荐断点：

```text
>= 1280px：三列
768px - 1279px：两列
```

---

### 14.2 平板与移动端（后续阶段）

第一版仅适配桌面端。平板与移动端适配为后续阶段工作，届时参考以下方向：

```text
平板端：边栏宽度略小（200px - 220px），工具卡片两列
移动端：顶部 Logo + 菜单按钮（抽屉式边栏），单列工具卡片，
        主容器改为更轻的背景层（padding: 20px 16px; 卡片高度 84px）
```

---

## 15. 空状态设计

如果某个分类暂无链接，显示空状态。

示例：

```text
暂无工具
这个分类下还没有添加链接。
```

空状态不展示新增按钮。

原因：

1. 首页和分类页不承担管理功能；
2. 新增能力未来放在独立管理页；
3. 保持当前页面纯浏览定位。

空状态样式：

```css
height: 280px;
display: flex;
align-items: center;
justify-content: center;
color: #64748B;
```

---

## 16. 加载状态设计

第一版数据来自本地数据配置，通常不需要明显 loading。

后续接入 Go 后端后，可以增加加载状态。

推荐加载方式：

```text
骨架屏
轻微渐入
不使用大面积转圈 loading
```

工具卡片骨架：

```css
height: 96px;
border-radius: 18px;
background: rgba(255, 255, 255, 0.36);
```

---

## 17. 错误状态设计

如果后续从后端加载失败，显示轻量错误提示。

示例：

```text
资源加载失败
请稍后重试。
```

错误状态不要占据过多视觉空间。

可以提供一个轻量重试按钮，但不要设计得像后台系统。

---

## 18. 视觉一致性要求

分类页必须和首页保持一致：

```text
相同背景
相同侧边栏
相同玻璃材质
相同圆角系统
相同阴影系统
相同字体系统
相同主色系统
相同导航选中态
```

分类页相比首页的区别：

```text
首页强调时间、搜索、常用链接
分类页强调标题、描述、链接集合
```

---

## 19. 不建议出现的元素

分类页第一版不建议出现：

```text
顶部搜索框
排列方式切换
表格视图
编辑按钮
删除按钮
拖拽排序
新增按钮
管理入口
筛选器
复杂标签
访问统计
最近访问时间
用户头像
登录状态
```

这些内容会让页面从“个人导航浏览页”变成“后台管理页”。

后续如果需要管理功能，应放入独立管理页面或隐藏入口。

---

## 20. 推荐组件拆分

前端组件可以拆分为：

```text
CategoryPage
CategoryHeader
CategorySectionHeader
ToolGrid
ToolCard
Sidebar
MainLayout
```

目录示例：

```text
src/
  app/
    categories/
      [categoryId]/
        page.tsx

  components/
    layout/
      Sidebar.tsx
      MainLayout.tsx

    category/
      CategoryHeader.tsx
      CategorySectionHeader.tsx
      ToolGrid.tsx
      ToolCard.tsx

  services/
    categories.ts
    links.ts

  types/
    navigation.ts
```

---

## 21. TypeScript 类型建议

```ts
export type Category = {
  id: string
  title: string
  description: string
  icon: string
  sort: number
}

export type NavLink = {
  id: string
  title: string
  description?: string
  url: string
  icon: string
  categoryId: string
  pinned: boolean
  keywords: string[]
  sort: number
}
```

分类页获取数据时：

```ts
type CategoryPageData = {
  category: Category
  links: NavLink[]
}
```

---

## 22. 分类页开发优先级

### 第一阶段

完成静态展示：

```text
分类页路由
分类标题
分类描述
全部工具数量
工具卡片网格
空分类展示空状态
左侧导航选中态
点击卡片跳转
```

---

### 第二阶段

完善响应式（后续阶段）：

```text
平板两列
移动端一列
侧边栏移动端适配
```

---

### 第三阶段

完善状态：

```text
空状态
加载状态
错误状态
卡片 hover
外链图标 hover
```

---

### 第四阶段

接入后端：

```text
从 Go API 获取分类
从 Go API 获取链接
支持按 categoryId 查询
支持服务层切换数据源
```

---

## 23. 开发工具页最终目标

开发工具页最终应呈现为：

> 一个安静、清爽、玻璃感的开发资源集合页。用户进入页面后，可以快速知道当前分类是什么，并直接浏览和打开开发相关工具。页面没有搜索框、没有排列切换、没有编辑管理按钮，整体保持和 Polaris 首页一致的个人起始页气质。

核心原则：

```text
分类页负责浏览
首页负责搜索
侧边栏负责导航
管理功能不进入主视觉
视觉风格保持轻玻璃和极简
```