@keyfunc/keybricks-ds 1.0.4 → 2.3.1

package/DEPLOY.md

@@ -55,11 +55,11 @@ deploys the documentation site. Watch it under *Build → Pipelines*.
 **5. Cut the first release.**
 
 ```bash
-git tag v1.0.4 && git push --tags
+git tag v2.3.1 && git push --tags
 ```
 
 That tag runs `generated:check` → `version:check` → `npm publish`. Confirm under *Deploy →
-Package Registry*: `@keyfunc/keybricks-ds` 1.0.4.
+Package Registry*: `@keyfunc/keybricks-ds` 2.3.1.
 
 **6. Hand developers two things:** the Pages URL, and the `.npmrc` snippet in §4 below.
 
@@ -90,13 +90,13 @@ and `npm pack` both produce it via the `prepack` hook; CI does it explicitly. Re
 is a normal committed file.
 
 Published (`files` in `package.json`): `components/`, `tokens/`, `assets/`, `_scripts/`,
-`styles.css`, the four `.md` guides, `_adherence.oxlintrc.json`.
+`styles.css`, `keybricks.css` (the `styles.css` export: tokens + `tokens/hover.css`), the four `.md` guides plus `readme.zh-CN.md`, `_adherence.oxlintrc.json`.
 
 > Installing from a **git tag** skips `prepack`, so `@keyfunc/keybricks-ds/vue` is absent in
 > that mode — Vue apps on a git dependency should deep-import
 > `@keyfunc/keybricks-ds/components/<group>/<Name>.vue`, which is the recommended path anyway.
 
-Not published: `guidelines/`, `ui_kits/`, `templates/`, `index.html`, `gallery.html`,
+Not published: `guidelines/`, `index.html`, `gallery.html`,
 `_ds_bundle.js`. Those are the documentation site — they go to Pages, not into every
 `node_modules`.
 
@@ -156,7 +156,7 @@ GitLab injects `CI_JOB_TOKEN` — use that instead and no secret is stored anywh
 **Install — straight from git** (no registry, no publish; works today)
 
 ```json
-"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v1.0.4"
+"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v2.3.1"
 ```
 
 Because the package has no build step, a git dependency needs no `prepare` script — npm
@@ -202,3 +202,12 @@ consuming app to fail CI on the two rules that break theming:
 
 Both are the same rule stated twice: components read the semantic layer, and only the
 semantic layer. That is what makes dark mode cost nothing.
+
+## Runtime checks
+
+`_tests/` holds browser pages that exercise the real components: `react-runtime.html` (the compiled
+bundle), `table-selection.html` (Table loaded from source: checkbox spacing at every width, code chips, two-line rows, sorting), `vue-runtime.html` (the `.vue` files, loaded with vue3-sfc-loader), `cards-interaction*.html`
+(clicks through the documentation demos) and `icon-rules.html` (the Keybricks glyphs against the drawing rules). Serve the repo root (`npx serve .`), open a page and read the
+console — every line starts with PASS or FAIL. Run them after changing a component in either framework.
+`measure-cards.html` is a tool, not a test: it measures each documentation page at its card width so the
+`viewport` sizes in the cards, `site-nav.js` and `gallery.html` can be kept in step.

package/DESIGN.md

@@ -33,7 +33,8 @@ One action hue. Color carries meaning; the interface itself is near-monochrome.
 | `--bg-app` | `#fafafa` | Page canvas behind panels |
 | `--bg-surface` | `#ffffff` | Cards, menus, table cells |
 | `--bg-raised` | `#ffffff` | Modals, drawers, popovers |
-| `--bg-inset` | `#fafafa` | Wells, table headers, code blocks |
+| `--bg-inset` | `#fafafa` | Wells, code blocks |
+| `--bg-table-header` | `#f5f5f5` | Table header row — one step below `--bg-app`, so it still reads when the table sits on a grey page |
 | `--bg-hover` | `#f5f5f5` | Row / item hover |
 | `--bg-active` | `#f5f5f5` | Selected nav pill, toggled control |
 | `--bg-press` | `#e5e5e5` | Press wash |
@@ -46,9 +47,9 @@ order (`app` → `surface` → `raised`) and depth reads correctly in both theme
 | Token | Light | Use |
 | --- | --- | --- |
 | `--text-primary` | `#0a0a0a` | Maximum emphasis |
-| `--text-heading` | `#171717` | Headings, table headers |
+| `--text-heading` | `#171717` | Headings |
 | `--text-body` | `#525252` | Default body text |
-| `--text-secondary` | `#737373` | Meta, labels, captions |
+| `--text-secondary` | `#737373` | Meta, labels, captions, table headers |
 | `--text-muted` | `#a1a1a1` | Placeholder, disabled glyph |
 | `--on-accent` | `#ffffff` | Text on any saturated fill — **both themes** |
 
@@ -57,7 +58,7 @@ order (`app` → `surface` → `raised`) and depth reads correctly in both theme
 | --- | --- | --- |
 | `--border-card` | `rgba(229,229,229,.6)` | Card hairline |
 | `--border-control` | `#e5e5e5` | Input / button edge |
-| `--border-subtle` | `#f5f5f5` | List and table dividers |
+| `--border-subtle` | `#f5f5f5` | List and table dividers — including the table header rule; a header is set apart by its `--bg-table-header` tint, never by a heavier line |
 | `--focus-border` | `#2b7fff` | Keyboard focus outline |
 
 ### Action
@@ -83,7 +84,7 @@ Never put `--success` (the solid) behind text — use the `-bg` / `-text` pair.
 Series walk `--series-1…10` in order; signed values are ALWAYS `--chart-pos` / `--chart-neg`
 (diverging bars, waterfall bridges, deltas, auto sparklines); totals and combo overlay lines are
 `--chart-total`; guides are dashed `--chart-guide`. Lines are straight or monotone-cubic — never
-a spline that overshoots a real value. Numbers are `--font-mono`, compact-formatted. Every chart
+a spline that overshoots a real value. Numbers are `--font-sans` with tabular figures, compact-formatted. Every chart
 answers a hover at every size: a tile-tier chart drops its axes and legend, never its tooltip.
 Geography is data, not a drawing — country outlines come from Natural Earth via d3-geo.
 3D charts are presentation, not analysis: plain SVG painter’s-algorithm rendering, one upper-left
@@ -98,46 +99,228 @@ feedback colors mean **severity**. Do not mix the two vocabularies.
 
 ## Typography
 
-`--font-sans` is Inter. `--font-mono` is Menlo. There is no third family.
+`--font-sans` is Inter. `--font-mono` is Menlo, and it is for code only: code blocks, logs, inline code in the docs, and config codes (`FIN_CURRENCY_DEFAULT`), which render as a code chip — Menlo at `--text-code` (12px; 11px in sm; Latin, so not bumped in CJK) on `--bg-inset` with a hairline border (`code: true` on a Table column). Everything else in the interface — IDs, amounts, chart numbers, keyboard keys — is `--font-sans`; numbers that must line up add `font-variant-numeric: tabular-nums`. There is no third family. Under
+`lang="zh" | "ja" | "ko"` the sans stack continues into the system CJK face (PingFang SC /
+Hiragino / Apple SD Gothic Neo on macOS, Microsoft YaHei / Yu Gothic UI / Malgun Gothic on
+Windows, Noto Sans CJK elsewhere); Latin glyphs stay Inter.
 
-| Token | Size / line-height | Use |
-| --- | --- | --- |
-| `--text-2xs` | 10 / 12.5 | Tile labels |
-| `--text-xs` | 11 / 16.5 | Table cells, captions, step labels |
-| `--text-sm` | 12 / 18 | Form labels, inputs, chips, meta |
-| `--text-base` | **13 / 19.5** | **Default UI text, buttons, nav** |
-| `--text-md` | 14 / 21 | Section headings, panel titles |
-| `--text-lg` | 15 / 22.5 | Page titles |
-| `--text-xl` | 20 / 30 | Greeting heading |
-| `--text-2xl` | 24 / 31 | Modal / page hero |
-
-Weights: `--weight-regular` 400, `--weight-medium` 500, `--weight-semibold` 600.
-**500 is the emphasis weight** — headings and active nav items are 500, not bold.
+**The 14px scale** — four sizes do almost all the work: 12 captions · 14 body and controls ·
+16 section titles · 20 page titles.
 
-Every size has a matching `--leading-*` and `--tracking-*`. Set all three together; the
-tracking values are negative at larger sizes and are not optional.
-
-This is a **dense, 13px-default interface**. If your text looks like a marketing site, it is
-too large.
+| Token | Size / line-height / tracking | Use |
+| --- | --- | --- |
+| `--text-2xs` | 11 / 16 / +.064 | Chart tick labels only — nothing in the system is smaller |
+| `--text-xs` | 12 / 16 / 0 | Captions, helper text, badges, tags, meta; control text at the `sm` tier |
+| `--text-base` | **14 / 20 / −.15** | **Body, buttons, inputs, labels, table cells, nav** |
+| `--text-md` | 16 / 24 / −.28 | Section headings, panel / card / dialog titles |
+| `--text-lg` | 20 / 28 / −.45 | Page titles |
+| `--text-xl` | 24 / 32 / −.54 | Greeting heading, page hero |
+| `--text-num` | 24 / 32 / +.07 | Stat numbers, weight 300 |
+| `--text-2xl` · `--text-3xl` · `--text-4xl` · `--text-display` | 30 · 38 · 48 · 60 | Report hero, marketing headings, dashboard hero numbers, slides |
+
+`--text-sm` is an alias of `--text-xs` (12px) kept for compatibility — write `--text-xs`.
+
+Weights: `--weight-light` 300, `--weight-regular` 400, `--weight-medium` 500,
+`--weight-semibold` 600. **500 is the emphasis weight** — headings and active nav items are
+500, not bold. Table headers and section labels are 600.
+
+Every size has a matching `--leading-*` and `--tracking-*`. Set all three together — or, inside
+a control, read `--control-text` / `--control-leading` / `--control-tracking` and the size tier
+hands you the right triple (see *Size tiers* below).
+
+This is a **dense, 14px-default interface**. If your text looks like a marketing site, it is
+too large; if a line of UI text is 11px, it is too small.
+
+### One size per line
+
+Text that shares a line shares a size. Inside a control bar every label, button, input, select
+and menu row is the tier's control text; a `Badge` or `Tag` is its own small object and the one
+exception. In content, a secondary annotation (a timestamp beside a name, a count beside a label)
+may be `--text-xs`. Never put a 14px label and a 12px control on the same baseline.
+
+### Table headers
+
+A header cell is the **same size as its data cells**, weight 600, `--text-secondary`, sentence
+case, no letter-spacing. The header is set apart by `--bg-table-header`, never by caps or a
+heavier rule. Amount and ID columns (`mono: true`) keep the row's size, font and colour and add
+only tabular figures; config-code columns (`code: true`) use the code chip — codes and amounts are never a point smaller than the words beside them.
+
+### Sortable headers
+
+Mark a column `sortable: true` and its header gets a sort button: a muted sm `IconButton` at the
+**right end of the header cell** — the same edge as a two-line row's `⋯`, so the two line up. The label
+keeps its alignment (left, or right for number columns, where it sits 4px before the button).
+
+- **Unsorted** — the button appears only while the header is hovered (or holds keyboard focus), icon
+  `arrow-up`. It keeps its space while hidden, so the label never shifts.
+- **Click** cycles ascending (`arrow-up`) → descending (`arrow-down`) → unsorted. The tooltip names the
+  next step: *Sort ascending* · *Sort descending* · *Clear sorting*.
+- **Sorted** — the button stays without hover and the label turns `--text-heading`; the header carries
+  `aria-sort`.
+- **One column at a time.** Clicking another column's button starts it at ascending and clears the first.
+- A long label truncates; the button never shrinks. With `resizable` the button sits inside the cell
+  padding, left of the divider, so the two never overlap.
+- Action columns (row ⋯, checkboxes) are never `sortable`, so they show no button.
+
+API: `sort` / `onSortChange` control it (`{ key, direction: "asc" | "desc" }` or `null`; Vue
+`v-model:sort`, `@sort-change`); `defaultSort` seeds it uncontrolled. The table reorders rows itself —
+numbers (commas allowed) numerically, text by locale with numeric collation, empty values last — unless
+the column passes `compare(a, b, rowA, rowB)` or the table sets `manualSort` (rows arrive sorted from
+the server). Selection indices and `onRowMore` always refer to the original `rows` order.
+
+### Two-line name rows
+
+The name column of a document list (folders, models, sheets) is a **two-line title cell**:
+`columns: [{ key: "name", label: "Name", width: 300, twoLine: true }, …]`. Left to right:
+
+1. an `IconTile kind="row"` tinted by the row's `hue` (`source` · `join` · `transform` · `merge` ·
+   `output`; `neutral` is the grey tile for folders and containers);
+2. two lines of text — the **title** in the tier's control text, `--text-heading`, regular weight, and the
+   **description** in `--text-xs`, `--text-secondary`. Each is one line and truncates with an ellipsis. Give the column a `width`; in a tight table it
+   shrinks to `minWidth` (default 180px) before the other columns give way;
+3. an sm `⋯` `IconButton` on the right (`onRowMore(row, index, event)`; Vue `@row-more`; `more: false` hides it).
+
+An optional 14px **mark** sits right after the title: `mark: "favorite"` is a filled star in `--warning`;
+`{ icon, color, label }` draws any 14px outline icon. Fields default to the row keys `icon`, `hue`,
+`description`, `mark`; pass `twoLine: { icon, hue, description, mark }` with field names or
+`(row, index) => value` accessors to read them from elsewhere.
+
+The header stays the tier's bar height; only body rows grow. Every other cell stays vertically centred
+and unchanged. All measures are `--title-cell-*` tier tokens:
+
+| | sm | md | lg |
+| --- | --- | --- | --- |
+| Icon tile (`--title-cell-tile`, `-tile-r`) | 28 · r8 | **32 · r8** | 40 · r10 |
+| Icon in the tile (`--title-cell-icon`) | 14 | 16 | 20 |
+| Tile → text (`--title-cell-tile-gap`) | 8 | 12 | 12 |
+| Title | 12 / 16 (13 / 18 CJK) | 14 / 20 | 14 / 20 |
+| Description | 12 / 16 (13 / 18 CJK) | 12 / 16 (13 / 18 CJK) | 12 / 16 (13 / 18 CJK) |
+| Title → description (`--title-cell-gap`) | 2 | 2 | 4 |
+| Row padding top and bottom (`--title-cell-py`) | 8 | 10 | 14 |
+| **Row height** (Latin / CJK) | **50 / 54** | **58 / 60** | **68 / 70** |
+| Header | 36 | 40 | 48 |
+| `⋯` button | sm 28 | sm 28 | sm 28 |
+
+**Opening a row.** Pass `onRowOpen(row, index, event)` (Vue `@row-open`) and the icon tile and the title open
+the row: both get the hand cursor, and the title is a keyboard target (Enter / Space). The ⋯ button and the
+expand arrow never open the row. Without the callback nothing in the cell looks clickable.
+
+**Tree rows.** Set `tree` on the table and nest rows through `children` — or set `hasChildren: true` on a
+row whose children you load when it opens. The two-line column then indents **24px per level** and reserves a
+**20px arrow slot + 4px** before the tile, so a child's arrow sits exactly under its parent's tile and leaf
+rows line up with folders. The arrow is a muted `chevron-right` (tier icon size) that turns down when
+open, with the `--overlay-hover` wash on hover; rows carry `aria-level` and `aria-expanded`. Expansion
+is `expandedKeys` / `onExpandChange(row, expanded, keys)` (Vue `v-model:expandedKeys`, `@expand-change`),
+or `defaultExpandedKeys` uncontrolled; `rowKey` names the key field (default `id`). Sorting reorders
+siblings only — children stay under their parent. Every index the table reports (selection, `onRowMore`,
+`onRowOpen`) is the row's depth-first position over all rows, expanded or not, so it never moves when the
+user sorts or expands; for a flat table that is simply its position in `rows`.
+
+**Labels.** The table draws six words itself — the sort tooltips, ⋯, and the arrow's expand / collapse.
+`labels: { sortAsc, sortDesc, sortClear, more, expand, collapse }` translates them; missing keys fall
+back to English. Pass them in the product's language — a Chinese table with English tooltips is a bug.
+
+In sm the title and description are the same size, so the description is told apart by colour alone —
+use sm two-line rows only where the list is dense and short labels are expected.
+
+### Chinese, Japanese and Korean
+
+Han, kana and Hangul have no capitals and no italics, so emphasis is weight. Under
+`:lang(zh|ja|ko)` the tokens change for you: `--weight-medium` and `--weight-semibold` both become
+**500** — square glyphs carry more strokes, so PingFang 600 next to Inter 500 reads a full step bolder —
+and every `--tracking-*` is **0**. (Microsoft YaHei, Meiryo, Yu Gothic UI and Malgun Gothic ship no 500
+face, so on Windows these render Regular; size, colour and the header fill keep the hierarchy.) Below 14px CJK is one step larger than
+Latin — `--text-xs` 13px (leading 18) and `--text-2xs` 12px — so no square glyph renders under
+12px; chart numerals read `--text-2xs-mono` and stay 11px. Text sized from geometry (switch inside text, avatar initials) is floored at `--text-glyph-min`: 11px, 12px in CJK. Inside an sm region `--weight-medium`
+is 400 for CJK, because bold strokes merge at 13px. Simplified and Traditional Chinese, Japanese
+and Korean get the same rule. CJK text is never smaller than the Latin
+text beside it, never letter-spaced and never transformed; a CJK table header or section label
+is emphasised by weight alone. Set `lang` on `<html>`, or on the region when one panel switches
+language — every component re-reads `--font-sans`, so a per-region switch works.
 
 ---
 
 ## Spacing, radii, sizing
 
 **Radii** — pick by element, not by taste:
-`--radius-sm` 4px (checkbox, stepper) · `--radius-md` 8px (buttons, inputs, nav, chips) ·
-`--radius-lg` 10px (cards, search, dropzone) · `--radius-tile` 14px · `--radius-node` 16px ·
-`--radius-full` (pills, avatars).
-
-**Control heights** — fixed, never improvised:
-`--h-button` 32px · `--h-button-sm` 30px · `--h-input` 36px · `--h-nav-item` 35.5px ·
-`--h-tree-item` 30px.
+`--radius-sm` 4px (checkbox) · `--radius-md` 8px (buttons, inputs, selects, search, steppers,
+segmented controls, nav, chips) · `--radius-lg` 10px (cards, menus, dropzone) ·
+`--radius-tile` 14px · `--radius-node` 16px · `--radius-full` (pills, avatars). Radii do not
+change with the size tier.
+
+### Size tiers — one per region
+
+Every control reads its height, text, icon size and padding from one set of tier tokens in
+`tokens/layout.css`. A **region** — the app root, a toolbar, a filter bar, a form, a table, a
+dialog, a drawer — declares `data-size="sm" | "md" | "lg"` and everything inside inherits it,
+so two controls that share a row can never disagree. `md` is the default on `:root`.
+**Change the region, not the control.**
+
+| Token | sm | md | lg | Used by |
+| --- | --- | --- | --- | --- |
+| `--control-h` | 28 | **32** | 40 | buttons, inputs, selects, search, steppers, segmented controls, chips, pagination items, menu rows |
+| `--control-text` | 12 (13 CJK) | **14** | 14 | text in controls and their labels, table cells |
+| `--control-icon` | 14 | 16 | 16 | icon inside a control |
+| `--control-px` | 8 | 12 | 16 | horizontal padding of a text control or button |
+| `--control-gap` | 8 | 8 | 8 | inside one group: label → its control, button → button |
+| `--group-gap` | 12 | 16 | 24 | between groups in one bar: field → next field |
+| `--bar-h` | 36 | 40 | 48 | toolbar, filter bar, tab bar, table row, list row |
+| `--bar-card-h` | 44 | 48 | 56 | a bar inside a bordered card (table toolbar, pagination) |
+| `--edge-pad` | 12 | 16 | 16 | card edge → first control or cell |
+| `--cell-px` | 8 | 12 | 16 | horizontal padding of a table cell |
+| `--check-size` | 14 | 16 | 16 | checkbox and radio box |
+| `--tag-h` | 20 | 24 | 28 | `Tag` |
+| `--switch-w` × `--switch-h` | 28 × 16 | 36 × 20 | 44 × 24 | `Switch` track |
+
+Where each tier belongs:
+
+- **sm** — dense data grids (`SmartTable`, `Spreadsheet` and `DataPreview` set it themselves),
+  controls inside pipeline nodes, a toolbar that must fit a 32px row.
+- **md** — everything else: app toolbars, filter bars, tables, long forms, settings pages.
+- **lg** — dialogs (`Modal` sets it), short forms, wizards, onboarding, a page with one task.
+
+Rules:
+
+- **One tier per row.** Never a 28px icon button beside a 32px input.
+- **Nothing interactive is smaller than 24px.** The former `xs` sizes and `dense` props map to `sm`.
+- A per-control `size` prop only stamps `data-size` on that control. Use it for a control that
+  stands alone in its band — never to "fix" one control inside a bar.
+- Text inside a control is `--control-text`, not `--text-xs` because it looks tidier.
+- `--h-button` and `--h-input` are aliases of `--control-h`; `--h-button-sm` is 28px. Prefer the
+  tier tokens in new code.
+
+### Button emphasis — pick the variant, never the size
+
+The tier says how dense a region is; the **variant** says how important an action is. Never
+shrink a button to make it feel lighter: a 28px button beside 32px controls and 14px text reads
+as a mistake on a calm page, and the tier rule above forbids it anyway. Reach for a quieter
+variant instead.
+
+| Variant | At rest | Where it lives |
+| --- | --- | --- |
+| `primary` | blue fill | The one main action of the view — page toolbar, dialog footer, wizard footer. Never two in sight. |
+| `outline` | hairline box | Secondary actions that must read as buttons at a glance: beside a primary, in forms, in toolbars. |
+| `ghost` | no box, grey wash on hover | Actions in card and section headers, table toolbars, panel chrome — anything that should stay quiet until needed. Same height and padding as `outline`, so it lines up with the controls beside it. Icon-only → `IconButton`, same rules. |
+| `text` | bare label, underline on hover | Links that happen to be buttons: *View all* at a list end or header right, *Clear filters* in an empty state, *Learn more* inside a sentence. Never beside a boxed button, never as a toolbar action. |
+| `primary-soft` · `dark` · `danger` · `danger-soft` | tint · near-black · red | Tinted secondary emphasis · brand / AI actions · destructive confirms and their softer in-row form. |
+
+**Card and section headers** (title left, actions right) hold either controls at the region's
+tier — `ghost` for secondary actions such as *Export* or *Filter*, and `primary` only when the
+card *is* the page's main object, which makes it the page's one primary — or a single `text` link
+such as *View all*. Not both in one header. The header row is the region's `--bar-h`; a 16px
+section title and 32px ghost buttons share it comfortably.
+
+**Chrome** (fixed, not tiered): `--sidebar-w` 240 · `--rail-w` 64 · `--topbar-h` 56 ·
+`--panel-w` 400 · `--drawer-h` 250 · `--h-nav-item` 36 · `--h-subnav-item` 32 ·
+`--h-tree-item` 32.
 
 **Page rhythm**: `--page-pad-y` 24px · `--page-pad-x` 32px · `--section-gap` 24px ·
-`--card-pad` 21px (`--card-pad-sm` 17px for dense cards).
+`--card-pad` 21px (`--card-pad-sm` 17px for dense cards). Gaps inside a bar come from the tier:
+8px inside a group, 12 / 16 / 24px between groups, `--edge-pad` from a card edge to its first
+control.
 
-The 35.5px and 21px are real. They come from the source design file. **Do not round them to
-36 or 24 to fit a mental 4px grid.**
+The 21px and 17px are real. They come from the source design file. **Do not round them to 24 or
+16 to fit a mental 4px grid.**
 
 **Shadows** — four, and only four: `--shadow-node` (canvas cards), `--shadow-menu` (dropdowns,
 popovers), `--shadow-modal` (modals), `--shadow-selected` (selected node). Cards in content
@@ -163,9 +346,18 @@ Nothing bounces. Nothing slides more than a few pixels. Keyframes available:
 
 ## Interaction states — you get these for free
 
-`tokens/interaction.css` applies press and keyboard focus globally. Do not re-implement them.
-
-- **Hover** — one step darker (`--bg-hover`, `--action-primary-hover`, `--soft-hover`)
+`tokens/interaction.css` applies press and keyboard focus globally; `tokens/hover.css` carries the hover hooks. Do not re-implement them.
+
+- **Hover** — every pointer target answers it, one step at a time:
+  filled and boxed buttons, menu rows, list rows, nav and tree items, segments → one surface step
+  (`--bg-hover`, `--action-primary-hover`, `--soft-hover`); a borderless `IconButton` → the alpha
+  overlay `--overlay-hover` (press `--overlay-press`), because it sits on white rows, grey table headers
+  and grey bars alike and a solid `--bg-hover` disappears on `--bg-table-header`; field boxes (inputs, selects, date,
+  combobox, multi-select, search, stepper) → border `--border-control` to `--border-strong`;
+  text-only controls (inactive tabs, legend items, clear ×, copy) → ink to `--text-heading`;
+  table body rows → `--bg-inset`; checkbox and radio rings → `--text-muted`; switch tracks →
+  one step toward the ink colour; inline action links → underline. Selected, open, focused and
+  error states never change on hover.
 - **Press** — a second step, applied automatically on `:active`
 - **Focus** — 2px `--focus-border` outline on `:focus-visible` only (never on mouse click)
 - **Disabled** — 55% opacity, default cursor
@@ -194,47 +386,41 @@ An indicator appears **only where a drop is legal**, and its shape names the ope
 
 ---
 
-## Brand expression
-
-`BrandVisual` is the only place saturated dark artwork is allowed, and it is decoration —
-never a data surface.
-
-- **Seven motifs, one canvas.** Every motif is authored at 1200×400 and cropped to fill its
-  box. Do not author a new one-off SVG for a hero; pick a motif.
-- **It never follows the theme.** The artwork is always the dark brand palette in both light
-  and dark mode — it is imagery, not a surface.
-- **Text on it uses `--on-accent`-weight foregrounds** (`#fff` / `#93c5fd` for eyebrows) and
-  sits in the calm region of the composition, never on top of the bright focal marker.
-- **Do not read data into it.** The arcs, lattices and ticks are not a chart; anything a user
-  must read goes in a real chart component.
-
----
-
 ## Do not
 
 The list that prevents the most rework. These are absolute.
 
 - **Do not hard-code a hex, rgb, or named color.** Use a semantic token.
-- **Do not put a `BrandVisual` behind readable content without a scrim or a calm region** —
-  and never restyle its palette to match a theme.
+- **Do not write a unitless number for a length in a Vue `:style`.** Vue does not add `px`;
+  write `'30px'` or `px(size)` from `components/px.js`. (React adds `px` itself — except for
+  `lineHeight`, where a bare number is a multiplier.)
 - **Do not reference a palette step** (`--neutral-500`, `--blue-600`) in component code.
 - **Do not use any font other than Inter and Menlo.** No Roboto, no Arial, no system-ui stack.
 - **Do not use gradients.** The only exception in the entire system is the chart area fill.
 - **Do not add drop shadows to content cards.** Cards use a 1px `--border-card` hairline.
-- **Do not round the odd numbers.** 35.5px, 21px, 17px, 11px are from the source file.
+- **Do not round the odd numbers.** `--card-pad` 21px and `--card-pad-sm` 17px are from the source
+  file; the 11px of `--text-2xs` is deliberate.
+- **Do not use size as emphasis.** A quieter action gets a quieter variant (`ghost`, `text`), never a
+  smaller size.
+- **Do not mix size tiers in one row.** The region declares `data-size`; the controls inherit. A
+  `size` prop on one control inside a bar is a bug, not a fix.
+- **Do not shrink, letter-space or uppercase Chinese, Japanese or Korean text.** Under `lang`
+  the emphasis and heading weight is 500 (medium 400 at sm), tracking is 0, and sizes under 14px step up by one — that is the whole CJK rule.
 - **Do not put dark text on a saturated fill.** `--on-accent` (white) is the only option,
   in both themes — this is why the dark-mode primary button keeps white text.
 - **Do not scale or shift elements on press.** Press is a color step only.
 - **Do not show a drop indicator where the drop is impossible.** No half-row boxes on a
   container, no insert rules on a node that can't take children.
 - **Do not build a new primitive when one exists.** Check the component index in
-  `INTEGRATION.md` first — there are 118.
-- **Do not use emoji as icons.** Use `<Icon name="..." />` (362 glyphs) or `<Unicon>` (1,206).
+  `INTEGRATION.md` first — there are 117.
+- **Do not use emoji as icons.** Use `<Icon name="..." />` (330 glyphs) or `<Unicon>` (1,206).
 - **Do not invent new component variants.** If `Button` lacks the variant you want, that is a
   design-system request, not a local override.
 - **Do not stack two primary buttons.** One primary action per view; everything else is
   `outline`, `ghost`, or `text`.
-- **Do not use full-uppercase text** except in 9–10px section labels with letter-spacing.
+- **Do not use full-uppercase text.** Table headers and section labels are sentence case, weight
+  600, tracking 0 — the same size as the text they label. (This site's own card labels follow the
+  same rule: 12px, sentence case.)
 - **Do not animate anything longer than 360ms** or with a bounce/elastic easing.
 
 ---