@keyfunc/keybricks-ds 1.0.0

package/DEPLOY.md

@@ -0,0 +1,204 @@
+# DEPLOY.md — running Keybricks on GitLab
+
+Two artifacts come out of this repository, from one pipeline:
+
+| Artifact | Where | Who uses it |
+| --- | --- | --- |
+| `@keyfunc/keybricks-ds` npm package | GitLab Package Registry | app developers |
+| Documentation site (`index.html` + live cards) | GitLab Pages | designers, PMs, developers |
+
+Configured for `gitlab.epm2demo.cn`, project `Felix/keybricks-ds`. Nothing else needs
+configuring — the pipeline runs on `CI_JOB_TOKEN`.
+
+---
+
+## 0. First-time setup (once, ~15 minutes)
+
+**1. Create the project.** *New project → Create blank project*. Name `Keybricks DS`, slug
+`keybricks-ds`. Visibility **Internal** if colleagues should be able to read the docs site
+without being added one by one; Private if not. Leave *Initialize repository with a README*
+**unchecked** — the repo already has one, and a README commit would make the first push a
+conflict.
+
+**2. Push this folder as the repo.**
+
+```bash
+cd keybricks-ds                 # the folder you downloaded
+git init -b main
+git add -A
+git commit -m "chore: import Keybricks design system"
+git remote add origin git@gitlab.epm2demo.cn:Felix/keybricks-ds.git
+git push -u origin main
+```
+
+**3. Host already filled in.** `package.json`, `DEPLOY.md` and `INTEGRATION.md` point at
+`gitlab.epm2demo.cn/Felix/keybricks-ds`. If the project ever moves to a group, re-run:
+
+```bash
+grep -rn "gitlab.epm2demo.cn" package.json DEPLOY.md INTEGRATION.md
+```
+
+Nothing in `.gitlab-ci.yml` needs editing — it reads `CI_API_V4_URL` and `CI_PROJECT_ID`
+from the runner.
+
+**4. Check the runner and the two features.**
+
+- *Settings → CI/CD → Runners* — an available shared or group runner (Docker executor;
+  the pipeline uses `node:20-alpine`).
+- *Settings → Packages and registries* — Package registry **enabled**.
+- *Deploy → Pages* — appears after the first successful `pages` job. If your instance
+  requires it, set *Settings → Pages → Access control* to “Only project members”.
+
+The push in step 2 already triggers a pipeline: `generated:check` runs, then `pages`
+deploys the documentation site. Watch it under *Build → Pipelines*.
+
+**5. Cut the first release.**
+
+```bash
+git tag v1.0.0 && git push --tags
+```
+
+That tag runs `generated:check` → `version:check` → `npm publish`. Confirm under *Deploy →
+Package Registry*: `@keyfunc/keybricks-ds` 1.0.0.
+
+**6. Hand developers two things:** the Pages URL, and the `.npmrc` snippet in §4 below.
+
+**7. Protect what you just built.** *Settings → Repository → Protected branches*: `main`,
+maintainers only, force-push off. *Protected tags*: pattern `v*`, maintainers only — a tag
+is a publish, so it deserves the same gate as a merge.
+
+---
+
+## 1. What ships, and what does not
+
+**Source-only package.** `.jsx` and `.vue` files are published as authored; the consuming
+app compiles them with its own toolchain. No `dist/`, no bundler here, no build step that
+can drift from the source. Every component has a sibling `.d.ts`, so editors and `tsc`
+still see the full props contract.
+
+This means a consumer's bundler must handle:
+
+- **React** — JSX in `node_modules`. Vite: add the package to `optimizeDeps.exclude` and
+  let esbuild transform it (see §4). Next.js: `transpilePackages`.
+- **Vue 3** — SFCs, so `@vitejs/plugin-vue` or `vue-loader` must already be installed
+  (it is, in any Vue app).
+
+The Vue barrel (`@keyfunc/keybricks-ds/vue`) is generated at publish time rather than
+committed — it statically imports `.vue` files, which only a Vue-aware bundler can resolve,
+so keeping it in the repo would break every non-Vue tool that walks the tree. `npm publish`
+and `npm pack` both produce it via the `prepack` hook; CI does it explicitly. React's barrel
+is a normal committed file.
+
+Published (`files` in `package.json`): `components/`, `tokens/`, `assets/`, `_scripts/`,
+`styles.css`, the four `.md` guides, `_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`,
+`_ds_bundle.js`. Those are the documentation site — they go to Pages, not into every
+`node_modules`.
+
+## 2. Entry points
+
+```js
+import { Button, DataTable } from '@keyfunc/keybricks-ds'            // React barrel
+import { Button } from '@keyfunc/keybricks-ds/vue'                    // Vue 3 barrel
+import Button from '@keyfunc/keybricks-ds/components/buttons/Button.vue'  // deep import
+import '@keyfunc/keybricks-ds/styles.css'                             // tokens + themes
+import { cssVar, light, dark } from '@keyfunc/keybricks-ds/tokens'     // JS constants
+import tokens from '@keyfunc/keybricks-ds/tokens.json'                 // cross-platform
+```
+
+Deep imports are the better default in Vue and in any app that cares about tree-shaking —
+a barrel of 122 exports asks the bundler to prove each one is unused.
+
+## 3. Publishing (maintainers)
+
+```bash
+# 1. edit tokens/ or components/
+node _scripts/build-tokens.mjs      # regenerates tokens.json / tokens.js / tokens.d.ts
+node _scripts/build-index.mjs       # regenerates the React/Vue barrels
+npm run check                      # same two scripts in --check mode; CI runs this
+
+# 2. bump, commit, tag — the tag is what publishes
+npm version minor -m "feat: 3D chart family"
+git push && git push --tags
+```
+
+`.gitlab-ci.yml` then runs: `generated:check` → `version:check` (tag must equal
+`package.json` version) → `npm publish` → `pages`.
+
+**Versioning policy.** A token's *value* changing is a minor; a token being *renamed or
+removed* is a major, because consumer code references `var(--name)` directly. Adding a
+component or a prop is a minor. Changing a component's default appearance is a major —
+consumers pin a version precisely so a redesign never lands unannounced.
+
+## 4. Consuming (app developers)
+
+**Install — registry**
+
+Commit a project-local `.npmrc` 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}
+```
+
+```bash
+npm install @keyfunc/keybricks-ds
+```
+
+`GITLAB_TOKEN` is a personal or group deploy token with `read_package_registry`. In CI,
+GitLab injects `CI_JOB_TOKEN` — use that instead and no secret is stored anywhere.
+
+**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"
+```
+
+Because the package has no build step, a git dependency needs no `prepare` script — npm
+checks out the tag and the files are already usable. Pin a tag, never a branch.
+
+**Vite (React)**
+
+```js
+export default defineConfig({
+  plugins: [react({ include: [/\.jsx?$/, /node_modules\/@keyfunc\/keybricks-ds\/.*\.jsx$/] })],
+  optimizeDeps: { exclude: ['@keyfunc/keybricks-ds'] },
+})
+```
+
+**Next.js**
+
+```js
+module.exports = { transpilePackages: ['@keyfunc/keybricks-ds'] }
+```
+
+Then, once, at the app entry: `import '@keyfunc/keybricks-ds/styles.css'`.
+
+## 5. Documentation site (Pages)
+
+The `pages` job copies the static tree into `public/` on every default-branch commit.
+Your Pages URL (shown under *Deploy → Pages* after the first run) then serves:
+
+- `index.html` — the browsable system: every card live in an iframe, EN / 中文 / 日本語,
+  light and dark, View Code on each component.
+- `gallery.html` — filterable thumbnail grid.
+- `DESIGN.md` — the rules file to hand to an AI coding agent or a new hire.
+
+If Pages is restricted to project members (Settings → Pages → *Access Control*), this is
+also the safest place to review upcoming work with people who have no repo access.
+
+## 6. Keeping consumers honest
+
+`_adherence.oxlintrc.json` is published as `@keyfunc/keybricks-ds/lint`. Extend it in the
+consuming app to fail CI on the two rules that break theming:
+
+- a raw hex, `rgb()` or named color in component code
+- a palette step (`--neutral-500`, `--blue-600`) referenced instead of a semantic token
+
+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.

package/DESIGN.md

@@ -0,0 +1,269 @@
+# DESIGN.md — Keybricks
+
+Rules for AI coding agents generating Keybricks UI. Read this before writing any markup or CSS.
+
+Values here are **absolutes, not suggestions**. Where a number is given, use that number.
+
+---
+
+## The one rule that matters most
+
+**Never write a raw hex, px size, or radius when a token exists.** Every value below is a CSS
+custom property defined in `styles.css`. Referencing the token gets you dark mode, the retheme
+path, and consistency for free. Writing `#155dfc` gets you a light-mode-only bug.
+
+```css
+color: var(--text-body);          /* ✅ */
+color: #525252;                   /* ❌ same color today, broken in dark mode */
+color: var(--neutral-600);        /* ❌ palette step — does not flip between themes */
+```
+
+Palette steps (`--neutral-*`, `--blue-*`) are raw material. **Only semantic roles
+(`--text-body`, `--bg-surface`, `--action-primary`) may appear in component code.**
+
+---
+
+## Colors
+
+One action hue. Color carries meaning; the interface itself is near-monochrome.
+
+### Surfaces
+| Token | Light | Use |
+| --- | --- | --- |
+| `--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-hover` | `#f5f5f5` | Row / item hover |
+| `--bg-active` | `#f5f5f5` | Selected nav pill, toggled control |
+| `--bg-press` | `#e5e5e5` | Press wash |
+| `--bg-scrim` | `rgba(10,10,10,.32)` | Behind modals |
+
+Surfaces get **lighter as they nest** in light mode, **brighter** in dark mode. Use them in
+order (`app` → `surface` → `raised`) and depth reads correctly in both themes.
+
+### Text
+| Token | Light | Use |
+| --- | --- | --- |
+| `--text-primary` | `#0a0a0a` | Maximum emphasis |
+| `--text-heading` | `#171717` | Headings, table headers |
+| `--text-body` | `#525252` | Default body text |
+| `--text-secondary` | `#737373` | Meta, labels, captions |
+| `--text-muted` | `#a1a1a1` | Placeholder, disabled glyph |
+| `--on-accent` | `#ffffff` | Text on any saturated fill — **both themes** |
+
+### Borders
+| Token | Light | Use |
+| --- | --- | --- |
+| `--border-card` | `rgba(229,229,229,.6)` | Card hairline |
+| `--border-control` | `#e5e5e5` | Input / button edge |
+| `--border-subtle` | `#f5f5f5` | List and table dividers |
+| `--focus-border` | `#2b7fff` | Keyboard focus outline |
+
+### Action
+| Token | Light | Use |
+| --- | --- | --- |
+| `--action-primary` | `#155dfc` | Primary button, link |
+| `--action-primary-hover` | `#1447e6` | Hover |
+| `--action-primary-active` | `#1039c4` | Press |
+| `--soft-bg` | `#eff6ff` | Tinted button surface |
+| `--action-dark` | `#171717` | Dark pill (AI actions) |
+
+### Feedback — always a trio (solid / tint / text-on-tint)
+| Meaning | Solid | Tint bg | Text on tint |
+| --- | --- | --- | --- |
+| Success | `--success` `#00bc7d` | `--success-bg` | `--success-text` |
+| Warning | `--warning` `#ffb900` | `--warning-bg` | `--warning-text` |
+| Danger | `--danger` `#fb2c36` | `--danger-bg` | `--danger-text` |
+| Info | `--action-primary` | `--info-bg` | `--info-fg` |
+
+Never put `--success` (the solid) behind text — use the `-bg` / `-text` pair.
+
+### Charts
+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
+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
+light, faces shaded by color-mix on the series color; pitch clamps to 8–80° and 3D pies never orbit.
+
+### Node-category hues (pipeline surface only)
+`--cat-source` green · `--cat-join` blue · `--cat-transform` orange · `--cat-merge` purple ·
+`--cat-output` teal. Each has a `-bg` tint for its icon tile. Hue means **category**; the four
+feedback colors mean **severity**. Do not mix the two vocabularies.
+
+---
+
+## Typography
+
+`--font-sans` is Inter. `--font-mono` is Menlo. There is no third family.
+
+| 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.
+
+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.
+
+---
+
+## 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.
+
+**Page rhythm**: `--page-pad-y` 24px · `--page-pad-x` 32px · `--section-gap` 24px ·
+`--card-pad` 21px (`--card-pad-sm` 17px for dense cards).
+
+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.**
+
+**Shadows** — four, and only four: `--shadow-node` (canvas cards), `--shadow-menu` (dropdowns,
+popovers), `--shadow-modal` (modals), `--shadow-selected` (selected node). Cards in content
+areas use a **border, not a shadow**.
+
+---
+
+## Motion
+
+`--dur-fast` 120ms (hover) · `--dur` 160ms (default) · `--dur-slow` 240ms (overlays).
+Easing is `--ease-out` for entrances, `--ease-in-out` for state changes.
+
+Use the prebuilt recipe rather than hand-writing transitions:
+
+```css
+transition: var(--t-hover);   /* background, border-color, color */
+```
+
+Nothing bounces. Nothing slides more than a few pixels. Keyframes available:
+`kb-fade-in`, `kb-rise`, `kb-toast-in`, `kb-spin`, `kb-pulse`, `kb-slide-in`.
+
+---
+
+## 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`)
+- **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
+
+For this to work on a custom clickable element, give it a role and make it focusable:
+
+```jsx
+<div role="button" tabIndex={0} onClick={...}>   {/* ✅ press + focus + keyboard */}
+<div onClick={...}>                              {/* ❌ inert, unreachable by keyboard */}
+```
+
+### Drag targets say what will happen
+
+An indicator appears **only where a drop is legal**, and its shape names the operation:
+
+- **Move into a container** — the whole target row fills `--soft-bg` with a 2px
+  `--action-primary` outline. Never a half-height box: the target is the row, not an edge.
+- **Insert between** — a 2px `--action-primary` rule inset at the row's top or bottom edge.
+  Only where ordering is a real operation (`Tree` opts in with `reorder`).
+- **Nothing** — hovering an illegal target (a file, a disabled row, a node's own subtree)
+  shows no indicator at all. An indicator for a drop that would be rejected is a lie.
+- **Connecting two things** (pipeline ports) — the source handle stays lit, a dashed
+  `--action-primary` bezier follows the cursor, and the reachable end point lights and swaps
+  its glyph for a crosshair. Snapping is by distance, not by hover, so the wire lands even
+  when the cursor is over the canvas rather than exactly on the 22px handle.
+
+---
+
+## 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 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 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).
+- **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 animate anything longer than 360ms** or with a bounce/elastic easing.
+
+---
+
+## Voice
+
+Direct, lowercase-shy, no exclamation marks. Address the user as *you*; never say *we*.
+Buttons are verbs (`Submit`, `Run Test`, `Export Log`), not `Click here` or `OK`.
+Empty states say what will appear and how to make it appear. Errors say what failed and what
+to do next — never `Oops!` or `Something went wrong`.
+
+---
+
+## Working with the components
+
+Prefer composing existing components over writing markup. The full index with import paths is
+in `INTEGRATION.md`; per-group usage notes are in each `components/<group>/*.prompt.md`; every
+component has a `.d.ts` next to it with the exact props contract.
+
+**When unsure how something should look, read a real card** in `components/_cards/` — those
+are the reference implementations and they are more reliable than any description here.
+
+```jsx
+import { Button, Field, Input, Card } from '@keyfunc/keybricks-ds'
+
+<Card>
+  <Field label="Run name" required>
+    <Input placeholder="August close" />
+  </Field>
+  <Button variant="primary">Start run</Button>
+</Card>
+```