@keyfunc/keybricks-ds 1.0.0

package/INTEGRATION.md

@@ -0,0 +1,417 @@
+# Keybricks Design System — Integration Guide
+
+Everything a product team needs to render Keybricks UI in their own app. Three steps to
+first paint; the rest of this file is reference.
+
+**Two frameworks, one design.** Every component ships as both `<Name>.jsx` (React) and
+`<Name>.vue` (Vue 3), reading the same CSS custom properties. A Button rendered by React
+and a Button rendered by Vue are pixel-identical, because neither one owns its colors —
+`styles.css` does.
+
+---
+
+## 1. Install
+
+```bash
+# Point npm at the GitLab Package Registry (once per machine, or commit an .npmrc)
+npm config set @keyfunc:registry "https://gitlab.epm2demo.cn/api/v4/packages/npm/"
+
+npm install @keyfunc/keybricks-ds
+```
+
+A project-local `.npmrc` is usually better than per-machine config — commit this next to
+`package.json` so CI and new hires need no setup:
+
+```ini
+@keyfunc:registry=https://gitlab.epm2demo.cn/api/v4/packages/npm/
+//gitlab.epm2demo.cn/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}
+```
+
+Not using a registry yet? A git dependency works with no publishing at all — the package
+has no build step, so npm can use the checkout as-is:
+
+```json
+"@keyfunc/keybricks-ds": "git+ssh://git@gitlab.epm2demo.cn/Felix/keybricks-ds.git#v1.0.0"
+```
+
+**Source-only package.** `.jsx` and `.vue` files are published as authored, so your
+bundler compiles them. Vite (React) needs the package excluded from `optimizeDeps` and
+included in the React plugin; Next.js needs `transpilePackages`. Both snippets, plus the
+release and Pages setup, are in `DEPLOY.md`.
+
+## 2. Load the stylesheet — once, at your app's entry point
+
+```js
+import '@keyfunc/keybricks-ds/styles.css'
+```
+
+This one line brings in the fonts, the color ramps, the type scale, spacing, radii,
+shadows, motion, the global press/focus layer, and the dark theme. **Nothing renders
+correctly without it** — components reference `var(--action-primary)`, not hex codes.
+
+Dark mode follows the OS automatically. To let users override it:
+
+```js
+document.documentElement.dataset.theme = 'dark'   // or 'light', or remove the attribute for auto
+```
+
+## 3. Use a component
+
+**React**
+
+```jsx
+import { Button, Field, Input } from '@keyfunc/keybricks-ds'
+
+export function LoginForm() {
+  return (
+    <form>
+      <Field label="Work email" required>
+        <Input type="email" placeholder="you@company.com" />
+      </Field>
+      <Button variant="primary" size="md">Sign in</Button>
+    </form>
+  )
+}
+```
+
+**Vue 3**
+
+```vue
+<script setup>
+import Button from '@keyfunc/keybricks-ds/components/buttons/Button.vue'
+import Field from '@keyfunc/keybricks-ds/components/forms/Field.vue'
+import Input from '@keyfunc/keybricks-ds/components/forms/Input.vue'
+</script>
+
+<template>
+  <form>
+    <Field label="Work email" required>
+      <Input type="email" placeholder="you@company.com" />
+    </Field>
+    <Button variant="primary" size="md">Sign in</Button>
+  </form>
+</template>
+```
+
+That is the whole integration. Everything below is reference material.
+
+---
+
+## What you can and cannot change
+
+Props are the knobs the design system deliberately exposes. **`variant`, `size`, `icon`,
+`disabled`, `loading` are yours to set.** The height, radius, exact blue, hover step, press
+step, focus ring and dark-mode behavior are not — they live inside the component so that
+every Button in every product looks like the same Button.
+
+```jsx
+<Button variant="primary" size="lg" icon="download">Export</Button>   // ✅ intended
+<Button style={{ background: '#0055ff', borderRadius: 2 }}>Export</Button>  // ❌ breaks the system
+```
+
+Need something the props don't cover? That is a design-system request, not a local
+override — file an issue. Local overrides are how design systems die: six months on,
+nobody knows which blue is correct.
+
+**When you do need a one-off**, compose with tokens rather than raw values, so the piece
+still flips correctly in dark mode:
+
+```jsx
+<div style={{ background: 'var(--bg-inset)', border: '1px solid var(--border-card)',
+              borderRadius: 'var(--radius-lg)', padding: 'var(--space-4)' }}>
+```
+
+## Component index (118 components)
+Import path is `@keyfunc/keybricks-ds/components/<group>/<Name>.jsx` (React) or `.vue` (Vue 3).
+Every component has a sibling `.d.ts` with its full props contract, and each group has a
+`.prompt.md` with usage notes.
+
+### `brand/` — brand expression
+| Component | What it's for |
+| --- | --- |
+| `BrandVisual` | Generative brand artwork for heroes, section headers and card headers. Seven motifs (`orbit`, `entropy`, `focal`, `manifold`, `tesseract`, `meridian`, `ledger`), each authored on one 1200×400 canvas and cropped to fill any box. Always dark — it does not follow the theme. Pass `children` to overlay headings. |
+
+### `buttons/` — actions
+| Component | What it's for |
+| --- | --- |
+| `Button` | The primary action element. 8 variants (primary, dark, outline, ghost, primary-soft, danger, danger-soft, text) × 3 sizes, with icon, loading and disabled states. |
+| `IconButton` | Square glyph-only button for toolbars and headers. 4 sizes, danger and muted tones, toggle-on `active` state. |
+| `ButtonGroup` | Joins buttons into a segmented control or split button — handles the shared borders and corner radii. |
+| `ActionChip` | Compact pill action, used in toolbars and empty states. |
+
+### `forms/` — data entry
+| Component | What it's for |
+| --- | --- |
+| `Field` | Label + required marker + hint + error wrapper. Wrap every input in one. |
+| `Input` | Single-line text input. Sizes, prefix/suffix, error and read-only states. |
+| `Textarea` | Multi-line input with optional character counter and auto-resize. |
+| `Select` | Native-feeling dropdown for a known list of options. |
+| `Combobox` | Type-to-filter single select, with keyboard nav and a no-results row. |
+| `MultiSelect` | Checkbox dropdown; picks render as removable tags with `+n` overflow. |
+| `SearchInput` | Search field with a leading glyph and a clear button. |
+| `Checkbox` | Two sizes, plus an indeterminate state for parent rows. |
+| `Radio` / `RadioGroup` | Single choice from a small set; the group handles layout and keyboard arrows. |
+| `Switch` | Immediate on/off toggle (no Save button). Two sizes. |
+| `NumberStepper` | Numeric input with − / + buttons and min/max clamping. |
+| `Slider` | Range input with a filled track, drag value bubble and optional min/max labels. |
+| `DatePicker` | Text field plus a month-grid popover. Values are `YYYY-MM-DD` strings. |
+| `Dropzone` | File drop target with hover, drag-over, uploaded and error states. |
+
+### `data/` — tables and structured values
+| Component | What it's for |
+| --- | --- |
+| `DataTable` | The standard table: sortable headers, per-column render functions, alignment, selection. |
+| `SmartTable` | Notion/Airtable-style table — typed field columns, inline editing, row hover actions. |
+| `Spreadsheet` | Excel-style grid: formula bar, frozen headers, range selection, `=SUM()` evaluation, sheet tabs. |
+| `FilterBar` | List-report filter bar with variant title, wrapping filter fields, and Adapt Filters / Go. |
+| `ListRow` | One row of a list view — icon, title, meta, trailing actions. |
+| `Pagination` | Page controls with a row-range label and first/last disabled states. |
+| `KeyValue` / `KeyValueList` | Label-and-value pairs for detail panels and summaries. |
+| `DiffValue` | Before → after comparison, used in migration and confirmation steps. |
+| `CodeBlock` | Monospace block with optional line numbers and a copy button. |
+
+### `navigation/` — getting around
+| Component | What it's for |
+| --- | --- |
+| `Sidebar` | The app's primary nav: collapsible sections, active state, footer items. `KEYBRICKS_NAV` is the product's real nav tree. |
+| `TopBar` | Global header — search, notifications, theme toggle, avatar. |
+| `PageHeading` | Page title with optional subtitle and right-aligned actions. |
+| `PageToolbar` | Secondary bar under the heading: filters, view toggles, bulk actions. |
+| `Breadcrumb` | Path trail; collapses to an ellipsis dropdown past `maxItems`. |
+| `Tree` | Generic nested tree: cascading checkboxes with indeterminate parents (`checkStrictly` opts out), disabled nodes vs. locked checkboxes, `showLine` guides, async `loadData`, search highlight, drag to move into a folder, full keyboard nav. |
+| `DocTree` | Document-oriented tree with file-type glyph hues. |
+| `ThemeToggle` | Light/dark/auto switch. `applyStoredTheme()` restores the choice on load. |
+
+### `tabs/` — switching views
+| Component | What it's for |
+| --- | --- |
+| `Tabs` | Page-level underline tabs. |
+| `PanelTabs` | Compact tabs inside a detail panel or drawer. |
+| `PillTabs` | Filter/status tabs as pills. |
+| `SegmentedControl` | Mutually exclusive options in one control; two sizes, optional icons. |
+| `ViewToggle` | List/grid icon toggle. |
+
+### `feedback/` — status, overlays, progress
+| Component | What it's for |
+| --- | --- |
+| `Alert` | In-card message, 4 tones, with or without body copy. |
+| `Banner` | Page-level notification strip with an inline action link. |
+| `Toast` / `ToastStack` | Transient confirmations. The stack handles positioning and queueing. |
+| `Modal` | Centered dialog over a scrim, with footer actions. |
+| `Drawer` | Right slide-out detail or settings panel. |
+| `Tooltip` | Hover hint on any element. |
+| `Menu` / `ContextMenu` | Dropdown and right-click menus, with separators and destructive items. |
+| `Accordion` | Collapsible sections for long forms and settings. |
+| `Stepper` | Multi-step flow header — done, current, upcoming. |
+| `Timeline` | Vertical activity feed with toned icon nodes. |
+| `ActivityItem` / `DotActivity` | Activity rows: full row with action, or compact status dot line. |
+| `LogViewer` | Monospace run log with info/warn/error line colors. |
+| `EmptyState` | First-run, no-results and error states with an optional action. |
+| `Skeleton` / `Spinner` | Loading placeholders and the inline busy indicator. |
+
+### `display/` — presenting values
+| Component | What it's for |
+| --- | --- |
+| `Card` | The standard surface. Default and dense padding, optional no-pad for tables. |
+| `StatCard` | Headline metric with label, delta and optional sparkline. |
+| `Badge` / `StatusBadge` | Status pills, and the bare colored dot. |
+| `Tag` | Label chip, optionally removable. |
+| `Avatar` / `AvatarGroup` | User image or initials; the group handles overlap and `+n`. |
+| `ProgressBar` | Determinate progress with optional label. |
+| `AreaChart` / `Donut` / `MiniBars` | The three chart primitives the product uses. |
+| `IconTile` | Rounded tinted tile behind a glyph — used in lists and node palettes. |
+| `Kbd` | Keyboard shortcut hint. |
+| `Divider` | Hairline separator, optionally with a centered label. |
+
+### `icons/` — iconography
+| Component | What it's for |
+| --- | --- |
+| `Icon` | 362 stroke glyphs (the product's own set plus all of Feather). `<Icon name="download" size={16} />` |
+| `Unicon` | 1,206 additional Unicons line glyphs, loaded from CDN. Use when `Icon` has no match. |
+
+### `pipeline/` — the data-pipeline editor
+Product-specific composites: `PipelineCanvas`, `NodeCard`, `Port`, `PortLabel`,
+`PalettePanel`, `PaletteItem`, `PaletteListItem`, `ConfigPanel`, `DataPreview`,
+`ZoomControls`, and `PIPELINE_CATALOG` (the real node inventory). Use these only when
+building the pipeline surface itself.
+
+### `charts/` — the charting module
+Twelve chart types on one geometry core, sized for three tiers: sm tile (`Sparkline`, or any chart with `axes={false}`), md interactive (hover tooltip, legend mute — the defaults), lg full-page (see the Full-Page Analytics card).
+
+| Component | What it's for |
+| --- | --- |
+| `Sparkline` | Micro line/area/bars in stat tiles, table cells, list rows. `tone="auto"` colors by direction. |
+| `LineChart` | Trends over time; `area`, `stacked`, dashed `target` guide. |
+| `BarChart` | Grouped / stacked / diverging (variance ±) bars; `overlay` adds a combo line on a right axis. |
+| `BarList` | Horizontal labeled bars — top-N, budget consumption. |
+| `DonutChart` | Composition with a KPI center; `pie` fills the middle. Cap ~6 segments. |
+| `ScatterChart` | Scatter / bubble with nearest-point tooltip. |
+| `HeatmapChart` | Matrix density; `scale="diverging"` for signed variance. |
+| `WaterfallChart` | Finance bridge — signed deltas, re-baselining totals, running-sum connectors. |
+| `BulletChart` | Actual vs. target rows with a target tick. |
+| `GaugeChart` | Semi-circular KPI, flat arc, threshold `bands`. |
+| `FunnelChart` | Stage counts with step conversion %. |
+| `TreemapChart` | Squarified composition for 15+ items. |
+| `RadarChart` | Profile comparison across 3–10 shared measures. |
+| `Histogram` | Distribution of one measure; raw values auto-bucketed. |
+| `BoxPlot` | Spread and Tukey outliers per group; `summarize()` exported. |
+| `ParetoChart` | Sorted bars + cumulative % line and the 80% guide. |
+| `CandlestickChart` | OHLC K-line with volume band and moving average. |
+| `SankeyChart` | Directional flow; columns derived from the graph. |
+| `ChordChart` | Circular Sankey for cyclical many-to-many flows. |
+| `SunburstChart` | Hierarchy as rings; click to zoom a branch. |
+| `WorldMap` | Country choropleth on real Natural Earth geometry (needs the pinned d3 + topojson tags). |
+| `GanttChart` | Task timeline with weekends, progress and a today marker. |
+| `Surface3D` | 3D surface z = f(x,y), heat-shaded, drag to orbit. |
+| `Scatter3D` | 3D scatter in an orientation cube, drag to orbit. |
+| `Bar3D` | 3D cuboid bars, grouped or stacked, drag to orbit. |
+| `Pie3D` | Extruded/stepped pie & donut; drag spins in place, hover lifts a slice. |
+| `Ribbon3D` | Series as extruded depth bands (the classic 3D area). |
+
+Series colors walk `--series-1…10`; signed values always use `--chart-pos`/`--chart-neg`; plot furniture reads `--chart-grid/-axis/-label/-guide/-track` (all theme-aware, from `tokens/charts.css`). Shared legend/tooltip live in `ChartKit`.
+
+Every chart answers a hover at every size — a tile-tier chart drops axes and legend, never the tooltip. `LineChart` and `Sparkline` take `curve="linear" | "smooth" | "step"`; stacked areas fill to the baseline so their gradients overlap, and stacked bars round only the topmost segment so joins stay flush. `WorldMap` requires these exact tags on the page (it reads them off `window` and fetches the pinned topology itself):
+
+```html
+<script src="https://unpkg.com/d3@7.9.0/dist/d3.min.js" integrity="sha384-CjloA8y00+1SDAUkjs099PVfnY2KmDC2BZnws9kh8D/lX1s46w6EPhpXdqMfjK6i" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/topojson-client@3.1.0/dist/topojson-client.min.js" integrity="sha384-Ukv1p/xTma6P4/2bY5KzWBw+ydSpXmhCMtyciIQVDJ1RmOxtCYNMF1uXT9T63H67" crossorigin="anonymous"></script>
+```
+
+Ports carry three tones — grey at rest, `--action-primary` on hover and while a wire is
+being dragged (`outputTone="active"`), and a crosshair drop target (`inputTones[i]="target"`).
+Pass `onConnect` to `PipelineCanvas` to enable wiring: holding an output port drags a dashed
+bezier, the canvas hit-tests the pointer against input-port geometry within `snapRadius`
+(30px), and the drop reports `{from, to, toPort}`. `DataPreview` is only the bottom drawer
+chrome (title, Debug Mode, collapse) around the shared dense `DataTable` — reach for
+`DataTable` directly unless you need that drawer.
+
+---
+
+## Design tokens
+
+Reference tokens, never raw values. The full list is in the Design System tab's Colors
+cards; the ones you will reach for daily:
+
+| Need | Token |
+| --- | --- |
+| Page background | `--bg-app` |
+| Card / panel background | `--bg-surface` |
+| Nested well, table header | `--bg-inset` |
+| Row hover | `--bg-hover` |
+| Body text | `--text-body` |
+| Headings | `--text-heading` |
+| Meta, labels | `--text-secondary` |
+| Placeholder, disabled | `--text-muted` |
+| Card hairline | `--border-card` |
+| Input / button edge | `--border-control` |
+| Primary action | `--action-primary` |
+| Text on any saturated fill | `--on-accent` |
+| Success / warning / danger / info | `--success` `--warning` `--danger` `--info-fg` (each with `-bg` and `-text` companions) |
+
+Three rules that keep a UI consistent:
+
+1. **Never hard-code a hex value.** It won't flip for dark mode and it won't survive a retheme.
+2. **Never use a palette step directly** (`--neutral-500`, `--blue-600`) — use the semantic
+   role (`--text-secondary`, `--action-primary`). Palette steps don't change between themes;
+   roles do.
+3. **White (`--on-accent`) is the only text color allowed on a saturated fill**, in both
+   themes. This is why the dark-mode primary button keeps white text.
+
+### Tokens outside CSS
+
+The CSS files are the source of truth. Two generated views ship alongside them for code
+that cannot read a stylesheet — canvas, PDF export, native, Figma round-trips:
+
+```js
+import { cssVar, light, dark } from '@keyfunc/keybricks-ds/tokens'
+
+cssVar.actionPrimary   // "var(--action-primary)"  ← use this in component styles
+light.actionPrimary    // "#155dfc"
+dark.actionPrimary     // "#1f6feb"
+```
+
+```js
+import tokens from '@keyfunc/keybricks-ds/tokens.json'
+// { "--action-primary": { group: "colors",
+//     light: { raw: "var(--blue-600)", value: "#155dfc" },
+//     dark:  { raw: "#1f6feb",        value: "#1f6feb" } }, … }
+```
+
+`cssVar` is the one to reach for in app code — it keeps theming live. The flattened
+`light`/`dark` maps are snapshots: correct at build time, but they do not follow a runtime
+theme switch. Never paste a literal from them into a stylesheet.
+
+Both files are regenerated by `node _scripts/build-tokens.mjs`; CI fails if they drift from
+the CSS.
+
+## Dark mode
+
+Automatic via `prefers-color-scheme`, and overridable with `data-theme` on `<html>`.
+If you build custom UI beside Keybricks components, reference the same semantic tokens and
+it will flip for free. Two things to watch:
+
+- A solid light tint (`#ECFDF5`) glows on a dark surface. That's why feedback tints become
+  10–14% alpha washes in dark mode — another reason to use `--success-bg` rather than a hex.
+- Surfaces get **lighter** as they nest in light mode and **brighter** in dark mode
+  (`--bg-app` → `--bg-surface` → `--bg-raised`). Use the roles in that order and depth reads
+  correctly in both.
+
+## Interaction states — you get these for free
+
+`tokens/interaction.css` delivers press and keyboard focus globally: `:active` adds
+`filter: var(--press-filter)` (which darkens in light mode and brightens in dark), and
+`:focus-visible` draws a 2px `--focus-border` outline. It applies to `button`, `a`, `label`,
+and anything with `role="button"`, `menuitem`, `option`, `tab`, `switch`, `treeitem` etc.
+
+**If you build a custom clickable element, give it a role and a `tabIndex`** and it inherits
+both states:
+
+```jsx
+<div role="button" tabIndex={0} onClick={...}>   // ✅ gets press + focus
+<div onClick={...}>                              // ❌ inert, and unreachable by keyboard
+```
+
+Button and IconButton carry `data-press="own"` because their press colors are explicit
+tokens rather than a filter.
+
+## Versioning
+
+Semver, tagged in GitLab. Patch = fixes; minor = new components, new props, and token
+*value* changes; major = a breaking prop change or a token *rename or removal*, always with
+a migration note in the release. Token renames are major because your own code references
+`var(--name)` directly.
+
+Pin a minor range and update deliberately:
+
+```json
+"@keyfunc/keybricks-ds": "~1.0.0"
+```
+
+Release mechanics, the CI pipeline and the Pages site are documented in `DEPLOY.md`.
+
+## Templates
+
+A template is a ready-made screen you copy into a new project as a starting point, rather than a
+component you import. Each lives in `templates/<slug>/`.
+
+| Template | What you get |
+| --- | --- |
+| `templates/web-app/` | The full app shell: sidebar with the real nav model, top bar, page heading, stat tiles and a data table. |
+
+Copy the folder, then edit one line — the `base` in `ds-base.js` — to point at wherever the design
+system sits relative to the copied page.
+
+## Getting help
+
+- **Documentation site** — the GitLab Pages build: `index.html` for the browsable system
+  (every card live, EN / 中文 / 日本語, light and dark, View Code per component) and
+  `gallery.html` for the filterable thumbnail grid.
+- **Props contract** — the `.d.ts` next to each component.
+- **Usage notes** — the `.prompt.md` in each component group.
+- **Rules for AI coding agents** — `DESIGN.md`, published as
+  `@keyfunc/keybricks-ds/DESIGN.md`. Point your agent at it before it writes any markup.
+- **Lint preset** — `@keyfunc/keybricks-ds/lint` fails CI on raw hex values and palette-step
+  references in your own components.
+- **Design rationale** — `readme.md` (content and visual foundations, iconography, tone).
+- **Something missing or wrong?** File an issue on the design-system project rather than
+  patching locally.

package/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: keybricks-design
+description: Use this skill to generate well-branded interfaces and assets for Keybricks (EPM/finance data platform), either for production or throwaway prototypes/mocks/etc. Contains essential design guidelines, colors, type, fonts, assets, and UI kit components for prototyping.
+user-invocable: true
+---
+
+Read the README.md file within this skill, and explore the other available files. This skill's documentation is bilingual (English / 中文)。
+
+Key facts / 关键信息: Keybricks is a near-monochrome, hairline-bordered, 13px-Inter enterprise UI with one action blue (#155dfc, dark mode #1f6feb), five node-category hues, and a signature node-pipeline editor.
+（Keybricks 是一个近乎单色、细边框、以 13px Inter 为主的企业级界面，仅有一个强调蓝（浅色 #155dfc / 深色 #1f6feb）、五种节点分类色，以及标志性的数据管道编辑器。）
+Tokens live in `tokens/*.css` (linked via `styles.css`, includes `tokens/dark.css` for dark mode and `tokens/motion.css` for motion); React components in `components/<group>/` (each with a `.d.ts` contract and `.prompt.md` usage note); full-screen recreations in `ui_kits/keybricks-app/`.
+（设计令牌位于 `tokens/*.css`（经 `styles.css` 汇总，含深色模式 `tokens/dark.css` 与动效 `tokens/motion.css`）；React 组件位于 `components/<分组>/`（各附 `.d.ts` 类型定义与 `.prompt.md` 用法说明）；完整界面复刻位于 `ui_kits/keybricks-app/`。）
+
+If creating visual artifacts (slides, mocks, throwaway prototypes, etc), copy assets out and create static HTML files for the user to view. If working on production code, you can copy assets and read the rules here to become an expert in designing with this brand.
+
+If the user invokes this skill without any other guidance, ask them what they want to build or design, ask some questions, and act as an expert designer who outputs HTML artifacts _or_ production code, depending on the need.
+
+Rules of thumb / 要点速览:
+- Inter 13px/400 is the default; 500 for nav/headings/labels; 600 for node & panel titles; 300 only for big numerals. Menlo for codes, data cells, logs.
+  （Inter 13px/常规 为默认；500 用于导航/标题/标签；600 用于节点与面板标题；300 仅用于大号数字。代码/数据/日志用 Menlo。）
+- Backgrounds: app #fafafa, surfaces white, hairline borders rgba(229,229,229,.6); shadows only on canvas nodes.
+  （背景：应用层 #fafafa，卡片层白色，细边框；仅画布节点有阴影。）
+- One blue CTA per view; ghost text buttons beside it. Color only for meaning (category hues, status).
+  （每个界面只有一个蓝色主按钮，旁边配文字按钮；颜色只用于表达含义。）
+- Icons: Lucide stroke set via the Icon component — never emoji, never hand-drawn SVG.
+  （图标统一用 Icon 组件封装的 Lucide 线性图标集——禁止 emoji，禁止手绘 SVG。）
+- Radii: 4 controls · 8 buttons/inputs · 10 cards · 14/16 tiles & nodes · full circles.
+  （圆角：4px 控件、8px 按钮/输入框、10px 卡片、14/16px 图标块与节点、端口/胶囊全圆角。）
+- Copy: Title Case labels, imperative verb-first buttons ("Run Test", "Mark as New"), terse technical vocabulary.
+  （文案：标签用词首大写，按钮用祈使动词开头，术语简洁精确。）
+- Dark mode: set `<html data-theme="dark">`. Style only via semantic tokens (`--bg-surface`, `--text-body`, `--border-card`, `--track`, `--soft-bg`, `--info-bg`, `--on-accent`, `--ring-surface`) — never raw `--neutral-*`/`--blue-*` — and both themes work automatically.
+  （深色模式：在 `<html>` 加 `data-theme="dark"`。组件只使用语义层变量，禁止直接用基础色变量，两套主题即可自动生效。）