feat: stash-ui 0.1.0（40 个组件 + 文档站 + 主题机制）
This commit is contained in:
stash
@@ -0,0 +1,82 @@
|
||||
---
|
||||
name: stash-ui
|
||||
description: Use, extend, or restyle the Stash UI component library (@stash/ui): a zero-dependency React design system with tokens, 37 components, an in-repo docs site and a full-page demo. Load before writing or changing any component, or before composing pages with @stash/ui.
|
||||
---
|
||||
|
||||
# Stash UI
|
||||
|
||||
这是一套独立的设计系统（React + CSS Modules + 设计令牌），零运行时依赖。
|
||||
文档是唯一事实来源，这个 skill 只做「入口 + 硬约束 + 验证流程」，**不要把它当成文档的副本**。
|
||||
|
||||
## 先读哪几份
|
||||
|
||||
按任务选读，不必全读：
|
||||
|
||||
| 文档 | 什么时候读 |
|
||||
| --- | --- |
|
||||
| `DESIGN.md` | 任何改动前：分层、令牌、状态矩阵、代码约定、验收清单 |
|
||||
| `docs/COMPONENTS.md` | 想用组件 / 判断有没有 / 看契约 / 看候选清单 |
|
||||
| `docs/ADDING-A-COMPONENT.md` | 要新增组件时，照 12 步走 |
|
||||
| `docs/ALRIGHT-DECOMPOSITION.md` | 怀疑某个数值（字号、阴影、间距）对不对时 |
|
||||
| `site/demo.html` 的源码 | 想看真实页面怎么把组件拼起来 |
|
||||
|
||||
## 三种任务
|
||||
|
||||
### A. 用组件拼页面
|
||||
|
||||
1. 先查 `COMPONENTS.md §2「用哪个」`决策表；能用现有组件组合就不要新增组件。
|
||||
2. 颜色 / 间距 / 字号 / 圆角只用 `--su-*` 令牌；页面自己的布局样式写页面级 CSS Module。
|
||||
3. 深色主题靠 `<html data-scheme="dark|auto">`，**页面和组件都不用改**。
|
||||
4. 常见组合（分区卡片、行式条目、工具条、海报卡）见 `COMPONENTS.md §4`。
|
||||
5. 页面外壳用 `Layout`（header / sider / children / footer），不要自己写一套 div 骨架。
|
||||
|
||||
### B. 改组件
|
||||
|
||||
1. 先看现有契约（`COMPONENTS.md §3`）。**改 props = 改契约**，必须同步三处：
|
||||
组件代码、展示页 section、`COMPONENTS.md` + README 组件表。
|
||||
2. 只用语义令牌（`bg-card` / `bg-subtle` / `bg-hover` / `text-*` / `border-*`）；
|
||||
不要直接用 `--su-gray-*`——灰阶在深色下是反相的。
|
||||
3. 状态要对齐 `DESIGN.md §4.3`：默认 / hover / active / disabled / loading /
|
||||
focus-visible / 空 / 错误。
|
||||
4. 改完跑下面的验证命令，并截图核对（含深色）。
|
||||
|
||||
### C. 加组件
|
||||
|
||||
严格按 `docs/ADDING-A-COMPONENT.md`：
|
||||
|
||||
```text
|
||||
登记(COMPONENTS §1 + §3 草稿) → 定层级/API → Xxx.tsx → Xxx.module.css
|
||||
→ src/index.ts 导出 → site/sections 展示页 → site/App.tsx 导航
|
||||
→ README 清单 → 契约定稿 → 验收清单 → 截图 → 提交
|
||||
```
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
npm run dev # 文档站 5199；整页示例 /demo.html（?scheme=dark）
|
||||
npm run typecheck # tsc --noEmit
|
||||
npm run lint # oxlint（要求 0 warnings）
|
||||
npm run build # 库产物 dist/stash-ui.js + .css + types
|
||||
npm run build:site # 静态站点 dist-site（index.html + demo.html）
|
||||
|
||||
# 视觉核对：需要本机 Chrome / Edge
|
||||
node scripts/screenshot.mjs http://127.0.0.1:5199/#buttons shots/buttons.png
|
||||
node scripts/screenshot.mjs http://127.0.0.1:5199/demo.html shots/demo.png full
|
||||
```
|
||||
|
||||
## 硬约束（违反就不合并）
|
||||
|
||||
- 组件 CSS 里禁止 hex / rgba / 字号 / 间距字面量；允许的只有 `0`、`1px` 边框、`100%`、
|
||||
以及组件内声明的 `--xxx-size` 尺寸变量。
|
||||
- `className` / `style` 落在外层元素；组件**不带 margin**，间距交给 `Space`。
|
||||
- 只有图标的控件必须传 `label`；错误提示 `role="alert"`；`focus-visible` 不得移除。
|
||||
- 不新增运行时依赖（只 peer 依赖 react / react-dom）。
|
||||
- 展示页的 demo 必须直接用真实组件，不写「演示专用版本」。
|
||||
- 组件不认识业务：不请求接口、不 import 业务类型、props 里不出现 `categoryId` 这类字段。
|
||||
|
||||
## 已知坑
|
||||
|
||||
- 比例封面不要放进 `flex-direction: column` 的父容器（行高会被压扁），用 grid / block。
|
||||
- 展示站 `site/main.tsx` 必须显式 import `tokens.css` 和 `iconfont.css`，否则生产构建会摇掉图标。
|
||||
- `<dialog>` 的居中被宿主 `* { margin: 0 }` 覆盖过，Modal / Drawer 里已显式写回 `margin`。
|
||||
- 图标名来自全量 iconfont（446 个，`src/theme/icons.ts`），新增字形要走 `COMPONENTS.md §7` 的流程。
|
||||
Reference in New Issue
Block a user