202 lines
13 KiB
Markdown
202 lines
13 KiB
Markdown
# Alright 参考站拆解
|
||
|
||
> 对标站点：<https://alright.demo.nicetheme.xyz/>
|
||
> 拆解日期：2026-10-26 · 对照版本：`@stash/ui` 0.1.0
|
||
> 产物：[DESIGN.md](../DESIGN.md)（规则）、[COMPONENTS.md](COMPONENTS.md)（契约）都按这份拆解更新。
|
||
|
||
## 1. 怎么拆的
|
||
|
||
不看截图猜，全部取实测值：
|
||
|
||
| 手段 | 用途 | 落盘位置 |
|
||
| --- | --- | --- |
|
||
| 抓取主题 CSS（620KB，Autoptimize 合并包） | 读原始规则：令牌、`:hover`、`@media`、暗色覆盖 | `.ref/theme.css` |
|
||
| Playwright 跑计算样式 | 拿到真实渲染值（字号、行高、圆角、阴影、尺寸、过渡） | `.ref/probe.json` |
|
||
| Playwright 截图 | 桌面 1440 / 移动 390、首页 / 详情页 | `.ref/shots/*.png` |
|
||
|
||
复现命令（都要先 `npm run dev`）：
|
||
|
||
```bash
|
||
node .ref/probe.mjs # 重新采集计算样式 + 截图
|
||
node .ref/layout.mjs # 只量布局（列宽、头部高度）
|
||
```
|
||
|
||
`.ref/` 只是拆解产物，不进构建、不进发布。
|
||
|
||
## 2. 站点底座（决定了哪些东西不该抄）
|
||
|
||
- **WordPress + Bootstrap 5**：按钮、表单、模态、分页的基础行为来自 Bootstrap；
|
||
- **Alpine.js**（`x-data` / `@click`）：交互状态，例如点赞、主题切换；
|
||
- **Swiper / Fancybox / Plyr / CKEditor**：轮播、灯箱、播放器、编辑器，各有独立样式；
|
||
- **自建 iconfont**（Project 4809463）：线性图标，字号 18~24；
|
||
- 主题自己的工具类：`.text-lg`、`.flex-avatar`、`.item-badge`、`.box-block`、`.tags-list`……
|
||
|
||
结论：**只对齐主题层**（令牌、尺寸、间距、圆角、阴影、交互节奏、组件外观），
|
||
不复刻 Bootstrap 的组件实现（下拉、模态那种带 JS 状态机的东西我们自己做，见 COMPONENTS.md §5）。
|
||
|
||
## 3. 设计令牌对照
|
||
|
||
| 参考站变量 | 值 | 我们的令牌 | 对齐情况 |
|
||
| --- | --- | --- | --- |
|
||
| `--gray-1 … --gray-8` | `#f7f8fa` `#f6f6f6` `#eee` `#c9cdd4` `#86909c` `#4e5969` `#2c343c` `#1d2129` | `--su-gray-1 … -8` | ✅ 完全一致 |
|
||
| `--blue` | `#3858f6` | `--su-color-primary` | ✅ |
|
||
| `--red` | `#ff3e3e` | `--su-color-danger` | ✅ |
|
||
| `--orange` / `--orange-dark` / `--orange-light` | `#ffba3a` / `#ff8338` / `#fffbe8` | `--su-color-warning` / `--su-color-orange-dark` / `--su-color-orange-light` | ✅ 本轮补齐后两项 |
|
||
| `--green` | `#4abd86` | `--su-color-success` | ✅ |
|
||
| `--gradient-red` | `linear-gradient(to right,#ff6034,#ff3e3e)` | `--su-gradient-red` | ✅ 本轮新增 |
|
||
| `.item-badge` 置顶 / 付费 | `135deg #ff2f43→#ff6327` / `#ff952f→#ff662b` | `--su-gradient-hot` / `--su-gradient-paid` | ✅ 本轮新增 |
|
||
| 认证角标 SVG | `#FFB74A → #FD900F` | `--su-gradient-verified` | ✅ |
|
||
| `--border-radius-xs/sm/md/lg/max` | 4 / 6 / 12 / 24 / 999 | `--su-radius-*` | ✅ |
|
||
| `--shadow` | `0 6px 16px 0 rgb(27 26 49 / 1%)` | `--su-shadow-card` | ⚠️ 原为 2%，**本轮改成 1%** |
|
||
| `--shadow-2` | `rgb(27 26 49 / 3%)` | `--su-shadow-hover` | ⚠️ 原为 6%，**本轮改成 3%** |
|
||
| `--border-color` / `--border-light` | `gray-2` / `gray-3` | `--su-border` / `--su-border-strong` | ✅ |
|
||
| `--card-border-color` | `gray-1` | `--su-card-border` | ✅ 本轮新增（卡片描边几乎不可见） |
|
||
| `--color-text` / `--color-secondary` | `gray-7` | `--su-text-secondary` | ✅ 本轮新增 |
|
||
| `--color-muted` | `gray-6` | `--su-text-sub` | ✅（我们的 `text-muted` 保留 `gray-5` 给更弱的占位） |
|
||
| `--bg-body` / `--card-bg` | `gray-1` / `#fff` | `--su-bg-page` / `--su-bg-card` | ✅ |
|
||
| `--bg-light` | `gray-2` | `--su-bg-subtle`（本轮改为 gray-1） | ⚠️ 参考站标签用的是 `gray-1`，见 §6 |
|
||
| `--animation-duration-fast/base` | `.2s` / `.3s` | `--su-duration-fast/base` | ✅ |
|
||
| `--animation-timing-function-enter/leave` | `ease-out` / `ease-in` | `--su-ease-out` / `--su-ease-in` | ✅ |
|
||
| 组件里的过渡 | 绝大多数是 `all .3s ease-in-out` | `--su-ease-in-out` | ✅ 本轮新增，组件过渡改用它 |
|
||
|
||
## 4. 字号与行高（最容易抄错的一处）
|
||
|
||
参考站 `:root` 里的 `--font-size-*`（10/12/14/16/24）**并不是页面实际字号**，
|
||
真正生效的是 `.text-*` 工具类，且在小屏还有一组覆盖：
|
||
|
||
| 类 | 桌面 | 小屏（≤600px） | 典型用途 |
|
||
| --- | --- | --- | --- |
|
||
| `.text-xs` | **13 / 20** | 12 / 16 | 标签、元信息 |
|
||
| `.text-sm` | **14 / 22** | — | 正文（侧栏简介） |
|
||
| `.text-md` | **16 / 24** | 15 / 24 | 正文、条目摘要 |
|
||
| `.text-lg` | **18 / 26** | — | 条目标题、卡片标题 |
|
||
| `body` | **16 / 24** | — | 全局 |
|
||
|
||
`.item-badge` 是 12 / 14.4（700 字重），标签 `.tags-list a` 是 13 / 20。
|
||
|
||
我们的处理：把 `--su-font-size-*` 改成 12 / 13 / 14 / 18 / 24，行高 16 / 20 / 22 / 26 / 32；
|
||
组件内文字只用到 `sm 13`（标签）、`md 14`（控件）、`lg 18`（图标），
|
||
`xs 12` 给角标。**基础字号仍是 14**（见 §10 的保留差异）。
|
||
|
||
## 5. 布局
|
||
|
||
| 项 | 参考站实测 | 说明 |
|
||
| --- | --- | --- |
|
||
| 容器 | 1320 宽，居中，左右 60 | 对应 `--layout-max-width` 一类变量 |
|
||
| 三栏 | 左 330 / 中 660 / 右 330（gutter 24） | `col-xl-3 / col-xl-6 / col-xl-3` |
|
||
| 顶栏 | 80 高，透明叠在渐变背景上 | 导航项 48 高、字号 16 |
|
||
| 内容起始 | y=112（顶栏 80 + 32） | 卡片与顶栏留 32 的呼吸 |
|
||
| 卡片内边距 | `40px 24px`（侧栏 widget） / `12px`（缩略图卡片） | 竖向留白明显大于横向 |
|
||
| 缩略图 | 3 列，间距 8，圆角 8 | 图集区块 |
|
||
|
||
这些是**页面级**参数，不进组件库；卡片的内边距档位（12 / 20 / 24）继续由 `Card padding` 管。
|
||
|
||
## 6. 组件实测（对齐依据）
|
||
|
||
| 组件 | 参考站选择器 | 实测关键值 | 我们的对应 |
|
||
| --- | --- | --- | --- |
|
||
| 卡片 | `.box-block` | `#fff`、radius 12、`1px solid gray-1`、shadow `0 6px 16px 1%`、padding `40/24`、过渡 opacity/transform .3s | `Card` |
|
||
| 缩略图卡 | `.item` | `#fff`、radius 12、同款描边与阴影、padding 0（内容 12） | `Card padding="none"` |
|
||
| 标签 | `.tags-list li a` | 高 24、`13/20`、radius 30、`gray-1` 底、`gray-6` 字、左侧 20×15 图标、hover 字色变 `gray-8`；hot 变体是 `rgba(255,94,68,.1)` 底 + 红字 | `Tag`（soft / solid / icon / dot） |
|
||
| 状态角标 | `.item-badge` | `12/14.4`、700、padding `2px 4px`、radius 4、白字、红/橙渐变底 | `ItemBadge`（本轮新增） |
|
||
| 数字角标 | `.btn-icon small` | 12px、padding `2px 5px`、radius 10、红底白字 | `Badge`（18 高） |
|
||
| 头像 | `.flex-avatar` + `.avatar-badge` | 96 / 40 / 20 三档；角标是 SVG 渐变对勾，尺寸 12 / 16 / 20 | `Avatar`（24/36/48 + 16/20 角标） |
|
||
| 图标按钮 | `.btn-icon` | 圆形，默认 42（变体 28 / 36 / 44），图标字号 16 / 20 / 24，无阴影 | `IconButton`（本轮改为圆形 28/36/44） |
|
||
| 按钮 | `.btn` / `.btn-rounded` | radius 6 / 32、padding `8px 20px`、字号 14、`transition all .3s`、`primary:hover` 是 **opacity .8** | `Button`（新增 `shape="pill"`，hover 用 opacity） |
|
||
| 输入框 | `.form-control` | 高 36、radius 6、padding `8px 14px`、`1px solid gray-3`、focus 换主色边框、无阴影 | `Input`（描边改 `gray-3`，focus 主色） |
|
||
| 图片悬浮 | `.custom-hover` / `.hover-content` | 图片 `scale(1.1) rotate(2deg)`；遮罩 `rgba(0,0,0,.65)` 淡入、图标上移 10px | 组合模式（见 COMPONENTS.md §4） |
|
||
| 分页 | `.page-numbers` | 32×32、radius 4、`gray-2` 底、当前项主色底白字 | 规划中（P3） |
|
||
| 弹层 | `.nice-tips` | 遮罩 `rgba(0,0,0,.6)`、内容 radius 12、padding 28、`translateY(-40px)→0 .3s` | 规划中（P3 Modal） |
|
||
| 滚动工具条 | `.scroll-toolbar` | `position:fixed; right:30; bottom:50%`，内部是 42px 圆形按钮 | `ScrollTop` |
|
||
|
||
## 7. 交互语言
|
||
|
||
| 行为 | 参考站做法 | 我们的做法 |
|
||
| --- | --- | --- |
|
||
| 颜色 / 背景过渡 | `all .3s ease-in-out`（部分图标 `color .3s`） | 具体属性 + `--su-duration-base` + `--su-ease-in-out` |
|
||
| 主按钮 hover | `opacity: .8`（不改色） | ✅ 一致（primary / danger） |
|
||
| 次要按钮 hover | 换 `gray-3` 底 | ✅ 一致 |
|
||
| 图标按钮 hover | 轻微底色 + 文字加深，无阴影 | ✅ 一致 |
|
||
| 卡片 hover | 部分列表 `translateY(-5px) scale(1.01)`；`hoverable` 只加深阴影 | 组件层只做阴影加深，位移留给页面（避免列表抖动） |
|
||
| 图片 hover | 图片放大 1.1 + 旋转 2°，遮罩淡入 | 组合模式，不做进组件 |
|
||
| 焦点 | 把 Bootstrap 的 `box-shadow` 去掉了（`box-shadow:none`） | **反着做**：补 2px 主色 focus ring（a11y 要求） |
|
||
| 减少动效 | 用 `@media (not (prefers-reduced-motion))` 包裹动画 | ✅ 每个带动效的组件都有 `prefers-reduced-motion` 分支 |
|
||
| 禁用 | 换浅底 + 弱文字（不是整体透明） | ✅ 一致（`bg-subtle` + `text-muted`） |
|
||
| 加载 | `.btn.loading` 浅底 + `cursor: wait` + `pointer-events:none` | `loading` 自动 disabled + spinner + `aria-busy` |
|
||
|
||
## 8. 暗色方案（参考站已支持，我们留接口）
|
||
|
||
参考站用 `body[data-scheme="dark|auto"]` 覆盖整套变量，灰阶整体反相：
|
||
|
||
```css
|
||
body[data-scheme=dark] {
|
||
--gray-1:#f7f8fa; --gray-2:#f2f3f5; --gray-3:#e5e6eb; --gray-4:#c9cdd4;
|
||
--gray-5:#494949; --gray-6:#303030; --gray-7:#202022; --gray-8:#0f0f11;
|
||
--color-text:var(--gray-1); --color-secondary:var(--gray-2);
|
||
--color-muted:var(--gray-4); --color-light:var(--gray-3);
|
||
--bg-body:var(--black); --bg-dark:var(--gray-8); --bg-secondary:var(--gray-7);
|
||
}
|
||
```
|
||
|
||
要点：**语义变量跟着翻转，灰阶保持不变**——所以组件只要引用语义令牌就自动适配。
|
||
我们的 `--su-*` 结构相同，后续加一份 `[data-scheme='dark']` 覆盖即可；
|
||
仍有少量组件直接用了 `--su-gray-*`（Button secondary、Tag neutral、IconButton hover），
|
||
深色主题落地时要把这些改成 `--su-bg-subtle` / `--su-bg-hover` 之类的语义令牌。
|
||
|
||
## 9. 本轮对齐清单
|
||
|
||
**令牌**（[tokens.css](../src/theme/tokens.css)）
|
||
|
||
- 阴影 2%/6% → **1%/3%**，补 `0 … 0` 的位置参数；
|
||
- 字阶 10/12/14/16 → **12/13/14/18**，行高 16/20/22/26；
|
||
- 新增：`--su-color-orange-dark/light`、`--su-gradient-hot/paid/red`、`--su-text-secondary`、
|
||
`--su-bg-subtle`、`--su-card-border`、`--su-ease-in-out`、`--su-focus-ring(-offset)`；
|
||
- 控件高度：`sm 28→32`；图标按钮 `24/32 → 28/36/44`。
|
||
|
||
**组件**
|
||
|
||
| 组件 | 变更 |
|
||
| --- | --- |
|
||
| `Button` | 新增 `shape="pill"`；hover 改 opacity .8；禁用改浅底弱字；补 focus ring；补 reduced-motion |
|
||
| `IconButton` | 改圆形，尺寸 `xs/sm/md = 28/36/44`，图标 16/20/24；补 focus ring |
|
||
| `Card` | 描边改 `--su-card-border`（gray-1），阴影用新令牌 |
|
||
| `Tag` | 重写：默认 `neutral` 浅底胶囊 24 高 13px；新增 `variant="solid"`、`icon`、`dot`；保留 `shape="rounded"` 做元信息前缀 |
|
||
| `Badge` | 高度 16→18，字号 10→12 |
|
||
| `Input` | 描边 `gray-3`；focus 主色边框 + 键盘 focus ring（`:has(:focus-visible)`） |
|
||
| `Avatar` | `lg` 认证角标 18→20，对齐参考站三档 |
|
||
| `ScrollTop` | 过渡改 `ease-in-out`，补 focus ring |
|
||
| `ItemBadge` | **新增**：置顶 / 付费 / HOT / 草稿 状态角标 |
|
||
|
||
**展示页**：Buttons 补「形状」与图标按钮三档；Marks 重构为「浅底 / 实底 / 状态角标 / 数字角标 / 组合」；
|
||
组合示例的卡片标题加入 `ItemBadge`。
|
||
|
||
## 10. 保留的差异（有意为之）
|
||
|
||
| 差异 | 参考站 | 我们 | 原因 |
|
||
| --- | --- | --- | --- |
|
||
| 基础字号 | body 16/24 | 14/22 | 这是本地工具的控制台，不是阅读型博客；14 更紧凑。内容页（文章正文）建议用 16 |
|
||
| 卡片内边距 | `40px 24px` | 12 / 20 / 24 档位 | 参考站的竖向留白是为 widget 设计的，工具里太松 |
|
||
| 标签图标 | 每个标签强制带 20×15 图标 | 可选 `icon` | 图标是主题的分类素材，通用组件不该强绑 |
|
||
| Bootstrap 组件 | 下拉、模态、分页都用 BS | 自己实现（规划中） | 不引 CSS 框架，避免 200KB+ 和样式覆盖战 |
|
||
| hover 位移 | 部分列表卡片抬升 5px | 组件不做位移 | 列表里位移会造成抖动；需要时页面自己加 |
|
||
| 动画时长 | 全站 `all .3s` | 按属性、默认 .3s | `all` 会把布局属性也带上，性能差 |
|
||
|
||
## 11. 生产标准补充（参考站没有的）
|
||
|
||
参考站是展示型主题，下面这些是我们作为组件库必须补的：
|
||
|
||
- **focus-visible**：所有可交互组件补 2px 主色焦点环（参考站把焦点样式删了）；
|
||
- **reduced-motion**：`Button` / `IconButton` / `Card` / `Input` / `ScrollTop` 都有降级分支；
|
||
- **disabled 语义**：`Button` 用真实 `disabled`，`loading` 同时 `aria-busy`；
|
||
- **图标按钮 label 必填**：`IconButton.label` 是必填 prop，防呆；
|
||
- **错误提示 `role="alert"`**、`Empty` 与 `Notice` 分工（§COMPONENTS）；
|
||
- **键盘可达**：`ScrollTop` 隐藏时 `tabIndex=-1`；Input 清除按钮是真实 `button`；
|
||
- **令牌约束**：组件 CSS 里没有裸色值（`DESIGN.md` §1 硬约束）。
|
||
|
||
## 12. 后续对齐项
|
||
|
||
1. ~~**暗色主题**~~：已完成（`data-scheme="dark|auto"`，见 DESIGN §7）；
|
||
2. **ScrollTop → 滚动工具条**：参考站是「点赞 / 收藏 / 回到顶部」三键竖排，等有收藏功能再做；
|
||
3. **图片悬浮遮罩**：抽成组合模式（`Card hoverable` + 遮罩层），配合未来的 `Image` 组件；
|
||
4. **分页 / 弹层**：按 COMPONENTS.md §5 的 P3 优先级补。
|