@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/input-otp/input-otp.meta.md

@@ -2,7 +2,7 @@
 id: input-otp
 name: InputOTP
 type: component
-category: form
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 验证码输入
@@ -30,20 +30,10 @@ OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/in
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`InputOTP` 透传 `input-otp` 的所有 props。
 
 <!-- auto:props:begin -->
-
-#### InputOTP
-
-| 名称                 | 类型     | 默认值 | 必填 | 说明                                                                                         |
-| -------------------- | -------- | ------ | ---- | -------------------------------------------------------------------------------------------- |
-| `className`          | `string` | –      | –    | 输入框 className，作用在隐藏的真实 input 上；通常无需关心。                                  |
-| `containerClassName` | `string` | –      | –    | 容器 className，作用在 slot 列表外层 wrapper 上， 用于覆盖默认的 `flex items-center gap-2`。 |
-
-#### InputOTPSlot
-
-| 名称    | 类型     | 默认值 | 必填 | 说明                                       |
-| ------- | -------- | ------ | ---- | ------------------------------------------ |
-| `index` | `number` | –      | ✔    | Slot 索引（必传）。OTP 的 slots 数组下标。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | – | – | 输入框 className,作用在隐藏的真实 input 上;通常无需关心。 |
+| `containerClassName` | `string` | – | – | 容器 className,作用在 slot 列表外层 wrapper 上, 用于覆盖默认的 `flex items-center gap-2`。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -51,14 +41,13 @@ OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/in
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add input-otp` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -67,7 +56,6 @@ OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/in
 ```bash
 pnpm add input-otp@^1.2.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 > 子组件:`InputOTP`(Root)/ `InputOTPGroup`(slot 容器)/ `InputOTPSlot`(单 slot,需 `index`)/ `InputOTPSeparator`(分隔符,如 4-4 数字之间的点)。

package/src/components/input-otp/input-otp.stories.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { REGEXP_ONLY_DIGITS } from 'input-otp';
 import {
   InputOTP,
@@ -9,14 +9,14 @@ import {
 } from './input-otp';
 
 const meta: Meta<typeof InputOTP> = {
-  title: '表单与输入 · Form/InputOTP',
+  title: '废弃 · Deprecated/InputOTP',
   component: InputOTP,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。',
       },
     },
   },

package/src/components/input-otp/input-otp.tsx

@@ -67,7 +67,7 @@ const InputOTPSlot = React.forwardRef<
     <div
       ref={ref}
       className={cn(
-        'relative flex size-10 items-center justify-center border-y border-r border-input text-sm shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md',
+        'relative flex size-10 items-center justify-center border-y border-r border-input text-xs shadow-sm transition-all first:rounded-l-md first:border-l last:rounded-r-md',
         isActive && 'z-10 ring-1 ring-ring',
         className,
       )}

package/src/components/item/item.meta.md

@@ -2,7 +2,7 @@
 id: item
 name: Item
 type: component
-category: layout
+category: data-display
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 列表项
@@ -28,39 +28,22 @@ displayName: 列表项
 ## Props
 
 <!-- auto:props:begin -->
-
-#### Item
-
-| 名称          | 类型                                | 默认值      | 必填 | 说明                                                                                                |
-| ------------- | ----------------------------------- | ----------- | ---- | --------------------------------------------------------------------------------------------------- |
-| `variant`     | `'default' \| 'outline' \| 'muted'` | `"default"` | –    | 视觉变体 — `default` 透明无边框(嵌入 List / Group 用);`outline` 卡片化(独立卡片);`muted` 灰底卡片。 |
-| `interactive` | `boolean`                           | `false`     | –    | 是否带 hover 高亮 + cursor-pointer(行可点击场景)。                                                  |
-
-#### ItemMedia
-
-| 名称   | 类型                | 默认值      | 必填 | 说明                                        |
-| ------ | ------------------- | ----------- | ---- | ------------------------------------------- |
-| `size` | `'default' \| 'lg'` | `"default"` | –    | 媒体尺寸 — `lg` 适用于大封面 / 大头像场景。 |
-
-#### ItemGroup
-
-| 名称      | 类型      | 默认值 | 必填 | 说明                           |
-| --------- | --------- | ------ | ---- | ------------------------------ |
-| `divided` | `boolean` | `true` | –    | 是否在各 Item 之间显示分割线。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `"default"` | – | 视觉变体 — `default` 透明无边框(嵌入 List / Group 用);`outline` 卡片化(独立卡片);`muted` 灰底卡片。 |
+| `interactive` | `boolean` | `false` | – | 是否带 hover 高亮 + cursor-pointer(行可点击场景)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add item` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -69,7 +52,6 @@ displayName: 列表项
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/item/item.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Item,
   ItemMedia,
@@ -13,7 +13,7 @@ import { Button } from '@/components/button/button';
 import { Switch } from '@/components/switch/switch';
 
 const meta: Meta<typeof Item> = {
-  title: '布局与容器 · Layout/Item',
+  title: '数据展示 · Data Display/Item',
   component: Item,
   tags: ['autodocs'],
   parameters: {
@@ -60,7 +60,7 @@ const users = [
 export const ContactList: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <ItemGroup className="w-96 rounded-md border">
+    <ItemGroup className="w-96 rounded-md border border-border">
       {users.map((u) => (
         <Item key={u.id} interactive className="px-3 py-2">
           <ItemMedia>

package/src/components/item/item.tsx

@@ -4,12 +4,13 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/utils/cn';
 
 const itemVariants = cva(
-  'flex w-full items-start gap-3 text-sm transition-colors',
+  'flex w-full items-start gap-3 text-xs transition-colors',
   {
     variants: {
       variant: {
         default: '',
-        outline: 'rounded-md border bg-card p-3 text-card-foreground shadow-sm',
+        outline:
+          'rounded-md border border-border bg-card p-3 text-card-foreground shadow-sm',
         muted: 'rounded-md bg-muted p-3',
       },
       interactive: {
@@ -61,11 +62,11 @@ export interface ItemMediaProps extends React.HTMLAttributes<HTMLDivElement> {
    * 媒体尺寸 — `default` 用于头像 / 图标;`lg` 用于缩略图。
    * @default "default"
    */
-  size?: 'default' | 'lg';
+  size?: 'md' | 'default' | 'lg';
 }
 
 const ItemMedia = React.forwardRef<HTMLDivElement, ItemMediaProps>(
-  ({ size = 'default', className, ...props }, ref) => (
+  ({ size = 'md', className, ...props }, ref) => (
     <div
       ref={ref}
       className={cn(
@@ -101,7 +102,7 @@ const ItemTitle = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <div
     ref={ref}
-    className={cn('truncate text-sm font-semibold leading-none', className)}
+    className={cn('truncate text-xs font-semibold leading-none', className)}
     {...props}
   />
 ));
@@ -113,7 +114,7 @@ const ItemDescription = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <p
     ref={ref}
-    className={cn('truncate text-sm text-muted-foreground', className)}
+    className={cn('truncate text-xs text-muted-foreground', className)}
     {...props}
   />
 ));

package/src/components/kbd/kbd.meta.md

@@ -3,7 +3,7 @@ id: kbd
 name: Kbd
 displayName: 键位展示
 type: component
-category: foundation
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -28,19 +28,9 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-#### Kbd
-
-| 名称   | 类型                        | 默认值      | 必填 | 说明                                                          |
-| ------ | --------------------------- | ----------- | ---- | ------------------------------------------------------------- |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | –    | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
-
-#### KbdGroup
-
-| 名称        | 类型     | 默认值 | 必填 | 说明                                                  |
-| ----------- | -------- | ------ | ---- | ----------------------------------------------------- |
-| `separator` | `string` | `""`   | –    | 组合键之间的分隔符(如 `"+"` / `"→"`),留空时仅用 gap。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -48,14 +38,13 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add kbd` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -64,7 +53,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/kbd/kbd.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Kbd, KbdGroup } from './kbd';
 
 const meta: Meta<typeof Kbd> = {
-  title: '基础原语 · Foundation/Kbd',
+  title: '废弃 · Deprecated/Kbd',
   component: Kbd,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '键位展示 — 语义化 `<kbd>` 元素，标注快捷键（⌘K / Ctrl + Enter）。单键 + KbdGroup 组合容器，常用于 Command Palette、Tooltip、文档帮助。antd 体系无对应原子。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n键位展示 — 语义化 `<kbd>` 元素，标注快捷键（⌘K / Ctrl + Enter）。单键 + KbdGroup 组合容器，常用于 Command Palette、Tooltip、文档帮助。antd 体系无对应原子。',
       },
     },
   },
@@ -59,7 +59,7 @@ export const WinCombo: Story = {
 export const InContext: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex items-center justify-between rounded-md border bg-card p-3 text-sm">
+    <div className="flex items-center justify-between rounded-md border border-border bg-card p-3 text-sm">
       <span>打开命令面板</span>
       <KbdGroup>
         <Kbd>⌘</Kbd>

package/src/components/kbd/kbd.tsx

@@ -5,16 +5,17 @@ import { cn } from '@/utils/cn';
 
 const kbdVariants = cva(
   // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- physical-key inset shadow; one-off effect not used elsewhere.
-  'pointer-events-none inline-flex select-none items-center gap-1 rounded border bg-muted font-mono tabular-nums text-muted-foreground shadow-[0_1px_0_0_rgba(0,0,0,0.08)]',
+  'pointer-events-none inline-flex select-none items-center gap-1 rounded border border-border bg-muted font-mono tabular-nums text-muted-foreground shadow-[0_1px_0_0_rgba(0,0,0,0.08)]',
   {
     variants: {
       size: {
         sm: 'h-4 px-1 text-xxs',
+        md: 'h-5 px-1.5 text-xs',
         default: 'h-5 px-1.5 text-xs',
         lg: 'h-6 px-2 text-sm',
       },
     },
-    defaultVariants: { size: 'default' },
+    defaultVariants: { size: 'md' },
   },
 );
 
@@ -25,7 +26,7 @@ export interface KbdProps
    * 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 
 /**
@@ -66,7 +67,10 @@ const KbdGroup = React.forwardRef<HTMLSpanElement, KbdGroupProps>(
         {items.map((child, i) => (
           <React.Fragment key={i}>
             {i > 0 && separator ? (
-              <span aria-hidden="true" className="text-xs text-muted-foreground">
+              <span
+                aria-hidden="true"
+                className="text-xs text-muted-foreground"
+              >
                 {separator}
               </span>
             ) : null}

package/src/components/label/label.meta.md

@@ -3,7 +3,7 @@ id: label
 name: Label
 displayName: 标签
 type: component
-category: foundation
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -11,7 +11,7 @@ package: '@teamix-evo/ui'
 # Label 标签
 
 表单字段标签 — 基于 [`@radix-ui/react-label`](https://www.radix-ui.com/primitives/docs/components/label) 包装。
-shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd Form.Item 风格的 `required`(红色 `*` 标记)+ 显式 `disabled` prop,适合 label 与目标控件**不直接相邻**的场景。
+shadcn 原版只继承 Radix 的 `peer-disabled:` 联动；本版本补一条 antd Form.Item 风格的 `required`（红色 `*` 标记，**后置**在文字和 tooltip icon 右侧）+ 显式 `disabled` prop，适合 label 与目标控件**不直接相邻**的场景。
 
 ## When to use
 
@@ -28,12 +28,14 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`label.tsx`](./label.tsx) 的 `LabelProps` interface JSDoc。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:props:begin -->
-
-| 名称       | 类型      | 默认值  | 必填 | 说明                                                                                                                                       |
-| ---------- | --------- | ------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `disabled` | `boolean` | `false` | –    | 视觉禁用态。除原生 `peer-disabled:` 联动外,显式置 `true` 也会触发禁用样式; 适合 label 与目标控件不直接相邻、无法走 `peer` 约束的场景。     |
-| `required` | `boolean` | `false` | –    | 必填标记。`true` 时在 children 后追加红色 `*`(语义来自 design destructive token), 配合 `aria-required` 在 input 上一起使用以保证可访问性。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean` | `false` | – | 视觉禁用态。除原生 `peer-disabled:` 联动外,显式置 `true` 也会触发禁用样式; 适合 label 与目标控件不直接相邻、无法走 `peer` 约束的场景。 |
+| `required` | `boolean` | `false` | – | 必填标记。`true` 时在 children 与 info icon **后**追加红色 `*` (语义来自 design destructive token);顺序为 `文字 ⓘ *`,三者间距 4px。 配合 `aria-required` 在 input 上一起使用以保证可访问性。 |
+| `tooltip` | `string` | – | – | 辅助说明文本 — 有值时在 label 文字后渲染 info icon + hover tooltip (对齐 antd `Form.Item.tooltip` 习惯)。 |
+| `tooltipSide` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | – | Tooltip 弹出方向。 |
+| `maxWidth` | `number \| string` | `undefined` | – | 最大宽度 — 超出时截断省略号。数字单位为 px,字符串直接用作 CSS 值。 适合长字段名在固定宽度表单中防止换行影响布局。 |
+| `minWidth` | `number` | `undefined` | – | 最小宽度(px) — 防止过度压缩,在响应式布局中保留可读宽度下限。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -41,14 +43,13 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add label` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -57,18 +58,20 @@ shadcn 原版只继承 Radix 的 `peer-disabled:` 联动;本版本补一条 antd
 ```bash
 pnpm add @radix-ui/react-label@^2.1.0 class-variance-authority@^0.7.0
 ```
-
 <!-- auto:deps:end -->
 
 > 除上述 props 外,Label 透传所有 `<label>` 原生属性(`htmlFor` / `id` / `aria-*` / `onClick` / ...)。
 
 ## AI 生成纪律
 
-- **`htmlFor` 必填**:Label 必须通过 `htmlFor` 关联到目标控件的 `id`,或把控件包裹在 Label 内。**不要**只渲染孤立 Label。
-- **`required` 配 `aria-required`**:仅视觉的 `*` 不够,目标 input 也要 `aria-required="true"`。
-- **`disabled` 不替代 input 的 disabled**:Label 的 `disabled` 仅控制视觉,目标控件的 `disabled` 必须独立设置。
-- **不内嵌交互元素**:Label 内不要放 button / link / 复杂控件 — Radix Label 的事件冒泡可能误触发关联控件。
-- **文案克制**:Label 文字 ≤ 8 个汉字 / 16 字符,过长用 Tooltip 补充。
+- **`htmlFor` 必填**：Label 必须通过 `htmlFor` 关联到目标控件的 `id`，或把控件包裹在 Label 内。**不要**只渲染孤立 Label。
+- **`required` 配 `aria-required`**：仅视觉的 `*` 不够，目标 input 也要 `aria-required="true"`。
+- **`*` 后置不可额外加空格**：请使用 `required` prop，不要手写 `<span>邮箱 *</span>`，走组件才能保证间距一致 + double-click 文字可快捷选中标题。
+- **`disabled` 不替代 input 的 disabled**：Label 的 `disabled` 仅控制视觉，目标控件的 `disabled` 必须独立设置。
+- **不内嵌交互元素**：Label 内不要放 button / link / 复杂控件 — Radix Label 的事件冒泡可能误触发关联控件。
+- **文案克制**：Label 文字 ≤ 8 个汉字 / 16 字符，过长用 `tooltip` prop 补充说明（不要手写 `<Tooltip>` 包裹）。
+- **截断走 `maxWidth`**：长 label 用 `maxWidth` 自动截断 + ellipsis，不要手写 `truncate` className。
+- **horizontal 对齐走 `minWidth`**：表单 label 列宽对齐用 `minWidth={120}` 等档位，不要手写 `min-w-32` 等 utility。
 
 ## Examples
 

package/src/components/label/label.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Label } from './label';
 
 const meta: Meta<typeof Label> = {
-  title: '基础原语 · Foundation/Label',
+  title: '数据录入 · Data Entry/Label',
   component: Label,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '表单字段标签 — Radix Label 包装,shadcn 工程基线 + antd `required` 红 `*` 与显式 `disabled` 视觉。',
+          '表单字段标签 —— 标记并描述表单控件的文本入口。Radix Label 实现 + 工程化扩展并集：`disabled` 显式禁用态(脱离 peer 也工作)、`required` 后置红色 `*`(顺序为 `文字 ⓘ *`,对齐设计规范)、`tooltip` 文字后 info icon hover 提示(对齐 antd `Form.Item.tooltip`)、`maxWidth` / `minWidth` 宽度约束 + `truncate` 省略号(应对长字段名固定栅格表单场景)。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
       },
     },
   },
@@ -19,13 +19,31 @@ const meta: Meta<typeof Label> = {
       control: 'boolean',
     },
     required: {
-      description: '必填标记,在文本后追加红色 `*`',
+      description:
+        '必填标记，在文字和 tooltip icon **后**追加红色 `*`（顺序为 `文字 ⓘ *`）',
       control: 'boolean',
     },
     children: {
       description: '标签文本',
       control: 'text',
     },
+    tooltip: {
+      description: '辅助说明文本，有值时在文字后渲染 info icon + hover tooltip',
+      control: 'text',
+    },
+    tooltipSide: {
+      description: 'tooltip 弹出方向',
+      control: 'inline-radio',
+      options: ['top', 'right', 'bottom', 'left'],
+    },
+    maxWidth: {
+      description: '最大宽度，超出截断省略号',
+      control: 'number',
+    },
+    minWidth: {
+      description: '最小宽度(px)',
+      control: 'number',
+    },
   },
   args: {
     children: '邮箱',
@@ -38,14 +56,27 @@ const meta: Meta<typeof Label> = {
 export default meta;
 type Story = StoryObj<typeof Label>;
 
-/** 默认 Label,可在 Controls 调 `required` / `disabled` 等 props。 */
+/** 默认 Label，可在 Controls 调 `required` / `disabled` 等 props。 */
 export const Playground: Story = {};
 
-/** 必填态:文本后追加红色 `*`(语义来自 design destructive token,不要手写颜色)。 */
+/** 必填态：文字和 tooltip icon **后**追加红色 `*`（顺序为 `文字 ⓘ *`，语义来自 design destructive token，对齐设计规范，不要手写颜色）。 */
 export const Required: Story = {
   args: { children: '用户名', required: true },
 };
 
+/** 对比：仅视觉示范必填 vs 非必填。 */
+export const RequiredComparison: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Label htmlFor="req-1" required>
+        必填字段
+      </Label>
+      <Label htmlFor="req-2">可选字段</Label>
+    </div>
+  ),
+};
+
 /** 禁用态:文字 70% 透明 + cursor-not-allowed。 */
 export const Disabled: Story = {
   args: { children: '只读字段', disabled: true },
@@ -85,3 +116,30 @@ export const PeerDisabled: Story = {
     </div>
   ),
 };
+
+/** 带 tooltip：文字后跟随 info icon，hover 触发气泡说明，对齐 antd `Form.Item.tooltip`。 */
+export const WithTooltip: Story = {
+  args: {
+    children: '客户编号',
+    tooltip: '由系统自动生成的全局唯一编号，提交后不可修改',
+  },
+};
+
+/** 截断：当字段名过长且布局栅格固定时，使用 `maxWidth` 触发 truncate 省略号。 */
+export const Truncated: Story = {
+  args: {
+    children: '这是一段非常非常非常长的字段标签文本',
+    maxWidth: 160,
+  },
+};
+
+/** 全特性组合：required 红 `*` + tooltip info icon + maxWidth 截断（典型业务表单形态）。 */
+export const WithAllFeatures: Story = {
+  args: {
+    children: '这是一段需要被截断的必填字段标签',
+    required: true,
+    tooltip: '该字段必填，长度限制 32 字符；超出栅格宽度自动省略，hover label 看完整文案。',
+    tooltipSide: 'right',
+    maxWidth: 200,
+  },
+};