UI 规范补上标签章节与 React 量法:§2 写清两族胶囊的分工、--tag-* 两档挂在容器上、TagGroup 的 6px/12px、min-height 与 font-size 两个 tailwind-merge 陷阱;§3 补 Field hint 的栅格写法与「一个容器只有一个 --ctl-h 档位」;§0.5 对照表按真实签名重写并登记已废弃的英文眉标;§1.3/§8 换成 React 时代的四条探针
parent
7fcfd2932b
commit
34f8862cfe
157
docs/UI规范.md
157
docs/UI规范.md
|
|
@ -26,7 +26,7 @@
|
|||
| R1 | **能一行的不许两行**:同一功能组的标签 + 控件 + 按钮必须同一行;只有放不下时才由浏览器换行 | 图1「深度思考 / 单步超时」两个下拉各占一行;图4「模型」独占整行 |
|
||||
| R2 | **控件栏里的标签一律写在控件左边**(`.fld`),不允许「标签在上、控件在下」的列方向写法 | 图3 筛选栏每个筛选项都多出一行标签高度 |
|
||||
| R3 | **同一行控件必须等高、垂直居中**(`align-items:center` + 继承 `--ctl-h`);一行里出现两种高度 = 尺子坏了 | 图3 搜索框与右侧下拉中心线错开 |
|
||||
| R4 | **chip / 标签行与下方内容至少 10px 间隔**(`.chipbar`),且标签行本身不参与贴边 | 图2 「标签」chip 行压住下方面板 |
|
||||
| R4 | **chip 行 / 标签行与下方内容至少 12px 间隔**(`ChipBar` 与 `TagGroup` 自带 `mb-3`),且行本身不参与贴边 | 图2 「标签」chip 行压住下方面板 |
|
||||
| R5 | **筛选项准入**:每个筛选项必须 ① 对应后端真实参数 ② 在当前设计里有可达的非默认值 ③ 与页面顶部已选的大分类一致。三者缺一就删 | 图3 「每页」属于分页条,不属于筛选栏 |
|
||||
| R6 | **不用原生 `<select>`**:单选 `Select`、多选 `MultiSelect`(`components/forms`);自动刷新类组件不放「立即刷新」按钮 | 全站历史问题 |
|
||||
|
||||
|
|
@ -45,7 +45,8 @@
|
|||
| `.fld`(标签在左、控件在右) | `<Field label required width="default\|grow\|narrow\|wide\|full" hint>` | `ui/Controls.tsx` |
|
||||
| 标签在上的字段(`.field` + `.lbl` + `.req`) | `<FieldBlock label required title>`,星号是 `<Req>` | `ui/Controls.tsx` |
|
||||
| `.frow cols3 stack tight segfields` | `<FormRow cols={3} stack tight>` | `ui/Controls.tsx` |
|
||||
| `.chipbar` / `.chipbar-label` / `.tag-chip` | `<ChipBar label>` + `<Chip>` / `<TagChip count on>` | `ui/Controls.tsx` |
|
||||
| `.chipbar` / `.chipbar-label`(**可点** chip 行)| `<ChipBar label top>` + `<Chip active size="sm\|md">` / `<TagChip onRemove removeTitle>`(可移除的选中态胶囊)| `ui/Controls.tsx` |
|
||||
| `.tag` / `.tag.ok` / `.tag.bad`…(**只读**标签)| `<Tag tone size icon>` · `<Status value>`(状态枚举)· `<Badge>`(计数)· `<TagGroup label size top>`(成排标签的间距)· `TAG_DENSE`(挂在容器上整片降档)| `ui/Status.tsx` |
|
||||
| `.view-btn` 分段视图切换 | `<ViewBtn on>` | `ui/Tabs.tsx` |
|
||||
| `.pager` | `<Pager sizes total pageSize onChange>`(`0` = 全部) | `ui/Controls.tsx` |
|
||||
| `.check` | `<Check checked onChange disabled title>` | `ui/Controls.tsx` |
|
||||
|
|
@ -54,12 +55,12 @@
|
|||
| `.primary` `.secondary` `.outline` `.ghost` `.tiny` `.danger` | `<Button variant size="sm\|md\|lg" danger on>` | `ui/Button.tsx` |
|
||||
| `.btn-add` `.btn-del` `.btn-del.solid` `.sq` `.lg` | `<Button variant="add">` / `variant="del"` / `variant="del" danger` / `square` / `size="lg"` | `ui/Button.tsx` |
|
||||
| `<a>` 要按钮皮肤(路由跳转) | `buttonCls({ variant })` 或 `<Button variant="link">` | `ui/Button.tsx` |
|
||||
| `.tag` `.tag.ok/.warn/…` | `<Tag tone="default\|ok\|bad\|warn\|info\|accent\|mono">` | `ui/Status.tsx` |
|
||||
| `.linehint` | `<LineHint>`(成行告警);空内容不渲染的用 `<Notice>` / `<ErrorText>` | `ui/Panel.tsx` · `ui/Page.tsx` |
|
||||
| `.drawer` `.drawer-backdrop` `.drawer-x` `.drawer-actions` | `<Drawer title sub eyebrow actions width>`(`actions` 就是外壳直接子元素那一层) | `ui/Overlay.tsx` |
|
||||
| 对话框 / `.modal` | `<Modal title eyebrow footer width>` | `ui/Overlay.tsx` |
|
||||
| `.drawer` `.drawer-backdrop` `.drawer-x` `.drawer-actions` | `<Drawer open onClose title sub actions width>`(`actions` 就是外壳直接子元素那一层)| `ui/Overlay.tsx` |
|
||||
| 对话框 / `.modal` | `<Modal open onClose title footer width>` | `ui/Overlay.tsx` |
|
||||
| 白屏 / 整页崩了(老站没有这一层,崩了就直接白屏) | `<ErrorBoundary>` 已在 `app/App.tsx` 包住两处 `<Suspense>`,页面**不要**自己再写 try/catch 或错误页 | `app/ErrorBoundary.tsx` |
|
||||
| `.small-label` + `.sect-act` | `<SectionTitle action>` / `<PanelHead right eyebrow sub>` | `ui/Panel.tsx` |
|
||||
| `.small-label` + `.sect-act` | `<SectionTitle action>` / `<PanelHead right sub>` | `ui/Panel.tsx` |
|
||||
| **中英并列的「英文眉标 + 中文标题」双层**(旧 `.eyebrow` / `.small-label` 前缀)| **已废弃**:标题只写一层中文,`Drawer` / `Modal` / `PanelHead` / `SectionTitle` 都没有 `eyebrow` 这个 prop,别把英文小标当装饰补回来 | — |
|
||||
| `v-if` / `v-show` | `{cond && <X />}` / `hidden`(条件挂载本身要保留,见 G2) | JSX |
|
||||
| `v-model.number="filters.page_size"` | `value={…}` + `onChange={(next) => …}` | 受控组件 |
|
||||
| `:deep(.aplay){min-width:110px}` | 传 `className`(`cn` 走 tailwind-merge,**后写的赢**)或容器上的任意变体 `[&>*]:min-w-[110px]` | `lib/cn.ts` |
|
||||
|
|
@ -209,34 +210,117 @@
|
|||
**复合选择器**,两条豁免同时失效,54 条镜头卡正文连报两轮。
|
||||
验法:挑一个**已知应当被豁免**的元素,先断言 `el.closest(DATA)` 为真,再看它是否仍进结果集。
|
||||
只看「总条数变少」发现不了整段白名单没生效 —— 报 61 条里有 54 条是探针自己造成的。
|
||||
- **React 时代的量法(`/tmp/nex_ctl.py`)**:不再靠类名认容器,改按计算样式判档。
|
||||
控件的档位取 `getComputedStyle(parentElement)['--ctl-h']`,实测高与档位差 > 0.6px 报红
|
||||
(textarea 只报「比档位矮」,它本来就该被 `TEXTAREA_TALL` 撑高)。档位只有两档,
|
||||
且**由容器自带**:`Ctlbar` / `ChipBar` / `CardActions` / `Pager` = 31px,
|
||||
`FormRow` / `FieldBlock` = 38px,根节点默认 38px。
|
||||
行内字段的「最小宽度」不是令牌而是 `FormRow` 的栅格轨道(auto-fit `minmax(190px,1fr)`、
|
||||
`cols={6}` 时 `minmax(78px,1fr)`),`Field` 的 `width` 只给 `basis`
|
||||
(narrow 122 / default 170 / grow 240 / wide 330 且封顶 58%)。
|
||||
**轨道窄于 190px 时标签与控件必然折行** —— 把成组筛选项塞进 `<PanelHead right>` 就是踩这个坑,见 §3 末条。
|
||||
|
||||
---
|
||||
|
||||
## 2. chip 行 / 标签行 / 视图切换
|
||||
|
||||
`.chipbar`(旧类 `.chips .tagrow .capsline .views` 归入同一语义):
|
||||
### 2.0 两族胶囊,先分清再谈样式
|
||||
|
||||
```html
|
||||
<div class="chipbar">
|
||||
<span class="chipbar-label">标签</span>
|
||||
<button class="tag-chip on">全部</button>
|
||||
<button class="tag-chip">夜景<em>12</em></button>
|
||||
<button class="tag-chip clear">✕ 清除全部筛选</button>
|
||||
</div>
|
||||
| 族 | 装什么 | 高度 | 唯一实现 |
|
||||
|---|---|---|---|
|
||||
| **chip(可点)** | 筛选开关、视图切换、多选回显 | 31px(`--ctl-h-md`) | `Chip` / `TagChip` / `ChipBar` |
|
||||
| **tag(只读)** | 「它是什么」「到哪了」「几个」 | 20px 或 18px(`--tag-*` 两档) | `Tag` / `Status` / `Badge` / `TagGroup` |
|
||||
|
||||
判据只有一句:**点下去有反应的才是 chip,只给眼睛看的必须是 Tag**。
|
||||
整改前最刺眼的两处不统一都在这里:只读回显借了 `Chip` 的皮肤(`as="span"`),
|
||||
于是同一行里 31px 的假标签和 20px 的真标签并排;`Tag` / `Status` / `Badge` 又各有
|
||||
自己一套 `padding` 与行高,混排必然差 2~3px。现在:
|
||||
|
||||
- `Tag` / `Status` / `Badge` 共用同一个壳(`SHELL`)+ 同一张色板(`TONES`),
|
||||
`Status` 只剩「后端状态枚举 → 色调」这一层映射;**别再新增第四种标签组件**。
|
||||
- `Chip` 的 `as="span"` 只留一个例外:文件选择旁边「已选 xxx.mp3」这种**跟同排可点
|
||||
chip 成组**的回显(全站现状:只剩时间轴「选择音频文件」一处)。跟标签成组的一律
|
||||
`Tag` / `TagGroup`——调度中心页头的队列计数、总控台的镜头状态计数都从这里改了出去。
|
||||
- **同一行只允许一种胶囊高度。** 只读 Tag 与可点 Chip 必须同行时,给 `Chip` 传
|
||||
`size="sm"`(它取的就是 `--tag-*` 令牌,不在这儿重复数字)。
|
||||
方角 `Button`(31/38px)不是胶囊,与标签同行不算违规。
|
||||
|
||||
分工记牢:`Tag` 名词(「竖屏」「已锁定」)· `Status` 状态枚举 · `Badge` 计数气泡 ·
|
||||
`Chip` 可点筛选 · `TagChip` 可移除的选中态胶囊。
|
||||
|
||||
### 2.1 尺寸:两档令牌挂在容器上,不写在标签上
|
||||
|
||||
```css
|
||||
/* styles/tokens.css —— 与 --ctl-h 同一套规矩 */
|
||||
--tag-h-main: 20px; --tag-px-main: 7px; --tag-gap-main: 5px; --tag-text-main: 11px;
|
||||
--tag-h-sm: 18px; --tag-px-sm: 6px; --tag-gap-sm: 4px; --tag-text-sm: 10px;
|
||||
--tag-h: var(--tag-h-main); /* --tag-px / --tag-gap / --tag-text 同理指向 main */
|
||||
```
|
||||
|
||||
- 高度 31px(`.tag-chip`/`.chip` 已定高);**页面内不得再给 chip 写 `padding`/`min-height` 覆盖**,
|
||||
尺寸只有一个来源(`Chip` / `TagChip` 原语 + 容器 `--ctl-h` 档)。
|
||||
- `margin:0 0 12px`(与下方网格/面板的呼吸),行首标签用 `.chipbar-label`(不要裸 `<span>`)。
|
||||
- 上方是**媒体预览 / 音频条**这类自带高度的块时,加 `.chipbar top`(`margin-top:12px`),
|
||||
不要在 markup 上写 `style="margin-top:…"`。
|
||||
- 老的 `.chips` 只允许作为**皮肤别名**与 `.chipbar` 同时出现(`class="chipbar chips"`),
|
||||
单独一个 `.chips` 没有下边距,就是图2「chip 行压住面板」的根因;
|
||||
页面 CSS 里不得再定义 `.chips{…}`/`.chip{padding…}`。
|
||||
- 选中态:实心 accent;带计数用 `<em>`;「清除全部筛选」只在真有筛选时出现。
|
||||
- 视图切换(网格/列表/素材墙)用 `.views` + `.view-btn`,与筛选栏同一行时放进 `.ctlbar` 的右侧。
|
||||
**档位由容器声明,标签自己不知道自己在哪**:`<TagGroup size="sm">`、`TAG_DENSE`
|
||||
(挂在任意容器上)、`<Table>`(自带 `[&_td]:[--tag-*:sm]`)一挂,那片标签一起降档,
|
||||
往密集区域里加标签的人不必再记一遍尺寸。只有**单个**标签要降档才写 `size="sm"`。
|
||||
两档只差高度/内边距/间隙/字号,圆角、边框、行高完全相同,混排仍然同形。
|
||||
sm 档给密度高的地方:表格单元格、缩略图角标、一行挤五六个的元信息行。
|
||||
现状(`/tmp/nex_tag.py` 逐路由实测):全站 399 个可见标签,高度只有 18px(265 个)与
|
||||
20px(134 个)两个值,度量组合只有 `(18,10px,6px)`、`(20,11px,7px)` 和 Badge 的
|
||||
`(20,11px,7px,圆角999)` —— 越档 0、文字截断 0、组内间距过紧 0。
|
||||
|
||||
探针:`CHIPBAR-GAP`(chip 行下边到下一块 < 8px 判红)、`TINY-FONT`(chip 文字 < 10px)。
|
||||
壳只有一份(`ui/Status.tsx` 的 `SHELL`),两条容易踩的坑就写在它的注释里:
|
||||
|
||||
- **高度只由 `min-height` 决定,不写 `padding-block`**:写了 padding,字号一变高度跟着变,
|
||||
又回到「三套高度」。
|
||||
- **字号必须写 `[font-size:var(--tag-text)]`,不能写 `text-(length:--tag-text)`**:
|
||||
tailwind-merge 认为「带任意值的 `text-*`」可能同时携带行高,会把同串的 `leading-[1.45]`
|
||||
判成冲突吃掉(DOM 里行高莫名消失就是这么来的)。
|
||||
|
||||
色板:`default`(中性名词)/ `ok` / `bad` / `warn` / `info` / `accent` / `mono`(等宽,
|
||||
给 ID、版本、计数)。色调只给真有语义的字段,别拿 `accent` 当装饰。
|
||||
|
||||
### 2.2 成排标签用 `TagGroup`:组内 6px、组与下方 12px
|
||||
|
||||
页面上手抄的 `flex flex-wrap gap-1` 有两种病,就是「标签行间距」的根因:
|
||||
|
||||
1. `gap-1`(4px)比标签自己的左右内边距(6~7px)还小,两个标签读起来像一个词被劈开;
|
||||
2. 没有下边距,标签行直接贴住下面的面板/网格 —— 违反 R4。
|
||||
|
||||
`<TagGroup>` 把「组内 `gap-[6px]`、组下 `mb-3`(12px)」定死;行首说明文字用 `label`
|
||||
(与 `ChipBar` 的 label 同一套字级),上方需要呼吸时给 `top`,整片降档用 `size="sm"`。
|
||||
**嵌在卡片里**不想要那 12px 时用 `className="mb-0"` 覆盖,不要另起一个 flex 容器。
|
||||
`ChipBar` 装可点、`TagGroup` 装只读,两者不混装。
|
||||
|
||||
### 2.3 chip 行(`.chipbar`,旧类 `.chips .tagrow .capsline` 归入同一语义)
|
||||
|
||||
```tsx
|
||||
<ChipBar label="标签">
|
||||
<Chip active>全部</Chip>
|
||||
<Chip onClick={pick}>夜景</Chip>
|
||||
<Chip onClick={clear}>✕ 清除全部筛选</Chip>
|
||||
</ChipBar>
|
||||
```
|
||||
|
||||
- 高度 31px(`Chip` / `TagChip` 定高,容器自带 `[--ctl-h:var(--ctl-h-md)]`);
|
||||
**页面内不得再给 chip 写 `padding` / `min-height` 覆盖**,尺寸只有一个来源。
|
||||
- 自带 `mb-3`(12px)与下方网格/面板呼吸;行首标签用 `label`,不要裸 `<span>`。
|
||||
- 上方是**媒体预览 / 音频条**这类自带高度的块时加 `top`(`margin-top:12px`),
|
||||
不要在 JSX 上写 `style={{ marginTop: … }}`。
|
||||
- 计数写在 chip 自己的文字里(旧站 `.tag-chip em`),**别往 chip 行里塞 `<Badge>`**:
|
||||
20px 标签混进 31px 胶囊行,就是 §2.0 那条禁令的现场;「清除全部筛选」只在真有筛选时出现。
|
||||
- 旧站页面级 `.chips{…}` / `.chip{padding…}` 已随旧 CSS 删除,新页面也不许再抄。
|
||||
- 整句话的说明(「当前音源:xxx,未上传时…」)**不要做成会折行的 Tag**,
|
||||
用 `<LineHint>`:胶囊一旦装下一句话,就必然出现「同一行两种胶囊高度」。
|
||||
|
||||
### 2.4 视图切换
|
||||
|
||||
网格 / 列表 / 素材墙用 `<ViewBtn on>`(`ui/Tabs.tsx`);与筛选栏同一行时放进 `<BarRight>`,
|
||||
单独成行时属于 chip 行那一族,不要混进 `TagGroup`。
|
||||
|
||||
探针:`/tmp/nex_tag.py` 逐路由量标签高度/字号/左右内边距/圆角,报越档与文字截断,
|
||||
并量标签行的 `gap` / `margin-bottom` / 与下方块的实际净距。标签判据 = class 含
|
||||
`leading-[1.45]` + `align-middle`(`SHELL` 的唯一出处),chip 判据 = `h-(--ctl-h-md)`,
|
||||
同一行出现两种胶囊高度报 `MIX-H`。两类**已知可接受**:`MIX-H` 报的是
|
||||
「Tag + 方角 Button」的(按钮不是胶囊);标签行「距下」为负的是右侧横排兄弟(假阳性)。
|
||||
`TINY-FONT`(chip 文字 < 10px)照旧。
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -282,6 +366,19 @@
|
|||
旧站那条全局兜底 `label:has(> .req)` 已经随旧 CSS 一起删掉了,**写错没人兜**。
|
||||
- 说明文字走 `<Field hint="…">`(贴在字段下面)或 `<LineHint>`(成行告警),
|
||||
配色 `text-muted` / `text-faint`,**不超过一行**;超出的解释进手册(`/help` → `frontend/src/pages/Help.tsx`)或 `title` 提示。
|
||||
规则说明以前塞在 `placeholder` 里(改密码页「至少 8 位,包含…」),一开始输入说明就消失了。
|
||||
`hint` 现在真正落地:带 hint 的 `Field` 把自己翻成
|
||||
`grid grid-cols-[auto_minmax(0,1fr)]`,标签左上、控件右上、说明贴在控件下面。
|
||||
**这里不能用 `flex-wrap`**:base.css 里控件是 `w-full`,一换行控件就整只跑到第二行、
|
||||
标签退回上面,同一栅格里就成了「一个横排、两个竖排」(违反 R3)。
|
||||
配套两条在 `FormRow` 上:`[&>*]:self-start`(带 hint 的字段把行撑高后,旁边的字段仍贴格子
|
||||
顶端,不会被垂直居中错开半行);`stack` 前必须先补 `[&>*]:flex`,
|
||||
因为 grid 元素不认 `flex-direction`,少了它竖排会漏给带 hint 的字段。
|
||||
- **一个容器只有一个 `--ctl-h` 档位**:`FormRow` / `FieldBlock` 显式声明自己是主尺寸(38px),
|
||||
`Ctlbar` / `ChipBar` / `CardActions` / `Pager` 显式声明紧凑档(31px)。
|
||||
抽屉里的字段因此不会因为外面套了一层紧凑档工具条就整排缩水成 31px,
|
||||
工具条里的控件也不会因为祖先没声明就偷偷回弹到 38px。页面**不要**自己再写 `[--ctl-h:…]`,
|
||||
确实是例外就登记进 §1.2.1。
|
||||
- 抽屉:标题块与第一个字段之间 ≥ 12px,由 `<Drawer>` 滚动区自己的 padding(`20px 24px 24px`)提供,
|
||||
不要在内容第一块上补 `margin-top`;标题与紧随其后的分组标题不得共用一行
|
||||
(图4「AI 试听」与「模型」挤在一起)。
|
||||
|
|
@ -302,6 +399,10 @@
|
|||
只允许在**行内多列栅格**里这么降,整宽字段仍走 86px。
|
||||
- 栅格:`grid2/grid3/grid4`(`<Grid>`)只用于**等宽内容卡**;字段排布一律 `<FormRow>`,
|
||||
响应式由 `auto-fit` 自己降列,页面别写 `@media` 改列数。
|
||||
- **成组筛选项不许塞进 `<PanelHead right>`**:标题行右侧那块常常不足 300px,放两个 `Field`
|
||||
就低于 §1.3 说的 190px 栅格轨道,标签与下拉箭头被挤成两行(用户管理的筛选条就是这样,
|
||||
已挪回标题下方的 `<Ctlbar>`,右侧只留计数 `<Badge>`)。`PanelHead right` 只放**一个**
|
||||
计数或单个动作(G1)。
|
||||
|
||||
探针:`REQ-WRAP`(星号与标签文字 `top` 不同)、`HEAD-CROWD`(标题/分组标题与首控件垂直间距 < 8px)、
|
||||
`STACK-WIDE`(`.field` 之外出现的整宽单选/下拉)、`ROW-STACK`(`.ctlbar` 里出现 ≥ 容器 80% 宽的控件)。
|
||||
|
|
@ -538,6 +639,12 @@
|
|||
而 `BAR / CHIPBAR-GAP / BAR-GAP / STACK-WIDE` 靠 `.ctlbar/.chipbar/.fselect` 这些
|
||||
**旧 DOM 类名**认容器,新代码里只剩 Tailwind 工具类,它们会**漏报而不是误报**。
|
||||
别把「探针 0 项」当成合规证据——那几条要么改探针选择器,要么人工看一遍。
|
||||
React 时代的替代探针在 `/tmp`(不进 `scripts/`,它们只服务这一轮整改):
|
||||
`nex_ctl.py`(§1 控件几何:控件实测高 = 所在容器的 `--ctl-h` 档位)、
|
||||
`nex_tag.py`(§2 标签度量与间距)、`nex_audit1.py`(全路由控件/小标题取证)、
|
||||
`nex_d_shot.py`(整页截图 + console/pageerror 计数,改完必须目视一遍)。
|
||||
判据全部走计算样式与 Tailwind 工具类,不依赖旧类名;四者都要求
|
||||
**0 红项 + 0 console error**,红项按 §2.4 / §1.2.1 的例外清单逐条解释。
|
||||
6. 改了 `styles/tokens.css` 的令牌或 `styles/base.css` 的元素基线(含 `--ctl-h*`、媒体查询)→ 必须双主题全量重跑
|
||||
(深浅各 83 + 浮层 16 + 用户位 5 + 生成台 2 = 195 作业),不能只跑改动页。
|
||||
**窄屏(430px)也在回归宽度里**:只在 ≤560px 生效的规则必须有证据,不能靠推理。
|
||||
|
|
|
|||
Loading…
Reference in New Issue