329 lines
12 KiB
Markdown
329 lines
12 KiB
Markdown
# Alright 主题设计规范（Stash 前端）
|
||
|
||
本文件记录 Stash 控制台在视觉上对齐 [Alright 主题](https://alright.demo.nicetheme.xyz/) 的各项标准，
|
||
用于后续新增组件、调整样式时保持一致。
|
||
|
||
- 参考站点：<https://alright.demo.nicetheme.xyz/>
|
||
- 生效范围：`stash-web/`（React 控制台）
|
||
- 令牌定义处：[`stash-web/src/index.css`](stash-web/src/index.css)
|
||
- 组件样式：[`stash-web/src/App.css`](stash-web/src/App.css)
|
||
|
||
> 所有色值、字号、圆角均取自主题的 `:root` 设计变量，不是肉眼取色。
|
||
|
||
---
|
||
|
||
## 1. 设计令牌
|
||
|
||
### 1.1 灰阶
|
||
|
||
| 令牌 | 值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `--gray-1` | `#f7f8fa` | 页面背景、浅底块 |
|
||
| `--gray-2` | `#f6f6f6` | 边框、次级浅底 |
|
||
| `--gray-3` | `#eeeeee` | hover 底色 |
|
||
| `--gray-4` | `#c9cdd4` | 分隔线、禁用态 |
|
||
| `--gray-5` | `#86909c` | 说明文字 |
|
||
| `--gray-6` | `#4e5969` | 次级文字 |
|
||
| `--gray-7` | `#2c343c` | 强调文字 |
|
||
| `--gray-8` | `#1d2129` | 主文字 |
|
||
|
||
### 1.2 语义色
|
||
|
||
| 令牌 | 值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `--color-primary` | `#3858f6` | 主色：链接、选中态、色条、图标 |
|
||
| `--color-primary` 10% | `rgba(56, 88, 246, 0.1)` | 主色浅底（`--primary-soft`） |
|
||
| `--color-danger` | `#ff3e3e` | 数量角标、错误提示 |
|
||
| `--color-warning` | `#ffba3a` | 橙色强调（CES 色条） |
|
||
| `--color-success` | `#4abd86` | 在线状态 |
|
||
| 渐变红 | `linear-gradient(to right, #ff6034, #ff3e3e)` | 热门标记 |
|
||
| HOT 渐变 | `#ff7b51 → #ff0e0e` | HOT 图形徽标 |
|
||
| 认证渐变 | `#ffb74a → #fd900f` | 头像认证角标 |
|
||
|
||
### 1.3 圆角
|
||
|
||
| 令牌 | 值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `--radius-xs` | `4px` | 小标签、徽标 |
|
||
| `--radius-sm` | `6px` | 小组件 |
|
||
| `--radius-main`(md) | `12px` | 卡片、面板 |
|
||
| `--radius-lg` | `24px` | 大容器 |
|
||
| `max` | `999px` | 胶囊、圆形 |
|
||
|
||
### 1.4 阴影
|
||
|
||
主题的阴影非常克制，只有两层：
|
||
|
||
```css
|
||
--shadow-card: 0 6px 16px rgba(27, 26, 49, 0.02); /* 常态 */
|
||
--shadow-hover: 0 6px 16px rgba(27, 26, 49, 0.06); /* 悬停 */
|
||
```
|
||
|
||
**注意**：应用条目、作者列表这类「行」不应该有阴影或描边。
|
||
|
||
### 1.5 字号阶梯
|
||
|
||
| 令牌 | 字号 | 行高 | 用途 |
|
||
| --- | --- | --- | --- |
|
||
| `xs` | 10px | 14px | 角标 |
|
||
| `sm` | 12px | 16px | 描述、元信息、HOT 旁注 |
|
||
| `md` | 14px | 20px | 正文、按钮、导航 |
|
||
| `lg` | 16px | 24px | 分区标题、条目标题 |
|
||
| `xl` | 24px | — | 详情页大标题 |
|
||
|
||
字重：主题的「加粗」是 `500`，不是 700。
|
||
|
||
### 1.6 动效时长
|
||
|
||
| 令牌 | 值 | 用途 |
|
||
| --- | --- | --- |
|
||
| `base` | 0.3s | 展开/收起、淡入淡出 |
|
||
| `fast` | 0.2s | 颜色、背景变化 |
|
||
| enter | `ease-out` | 出现 |
|
||
| leave | `ease-in` | 消失 |
|
||
|
||
---
|
||
|
||
## 2. 字体
|
||
|
||
| 角色 | 字体 | 说明 |
|
||
| --- | --- | --- |
|
||
| 正文 | **LXGW WenKai（霞鹜文楷）** | 与演示站同一份 webfont，`cdn.staticfile.net` |
|
||
| 回退 | `-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Hiragino Sans GB', 'Microsoft YaHei', sans-serif` | 字体加载失败时 |
|
||
| 数字（主题） | `Outfit-Medium` | 仅主题的 `font-price` / `font-number` 使用，Stash 未引入 |
|
||
| 等宽 | `ui-monospace, Consolas, monospace` | 路由地址等路径文本 |
|
||
|
||
引入位置：[`stash-web/index.html`](stash-web/index.html) 的 `<link>`，
|
||
CSS 变量 `--font-sans` / `--font-mono` 定义在 `index.css`。
|
||
|
||
---
|
||
|
||
## 3. 图标
|
||
|
||
### 3.1 图标字体
|
||
|
||
主题使用自建 iconfont（线性风格，Project id 4809463）。
|
||
Stash 自托管了一份 **只含所需字形** 的子集：
|
||
|
||
- 字体文件：[`stash-web/src/assets/iconfont.woff2`](stash-web/src/assets/iconfont.woff2)
|
||
- 样式：[`stash-web/src/iconfont.css`](stash-web/src/iconfont.css)
|
||
- 组件封装：[`stash-web/src/components/common/Icon.tsx`](stash-web/src/components/common/Icon.tsx)
|
||
|
||
| 用途 | 主题字形 | 码点 | Stash 类名 |
|
||
| --- | --- | --- | --- |
|
||
| 搜索 | `search_3_line` | `\e942` | `.icon-search` |
|
||
| 用户 / 登录 | `user_3_line` | `\e966` | `.icon-user` |
|
||
| 重新扫描 | `refresh_3_line` | `\e93d` | `.icon-refresh` |
|
||
| 查看接口 | `link_line` | `\ea37` | `.icon-link` |
|
||
| 跳转 | `arrow_right_up_line` | `\e8be` | `.icon-external` |
|
||
| 浏览量 | `eye_line` | `\e8fd` | `.icon-eye` |
|
||
| 点赞 | `thumb_up_2_line` | `\e957` | `.icon-thumb-up` |
|
||
| 分享 | `share_3_line` | `\e946` | `.icon-share` |
|
||
| 清空搜索 | `close_line` | `\e8e4` | `.icon-close` |
|
||
| 分区更多 | `more_3_line` | `\e91f` | `.icon-more` |
|
||
| 回到顶部 | `arrow_to_up_line` | `\e8c1` | `.icon-arrow-up` |
|
||
| 返回 | `arrow_left_line` | `\e8b5` | `.icon-arrow-left` |
|
||
| 导航展开 | `arrow_down_line` | `\e8b7` | `.icon-arrow-down`（未使用，见下） |
|
||
|
||
用法：`<i className="iconfont icon-search" />`，尺寸用 `font-size`、颜色用 `color` 控制。
|
||
|
||
### 3.2 CSS 绘制的箭头
|
||
|
||
主题的**导航折叠箭头不是图标字体**，而是一个 6×6 的描边方块旋转而成：
|
||
|
||
```css
|
||
.nav-link.has-children::after {
|
||
content: '';
|
||
width: 6px; height: 6px;
|
||
border-left: 1px solid currentColor;
|
||
border-bottom: 1px solid currentColor;
|
||
transform: rotate(315deg); /* 展开时 135deg */
|
||
opacity: 0.4;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 布局
|
||
|
||
### 4.1 整体结构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ SiteHeader（固定 60px，白底、底部 1px 分隔） │
|
||
├──────────────────────────────────────────────┤
|
||
│ 搜索框（固定，480×44，居中） │
|
||
│ ┌──────────┬─────────────────────────────┐ │
|
||
│ │ Sidebar │ 内容区（内部滚动） │ │
|
||
│ │ 240px │ 分区卡片 / 明细页 │ │
|
||
│ └──────────┴─────────────────────────────┘ │
|
||
└──────────────────────────────────────────────┘
|
||
```
|
||
|
||
| 项 | 值 | 说明 |
|
||
| --- | --- | --- |
|
||
| 版心宽度 | `1380px` | `--layout-max-width`，超宽屏居中 |
|
||
| 顶栏高度 | `60px` | `--top-nav-height` |
|
||
| 侧栏宽度 | `240px` | `--sidebar-width`（主题为 260px，Stash 收窄） |
|
||
| 栅格间距 | `20px` | 侧栏与内容区之间 |
|
||
| 内容区顶部让位 | `52px` | `--content-top-offset`，给悬浮搜索框 |
|
||
| 搜索框 | `480 × 44`，距顶 `76px` | 相对整页居中 |
|
||
|
||
### 4.2 页面背景
|
||
|
||
主题在 body 上叠了一层固定背景图：
|
||
|
||
```css
|
||
.site-background {
|
||
position: fixed; inset: 0 auto auto 0;
|
||
width: 100%; height: 65vh;
|
||
background: url('./assets/site-bg.jpg') top center / cover no-repeat;
|
||
pointer-events: none;
|
||
}
|
||
.site-background::after { /* 底部 80% 渐隐到页面底色 */
|
||
content: ''; position: absolute; inset: auto 0 0 0; height: 80%;
|
||
background-image: linear-gradient(0deg, var(--bg-color) 0%, transparent 100%);
|
||
}
|
||
```
|
||
|
||
滚动时背景不动，形成轻微视差。
|
||
|
||
---
|
||
|
||
## 5. 组件规范
|
||
|
||
### 5.1 分区卡片（首页每一块）
|
||
|
||
| 属性 | 值 |
|
||
| --- | --- |
|
||
| 容器 | 白底、`1px solid var(--border-color)`、圆角 12、内边距 20、`var(--shadow-card)` |
|
||
| 标题色条 | `4 × 16px`，圆角 2，分类色（本地/推荐 `#3858f6`、电影 `#ff6034`、CES `#ffba3a`） |
|
||
| 标题 | 16px / 500 |
|
||
| 数量角标 | 红色 `#ff3e3e`、10px 字号、圆角 8、贴在标题右上角（`top:-8px; right:-18px`） |
|
||
| 更多按钮 | `.icon-more`，16px，右对齐 |
|
||
|
||
### 5.2 应用条目（对齐主题「推荐作者」）
|
||
|
||
对应标记：
|
||
|
||
```html
|
||
<a class="item">
|
||
<div class="flex-avatar">
|
||
<img class="avatar-48">
|
||
<span class="avatar-badge badge_5 w-10"></span>
|
||
</div>
|
||
<div class="item-content">
|
||
<h3 class="font-title text-md">名字 <span class="item-badge hot"></span></h3>
|
||
<div class="text-xs text-muted h-1x">描述</div>
|
||
</div>
|
||
</a>
|
||
```
|
||
|
||
| 元素 | 规格 |
|
||
| --- | --- |
|
||
| 行 | `display:flex; gap:15px`，**无底色、无描边、无阴影** |
|
||
| 头像 | 48×48，`border-radius:100%`，图片 `object-fit:cover` |
|
||
| 认证角标 | 10×10，绝对定位右下角，内联 `badge_5` 的 SVG |
|
||
| 名字 | 16px / 行高 24px / 500 |
|
||
| HOT 徽标 | 24×16 的**图片**（内联主题 `--hot-icon` SVG），不是文字 |
|
||
| 描述 | 12px / 行高 16px / `--text-muted`，单行省略 |
|
||
| 悬停 | 名字变主色，不加阴影 |
|
||
|
||
> HOT 与认证角标只出现在 `hot: true` 的条目上，不是每个都有。
|
||
|
||
### 5.3 海报 / 图文
|
||
|
||
| 网格 | 列数 | 间距 | 比例 |
|
||
| --- | --- | --- | --- |
|
||
| 应用 | 4（≤1100px 变 2） | 12px | — |
|
||
| 电影海报 | 6（≤1100px 变 3） | 12px | 2:3 |
|
||
| 首页图文 | 4（≤1100px 变 2） | 12px | 4:3 |
|
||
| 明细页图文白卡 | 4（≤1100px 变 2） | 16px | 封面 16:10 |
|
||
|
||
封面下方统一用「黑色渐变 → 透明」遮罩压住白色标题：
|
||
|
||
```css
|
||
background: linear-gradient(to top, rgba(0,0,0,.85) 0%, rgba(0,0,0,.4) 60%, transparent 100%);
|
||
```
|
||
|
||
### 5.4 侧栏
|
||
|
||
| 模块 | 规格 |
|
||
| --- | --- |
|
||
| 用户卡 | 64px 圆形头像 + 认证角标、14px 名字、11–12px 角色/简介/属地 |
|
||
| 本地服务面板 | 标题 14px、状态胶囊、两行统计（`dt` 12px / `dd` 12px 等宽）、两个操作按钮 |
|
||
| 分类导航 | 行高 `9px 12px` 内边距、圆角 8、14px；子项 12px、缩进 12px |
|
||
|
||
### 5.5 返回顶部
|
||
|
||
对应主题 `.scroll-toolbar .totop-button`：
|
||
|
||
```css
|
||
.back-to-top {
|
||
position: fixed; top: 50%; right: 30px;
|
||
width: 42px; height: 42px;
|
||
border-radius: 50%;
|
||
background-color: var(--border-color);
|
||
color: var(--text-sub);
|
||
opacity: 0; visibility: hidden; /* 默认隐藏 */
|
||
transform: translateY(-50%) translateY(15px);
|
||
transition: opacity .3s, visibility .3s, transform .3s;
|
||
}
|
||
.back-to-top.is-visible {
|
||
opacity: 1; visibility: visible;
|
||
transform: translateY(-50%);
|
||
}
|
||
```
|
||
|
||
滚动超过 4px 才出现，回到顶部后自动隐藏；窄屏改为 `right:15px; bottom:30%`。
|
||
|
||
---
|
||
|
||
## 6. 动效
|
||
|
||
| 效果 | 实现 |
|
||
| --- | --- |
|
||
| 视图切换（首页 ↔ 明细 ↔ 条目） | `view-in`：0.22s 淡入 + 上移 6px |
|
||
| 侧栏子菜单展开 | `grid-template-rows: 0fr → 1fr`，0.28s，全程 `overflow:hidden`（不产生滚动条） |
|
||
| 导航箭头 | `rotate(315deg) → 135deg`，0.3s |
|
||
| 分区卡片 / 海报 / 图文悬停 | `translateY(-2px)`，0.2s |
|
||
| 应用条目悬停 | 仅名字改为主色 |
|
||
| 回到顶部 | 淡入 + 上移 15px，0.3s |
|
||
| 刷新按钮加载 | `spin 0.9s linear infinite` |
|
||
| 内容区顶部遮罩 | 滚动后 0.2s 淡入 |
|
||
|
||
---
|
||
|
||
## 7. 与演示站的有意差异
|
||
|
||
| 项 | 主题 | Stash | 原因 |
|
||
| --- | --- | --- | --- |
|
||
| 侧栏宽度 | 260px | 240px | 控制台信息密度略高 |
|
||
| 深色模式 | 支持 | 未实现 | 当前只做浅色主题 |
|
||
| 数字字体 | Outfit-Medium | 未引入 | 少一个外部字体请求 |
|
||
| 图标集 | 全量 446 个 | 13 个子集 | 控制体积（woff2 52KB） |
|
||
| 导航箭头位置 | 紧贴文字右侧 | 行末右对齐 | 视觉上更整齐 |
|
||
|
||
---
|
||
|
||
## 8. 扩展指引
|
||
|
||
| 需求 | 改动位置 |
|
||
| --- | --- |
|
||
| 改主色 / 灰阶 / 圆角 | [`stash-web/src/index.css`](stash-web/src/index.css) 的 `:root` |
|
||
| 新增图标 | 把 codepoint 加进 [`stash-web/src/iconfont.css`](stash-web/src/iconfont.css)，在 `Icon.tsx` 包一个组件 |
|
||
| 新增分类 | 内容库 `category` 表（首次启动前可改 [`src/db/seed.json`](src/db/seed.json)），首页与明细页自动适配 |
|
||
| 调整侧栏导航 | 内容库 `nav_entry` 表，标签 / 层级 / 跳转目标都可在库里改 |
|
||
| 新增卡片类型 | 在 `data/types.ts` 增加 kind，`HomeView` / `DetailView` 各加一个分支 |
|
||
| 调整分区样式 | [`stash-web/src/App.css`](stash-web/src/App.css) 的「分区卡片」段落 |
|
||
| 换背景图 | 替换 `stash-web/src/assets/site-bg.jpg` |
|
||
|
||
---
|
||
|
||
## 9. 变更记录
|
||
|
||
- 2026-10-22：按本规范完成整体换肤（配色、字体、图标、背景、应用条目、返回顶部），
|
||
并将侧栏导航箭头改为与主题一致的 CSS 箭头。
|
||
- 2026-10-23：分类内容与侧栏导航迁入 SQLite 内容库（`data/stash.db`），
|
||
前端静态数据下线；视觉与交互未变。
|