@keyfunc/keybricks-ds 1.0.3 → 2.1.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.0 && git push --tags
+git tag v2.1.1 && git push --tags
 ```
 
 That tag runs `generated:check` → `version:check` → `npm publish`. Confirm under *Deploy →
-Package Registry*: `@keyfunc/keybricks-ds` 1.0.0.
+Package Registry*: `@keyfunc/keybricks-ds` 2.1.1.
 
 **6. Hand developers two things:** the Pages URL, and the `.npmrc` snippet in §4 below.
 
@@ -90,7 +90,7 @@ 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
@@ -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.0"
+"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v2.1.1"
 ```
 
 Because the package has no build step, a git dependency needs no `prepare` script — npm

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
@@ -98,46 +99,145 @@ 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. 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 |
+**The 14px scale** — four sizes do almost all the work: 12 captions · 14 body and controls ·
+16 section titles · 20 page titles.
+
+| Token | Size / line-height / tracking | 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 |
+| `--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
 
-Weights: `--weight-regular` 400, `--weight-medium` 500, `--weight-semibold` 600.
-**500 is the emphasis weight** — headings and active nav items are 500, not bold.
+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. Mono columns (`mono: true`) keep the row's size in `--font-mono` with tabular
+figures — codes and amounts are never a point smaller than the words beside them.
 
-Every size has a matching `--leading-*` and `--tracking-*`. Set all three together; the
-tracking values are negative at larger sizes and are not optional.
+### Chinese, Japanese and Korean
 
-This is a **dense, 13px-default interface**. If your text looks like a marketing site, it is
-too large.
+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` becomes **600** (Microsoft
+YaHei, Meiryo, Yu Gothic UI and Malgun Gothic ship no 500 face, so 500 silently renders as
+Regular on Windows) and every `--tracking-*` is **0**. 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` | 24 | **32** | 36 | buttons, inputs, selects, search, steppers, segmented controls, chips, pagination items, menu rows |
+| `--control-text` | 12 | **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` | 32 | 40 | 44 | toolbar, filter bar, tab bar, table row, list row |
+| `--bar-card-h` | 40 | 48 | 52 | 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 24px 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 24px. 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 24px 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 +263,16 @@ 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.
+`tokens/interaction.css` applies press and keyboard focus globally; `tokens/hover.css` carries the hover hooks. Do not re-implement them.
 
-- **Hover** — one step darker (`--bg-hover`, `--action-primary-hover`, `--soft-hover`)
+- **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`); 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 +301,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 weight is 600 and tracking is 0 — 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.
+  `INTEGRATION.md` first — there are 117.
 - **Do not use emoji as icons.** Use `<Icon name="..." />` (362 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. (The 10px eyebrows in this site's own
+  card chrome are documentation furniture, not a component pattern.)
 - **Do not animate anything longer than 360ms** or with a bounce/elastic easing.
 
 ---