@hsu-react/ui 1.0.0 → 2.0.0

package/lib/styles/tokens.json

@@ -0,0 +1,82 @@
+{
+  "$comment": [
+    "Single source of truth for the Hsu UI design tokens.",
+    "",
+    "Two consumers read this file and must never drift apart:",
+    "  1. scripts/gen-tokens-scss.cjs emits src/styles/tokens.scss (the --vita-* CSS variables)",
+    "  2. src/styles/tokens.ts turns it into antd's `theme.token` object",
+    "",
+    "It is JSON rather than TS precisely so the generator can read it without a TS runtime, and",
+    "it must stay plain values: antd derives 10-step palettes from colorPrimary via",
+    "@ant-design/colors, which needs a real colour — a `var(--vita-primary)` string would break",
+    "the derivation. That is why the CSS-variable layer is generated *from* here and not the",
+    "other way round.",
+    "",
+    "Palette follows shadcn/ui's zinc scale; the brand accent stays configurable."
+  ],
+  "primary": "#1677ff",
+  "light": {
+    "background": "#fafafa",
+    "surface": "#ffffff",
+    "muted": "#f4f4f5",
+    "border": "#e4e4e7",
+    "borderWeak": "#f4f4f5",
+    "foreground": "#09090b",
+    "mutedForeground": "#71717a",
+    "subtleForeground": "#a1a1aa",
+    "hover": "#f4f4f5",
+    "success": "#16a34a",
+    "warning": "#f59e0b",
+    "error": "#ef4444",
+    "shadow1": "0 1px 2px 0 rgba(9, 9, 11, 0.05)",
+    "shadow2": "0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06)",
+    "shadow3": "0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08)"
+  },
+  "dark": {
+    "background": "#09090b",
+    "surface": "#18181b",
+    "muted": "#27272a",
+    "border": "#27272a",
+    "borderWeak": "#1f1f23",
+    "foreground": "#fafafa",
+    "mutedForeground": "#a1a1aa",
+    "subtleForeground": "#71717a",
+    "hover": "#27272a",
+    "success": "#22c55e",
+    "warning": "#fbbf24",
+    "error": "#f87171",
+    "shadow1": "0 1px 2px 0 rgba(0, 0, 0, 0.4)",
+    "shadow2": "0 4px 6px -1px rgba(0, 0, 0, 0.5), 0 2px 4px -2px rgba(0, 0, 0, 0.4)",
+    "shadow3": "0 10px 15px -3px rgba(0, 0, 0, 0.6), 0 4px 6px -4px rgba(0, 0, 0, 0.5)"
+  },
+  "radius": {
+    "xs": 4,
+    "sm": 6,
+    "base": 8,
+    "lg": 12
+  },
+  "font": {
+    "family": "system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, \"Helvetica Neue\", \"PingFang SC\", \"Microsoft YaHei\", Arial, sans-serif",
+    "sizeSm": 12,
+    "size": 14,
+    "sizeLg": 16
+  },
+  "control": {
+    "height": 32,
+    "heightSm": 24,
+    "heightLg": 40,
+    "ringWidth": 2
+  },
+  "modalWidth": {
+    "sm": 600,
+    "md": 800,
+    "lg": 1200
+  },
+  "breakpoint": {
+    "sm": 640,
+    "md": 768,
+    "lg": 1024,
+    "xl": 1280,
+    "xxl": 1536
+  }
+}

package/lib/styles/tokens.scss

@@ -1,62 +1,109 @@
 // =============================================================
-// Hsu UI design tokens (single source of truth)
-// Two value sets, light/dark; dark is activated by html[data-theme="dark"] (Theme toggle in consuming projects)
-// or html[data-prefers-color-scheme="dark"] (dumi docs site).
-// TS-side constants live in ./tokens.ts (for JS consumers such as antd themeConfig); the two must be kept in sync.
+// 本文件由 scripts/gen-tokens-scss.cjs 从 src/styles/tokens.json 生成，请勿手改。
+// 改令牌请改 tokens.json，然后跑 `yarn tokens`（build / prepublish 会自动跑并校验）。
+//
+// 暗色由 html[data-theme="dark"] 激活（消费方主题开关），
+// 或 html[data-prefers-color(-scheme)="dark"]（dumi 文档站）。
 // =============================================================
 
 :root {
-  // ---- Colors - neutral ----
-  --cf-canvas: #f6f7f9; // Page canvas
-  --cf-surface: #ffffff; // Card/panel background
-  --cf-subtle: #fafbfc; // Table header/secondary background
-  --cf-border: #e6e8eb; // Border
-  --cf-border-weak: #eceef1; // Lighter border
-  --cf-text: rgba(0, 0, 0, 0.88);
-  --cf-text-2: rgba(0, 0, 0, 0.45);
-  --cf-text-3: rgba(0, 0, 0, 0.35);
-  --cf-row-hover: #f6f7f9;
-
-  // ---- Colors - brand & functional ----
-  --primary-color: #1677ff; // Default primary color (consuming projects may override at runtime)
-  --cf-success: #52c41a;
-  --cf-warning: #faad14;
-  --cf-error: #ff4d4f;
-
-  // ---- Fonts ----
-  --cf-font-family:
-    PingFangSC-Regular, "PingFang SC", -apple-system, BlinkMacSystemFont,
-    "Segoe UI", Roboto, "Helvetica Neue", Arial, "Microsoft YaHei", sans-serif;
-  --cf-font-size-sm: 12px;
-  --cf-font-size: 14px;
-  --cf-font-size-lg: 16px;
-
-  // ---- Border radius ----
-  --cf-radius-sm: 6px;
-  --cf-radius: 8px;
-  --cf-radius-lg: 12px;
-
-  // ---- Shadows (the CF look relies mainly on borders; shadows are for overlays only) ----
-  --cf-shadow-1: 0 1px 2px rgba(16, 24, 40, 0.05);
-  --cf-shadow-2: 0 4px 12px rgba(16, 24, 40, 0.08);
-  --cf-shadow-3: 0 8px 24px rgba(16, 24, 40, 0.12);
+  // ---- 品牌色 ----
+  // 兼容位：2.0 之前消费方就是通过覆盖 --primary-color 换主题色的，
+  // 所以真源反过来引用它，两种写法都生效。
+  --primary-color: #1677ff;
+  --vita-primary: var(--primary-color);
+  --vita-primary-foreground: #ffffff;
+  // focus ring：shadcn 的 2px 环。收成令牌之前各组件各写各的透明度
+  // （6% / 10% / 12% / 20% 都出现过），聚焦态在不同控件上深浅不一。
+  --vita-ring: color-mix(in srgb, var(--vita-primary) 35%, transparent);
+  --vita-ring-error: color-mix(in srgb, var(--vita-error) 30%, transparent);
+  --vita-ring-width: 2px;
+  --vita-focus-ring: 0 0 0 var(--vita-ring-width) var(--vita-ring);
+  --vita-focus-ring-error: 0 0 0 var(--vita-ring-width) var(--vita-ring-error);
+
+  // ---- 中性色（浅色）----
+  --vita-background: #fafafa; // 页面画布
+  --vita-surface: #ffffff; // 卡片 / 面板背景
+  --vita-muted: #f4f4f5; // 次级背景（表头、只读区）
+  --vita-border: #e4e4e7; // 边框
+  --vita-border-weak: #f4f4f5; // 更浅的分隔线
+  --vita-foreground: #09090b; // 主文字
+  --vita-muted-foreground: #71717a; // 次级文字
+  --vita-subtle-foreground: #a1a1aa; // 占位 / 禁用文字
+  --vita-hover: #f4f4f5; // 行 / 项 hover 背景
+  --vita-success: #16a34a;
+  --vita-warning: #f59e0b;
+  --vita-error: #ef4444;
+  --vita-shadow-1: 0 1px 2px 0 rgba(9, 9, 11, 0.05); // 浮层阴影 - 弱
+  --vita-shadow-2: 0 4px 6px -1px rgba(9, 9, 11, 0.08), 0 2px 4px -2px rgba(9, 9, 11, 0.06); // 浮层阴影 - 中
+  --vita-shadow-3: 0 10px 15px -3px rgba(9, 9, 11, 0.1), 0 4px 6px -4px rgba(9, 9, 11, 0.08); // 浮层阴影 - 强
+
+  // ---- 字体 ----
+  --vita-font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", "PingFang SC", "Microsoft YaHei", Arial, sans-serif;
+  --vita-font-size-sm: 12px;
+  --vita-font-size: 14px;
+  --vita-font-size-lg: 16px;
+
+  // ---- 圆角 ----
+  --vita-radius-xs: 4px;
+  --vita-radius-sm: 6px;
+  --vita-radius: 8px;
+  --vita-radius-lg: 12px;
+
+  // ---- 控件高度 ----
+  --vita-control-height: 32px;
+  --vita-control-height-sm: 24px;
+  --vita-control-height-lg: 40px;
+
+  // ---- 断点（媒体查询用不了 CSS 变量，这里只是让 JS 侧与文档能读到同一份值；
+  //      真正的断点判断走 styles/_responsive.scss 的 mixin 或 useBreakpoint）----
+  --vita-screen-sm: 640px;
+  --vita-screen-md: 768px;
+  --vita-screen-lg: 1024px;
+  --vita-screen-xl: 1280px;
+  --vita-screen-xxl: 1536px;
+
+  // ---- 兼容别名（2.0 前的 --cf-*，单向指向新名）----
+  --cf-canvas: var(--vita-background);
+  --cf-surface: var(--vita-surface);
+  --cf-subtle: var(--vita-muted);
+  --cf-border: var(--vita-border);
+  --cf-border-weak: var(--vita-border-weak);
+  --cf-text: var(--vita-foreground);
+  --cf-text-2: var(--vita-muted-foreground);
+  --cf-text-3: var(--vita-subtle-foreground);
+  --cf-row-hover: var(--vita-hover);
+  --cf-success: var(--vita-success);
+  --cf-warning: var(--vita-warning);
+  --cf-error: var(--vita-error);
+  --cf-font-family: var(--vita-font-family);
+  --cf-font-size-sm: var(--vita-font-size-sm);
+  --cf-font-size: var(--vita-font-size);
+  --cf-font-size-lg: var(--vita-font-size-lg);
+  --cf-radius-sm: var(--vita-radius-sm);
+  --cf-radius: var(--vita-radius);
+  --cf-radius-lg: var(--vita-radius-lg);
+  --cf-shadow-1: var(--vita-shadow-1);
+  --cf-shadow-2: var(--vita-shadow-2);
+  --cf-shadow-3: var(--vita-shadow-3);
 }
 
 html[data-theme="dark"],
 html[data-prefers-color="dark"],
 html[data-prefers-color-scheme="dark"] {
-  --cf-canvas: #131314;
-  --cf-surface: #1c1c1e;
-  --cf-subtle: #232325;
-  --cf-border: rgba(255, 255, 255, 0.12);
-  --cf-border-weak: rgba(255, 255, 255, 0.08);
-  --cf-text: rgba(255, 255, 255, 0.85);
-  --cf-text-2: rgba(255, 255, 255, 0.45);
-  --cf-text-3: rgba(255, 255, 255, 0.35);
-  --cf-row-hover: rgba(255, 255, 255, 0.04);
-
-  // Deeper shadows in dark mode (to distinguish overlays from the dark background)
-  --cf-shadow-1: 0 1px 2px rgba(0, 0, 0, 0.35);
-  --cf-shadow-2: 0 4px 12px rgba(0, 0, 0, 0.45);
-  --cf-shadow-3: 0 8px 24px rgba(0, 0, 0, 0.55);
+  --vita-background: #09090b;
+  --vita-surface: #18181b;
+  --vita-muted: #27272a;
+  --vita-border: #27272a;
+  --vita-border-weak: #1f1f23;
+  --vita-foreground: #fafafa;
+  --vita-muted-foreground: #a1a1aa;
+  --vita-subtle-foreground: #71717a;
+  --vita-hover: #27272a;
+  --vita-success: #22c55e;
+  --vita-warning: #fbbf24;
+  --vita-error: #f87171;
+  --vita-shadow-1: 0 1px 2px 0 rgba(0, 0, 0, 0.4);
+  --vita-shadow-2: 0 4px 6px -1px rgba(0, 0, 0, 0.5), 0 2px 4px -2px rgba(0, 0, 0, 0.4);
+  --vita-shadow-3: 0 10px 15px -3px rgba(0, 0, 0, 0.6), 0 4px 6px -4px rgba(0, 0, 0, 0.5);
 }

package/lib/types/antd.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Local derivations of antd's internal ref / callback-argument types.
+ *
+ * antd does not re-export these from its package entry, so they used to be pulled straight from
+ * `rc-select` / `rc-picker` / `rc-field-form` / `rc-tree-select` / `rc-upload`. antd v6 moved every
+ * one of those internals to the `@rc-component/*` scope, so importing the old packages now yields
+ * types that are *not the same declarations* antd uses internally — under v6 that surfaces as
+ * `RefObject<T> is not assignable to LegacyRef<T>` when the ref is handed to an antd component.
+ *
+ * Deriving from antd's own public declarations instead means: no runtime dependency, and no need to
+ * list `@rc-component/*` in dependencies and chase antd's version pins — the aliases follow antd
+ * automatically on every upgrade. Each one was checked to be *exactly* equivalent (mutually
+ * assignable) to the original `@rc-component/*` definition.
+ */
+import type React from "react";
+import type { DatePicker, Form, InputNumber, TreeSelect } from "antd";
+import type { TreeSelectProps, UploadProps } from "antd";
+/** Ref exposed by antd `Select` / `AutoComplete` (`@rc-component/select`'s `BaseSelectRef`) */
+export type { RefSelectProps as SelectRef } from "antd/es/select";
+/** Ref exposed by antd `TreeSelect` — also a `BaseSelectRef` */
+export type TreeSelectRef = React.ElementRef<typeof TreeSelect>;
+/** Ref exposed by antd `InputNumber` — an `HTMLInputElement` plus `nativeElement` */
+export type InputNumberRef = React.ElementRef<typeof InputNumber>;
+/** Ref exposed by antd `DatePicker` (`@rc-component/picker`'s `PickerRef`) */
+export type PickerRef = React.ElementRef<typeof DatePicker>;
+/** Ref exposed by antd `DatePicker.RangePicker` (`RangePickerRef`: `PickerRef` without `focus`) */
+export type RangePickerRef = React.ElementRef<typeof DatePicker.RangePicker>;
+/** Ref exposed by antd `Form` — `FormInstance` plus an optional `nativeElement` */
+export type FormRef<Values = any> = React.ElementRef<typeof Form<Values>>;
+/** Argument handed to `Upload`'s `customRequest` (`@rc-component/upload`'s `UploadRequestOption`) */
+export type UploadRequestOption = Parameters<NonNullable<UploadProps["customRequest"]>>[0];
+/** A single node of `TreeSelect`'s `treeData` */
+export type TreeSelectDataNode = NonNullable<TreeSelectProps["treeData"]>[number];
+/** Key type accepted by `TreeSelect` — `React.Key` without `bigint` */
+export type SafeKey = Exclude<React.Key, bigint>;

package/lib/types/antd.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/lib/utils/semantic.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Helpers for antd v6's semantic `classNames` / `styles` props.
+ *
+ * In v5 these were plain objects, so wrappers could merge their own class names with the caller's
+ * by spreading. v6 widened them to `object | ((info) => object)` so a caller can decide per render
+ * — which breaks every `classNames?.header` read in this library.
+ *
+ * Reading only the object branch (or ignoring the function branch) would silently drop whatever a
+ * caller passed as a function. `mergeSemantic` instead always hands antd back the *function* form:
+ * antd calls it, we resolve the caller's value at that moment, and merge our own on top. Both
+ * branches are therefore honoured, and the merge stays lazy just like antd expects.
+ */
+/** The function branch of a semantic prop, e.g. `ModalProps["classNames"]` */
+type SemanticFn<P> = Extract<NonNullable<P>, (...args: never[]) => unknown>;
+/** The resolved object a semantic prop yields, with `undefined` stripped */
+type SemanticValue<P> = NonNullable<ReturnType<SemanticFn<P>>>;
+/**
+ * Merge this library's own semantic slots onto whatever the caller passed.
+ *
+ * @param incoming the caller's `classNames` / `styles` prop, in either form
+ * @param merge receives the caller's resolved slots (`{}` when they passed nothing) and returns the
+ *   merged result — spread `outer` first, then override the slots this component owns
+ *
+ * @example
+ * classNames={mergeSemantic(classNames, (outer) => ({
+ *   ...outer,
+ *   body: `${styles.body} ${outer.body ?? ""}`,
+ * }))}
+ */
+export declare function mergeSemantic<P>(incoming: P, merge: (outer: Partial<SemanticValue<P>>) => SemanticValue<P>): SemanticFn<P>;
+export {};

package/lib/utils/semantic.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.mergeSemantic = mergeSemantic;
+/**
+ * Helpers for antd v6's semantic `classNames` / `styles` props.
+ *
+ * In v5 these were plain objects, so wrappers could merge their own class names with the caller's
+ * by spreading. v6 widened them to `object | ((info) => object)` so a caller can decide per render
+ * — which breaks every `classNames?.header` read in this library.
+ *
+ * Reading only the object branch (or ignoring the function branch) would silently drop whatever a
+ * caller passed as a function. `mergeSemantic` instead always hands antd back the *function* form:
+ * antd calls it, we resolve the caller's value at that moment, and merge our own on top. Both
+ * branches are therefore honoured, and the merge stays lazy just like antd expects.
+ */
+
+/** The function branch of a semantic prop, e.g. `ModalProps["classNames"]` */
+
+/** The resolved object a semantic prop yields, with `undefined` stripped */
+
+/**
+ * Merge this library's own semantic slots onto whatever the caller passed.
+ *
+ * @param incoming the caller's `classNames` / `styles` prop, in either form
+ * @param merge receives the caller's resolved slots (`{}` when they passed nothing) and returns the
+ *   merged result — spread `outer` first, then override the slots this component owns
+ *
+ * @example
+ * classNames={mergeSemantic(classNames, (outer) => ({
+ *   ...outer,
+ *   body: `${styles.body} ${outer.body ?? ""}`,
+ * }))}
+ */
+function mergeSemantic(incoming, merge) {
+  const resolve = info => merge((typeof incoming === "function" ? incoming(info) : incoming) ?? {});
+  return resolve;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",
@@ -17,11 +17,11 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/VitaTsui/hsu-ui.git"
+    "url": "git+https://github.com/VitaTsui/hsu-ui-v2.git"
   },
-  "homepage": "https://github.com/VitaTsui/hsu-ui#readme",
+  "homepage": "https://github.com/VitaTsui/hsu-ui-v2#readme",
   "bugs": {
-    "url": "https://github.com/VitaTsui/hsu-ui/issues"
+    "url": "https://github.com/VitaTsui/hsu-ui-v2/issues"
   },
   "publishConfig": {
     "access": "public"
@@ -41,16 +41,17 @@
     "dev": "dumi dev",
     "docs:build": "dumi build",
     "docs:preview": "dumi preview",
-    "build": "father build && node scripts/check-heavy-deps.cjs",
-    "prepublishOnly": "father build && node scripts/check-heavy-deps.cjs",
-    "check:deps": "node scripts/check-heavy-deps.cjs"
+    "build": "node scripts/clean-dist.cjs && node scripts/gen-tokens-scss.cjs && father build && node scripts/check-heavy-deps.cjs",
+    "prepublishOnly": "node scripts/clean-dist.cjs && node scripts/gen-tokens-scss.cjs --check && father build && node scripts/check-heavy-deps.cjs",
+    "check:deps": "node scripts/check-heavy-deps.cjs",
+    "tokens": "node scripts/gen-tokens-scss.cjs",
+    "check:tokens": "node scripts/gen-tokens-scss.cjs --check"
   },
   "dependencies": {
-    "@ant-design/x": "^2.0.1",
+    "@ant-design/x": "^2.9.0",
     "@antv/g": "^6.1.21",
     "@antv/g6": "4.8.24",
     "@antv/g6-plugin": "0.8.24",
-    "@chakra-ui/react": "^3.30.0",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/lang-sql": "^6.9.1",
     "@codemirror/lint": "^6.8.5",
@@ -61,9 +62,6 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "@emotion/cache": "^11.14.0",
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.1",
     "@hsu-react/single-router": ">=0.0.28 <0.1.0",
     "@iconify/json": "^2.2.385",
     "@iconify/react": "^5.0.1",
@@ -90,11 +88,6 @@
     "mermaid": "^11.15.0",
     "mongodb-query-parser": "^4.6.0",
     "node-sql-parser": "^5.3.12",
-    "rc-field-form": "^2.7.0",
-    "rc-picker": "^4.11.3",
-    "rc-select": "^14.15.1",
-    "rc-tree-select": "^5.27.0",
-    "rc-upload": "^4.8.1",
     "react-activation": "^0.13.4",
     "react-markdown": "^9.0.1",
     "react-markdown-editor-lite": "^1.3.4",
@@ -110,15 +103,17 @@
     "zxcvbn": "^4.4.2"
   },
   "peerDependencies": {
-    "@ant-design/icons": ">=5 <6",
-    "antd": ">=5 <6",
+    "@ant-design/icons": ">=6",
+    "antd": ">=6",
     "mobx": ">=6",
     "mobx-react-lite": ">=4",
     "react": ">=18",
-    "react-dom": ">=18"
+    "react-dom": ">=18",
+    "react-intl": ">=6",
+    "react-router": ">=6 <7"
   },
   "devDependencies": {
-    "@ant-design/icons": "^5.3.7",
+    "@ant-design/icons": "^6.3.2",
     "@types/js-cookie": "^3.0.6",
     "@types/lodash": "^4.17.4",
     "@types/markdown-it": "^14.1.2",
@@ -127,14 +122,25 @@
     "@types/react-dom": "^18.3.0",
     "@types/turndown": "^5.0.5",
     "@types/zxcvbn": "^4.4.4",
-    "antd": "5.24.3",
+    "antd": "6.5.4",
     "dumi": "^2.4.0",
     "father": "^4.5.0",
     "mobx": "^6.12.3",
     "mobx-react-lite": "^4.0.7",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "react-intl": "^6.6.8",
+    "react-router": "^6.23.1",
+    "react-router-dom": "^6.23.1",
     "sass": "^1.101.0",
     "typescript": "^5.4.5"
+  },
+  "peerDependenciesMeta": {
+    "react-router": {
+      "optional": true
+    },
+    "react-intl": {
+      "optional": true
+    }
   }
 }

package/src/components/Button/index.md

@@ -35,23 +35,65 @@ export default () => (
 );
 ```
 
-## Chakra 按钮
+## 按钮形态
+
+`variant` 与 `color` 直接用 antd v6 的原生能力：6 种形态 × 16 个预设色。
+
+> **2.0 破坏性变更**：`Button.Chakra`（后改名 `Button.Basic`）这个子组件**已删除**。
+>
+> 它当初存在是因为 antd v5 的 Button 只有 `type`，表达不了 outline / subtle / ghost 这些形态，于是引了 Chakra UI 来补。antd v6 原生加了 `color` + `variant`，正好就是它存在的理由，所以整个删掉、`Button` 重新成为唯一的按钮，chakra 全家（约 560 KB）也一并移除。
+>
+> 旧属性对照：
+>
+> | 旧写法 | 新写法 |
+> | --- | --- |
+> | `variant="solid"` | `variant="solid"` |
+> | `variant="outline"` | `variant="outlined"` |
+> | `variant="surface"` | `variant="surface"`（保留，见下） |
+> | `variant="subtle"` | `variant="filled"` |
+> | `variant="ghost"` | `variant="text"` |
+> | `variant="plain"` | `variant="link"` |
+> | `colorPalette="gray"` | `color="default"` |
+> | `colorPalette="blue"` 等 | `color="blue"` 等 |
+> | `size="xs" \| "sm" \| "md" \| "lg"` | `size="small" \| "small" \| "middle" \| "large"` |
+>
+> Chakra 的样式属性（`px`、`bg`、`_hover` 等）不再支持，请改用 `className`。
 
-基于 Chakra UI 的按钮，支持 `hasPermi`、`hidden`、`iconPosition`、`icon` 等扩展属性。
+```tsx
+import React from "react";
+import { Button } from "@hsu-react/ui";
+
+export default () => (
+  <div style={{ display: "flex", gap: 12, alignItems: "center", flexWrap: "wrap" }}>
+    <Button color="primary" variant="solid">实心</Button>
+    <Button variant="surface">浅底边框</Button>
+    <Button variant="outlined">描边</Button>
+    <Button variant="filled">浅底</Button>
+    <Button variant="text">文字</Button>
+    <Button variant="link">链接</Button>
+    <Button variant="dashed">虚线</Button>
+  </div>
+);
+```
+
+### surface：浅底 + 边框
 
-Chakra 的 system 与 emotion cache 由组件**自带**（内部包了一层 `ChakraRoot`），消费方**不需要**在应用入口挂全局 `ChakraProvider` / `CacheProvider`。这样 `@chakra-ui/react` + `@emotion/*` + zag-js（合计约 570 KB）只存在于 `Button.Chakra` 的异步 chunk 里，不进首屏。
+这是本库在 antd 之上唯一扩展的形态，也正是当初引入 Chakra 按钮要补的那个样式 —— antd 没有它：`filled` 有底色但把边框显式设成了透明，`outlined` 有边框但没底色。
 
-> 从 `0.0.23` 起：入口若仍留着全局 Provider，不会出错，但那 570 KB 会照旧留在首屏——要拿到收益需把它删掉。若页面要**直接**使用 chakra 组件（不经 `Button.Chakra`），用库导出的 `ChakraRoot` 自行包一层即可。
+实现上它走 antd 的 `filled`（底色、文字色、hover / active / disabled 全都照旧由 antd 那条色阶算），只把边框变量按同一条色阶调回来。因为改的是 antd 自己的 CSS 变量而不是写死颜色，**16 个预设色与明暗主题都自动跟着走**。
 
 ```tsx
 import React from "react";
 import { Button } from "@hsu-react/ui";
 
 export default () => (
-  <div style={{ display: "flex", gap: 12, alignItems: "center" }}>
-    <Button.Chakra colorPalette="blue">主要按钮</Button.Chakra>
-    <Button.Chakra variant="outline">描边按钮</Button.Chakra>
-    <Button.Chakra disabled>禁用</Button.Chakra>
+  <div style={{ display: "flex", gap: 12, alignItems: "center", flexWrap: "wrap" }}>
+    <Button variant="surface">默认</Button>
+    <Button variant="surface" color="primary">主色</Button>
+    <Button variant="surface" color="danger">危险</Button>
+    <Button variant="surface" color="green">绿</Button>
+    <Button variant="surface" color="purple">紫</Button>
+    <Button variant="surface" disabled>禁用</Button>
   </div>
 );
 ```
@@ -64,6 +106,8 @@ export default () => (
 | --- | --- | --- | --- |
 | hasPermi | 权限码；当前用户不具备时按钮不渲染（配合 `ConfigProvider.permissions`） | `string[]` | - |
 | hidden | 是否隐藏（不渲染） | `boolean` | `false` |
-| iconPosition | 图标位置 | `'start' \| 'end'` | `'start'` |
+| iconPosition | 图标位置。antd v6 起这个属性改名为 `iconPlacement`，两个名字这里都接受，内部统一翻成 `iconPlacement`，不会触发 antd 的弃用告警 | `'start' \| 'end'` | `'start'` |
+| variant | 形态；比 antd 多一个 `surface`（浅底 + 边框） | `'solid' \| 'outlined' \| 'dashed' \| 'filled' \| 'text' \| 'link' \| 'surface'` | - |
+| reRender | 包裹渲染结果，便于套 Tooltip / Popconfirm | `(btn: ReactElement) => ReactNode` | - |
 
-> 另提供 `Button.Chakra`，用于需要 Chakra UI 按钮样式的场景。
+> `variant` / `color` / `size` / `shape` 等其余属性与 [antd Button](https://ant.design/components/button-cn) 一致，`variant` 额外多一个 `surface`。

package/src/components/Button/index.module.scss

@@ -9,3 +9,41 @@
     flex-direction: row-reverse;
   }
 }
+
+// `variant="surface"`：浅底 + 边框。
+//
+// antd v6 没有这个形态 —— `filled` 有底色但把 --ant-btn-border-color 显式设成了 transparent，
+// `outlined` 有边框但没底色。这里让它走 antd 的 `filled`（底色、文字色、hover / active、
+// disabled 全都照旧由 antd 那条色阶算），只把边框变量按同一条色阶调回来。
+//
+// 因为改的是 antd 自己的变量而不是写死颜色，16 个 color 预设（default / primary / danger /
+// blue / purple / … / gold）与明暗主题都自动跟着走，不必逐色枚举。
+// 选择器要连 antd 的两个类一起写：antd 是在 `.ant-btn.ant-btn-variant-filled`（0,2,0）里把
+// --ant-btn-border-color 设成 transparent 的，单靠一个 CSS Module 类（0,1,0）压不过它。
+// 这里写成 (0,3,0)，与注入顺序无关，也就不需要 !important。
+//
+// 边框用满强度的 color-base，不要再乘一个透明度：默认色系下 color-base 本身就是标准边框色
+// #e4e4e7，再乘 25% 之后压在 #f4f4f5 的浅底上等于没有 —— 那样 surface 看起来就和 filled
+// 一模一样。满强度等于「filled 的底 + outlined 的边」，这正是这个形态的定义。
+.surface:global(.ant-btn.ant-btn-variant-filled) {
+  --ant-btn-border-color: var(--ant-btn-color-base);
+  --ant-btn-border-color-hover: var(--ant-btn-color-hover);
+  --ant-btn-border-color-active: var(--ant-btn-color-active);
+
+  // 中性色系要单独抬一档：它的 color-base 就是边框色，而边框色与浅底色在暗色下恰好同值
+  // （--vita-border 与 --vita-muted 都是 #27272a），照抄就等于没有边框。
+  // 往文字色方向混一点即可 —— 浅色下变深、暗色下变浅，一条规则两个主题都成立。
+  &:global(.ant-btn-color-default) {
+    --ant-btn-border-color: color-mix(
+      in srgb,
+      var(--ant-btn-color-base) 62%,
+      var(--vita-foreground)
+    );
+    --ant-btn-border-color-hover: color-mix(
+      in srgb,
+      var(--ant-btn-color-base) 40%,
+      var(--vita-foreground)
+    );
+    --ant-btn-border-color-active: var(--ant-btn-border-color-hover);
+  }
+}