# 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（霞鹜文楷）** | 内置默认，`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`](stash-web/index.html) 的 `<link>`，
CSS 变量 `--font-sans` / `--font-mono` 定义在 `index.css`。

---

## 3. 图标

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

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

```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` |
| 新增图标 | 在 `@stash/ui` 的 iconfont 中补图标，再通过 `<Icon name>` 使用 |
| 新增分组 | 后台「分组管理」新建根分组 / 子分组，内容挂在分组上 |
| 调整侧栏导航 | 后台「侧边栏」勾选要显示的卡片与分组 |
| 新增卡片类型 | 在 `AppNext.tsx` 的 `renderEntries` / `renderCard` 增加分支 |
| 调整分区样式 | [`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`），
  前端静态数据下线；视觉与交互未变。