@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/flex/flex.meta.md

@@ -10,52 +10,54 @@ package: '@teamix-evo/ui'
 
 # Flex 弹性布局
 
-Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举,避免散落的 `flex flex-col items-start gap-4 ...` 反复手写。
+Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+) ∪ **antd `Space`**——一个原子覆盖 layout 类目两个原子场景:
+
+- **完整布局容器**(页头 / 卡片体 / 整页): `<Flex as="header" justify="between" align="center" />`
+- **inline 小集合**(按钮组 / tag 组 / 链接组,等价 antd `Space`): `<Flex inline gap="sm" align="center" />`
+- **链接组带分隔**(等价 antd `Space.split`): `<Flex inline gap="sm" split={<Separator orientation="vertical" />} />`
 
 ## When to use
 
-- 完整页面 / 卡片 / Section 的容器布局
+- 页面 / 卡片 / Section 的容器布局
 - 需要语义化 HTML 标签(`<header>` `<aside>` `<main>` `<nav>`)时用 `as`
+- 按钮组 / tag 组 / 表单 label-value 对 / 列表行末操作链接组(原 Space 场景 — 加 `inline`)
 - 多次重复的相同对齐组合(可以靠 Flex 收敛模板)
 
 ## When NOT to use
 
-- 小集合 inline 间距 → `Space`
-- 网格 → `Grid`(`Row + Col`)
+- 网格列分配 → `Grid`(`Row + Col`)
+- 按钮粘连共享边线 → `ButtonGroup`
 - 仅一次性自由布局 → 直接写 className 也行,不强求
 
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称        | 类型                                                                                                                               | 默认值      | 必填 | 说明                                                                                                  |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---- | ----------------------------------------------------------------------------------------------------- |
-| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'`                                                                           | `"row"`     | –    | 方向(antd `vertical` 并集) — `row`(默认)/ `column` 直观可读;antd `vertical` boolean 映射为 `column`。 |
-| `gap`       | `'none' \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'`                                                                              | `"default"` | –    | 子项之间的间距档位(走 design 间距刻度,不接受任意 number)。                                            |
-| `align`     | `keyof typeof alignMap`                                                                                                            | `"stretch"` | –    | 副轴对齐方式。                                                                                        |
-| `justify`   | `keyof typeof justifyMap`                                                                                                          | `"start"`   | –    | 主轴对齐方式。                                                                                        |
-| `wrap`      | `boolean`                                                                                                                          | `false`     | –    | 是否允许换行(antd `wrap` 并集)。                                                                      |
-| `inline`    | `boolean`                                                                                                                          | `false`     | –    | inline-flex 而非 block-flex。                                                                         |
-| `as`        | `keyof Pick< React.JSX.IntrinsicElements, 'div' \| 'section' \| 'header' \| 'footer' \| 'aside' \| 'main' \| 'nav' \| 'article' >` | `"div"`     | –    | 渲染元素(antd `component` 并集) — 支持 `section / header / aside / main / nav` 等语义标签。           |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `"row"` | – | 方向(antd `vertical` 并集) — `row`(默认)/ `column` 直观可读;antd `vertical` boolean 映射为 `column`。 |
+| `gap` | `'none' \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 子项之间的间距档位(走 design 间距刻度,不接受任意 number)。 |
+| `align` | `keyof typeof alignMap` | `"stretch"` | – | 副轴对齐方式。 |
+| `justify` | `keyof typeof justifyMap` | `"start"` | – | 主轴对齐方式。 |
+| `wrap` | `boolean` | `false` | – | 是否允许换行(antd `wrap` 并集)。 |
+| `inline` | `boolean` | `false` | – | inline-flex 而非 block-flex。 |
+| `as` | `keyof Pick< React.JSX.IntrinsicElements, 'div' \| 'section' \| 'header' \| 'footer' \| 'aside' \| 'main' \| 'nav' \| 'article' >` | `"div"` | – | 渲染元素(antd `component` 并集) — 支持 `section / header / aside / main / nav` 等语义标签。 |
+| `split` | `React.ReactNode` | – | – | 子项之间的分隔节点(antd `Space.split` 并集) — 常用 `<Separator orientation="vertical" />`、`'·'`、`'\|'`。 设置后会在每两个相邻子项之间插入该节点。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add flex` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
@@ -63,13 +65,37 @@ _无 — 本组件不依赖任何 npm 包。_
 - **`gap` 是档位枚举**(none / xs / sm / default / lg / xl),**不接受 number** — 走 design 间距刻度
 - **`direction="column"` 等价 antd `vertical`** — antd 的 `vertical={true}` 我们没沿用 boolean,直接走 direction 更直观
 - **`as` 仅限语义化标签集**(`section / header / aside / main / nav / footer / article / div`)— 不要传 `'span' / 'h1'` 等非 block 标签
+- **`inline` 是原 Space 的入口** — 表达 inline 小集合请加 `inline gap="sm" align="center"`,不要再去找 `Space`(已与 Flex 合并)
+- **`split` 应是无状态轻节点**(Separator / `|` / dot 字符),不要传 Button 等复杂组件,语义混乱
 - **不要嵌套 Flex 表达栅格** — 用 `Grid (Row/Col)`
 - **align/justify 默认值**:`align="stretch"`(子项填满高度)、`justify="start"`(主轴起始)— 大部分场景符合直觉
 
+## 从 antd `Space` 迁移
+
+v0.x 起 `Space` 已合并进 `Flex`。迁移 mapping(IDE 全局替换可解):
+
+```tsx
+// before
+<Space size="sm" align="center">…</Space>
+// after
+<Flex inline gap="sm" align="center">…</Flex>
+
+// before
+<Space split={<Separator orientation="vertical" />} size="sm">…</Space>
+// after
+<Flex inline gap="sm" align="center" split={<Separator orientation="vertical" />}>…</Flex>
+
+// before
+<Space direction="vertical" align="start">…</Space>
+// after
+<Flex direction="column" gap="sm" align="start">…</Flex>
+```
+
 ## Examples
 
 ```tsx
 import { Flex } from '@/components/ui/flex';
+import { Separator } from '@/components/ui/separator';
 
 // 居中对话框
 <Flex justify="center" align="center" className="min-h-screen">
@@ -96,6 +122,19 @@ import { Flex } from '@/components/ui/flex';
   <Button>提交</Button>
 </Flex>
 
+// inline 小集合(原 Space 场景)
+<Flex inline gap="sm" align="center">
+  <Button variant="outline">取消</Button>
+  <Button>确定</Button>
+</Flex>
+
+// 链接组 + split(原 Space.split 场景)
+<Flex inline gap="sm" align="center" split={<Separator orientation="vertical" className="h-4" />}>
+  <a href="#">查看</a>
+  <a href="#">编辑</a>
+  <a href="#">删除</a>
+</Flex>
+
 // 标签云
 <Flex wrap gap="sm">
   {tags.map((t) => <Tag key={t}>{t}</Tag>)}

package/src/components/flex/flex.stories.tsx

@@ -1,16 +1,17 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Flex } from './flex';
 import { Button } from '@/components/button/button';
+import { Separator } from '@/components/separator/separator';
 
 const meta: Meta<typeof Flex> = {
-  title: '布局与容器 · Layout/Flex',
+  title: '布局 · Layout/Flex',
   component: Flex,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          'Flex 布局容器 — 把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举。等价 antd `Flex`(v5.10+),与 Space 互补:Flex 偏完整布局容器,Space 偏 inline 小集合。',
+          'Flex 弹性布局 —— 以架构者语言描述一维 / 二维的子项排列。**等价 antd `Flex`**(v5.10+) **∪ antd `Space`**——覆盖完整布局容器(页头 / 卡片 / 整页)与 inline 小集合(按钮组 / tag 组 / 链接组)两类场景:`direction`(row/column/-reverse) / `gap`(none→xl 6 档走 design 间距刻度) / `align` / `justify` / `wrap` / `inline`(等价 antd `Space`) / `as`(语义标签 section/header/main…) / `split`(等价 antd `Space.split`,在相邻子项间插入分隔节点)。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
       },
     },
   },
@@ -48,14 +49,14 @@ export default meta;
 type Story = StoryObj<typeof Flex>;
 
 const swatch = (label: string) => (
-  <div className="grid h-12 w-20 place-items-center rounded-md border bg-muted text-xs">
+  <div className="grid h-12 w-20 place-items-center rounded-md border border-border bg-muted text-xs">
     {label}
   </div>
 );
 
 export const Playground: Story = {
   render: (args) => (
-    <Flex {...args} className="min-h-32 rounded-md border bg-card p-4">
+    <Flex {...args} className="min-h-32 rounded-md border border-border bg-card p-4">
       {swatch('A')}
       {swatch('B')}
       {swatch('C')}
@@ -70,7 +71,7 @@ export const Header: Story = {
       as="header"
       justify="between"
       align="center"
-      className="rounded-md border bg-card px-6 py-3"
+      className="rounded-md border border-border bg-card px-6 py-3"
     >
       <span className="font-semibold">Logo</span>
       <Flex gap="sm">
@@ -95,7 +96,7 @@ export const ColumnStack: Story = {
     <Flex
       direction="column"
       gap="sm"
-      className="w-80 rounded-md border bg-card p-6"
+      className="w-80 rounded-md border border-border bg-card p-6"
     >
       <span className="text-lg font-semibold">标题</span>
       <span className="text-sm text-muted-foreground">这是一段描述文字</span>
@@ -107,17 +108,71 @@ export const ColumnStack: Story = {
 export const Toolbar: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Flex justify="end" gap="sm" className="rounded-md border bg-card p-3">
+    <Flex justify="end" gap="sm" className="rounded-md border border-border bg-card p-3">
       <Button variant="outline">取消</Button>
       <Button>提交</Button>
     </Flex>
   ),
 };
 
+/**
+ * inline 小集合——等价 antd `Space`。加 `inline` + 小 `gap` + `align="center"` 即可覆盖原 Space 场景。
+ */
+export const InlineGroup: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Flex inline gap="sm" align="center">
+      <Button variant="outline">取消</Button>
+      <Button>确定</Button>
+      <Button variant="ghost">更多</Button>
+    </Flex>
+  ),
+};
+
+/**
+ * 链接组带分隔——等价 antd `Space.split`。`split` 接受任意 ReactNode,常用 `<Separator orientation="vertical" />`。
+ */
+export const WithSplit: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Flex
+      inline
+      gap="sm"
+      align="center"
+      split={<Separator orientation="vertical" className="h-4" />}
+    >
+      <a href="#" className="text-sm text-primary hover:underline">
+        查看
+      </a>
+      <a href="#" className="text-sm text-primary hover:underline">
+        编辑
+      </a>
+      <a href="#" className="text-sm text-destructive hover:underline">
+        删除
+      </a>
+    </Flex>
+  ),
+};
+
+/**
+ * 主轴分几——表单行 “总计 / 金额”。等价 antd `Space justify="between"`。
+ */
+export const Between: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80 rounded-md border border-border p-3">
+      <Flex justify="between" align="center">
+        <span className="text-sm text-muted-foreground">总计</span>
+        <span className="text-lg font-semibold">¥ 1,299</span>
+      </Flex>
+    </div>
+  ),
+};
+
 export const WrapCloud: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Flex wrap gap="sm" className="w-96 rounded-md border bg-card p-3">
+    <Flex wrap gap="sm" className="w-96 rounded-md border border-border bg-card p-3">
       {[
         'React',
         'Vue',
@@ -134,7 +189,7 @@ export const WrapCloud: Story = {
       ].map((t) => (
         <span
           key={t}
-          className="rounded-md border bg-muted px-2 py-0.5 text-xs"
+          className="rounded-md border border-border bg-muted px-2 py-0.5 text-xs"
         >
           {t}
         </span>

package/src/components/flex/flex.tsx

@@ -67,13 +67,21 @@ export interface FlexProps extends React.HTMLAttributes<HTMLDivElement> {
     React.JSX.IntrinsicElements,
     'div' | 'section' | 'header' | 'footer' | 'aside' | 'main' | 'nav' | 'article'
   >;
+  /**
+   * 子项之间的分隔节点(antd `Space.split` 并集) — 常用 `<Separator orientation="vertical" />`、`'·'`、`'|'`。
+   * 设置后会在每两个相邻子项之间插入该节点。
+   */
+  split?: React.ReactNode;
 }
 
 /**
- * Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),提供 Tailwind flex 的语义封装,
- * 把常用对齐 / 间距 / 换行 / 方向 / 渲染元素收敛为枚举,避免散落的 className 反复手写。
+ * Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+) ∪ **antd `Space`**(`split`)。
+ * 把 Tailwind flex 的常用对齐 / 间距 / 换行 / 方向 / 渲染元素 / 分隔节点收敛为枚举,避免散落的 className 反复手写。
  *
- * 与 `Space` 区别:Flex 偏向**完整布局容器**(页头、卡片体、整页),Space 偏向 inline 小集合。
+ * 用法约定:
+ * - 完整布局容器(页头、卡片体、整页): `<Flex as="header" justify="between" align="center" />`
+ * - inline 小集合(按钮组、tag 组、链接组): `<Flex inline gap="sm" align="center" />`(等价 antd `Space`)
+ * - 链接组带分隔: `<Flex inline gap="sm" split={<Separator orientation="vertical" />} />`
  */
 const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
   (
@@ -85,7 +93,9 @@ const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
       wrap = false,
       inline = false,
       as = 'div',
+      split,
       className,
+      children,
       ...props
     },
     ref,
@@ -100,6 +110,17 @@ const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
             ? 'flex-row-reverse'
             : 'flex-col-reverse';
 
+    const content = split
+      ? React.Children.toArray(children)
+          .filter(Boolean)
+          .map((child, i) => (
+            <React.Fragment key={i}>
+              {i > 0 ? split : null}
+              {child}
+            </React.Fragment>
+          ))
+      : children;
+
     return (
       <Tag
         ref={ref}
@@ -113,7 +134,9 @@ const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
           className,
         )}
         {...props}
-      />
+      >
+        {content}
+      </Tag>
     );
   },
 );

package/src/components/float-button/float-button.meta.md

@@ -2,7 +2,7 @@
 id: float-button
 name: FloatButton
 type: component
-category: navigation
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 悬浮按钮
@@ -28,42 +28,24 @@ displayName: 悬浮按钮
 ## Props
 
 <!-- auto:props:begin -->
-
-#### FloatButton
-
-| 名称      | 类型                     | 默认值      | 必填 | 说明                                               |
-| --------- | ------------------------ | ----------- | ---- | -------------------------------------------------- |
-| `icon`    | `React.ReactNode`        | –           | –    | 图标(antd `icon` 并集)。                           |
-| `variant` | `'primary' \| 'default'` | `"primary"` | –    | 视觉风格 — `primary` 主色填充;`default` 灰色轮廓。 |
-| `shape`   | `'circle' \| 'square'`   | `"circle"`  | –    | 形状 — `circle`(默认)圆形;`square` 方形圆角。      |
-| `badge`   | `React.ReactNode`        | –           | –    | 触发徽标(antd `badge` 并集) — 简短数字 / 字符。    |
-
-#### FloatButtonGroup
-
-| 名称     | 类型     | 默认值 | 必填 | 说明                 |
-| -------- | -------- | ------ | ---- | -------------------- |
-| `right`  | `number` | `24`   | –    | 距视口右侧距离(px)。 |
-| `bottom` | `number` | `24`   | –    | 距视口底部距离(px)。 |
-
-#### FloatButtonBackTop
-
-| 名称               | 类型     | 默认值 | 必填 | 说明                                   |
-| ------------------ | -------- | ------ | ---- | -------------------------------------- |
-| `visibilityHeight` | `number` | `200`  | –    | 滚动距离超过此值(px)时才显示回到顶部。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `icon` | `React.ReactNode` | – | – | 图标(antd `icon` 并集)。 |
+| `variant` | `'primary' \| 'default'` | `"primary"` | – | 视觉风格 — `primary` 主色填充;`default` 灰色轮廓。 |
+| `shape` | `'circle' \| 'square'` | `"circle"` | – | 形状 — `circle`(默认)圆形;`square` 方形圆角。 |
+| `badge` | `React.ReactNode` | – | – | 触发徽标(antd `badge` 并集) — 简短数字 / 字符。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add float-button` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -72,7 +54,6 @@ displayName: 悬浮按钮
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/float-button/float-button.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { MessageCircle, Plus } from 'lucide-react';
 import {
   FloatButton,
@@ -7,14 +7,14 @@ import {
 } from './float-button';
 
 const meta: Meta<typeof FloatButton> = {
-  title: '导航 · Navigation/FloatButton',
+  title: '废弃 · Deprecated/FloatButton',
   component: FloatButton,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '悬浮按钮 — position: fixed 在右下角的强主张操作按钮（回到顶部 / 客服 / 新建）。配 FloatButtonGroup 堆叠多个，FloatButtonBackTop 是预置的“回到顶部”。等价 antd `FloatButton`（v5.0，替代旧 BackTop）。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n悬浮按钮 — position: fixed 在右下角的强主张操作按钮（回到顶部 / 客服 / 新建）。配 FloatButtonGroup 堆叠多个，FloatButtonBackTop 是预置的“回到顶部”。等价 antd `FloatButton`（v5.0，替代旧 BackTop）。',
       },
     },
   },
@@ -26,7 +26,7 @@ type Story = StoryObj<typeof FloatButton>;
 export const Playground: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="relative h-72 overflow-hidden rounded-md border">
+    <div className="relative h-72 overflow-hidden rounded-md border border-border">
       <div className="p-4 text-sm text-muted-foreground">
         ← 右下角是 FloatButton 演示
       </div>
@@ -40,7 +40,7 @@ export const Playground: Story = {
 export const Group: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="relative h-96 overflow-hidden rounded-md border">
+    <div className="relative h-96 overflow-hidden rounded-md border border-border">
       <div className="p-4 text-sm text-muted-foreground">右下角浮动按钮组</div>
       <div className="absolute bottom-6 right-6 flex flex-col items-end gap-3">
         <FloatButton
@@ -67,7 +67,7 @@ export const BackTopReal: Story = {
       </div>
       <div className="mt-3 space-y-3">
         {Array.from({ length: 30 }).map((_, i) => (
-          <div key={i} className="rounded-md border bg-muted/30 p-6">
+          <div key={i} className="rounded-md border border-border bg-muted/30 p-6">
             占位段落 {i + 1}
           </div>
         ))}

package/src/components/form/form.meta.md

@@ -3,7 +3,7 @@ id: form
 name: Form
 displayName: 表单
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -30,43 +30,9 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`Form` 是 `FormProvider` 别名,直接接受 `useForm()` 返回值;下表按子组件分节列出各自的 Props。
 
 <!-- auto:props:begin -->
-
-#### Form
-
-| 名称       | 类型              | 默认值 | 必填 | 说明                                              |
-| ---------- | ----------------- | ------ | ---- | ------------------------------------------------- |
-| `children` | `React.ReactNode` | –      | –    | 表单内容 — 通常是 `<form>` + `<FormField>` 列表。 |
-
-> `Form` 透传 `useForm()` 返回值的所有属性(`UseFormReturn`),作为 `FormProvider` 下发给子组件。
-
-#### FormField
-
-| 名称      | 类型                                                       | 默认值 | 必填 | 说明                                        |
-| --------- | ---------------------------------------------------------- | ------ | ---- | ------------------------------------------- |
-| `name`    | `FieldPath<TFieldValues>`                                  | –      | ✔    | 字段名称,对应 schema 中的 key。             |
-| `control` | `Control<TFieldValues>`                                    | –      | ✔    | `useForm()` 返回的 `control` 实例。         |
-| `render`  | `({ field, fieldState, formState }) => React.ReactElement` | –      | ✔    | 渲染函数,接收 field/fieldState 注入到控件。 |
-
-#### FormItem
-
-> 单个表单字段容器,生成稳定 id 供 Label/Description/Message 关联。无自定义 props,仅透传 `HTMLDivElement` 属性。
-
-#### FormLabel
-
-> 扩展自 `Label` 组件,自动通过 `useFormField()` 关联 `htmlFor`,校验失败时自动变红。支持 `Label` 的所有 props(`required` / `disabled`)。
-
-#### FormControl
-
-> Slot 包装器,自动注入 `id` / `aria-describedby` / `aria-invalid` 到子控件。无自定义 props。
-
-#### FormDescription
-
-> 辅助说明文本(`text-xs text-muted-foreground`)。无自定义 props,仅透传 `HTMLParagraphElement` 属性。
-
-#### FormMessage
-
-> 错误消息显示,自动从 `fieldState.error` 读取。无自定义 props,仅透传 `HTMLParagraphElement` 属性。
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactNode` | – | – | 表单内容 — 通常是 `<form>` + `<FormField>` 列表。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -74,35 +40,48 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add form` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry   | 类型      | 描述                                                                                  |
-| ------- | --------- | ------------------------------------------------------------------------------------- |
-| `cn`    | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                    |
-| `label` | component | 表单字段标签 — Radix Label 包装,补 antd Form.Item 风格的 required / disabled 显式视觉 |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `field` | component | 通用表单字段抽象 — shadcn 2025-10 新增。Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend 7 个语义槽,跟任何状态管理(Server Actions / RHF / TanStack Form)都能搭,与 form 共存 |
 
 ### npm 依赖
 
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```bash
-pnpm add react-hook-form@^7.50.0 @hookform/resolvers@^3.0.0 zod@^3.22.0 @radix-ui/react-label@^2.1.0 @radix-ui/react-slot@^1.1.0
+pnpm add react-hook-form@^7.50.0 @hookform/resolvers@^3.0.0 zod@^3.22.0 @radix-ui/react-slot@^1.1.0
 ```
-
 <!-- auto:deps:end -->
 
+## 子组件
+
+除 shadcn 7 件套（`Form / FormField / FormItem / FormLabel / FormControl / FormDescription / FormMessage`）外，本包补两个表单骨架子组件：
+
+- **`FormSection`**：表单分组容器，支持 `title`（组标题，14px medium）和 `columns`（`1 \| 2 \| 3 \| 4` 多栏 grid）。代替手写 h3 + Row/Col。
+- **`FormActions`**：表单操作按钮容器，支持 `position`（`'inline'` / `'sticky'`）、`align`（`'start'` / `'end'`）和 `alignWithInput`（与输入域基线对齐，避免按钮与 label 列重叠）。
+
+> **实现共享**：`FormSection` / `FormActions` 是 Field 包同名组件的 re-export 别名（一处实现，规范变更只改一处）。Props 与行为完全等同 `FieldSection` / `FieldActions`，详见 [`field.meta.md`](../field/field.meta.md)。
+
 ## AI 生成纪律
 
-- **`Form` 必包 `useForm()`**:`<Form {...form}>...</Form>`,把整个 form instance 散开传入(FormProvider 期望)
-- **每个字段必有 `<FormField name="..." control={form.control} render={({ field }) => <FormItem>...</FormItem>} />`**:不要直接渲染 input 不走 Field,会失去校验关联
-- **`<FormControl>` 只放真正的输入控件**:input / textarea / Select / Checkbox 等;Slot 模式自动注入 id / aria-describedby / aria-invalid
-- **错误消息走 `<FormMessage />`**:不要手写 `{errors.x?.message}` — FormMessage 自动连接 fieldState
-- **schema 优先**:用 zod 写 schema → `useForm({ resolver: zodResolver(schema) })`;校验逻辑集中在 schema,不要散在 input 上
-- **提交后保留状态**:`form.reset()` 重置;**不要**手动清空每个字段
-- **不要嵌套 Form**:嵌套会破坏 React Context
+- **`Form` 必包 `useForm()`**：`<Form {...form}>...</Form>`，把整个 form instance 散开传入（FormProvider 期望）
+- **每个字段必有 `<FormField name="..." control={form.control} render={({ field }) => <FormItem>...</FormItem>} />`**：不要直接渲染 input 不走 Field，会失去校验关联
+- **`<FormControl>` 只放真正的输入控件**：input / textarea / Select / Checkbox 等；Slot 模式自动注入 id / aria-describedby / aria-invalid
+- **错误消息走 `<FormMessage />`**：不要手写 `{errors.x?.message}` — FormMessage 自动连接 fieldState
+- **必填标记 `*` 总是后置**：`<FormLabel required>` 由底层 `Label` 组件在文字与 tooltip icon **后**渲染红色 `*`（顺序为 `文字 ⓘ *`），对齐设计规范；不要手写 `<FormLabel>邮箱 *</FormLabel>` 或 `<FormLabel>* 邮箱</FormLabel>`。同时记得在 schema 里 `z.string().min(1)` 或控件上 `aria-required="true"`。
+- **schema 优先**：用 zod 写 schema → `useForm({ resolver: zodResolver(schema) })`；校验逻辑集中在 schema，不要散在 input 上
+- **提交后保留状态**：`form.reset()` 重置；**不要**手动清空每个字段
+- **不要嵌套 Form**：嵌套会破坏 React Context
+- ✅ 复杂表单必须用 `FormSection` 分组（组标题用 `title` prop，不要手写 `<h3>`）
+- ✅ 多栏布局用 `FormSection columns={N}`（不要手写 `Row`/`Col` 或 `grid grid-cols-N`）
+- ✅ 表单提交 / 取消按钮必须用 `FormActions`
+- ✅ 多个 `FormSection` 的父容器必须用 `gap-8`（32px 组间距）
+- ✅ 错误信息（`FormMessage`）紧贴 input，不要额外加 `mt-*` 或包裹 `<div>`
 
 ## Examples