Files

T

labmemandClaude Opus 4.8 9754d61ffe feat(ts): 实现 Polaris 可交互首页

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-09-02 23:53:28 +08:00

23 KiB

Raw Blame History

Polaris 分类页设计文档

关联文档： Polaris 项目说明文档 —— 项目定位、技术选型、数据结构、开发阶段 Polaris 首页设计文档 —— 首页布局与搜索交互

1. 页面定位

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

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

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

它的核心目标是：

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

分类页应给人的感觉是：

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

2. 页面示例

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

页面标题：

开发工具

页面描述：

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

展示内容示例：

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

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

3. 与首页的关系

首页负责最高频入口：

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

分类页负责分类浏览：

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

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

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

4. 分类页不保留搜索框

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

原因：

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

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

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

未来可选方案：

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

当前阶段不实现。

5. 页面整体布局

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

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

布局原则：

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

6. 左侧边栏

6.1 边栏内容

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

展开状态下包含：

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

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

6.2 选中态

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

推荐样式：

background: rgba(99, 102, 241, 0.1);
color: #2563eb;

图标和文字同时高亮。

选中项圆角：

border-radius: 16px;

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

6.3 折叠按钮

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

示意：

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

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

按钮样式应低调：

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

Hover 状态：

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

7. 主内容容器

7.1 容器定位

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

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

推荐布局：

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

7.2 容器样式

推荐样式：

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.1);

容器与页面边距：

margin: 24px 30px 24px 0;

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

gap: 24px;

7.3 容器内部间距

推荐内边距：

padding: 56px 64px;

小屏幕可降低为：

padding: 32px 24px;

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

8. 分类标题区域

8.1 标题

开发工具页标题为：

开发工具

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

推荐样式：

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

大屏幕可使用：

font-size: 44px;

8.2 描述

标题下方展示分类描述。

示例：

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

推荐样式：

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

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

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

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

9. 分组标题区域

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

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

全部工具

旁边展示数量：

共 15 个

示意：

全部工具    共 15 个

推荐样式：

.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;
}

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

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

10. 工具卡片网格

10.1 网格布局

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

桌面端：

三列网格
每行 3 个
共 5 行

示意：

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

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

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

10.2 响应式网格

不同屏幕下的网格建议：

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

推荐实现：

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

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

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

11. 工具卡片设计

11.1 卡片内容

每个工具卡片展示：

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

示例：

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

不展示：

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

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

11.2 卡片结构

推荐结构：

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

图标左侧对齐。

文字区域位于图标右侧。

外链图标位于右上角。

11.3 卡片尺寸

推荐桌面端尺寸：

height: 96px;
min-width: 0;

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

推荐内边距：

padding: 24px 28px;

11.4 卡片样式

推荐样式：

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 状态：

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);

过渡：

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

11.5 图标尺寸

工具图标推荐尺寸：

width: 40px;
height: 40px;

对于复杂图标，可使用：

width: 44px;
height: 44px;

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

图标来源遵循统一图标方案（见项目说明文档）：

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

推荐包裹容器：

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

11.6 文字样式

工具名称：

font-size: 17px;
font-weight: 700;
color: #0f172a;

工具描述：

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

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

示例：

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

12. 开发工具页数据示例

12.1 分类数据

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

12.2 链接数据

[
  {
    "id": "github",
    "title": "GitHub",
    "description": "全球最大的代码托管平台",
    "url": "https://github.com",
    "icon": "si:github",
    "categoryId": "dev",
    "pinned": true,
    "pinnedSort": 10,
    "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,
    "pinnedSort": 70,
    "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,
    "pinnedSort": 50,
    "keywords": ["设计", "ui", "协作"],
    "sort": 150
  }
]

13. 交互行为

13.1 点击卡片

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

推荐行为：

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

13.2 外链图标

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

作用：

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

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

推荐样式：

width: 16px;
height: 16px;
color: #64748b;
opacity: 0.75;

Hover 时：

color: #2563eb;
opacity: 1;

13.3 卡片 hover

Hover 时只做轻微反馈：

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

不要使用夸张动画。

13.4 快捷键

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

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

14. 响应式设计

14.1 桌面端

桌面端布局：

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

推荐断点：

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

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

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

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

15. 空状态设计

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

示例：

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

空状态不展示新增按钮。

原因：

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

空状态样式：

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

16. 加载状态设计

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

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

推荐加载方式：

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

工具卡片骨架：

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

17. 错误状态设计

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

示例：

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

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

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

18. 视觉一致性要求

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

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

分类页相比首页的区别：

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

19. 不建议出现的元素

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

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

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

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

20. 推荐组件拆分

前端组件可以拆分为：

CategoryPage
CategoryHeader
CategorySectionHeader
ToolGrid
ToolCard
Sidebar
MainLayout

目录示例：

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 类型建议

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
  pinnedSort?: number
  keywords: string[]
  sort: number
}

分类页获取数据时：

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

22. 分类页开发优先级

第一阶段

完成静态展示：

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

第二阶段

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

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

第三阶段

完善状态：

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

第四阶段

接入后端：

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

23. 开发工具页最终目标

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

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

核心原则：

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

23 KiB Raw Blame History Unescape Escape

Polaris 分类页设计文档

1. 页面定位

2. 页面示例

3. 与首页的关系

4. 分类页不保留搜索框

5. 页面整体布局

6. 左侧边栏

6.1 边栏内容

6.2 选中态

6.3 折叠按钮

7. 主内容容器

7.1 容器定位

7.2 容器样式

7.3 容器内部间距

8. 分类标题区域

8.1 标题

8.2 描述

9. 分组标题区域

10. 工具卡片网格

10.1 网格布局

10.2 响应式网格

11. 工具卡片设计

11.1 卡片内容

11.2 卡片结构

11.3 卡片尺寸

11.4 卡片样式

11.5 图标尺寸

11.6 文字样式

12. 开发工具页数据示例

12.1 分类数据

12.2 链接数据

13. 交互行为

13.1 点击卡片

13.2 外链图标

13.3 卡片 hover

13.4 快捷键

14. 响应式设计

14.1 桌面端

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

15. 空状态设计

16. 加载状态设计

17. 错误状态设计

18. 视觉一致性要求

19. 不建议出现的元素

20. 推荐组件拆分

21. TypeScript 类型建议

22. 分类页开发优先级

第一阶段

第二阶段

第三阶段

第四阶段

23. 开发工具页最终目标

23 KiB

Raw Blame History