klun-ui 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -5,7 +5,298 @@ All notable changes to **klun-ui** are documented here. The format follows
 [Semantic Versioning](https://semver.org/) (pre-1.0: minor/patch bumps may carry
 small breaking changes).
 
-## [Unreleased]
+## [0.6.0] — 2026-10-06
+
+KDS 设计标准升级。**含破坏性变更**——完整迁移指引见 `docs/design-standards/MIGRATION.md`。
+
+### Breaking
+- **移除 `FormInstance.registerRules`** —— 请改用 `<FormItem rules={…} />`。
+  依据：源码中已标 `@deprecated`，且**已登记消费者零使用**。
+- **移除 `DrawerProps.side`** —— 请改用 `placement`（支持 `top`/`right`/`bottom`/`left`，比 `side` 更宽）。
+- **覆盖层 `align` 默认值由物理改为逻辑**（`Popover`/`Dropdown`/`SelectMenu`/`DatePicker`/
+  `DateRangePicker`/`DateTimePicker`）：默认 `"start"`。**LTR 行为不变**，RTL 下改为贴内联起始边（修复锚错边）。
+  需要原有物理行为时显式传 `align="left"` / `align="right"`。
+
+### Added
+- **按下态反馈**：Button / IconButton / CopyButton 新增 `translateY(1px)`。
+- **RTL 逻辑属性**：RangeSlider 镜像、Tree 层级缩进、Notification 关闭按钮、Chip 内边距、
+  CodeViewer 浮动按钮、覆盖层对齐。
+- **密度跟随**：`Result`/`EmptyState`/`Collapse`/`Accordion`/`Sidebar`/`Chip`/`Message`/`Banner`/
+  `Notification`/`Timeline`/`CodeViewer`/`DiffViewer`/`Kanban`/`RichEditor` 在 `density="compact"` 下
+  跟随缩放（此前保持桌面留白）。
+- **长文案健壮性**：`Alert`/`Banner`/`Notification`/`Message`/`Tabs`/`StepIndicator`/`Timeline`/
+  `ChartLegend`/`DiffViewer` 在超长文本下折行或可滚动（此前溢出或被静默裁掉）。
+- **代码块横向滚动**：`CodeViewer` / `DiffViewer` 的长行可横向滚动查看，不再被裁掉。
+
+### Fixed
+- **`CodeViewer` / `LogViewer` 的 `--dark` 变体在暗色主题下白底白字**（对比度 **1.0**，代码不可见）。
+  根因：背景用了会随主题翻转的 `--klun-bg-strong-950`，而文字是写死的白色。
+  改用主题恒定的 `--klun-static-static-black`（**浅色下同值，浅色观感不变**）。
+- **焦点环**由「2px 白 + 2px 主色」收窄为单层 2px，且补上 `RichEditor` 编辑区缺失的焦点样式。
+- **`prefers-reduced-motion`**：5 个文件 6 个动画补齐降级。
+- 约 35 个组件的次要文字加深，达到对比度要求。
+- 暗色皮肤覆写此前**未真正生效**，已修复。
+
+### Changed
+- **控件尺寸**：默认档 32/36/40/48、紧凑档 28/32/36/40；圆角 6/6/8/10；正文 14/20。
+- **`kk` 皮肤**控制高度由「全部 32px」改为**五档** 20/24/28/32/36（默认档仍 32px，常规观感不变）。
+
+### Known issues（**已知未修，待设计决策**）
+- **按钮文字对比度**：12 种样式（3 变体 × 4 外观）里 **8 种**在多数主题组合下低于 4.5:1
+  （`neutral` 四种全部达标）。
+- **Badge 强调色对比度**：`filled` 外观 **5/6 色相**不达标，`orange-filled`/`yellow-filled` **全组合不达标**。
+  根因：`filled` 对所有色相统一用白字，而黄/橙是浅色相（对照 `lighter` 外观**已按色相**配深色文字）。
+  修法需**加深强调色**或**按色相配文字色**，两者都改变品牌观感，故本版未改。
+- 读屏实际朗读、真机触摸、forced-colors、200% 文字与 320px 重排**未验证**。
+
+## [0.5.0] — 2026-09-29
+
+### Added
+- **`kk` theme** (`src/styles/tokens/kk-theme.css`, ships with `styles.css`) — the
+  admin-console skin, activated with `data-mode="kk"` or `<ConfigProvider accent="kk">`.
+  It carries a `--kk-*` palette (light + dark) that re-points the klun semantic
+  tokens (so Button / Input / Switch / Modal / Cascader… render in the console
+  style on their own) plus the shared console blocks — `.kk-page`, `.kk-aside`,
+  `.kk-node`, `.kk-toolbar`, `.kk-btn`, `.kk-table` (+ `--grid` form table),
+  `.kk-check`, `.kk-switch`, `.kk-pager`, `.kk-move`, form rows… — so a console
+  page ships markup instead of its own stylesheet. The SCUI console pages
+  (用户管理 / 菜单管理 / 字典管理) now carry **no page CSS at all** and the shell
+  sets `data-mode="kk"` on its root, so the klun components they embed
+  (`IconPicker`, `Modal`, `Cascader`, `Popconfirm`) pick up the console palette too.
+  The console **shell frame** moved in as well (`:where([data-mode="kk"]) .scui*`
+  blocks — 65px rail, 210px panel, 50px topbar, 35px tag bar, drawer, with the
+  `--scui-*` palette), so `ScuiShell` ships no CSS either. `:where()` keeps every
+  selector at the specificity it had inline, and the root itself is matched with
+  `.scui:where([data-mode="kk"])` (the attribute sits on that element, not an
+  ancestor — a plain descendant selector silently skips the root).
+  **kk is square (直角)**: every *corner* radius token collapses to 0 (only real
+  circles — avatars, switch knobs, round icon buttons — keep their 50%), and klun
+  components embedded in a console page are skinned to the same standard: 32px
+  control height, square corners, Element Plus colours (buttons: `primary` filled
+  blue, `neutral`/`stroke` white + `#dcdfe6` border; dialogs: 16px padding, no
+  divider above the buttons), and the Cascader fills its field, is 32px tall and
+  keeps its dropdown left-aligned with 108px columns, so even a two-column panel
+  stays inside the narrowest console dialog. The console's element resets sit in
+  `:where()` end-to-end (zero specificity) — at (0,2,0) they used to beat a
+  component's own rules, e.g. wiping the Cascader trigger's inner padding.
+  Row actions are one icon family (Element Plus `Edit` / `Plus` / `Delete` SVGs,
+  exported from the SCUI pages as `IconEdit` / `IconPlus` / `IconDelete` — no
+  Remix font icons mixed in) and carry no frame: `.kk-iconbtn` defaults to a
+  transparent border, so a row's 编辑/删除 reads as two bare icons, while the
+  `--plain` / `--primary` / `--danger` variants opt back in with their own border
+  (previously the base left the border colour unset, which painted it
+  `currentColor` — a dark box around every action).
+  One **6px scrollbar for every scrolling console block** (`--kk-scrollbar` /
+  `--kk-scrollbar-hover`, Element Plus' translucent grey: reads on light and
+  dark, rails keep their own light thumb) instead of the browser's fat default,
+  plus the two form controls a console page was missing: `.kk-textarea` and the
+  disabled state of `.kk-input` (`--kk-hover` fill, weak text).
+- `ScuiDictPage` — SCUI's 配置 → 字典管理 page: 300px dictionary-type tree
+  (filter, hover 编辑/删除, 字典分类 button) + the item table (selection, drag
+  handle column, 名称 / 键值 / 是否有效 switch / 操作) with a pager. Both sides are
+  editable (dialogs via `Modal` + `Cascader`, `Popconfirm` for row delete) and
+  both sides reorder by drag (dnd-kit, siblings-only for the tree). It is the
+  first console page with **no page CSS at all** — everything comes from the `kk`
+  theme.
+- `ScuiDeptPage` (`src/templates/scui/DeptPage.tsx`) — SCUI's 配置 → 部门管理
+  page, 左树右明细: a 300px organisation tree (keyword filter, expand/collapse,
+  sibling drag sorting, footer 新增子部门 / 删除 acting on the selection) and the
+  明细 pane on the right — 部门名称 / 部门编码 / 上级部门 (read-only, the hierarchy
+  comes from 新增子部门) / 负责人 / 联系电话 / 状态 switch / 备注 / 创建时间, saved with
+  保存 and reverted with 重置. Deleting a branch warns about its children first.
+  Ships `SCUI_DEPTS` (3 levels) and the same demo data shape as the other pages.
+- `ScuiRolePage` (`src/templates/scui/RolePage.tsx`) — SCUI's 配置 → 角色管理
+  page, 左角色列表 + 右权限树: the 300px list holds 名称/标识 (keyword filter, hover
+  编辑, footer ＋ 新增角色 / 🗑 删除 with a warning about the granted permissions),
+  the right pane is the selected role's 菜单权限树 built from the console's own
+  navigation (`SCUI_PERM_TREE`, 78 nodes, 3 levels, expanded by default).
+  **改动即保存** — a click writes into the role， no 保存 button. A node counts as
+  granted only when its whole branch is (`aria-checked="mixed"` + the new
+  `.kk-check.is-half` dash while partial), so clicking a half-granted group grants
+  or clears its entire branch; the toolbar carries 全选 / 清空 and the
+  `已授权 N 项` count.
+- `ScuiWorkflowPage` (`src/templates/scui/WorkflowPage.tsx`) — SCUI's 组件 →
+  工作流设计器 page: a **1:1 port** of the live demo's `vab/workflow` canvas (the
+  vue-admin-beautiful "workflow-design" component). The original class names and
+  values live in `kk-theme.css` under `.sc-workflow-design` (12px content font,
+  220×72 cards, 4px radius, `0 2px 5px rgba(0,0,0,.1)`, 24px title bars in
+  `#576a95` 发起人 / `#ff943e` 审批人 / `#3296fa` 抄送人, 2px `#cacaca` connectors,
+  `#cccccc` branch rules with cover lines masking their ends, `54.5px 0` canvas
+  padding, 10px `#dbdcdc` end dot) — verified by measuring live and port with the
+  same selectors: every value matches (the last 1px on the condition card is line
+  box rounding). Interaction: every card is followed by a round ＋ whose popup
+  (270px, right of the button) appends 审批节点 / 抄送节点 / 条件分支 — a column's ＋
+  sits between its condition card and the branch's steps, exactly like the live
+  one; ✕ deletes a node or a 条件 (hover); ▸/◂ swap the 优先级 columns. Clicking a
+  card opens its config drawer: steps edit 节点名称 / 负责人, 条件 opens the 600px
+  **条件设置** drawer — editable title (pencil), 条件关系 且/或, and the
+  描述 / 条件字段 / 运算符 / 值 / 移除 table with 暂无数据, ＋ 增加条件 and 保存 / 取 消
+  (the drawer works on a copy, so 取消 really drops the edits; the else branch
+  keeps 其他条件进入此流程 and offers no rows). 导出 JSON still dumps the tree.
+  The 条件字段 list is **data-driven** (`WF_FIELDS`: label + kind + options) and the
+  rest of the row follows it — 请假天数 offers the six comparison operators and a
+  number input, 请假类型 the four text ones (`= != 包含 不包含`) and a dropdown of its
+  own options — so changing the field rewrites the operator list and the value
+  control, the way the live form does.
+- 审批 / 抄送 nodes carry the live demo's **人员设置**: 审批人员类型 (指定成员 / 主管 /
+  角色 / 发起人自选 / 发起人自己 / 连续多级主管), a ＋ 选择人员 button growing 人员 chips
+  (× removes one), ☐ 超时自动审批 and 多人审批时审批方式 (按顺序依次审批 / 会签 / 或签).
+  The type actually takes effect: 指定成员 opens the 640px 人员选择 dialog (部门导航
+  filters the member list, 请输入成员姓名 searches it, 已选 (N) collects the picks),
+  角色 opens the 460px 角色选择 dialog, and the kinds that need no picker (主管 /
+  发起人自选 / 发起人自己 / 连续多级主管) hide the row and write the type onto the card.
+  保存 joins the picked names into the card's second line.
+- A **`Fixed`** note for the same page: an empty 条件 column renders a **single** ＋ now
+  (its own, between the condition card and the — empty — step chain) instead of
+  stacking the chain's fallback ＋ under it, so a fresh 条件 shows one unbroken 单线; the
+  **汇聚点** ＋ the live demo puts under a 条件组 (inside `.branch-box-wrap`, after
+  `.branch-box`) is back too — both shapes were measured against the live page with the
+  same selectors (`branch-box-wrap` children = `branch-box, add-node-btn-box`).
+- **工作流设计器拆成模块组** (`src/templates/scui/workflow/`): `model.ts` (节点/条件类型、
+  演示数据、`opsFor` / `summaryOf` / `scopeLabel` / `edit` 等纯函数), `WorkflowGlyphs.tsx`
+  (原版 SVG), `WfMemberPicker.tsx` 与 `WfScopePicker.tsx` (两张选择弹窗) — `WorkflowPage.tsx`
+  只留画布与两个抽屉（1386 → 919 行），并 `export *` 保持原来的导入路径与公开面不变。
+- `src/templates/scui/tree.ts` — the tree helpers (path lookup, insert/update/
+  remove, filter, flatten, `collectIds`) shared by the 菜单管理 / 字典管理 / 部门管理
+  trees — a keyword filter passes `collectIds(...)` as the open list, so matches
+  inside collapsed branches show up instead of staying hidden (the 菜单管理 tree
+  now does the same).
+- `IconPicker` (`src/components/forms/`) — generic icon picker: a 38×32 icon-only
+  trigger (like SCUI's 菜单图标 field) opening a 520px dialog with category tabs,
+  an auto-filling grid, live search across every group, a 清除 action and Esc/✕ to
+  bail out. Picking commits straight away — no OK button.
+  Ships `ICON_GROUPS` (100 Remix line icons in 5 categories); `groups` + `renderIcon`
+  swap in any other icon set. Built on `Modal` and the `--klun-*` tokens, so it
+  follows the host page's light/dark palette (`data-theme="dark"`); the SCUI shell
+  root now carries that attribute for the components it embeds.
+- **SCUI shell template** (`src/templates/scui/` → `Templates/SCUI` in Storybook) —
+  a 1:1 port of the [SCUI](https://github.com/scui-plus/scui) admin layout:
+  65px dark icon rail (`#222B45`, SCUI's own SVG glyphs incl. the brand "S" mark),
+  210px secondary menu panel with collapse, 50px breadcrumb topbar with action
+  icons + notification badge + user chip, 35px multi-view tag bar (closable tabs,
+  the home tab stays), `#F6F8F9` content slot, and the floating 布局设置 drawer
+  (dark mode, accent presets, language). Dimensions/colours follow the live demo
+  instead of the klun-ui theme.
+- SCUI's **real menu tree** (`menuData.ts`, generated from the live demo): nested
+  sub-menus (组件/模板/其他), SCUI's own icon paths (30, deduplicated) and the
+  entries it leaves bare — so the panel matches the original item for item. The
+  submenu arrow is Element Plus' `ArrowDown` SVG at 12px (rotating 180° while
+  open), exactly what the live demo renders — it used to be a 24×18 Remix font
+  chevron pointing right.
+- `ScuiUsersPage` — SCUI's 配置 → 用户管理 CRUD page: department tree with filter,
+  selection toolbar (新增 / 删除 / 分配角色 / 密码重置 + search), user table
+  (ID / 头像 / 登录账号 / 姓名 / 所属角色 / 加入时间 / 操作) and the pager. The shell
+  gained `initialView` + `renderView` so tabs can mount real pages.
+- Selected-state wash in the SCUI shell: the current secondary-menu item and the
+  current department-tree node both get the light-blue highlight (`#ECF5FF`,
+  dark mode uses the themed hover colour).
+- `ScuiMenuPage` — SCUI's 配置 → 菜单管理 page: the 300px menu tree (checkbox,
+  18px indents, **hovering a row reveals its 新增 button**), the 菜单表单
+  (显示名称 / 上级菜单 / 类型 / 别名 / 菜单图标 / 路由地址 / 重定向 / 菜单高亮 /
+  视图 / 颜色 / 是否隐藏 / 整页路由 / 标签) and the 接口权限 table — its 50px first
+  column is centred (same centre line as the header's ＋) and shows the row number,
+  which swaps in place for a plain-danger circle delete button while the row is
+  hovered or focused. Dark mode covered like the other SCUI pages.
+- The 菜单管理 tree is **drag-to-reorder** (dnd-kit, same engine as `Table` /
+  `Kanban`): grab a row to sort it among its siblings — pointer or keyboard
+  (space / arrows). Nodes carry stable ids, so the open/checked/selected state
+  survives reorders, and a drag toward another branch never reparents.
+- Dark mode follows the live demo's Element Plus dark palette — rail `#141414`,
+  panel/topbar/tag bar `#1D1E1F` with `#414243` borders, content `#141414`,
+  menu/breadcrumb text `#D0D0D0`/`#CFD3DA`, hover wash `#0C1F32`, table borders
+  `#363637` — and the ported 用户管理 page carries its own dark overrides.
+- **klun-web console, ported page by page** (`src/templates/scui/` → story
+  `Templates/SCUI → Console — 全站（所有页面）`). The whole admin console is rebuilt
+  in the SCUI language on **one entry point**: `KLUN_PAGES` maps a view key
+  (`<group>/<label>`) to a page element and `KlunConsoleShell` renders it through
+  the SCUI shell with klun-web's own 7-group menu, so a new page is one line in
+  the registry — the shell, the menu and the stylesheet stay untouched.
+  Each page is self-contained demo data shaped like klun-web's `lib/api/klun.ts` types —
+  CRUD pages really mutate (注册/同步集群, 封锁节点, 伸缩副本, 添加解析, 签发证书…),
+  read-only pages (网络/存储/配置) show live-looking state.
+- **The port now covers every klun-web menu entry** — 31/31 entries plus klun-ui's own
+  字典管理 · 工作流设计器: 控制台/概览 · 收件箱, 运维/资产管理 · 审计日志 · 会话审计,
+  服务与监控/应用清单 · 域名探活 · 接口监控 · 告警 · 告警规则, 容器管理/集群 · 节点 ·
+  命名空间 · 工作负载 · 网络 · 存储 · 配置 · 诊断, 云服务/Cloudflare 账号 · DNS 解析 ·
+  站点设置 · 证书 · Google 账号 · 云盘, 团队/用户管理 · 角色管理 · 部门管理,
+  系统/版本发布 · 配置中心 · 设置 · 菜单管理 · 字典管理 · 工作流设计器.
+  The system pages keep their real behaviour: 版本发布 knows the "latest" rule (highest
+  `active` version per app), warns before disabling/revoking and shows a version's
+  artifacts with their sha256; 配置中心 never echoes secret values (it shows
+  「已配置（不回显）」 and treats an empty secret value as "keep the stored one"); 设置
+  renders appearance changes on a real preview element (`data-theme` / `data-density` /
+  `data-radius` on the preview card) and walks through MFA enrolment, recovery-code
+  rotation and per-device session revocation; 收件箱 marks a message read when its detail
+  opens, and can send to everyone or to picked members.
+- The remaining non-menu klun-web screens (登录 / 403 / 404 / CLI 授权 / 终端) are not
+  ported — they sit outside the console's navigation.
+- **Shared console pieces** instead of per-page styling: `ScuiPage` (the five-slot
+  skeleton — head / stat cards / toolbar / body / pager, each slot opt-in) with
+  `ScuiStat` + `ScuiPager`, `containerModel.tsx` (the cross-cluster dataset, a
+  `ScuiScopeBar` cluster+namespace scope bar with `hideNamespace` for cluster-scoped
+  resources, and `ScuiFailedBanner` for "some clusters could not be read" with the
+  real error text), `cloudModel.tsx` (Cloudflare + Google dataset, a `ScuiCloudBar`
+  account/zone scope bar, `formatSize`, `driveIcon`) and `consoleFormat.ts`. New `kk`
+  blocks back them: `.kk-scope(--field/--refresh/--hint)`, `.kk-banner`, `.kk-summary`,
+  `.kk-message`, `.kk-textarea--mono`, `.kk-tip--block`.
+- The Cloudflare / Google flows keep their real shape: the account pages open the
+  authorization window and only write the account back once it returns; 站点设置 renders
+  the editor that matches each setting's value type (switch / number / enum / string /
+  read-only JSON) and tracks unsaved drafts; 证书 issues Origin CA certificates whose
+  private key is shown exactly once; 云盘 keeps a breadcrumb path stack and can search
+  across folders.
+- Two console fixes found by porting: `.kk-node-do` (the row action group) is
+  hidden until its `.kk-node` row is hovered — right for tree rows, invisible for
+  table rows, so `.kk-table .kk-node-do` is now always shown; and Remix font icons
+  inherit the row's `line-height` (56px menu rows) which draws the glyph below the
+  baseline — every `i.ri-*` inside `[data-mode="kk"]` is normalised to
+  `line-height: 1` + inline-flex centring.
+- **`Sidebar`** — two-level navigation ported 1:1 from the “Minimalist sidebar”
+  Figma Make community file: a 64px icon rail (brand slot, nav items, foot items,
+  avatar) beside a 320px detail panel that collapses to the rail width with the
+  original soft-spring animation (500ms, `cubic-bezier(0.25, 1.1, 0.4, 1)`;
+  override `--klun-sidebar-ease` for the stock klun curve). Data-driven
+  (`navItems` / `footNavItems` / `sections`, icons as `ReactNode`), controlled or
+  uncontrolled rail selection and collapse, expandable rows, optional search.
+  Geometry matches the source (40px rows, 16px shell / 8px row radii, 36px nested
+  indent); colours ride the klun semantic tokens, so it re-themes in light/dark —
+  dark lands on the original near-black surfaces. The story ships the full
+  eight-section demo data set from the community file.
+- **Multica UI migration** — ten components ported from the Multica UI
+  (`packages/ui`) into the klun class + token architecture, dependency-free:
+  `ActorAvatar` (member / agent / squad / system + `emoji:` avatars),
+  `ReactionBar` (+ `groupReactions`), `EmojiPicker` / `QuickEmojiPicker` (built-in
+  trimmed emoji-mart dataset, grouped and searchable), `ShimmerText`,
+  `UnicodeSpinner` (18 braille/unicode frame sets), `BorderBeam`,
+  `NumberFlow` (+ currency / compact / capped variants — a rolling-digit
+  implementation, no `@number-flow` dependency), `DotSphere` (canvas),
+  `ListGrid` (subgrid list with sortable headers) and `CapabilityBanner`.
+  Colours ride the klun tokens (light/dark); geometry, copy and animations
+  follow the originals (border beam tinted to the theme accent).
+- **Multica UI migration, part two** — six more components ported from the Multica
+  UI, again dependency-free: `Toggle` (pressed button, default / outline, three
+  sizes), `HoverCard` (hover/focus popover with open+close delays, four sides,
+  controlled or not, click-through inside the panel), `InputGroup` (+ `Input` /
+  `Addon` / `Text` / `Button` — inline or block affixes, click-to-focus, four
+  button sizes), `Field` (+ `FieldGroup` / `FieldContent` / `FieldLabel` /
+  `FieldTitle` / `FieldDescription` / `FieldError` — vertical or horizontal
+  forms, `invalid` sets `role="alert"` errors in red), `Item` (+ `ItemGroup` /
+  `ItemSeparator` / `ItemMedia` / `ItemContent` / `ItemTitle` / `ItemDescription` /
+  `ItemActions` / `ItemHeader` / `ItemFooter` — list rows with icon or image
+  media) and `Stepper` (+ `StepperNav` / `StepperItem` / `StepperTrigger` /
+  `StepperIndicator` / `StepperSeparator` / `StepperTitle` / `StepperDescription` /
+  `StepperPanel` / `StepperContent` — tab-style steps, horizontal or vertical,
+  completed / loading states, arrow-key navigation).
+- **Multica UI migration, part three — from `packages/views`** — the product
+  layer of the Multica repo was swept for library-grade pieces; two made the
+  cut (the rest are page logic tied to their router / data layer):
+  `ActivityHeatmap` (zero-dependency GitHub-style calendar heatmap on a plain
+  `date -> value` map — quartile colour ramp riding the theme accent, month /
+  weekday labels via `Intl`, plus pure `buildHeatmapGrid()` / `summarizeHeatmap()`
+  helpers for custom insights panels) and `NavigationProgress` (2px
+  indeterminate top progress bar for route transitions — `active`-driven,
+  `position: fixed | absolute`, sweep mounted only while visible,
+  `prefers-reduced-motion` aware).
 
 ## [0.4.1] — 2026-09-17
 

package/README.md

@@ -1,5 +1,11 @@
 # klun-ui
 
+## Klun Design Standard
+
+KDS `1.0.0-draft.1` is a proposed design, component, interaction and quality standard. It does not mean the current library already complies; adoption and implementation require the documented review and migration process.
+
+The standard lives in the repository at `docs/design-standards/` (start with `README.md`, full text in `COMPLETE.md`, upgrade work packages in `UPGRADE-PLAN.md`). It is **not** included in the published npm tarball — `package.json` `files` ships only `dist`, `README.md`, `CHANGELOG.md` and `LICENSE`. Whether the KDS should be published (and how, given `docs/design-standards/references/` contains large HTML snapshots) is tracked as U23 in the upgrade plan.
+
 [![npm version](https://img.shields.io/npm/v/klun-ui)](https://www.npmjs.com/package/klun-ui)
 [![license](https://img.shields.io/npm/l/klun-ui)](./LICENSE)
 [![types included](https://img.shields.io/npm/types/klun-ui)](https://www.npmjs.com/package/klun-ui)
@@ -96,12 +102,12 @@ For extra-fine control, the button family adds a `size="tiny"` tier (28px, icon-
 
 | Group | Components |
 |---|---|
-| **Buttons** | Button (kinds: default / fancy / compact / link), ButtonGroup, CopyButton |
-| **Forms** | AutoComplete, Cascader, CharacterCounter, Checkbox, CheckboxGroup, CheckboxCard, ColorDot, ColorPicker, ColorSlider, CompactSelect, CompactSelectForInput, CounterInput, CronEditor, DatePicker, DateRangePicker, DateTimePicker, DigitInput, FileUpload, Form (+ FormItem, FormList, useForm), Hint, ImageUpload, InlineInput, InlineSelect, Input, Label, PasswordStrength, Radio, RadioCard, RangeSlider, RichEditor, RichEditorToolbar, Select, SelectMenu, Slider, Switch, Textarea, TimePicker |
-| **Data display** | Avatar, AvatarGroup, Badge, BulkActionBar (+ BulkAction), Carousel, ChartLegend, ChartTooltip, Chip, CodeViewer (+ LogViewer), ContentLabel, CrossRefBadge, Descriptions, DiffViewer, Kbd, Kanban, KeyIcon, List (+ ListItem), Markdown, Money, Rating, RelativeTime (+ ExpiryCountdown), StatCard, Statistic, StatusBadge, StatusDot (+ LiveDot), Table, Tag, Timeline, Tooltip, Tree, VirtualTable |
-| **Feedback** | Alert, Banner, CircularProgress, EmptyState, GaugeBar, Message (useMessage), Notification (useNotification), ProgressBar, Result, SegmentedProgress, Skeleton, Spinner, Toast, Toaster (+ toast) |
-| **Navigation** | Breadcrumb, Divider, HorizontalFilter, Menu, PageHeader, Pagination, SegmentedControl, StepIndicator, Tabs, Wizard |
-| **Overlays** | CommandMenu, Confirm, ContextMenu, Drawer, Dropdown, ImageViewer, Modal, Popconfirm, Popover |
+| **Buttons** | Button (kinds: default / fancy / compact / link), ButtonGroup, CopyButton, Toggle |
+| **Forms** | AutoComplete, Cascader, CharacterCounter, Checkbox, CheckboxGroup, CheckboxCard, ColorDot, ColorPicker, ColorSlider, CompactSelect, CompactSelectForInput, CounterInput, CronEditor, DatePicker, DateRangePicker, DateTimePicker, DigitInput, EmojiPicker, Field (+ FieldGroup / FieldContent / FieldLabel / FieldTitle / FieldDescription / FieldError), FileUpload, Form (+ FormItem, FormList, useForm), Hint, ImageUpload, InlineInput, InlineSelect, Input, InputGroup (+ Input / Addon / Text / Button), Label, PasswordStrength, QuickEmojiPicker, Radio, RadioCard, RangeSlider, RichEditor, RichEditorToolbar, Select, SelectMenu, Slider, Switch, Textarea, TimePicker |
+| **Data display** | ActivityHeatmap, ActorAvatar, Avatar, AvatarGroup, Badge, BulkActionBar (+ BulkAction), Carousel, ChartLegend, ChartTooltip, Chip, CodeViewer (+ LogViewer), ContentLabel, CrossRefBadge, Descriptions, DiffViewer, Item (+ ItemGroup / ItemSeparator / ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions), Kbd, Kanban, KeyIcon, List (+ ListItem), ListGrid, Markdown, Money, NumberFlow (+ Currency / Compact / Capped), Rating, ReactionBar, RelativeTime (+ ExpiryCountdown), ShimmerText, StatCard, Statistic, StatusBadge, StatusDot (+ LiveDot), Table, Tag, Timeline, Tooltip, Tree, VirtualTable |
+| **Feedback** | Alert, Banner, BorderBeam, CapabilityBanner, CircularProgress, DotSphere, EmptyState, GaugeBar, Message (useMessage), NavigationProgress, Notification (useNotification), ProgressBar, Result, SegmentedProgress, Skeleton, Spinner, Toast, Toaster (+ toast), UnicodeSpinner |
+| **Navigation** | Breadcrumb, Divider, HorizontalFilter, Menu, PageHeader, Pagination, SegmentedControl, Sidebar, StepIndicator, Stepper (+ StepperNav / StepperItem / StepperTrigger / StepperIndicator / StepperSeparator / StepperPanel / StepperContent), Tabs, Wizard |
+| **Overlays** | CommandMenu, Confirm, ContextMenu, Drawer, Dropdown, HoverCard (+ HoverCardTrigger / HoverCardContent), ImageViewer, Modal, Popconfirm, Popover |
 | **Disclosure** | Accordion, Collapse |
 | **Layout** | Card, Flex, Grid (Row / Col / useBreakpoint), Layout (+ Header / Content / Footer / Sider), Masonry, Space, Splitter (+ SplitterPanel) |
 | **Config** | ConfigProvider (theme / accent / radius / size / locale / dir), 17 locale dictionaries, Format utils |