stash/ALRIGHT-DESIGN.md

Alright 主题设计规范（Stash 前端）

本文件记录 Stash 控制台在视觉上对齐 Alright 主题 的各项标准， 用于后续新增组件、调整样式时保持一致。

• 参考站点：https://alright.demo.nicetheme.xyz/
• 生效范围：stash-web/（React 控制台）
• 令牌定义处：stash-web/src/index.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 阴影

主题的阴影非常克制，只有两层：

--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（霞鹜文楷）	内置默认，cdn.staticfile.net；后台「系统管理 → 字体」可换成 font/ 目录里的字体或外部字体链接
回退	-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 的 <link>， CSS 变量 --font-sans / --font-mono 定义在 index.css。

---

3. 图标

图标统一来自组件库 @stash/ui：

import { Icon } from '@stash/ui'

<Icon name="search_3_line" />

可用名称见 @stash/ui 导出的 ICON_NAMES，尺寸与颜色分别由 size / CSS color 控制。stash-web 不再维护本地 iconfont 或 Icon.tsx。

---

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 上叠了一层固定背景图：

.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 应用条目（对齐主题「推荐作者」）

对应标记：

<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

封面下方统一用「黑色渐变 → 透明」遮罩压住白色标题：

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：

.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 的 :root
新增图标	在 @stash/ui 的 iconfont 中补图标，再通过 <Icon name> 使用
新增分组	后台「分组管理」新建根分组 / 子分组，内容挂在分组上
调整侧栏导航	后台「侧边栏」勾选要显示的卡片与分组
新增卡片类型	在 AppNext.tsx 的 renderEntries / renderCard 增加分支
调整分区样式	stash-web/src/App.css 的「分区卡片」段落
换背景图	替换 stash-web/src/assets/site-bg.jpg

---

9. 变更记录

• 2026-10-22：按本规范完成整体换肤（配色、字体、图标、背景、应用条目、返回顶部）， 并将侧栏导航箭头改为与主题一致的 CSS 箭头。
• 2026-10-23：分类内容与侧栏导航迁入 SQLite 内容库（data/stash.db）， 前端静态数据下线；视觉与交互未变。