@teamix-evo/ui 0.1.1 → 0.2.0

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

@@ -59,9 +59,10 @@ const InputGroupAddon = React.forwardRef<HTMLDivElement, InputGroupAddonProps>(
         variant === 'text' &&
           'border-input bg-muted px-3 text-sm text-muted-foreground',
         variant === 'icon' && 'px-2 text-muted-foreground',
-        variant === 'button' && '[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none',
-        position === 'before' && variant !== 'icon' && 'border-r',
-        position === 'after' && variant !== 'icon' && 'border-l',
+        variant === 'button' &&
+          '[&>*]:rounded-none [&>*]:border-0 [&>*]:shadow-none',
+        position === 'before' && variant !== 'icon' && 'border-r border-input',
+        position === 'after' && variant !== 'icon' && 'border-l border-input',
         className,
       )}
       {...props}

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

@@ -4,10 +4,11 @@ name: InputNumber
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 数字输入框
 ---
 
-# InputNumber
+# InputNumber 数字输入框
 
 数字输入 — antd 独有补足。**等价 antd `InputNumber`**。区别于原生 `<input type="number">`:步进按钮显隐可配、范围裁剪与精度由组件保证、千分位展示、键盘 ↑↓ 步进、支持空状态(`value=null`)。
 
@@ -24,29 +25,36 @@ package: "@teamix-evo/ui"
 - 多档枚举 → `Segmented` / `RadioGroup`
 - 普通文本输入 → `Input`
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `value` | `number \| null` | – | – | 受控值 — `null` 等价空输入。 |
-| `defaultValue` | `number \| null` | – | – | uncontrolled 初值。 |
-| `onChange` | `(value: number \| null) => void` | – | – | 值变化回调 — 输入清空时传 `null`,正常输入 / 步进传 `number`。 |
-| `min` | `number` | – | – | 最小值(antd `min` 并集)。 |
-| `max` | `number` | – | – | 最大值(antd `max` 并集)。 |
-| `step` | `number` | `1` | – | 步长(antd `step` 并集) — 增 / 减按钮以及键盘 ↑↓ 都按此步长。 |
-| `precision` | `number` | – | – | 数值精度(antd `precision` 并集) — 保留小数位数(超出会四舍五入)。 |
-| `groupSeparator` | `boolean` | `false` | – | 千分位分隔展示(仅展示用,实际 value 仍是 number)。 |
-| `controls` | `boolean` | `true` | – | 是否显示右侧上下步进按钮(antd `controls` 并集) — `false` 时隐藏。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
+
+| 名称             | 类型                              | 默认值      | 必填 | 说明                                                              |
+| ---------------- | --------------------------------- | ----------- | ---- | ----------------------------------------------------------------- |
+| `value`          | `number \| null`                  | –           | –    | 受控值 — `null` 等价空输入。                                      |
+| `defaultValue`   | `number \| null`                  | –           | –    | uncontrolled 初值。                                               |
+| `onChange`       | `(value: number \| null) => void` | –           | –    | 值变化回调 — 输入清空时传 `null`,正常输入 / 步进传 `number`。     |
+| `min`            | `number`                          | –           | –    | 最小值(antd `min` 并集)。                                         |
+| `max`            | `number`                          | –           | –    | 最大值(antd `max` 并集)。                                         |
+| `step`           | `number`                          | `1`         | –    | 步长(antd `step` 并集) — 增 / 减按钮以及键盘 ↑↓ 都按此步长。      |
+| `precision`      | `number`                          | –           | –    | 数值精度(antd `precision` 并集) — 保留小数位数(超出会四舍五入)。  |
+| `groupSeparator` | `boolean`                         | `false`     | –    | 千分位分隔展示(仅展示用,实际 value 仍是 number)。                 |
+| `controls`       | `boolean`                         | `true`      | –    | 是否显示右侧上下步进按钮(antd `controls` 并集) — `false` 时隐藏。 |
+| `size`           | `'sm' \| 'default' \| 'lg'`       | `"default"` | –    | 尺寸。                                                            |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add input-number` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -55,6 +63,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

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

@@ -10,7 +10,7 @@ const meta: Meta<typeof InputNumber> = {
     docs: {
       description: {
         component:
-          '数字输入框 — 区别于原生 type=number:步进按钮显隐可配、范围裁剪与精度由组件保证、千分位展示、键盘 ↑↓ 步进、支持空状态。等价 antd `InputNumber`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '数字输入框 — 区别于原生 type=number：步进按钮显隐可配、范围裁剪与精度由组件保证、千分位展示、键盘 ↑↓ 步进、支持空状态。等价 antd `InputNumber`。',
       },
     },
   },
@@ -20,7 +20,12 @@ const meta: Meta<typeof InputNumber> = {
     groupSeparator: { control: 'boolean' },
     disabled: { control: 'boolean' },
   },
-  args: { size: 'default', controls: true, groupSeparator: false, disabled: false },
+  args: {
+    size: 'default',
+    controls: true,
+    groupSeparator: false,
+    disabled: false,
+  },
 };
 
 export default meta;
@@ -28,7 +33,13 @@ type Story = StoryObj<typeof InputNumber>;
 
 export const Playground: Story = {
   render: (args) => (
-    <InputNumber {...args} defaultValue={10} min={0} max={100} className="w-40" />
+    <InputNumber
+      {...args}
+      defaultValue={10}
+      min={0}
+      max={100}
+      className="w-40"
+    />
   ),
 };
 

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

@@ -6,7 +6,14 @@ import { cn } from '@/utils/cn';
 export interface InputNumberProps
   extends Omit<
     React.InputHTMLAttributes<HTMLInputElement>,
-    'onChange' | 'value' | 'defaultValue' | 'min' | 'max' | 'step' | 'type' | 'size'
+    | 'onChange'
+    | 'value'
+    | 'defaultValue'
+    | 'min'
+    | 'max'
+    | 'step'
+    | 'type'
+    | 'size'
   > {
   /** 受控值 — `null` 等价空输入。 */
   value?: number | null;
@@ -100,7 +107,8 @@ const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
     const current = isControlled ? value! : internal;
     const [editing, setEditing] = React.useState<string | null>(null);
 
-    const display = editing !== null ? editing : format(current, precision, groupSeparator);
+    const display =
+      editing !== null ? editing : format(current, precision, groupSeparator);
 
     const clamp = (n: number): number => {
       let v = n;
@@ -178,11 +186,14 @@ const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
           {...props}
         />
         {controls ? (
-          <div className="flex flex-col border-l">
+          <div className="flex flex-col border-l border-input">
             <button
               type="button"
               tabIndex={-1}
-              disabled={disabled || (typeof max === 'number' && (current ?? -Infinity) >= max)}
+              disabled={
+                disabled ||
+                (typeof max === 'number' && (current ?? -Infinity) >= max)
+              }
               onClick={() => step1(1)}
               aria-label="增加"
               className="flex h-1/2 items-center justify-center px-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-30"
@@ -192,10 +203,13 @@ const InputNumber = React.forwardRef<HTMLInputElement, InputNumberProps>(
             <button
               type="button"
               tabIndex={-1}
-              disabled={disabled || (typeof min === 'number' && (current ?? Infinity) <= min)}
+              disabled={
+                disabled ||
+                (typeof min === 'number' && (current ?? Infinity) <= min)
+              }
               onClick={() => step1(-1)}
               aria-label="减少"
-              className="flex h-1/2 items-center justify-center border-t px-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-30"
+              className="flex h-1/2 items-center justify-center border-t border-input px-1.5 text-muted-foreground hover:bg-accent hover:text-foreground disabled:cursor-not-allowed disabled:opacity-30"
             >
               <ChevronDown className="size-3" />
             </button>

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

@@ -4,10 +4,11 @@ name: InputOTP
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 验证码输入
 ---
 
-# InputOTP
+# InputOTP 验证码输入
 
 OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/input-otp)。**shadcn-only**(antd 无对标组件)。
 4~8 位短验证码常见场景:登录、二步验证、支付确认。
@@ -29,10 +30,20 @@ OTP 验证码输入 — 基于 [`input-otp`](https://github.com/guilhermerodz/in
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`InputOTP` 透传 `input-otp` 的所有 props。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `className` | `string` | – | – | 输入框 className,作用在隐藏的真实 input 上;通常无需关心。 |
-| `containerClassName` | `string` | – | – | 容器 className,作用在 slot 列表外层 wrapper 上, 用于覆盖默认的 `flex items-center gap-2`。 |
+
+#### InputOTP
+
+| 名称                 | 类型     | 默认值 | 必填 | 说明                                                                                         |
+| -------------------- | -------- | ------ | ---- | -------------------------------------------------------------------------------------------- |
+| `className`          | `string` | –      | –    | 输入框 className，作用在隐藏的真实 input 上；通常无需关心。                                  |
+| `containerClassName` | `string` | –      | –    | 容器 className，作用在 slot 列表外层 wrapper 上， 用于覆盖默认的 `flex items-center gap-2`。 |
+
+#### InputOTPSlot
+
+| 名称    | 类型     | 默认值 | 必填 | 说明                                       |
+| ------- | -------- | ------ | ---- | ------------------------------------------ |
+| `index` | `number` | –      | ✔    | Slot 索引（必传）。OTP 的 slots 数组下标。 |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -40,13 +51,14 @@ 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 依赖
 
@@ -55,6 +67,7 @@ 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

@@ -16,7 +16,7 @@ const meta: Meta<typeof InputOTP> = {
     docs: {
       description: {
         component:
-          '一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '一次性密码输入 — 短信 / 邮箱验证码场景的格式化输入，每位字符独立可视 slot。基于 [`input-otp`](https://input-otp.rodz.dev/) 实现，自动处理粘贴、键盘前后切换、IME 与 SMS autofill；通过 `pattern` 限制输入字符集(数字 / 字母数字)。shadcn 专有能力，填补 antd 未提供的验证码输入场景。',
       },
     },
   },

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

@@ -4,10 +4,11 @@ name: Item
 type: component
 category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 列表项
 ---
 
-# Item
+# Item 列表项
 
 通用列表项 / 卡片项容器 — shadcn 2025-10 新增。**取代我们之前自实现的 `List.Item` + `List.Item.Meta`**(antd 老 List 在 v6 已 deprecated)。用 5 个语义槽组合:`ItemMedia` 媒体 / `ItemContent` 主体 / `ItemTitle` 标题 / `ItemDescription` 描述 / `ItemActions` 操作。排列用 `ItemGroup`(纵向 + 分隔)或自行 div / ul 自由布局。
 
@@ -24,21 +25,42 @@ package: "@teamix-evo/ui"
 - 完整业务卡片(带 Header / Cover / Footer)→ `Card`
 - 树形嵌套 → `Tree`
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `variant` | `'default' \| 'outline' \| 'muted'` | `"default"` | – | 视觉变体 — `default` 透明无边框(嵌入 List / Group 用);`outline` 卡片化(独立卡片);`muted` 灰底卡片。 |
-| `interactive` | `boolean` | `false` | – | 是否带 hover 高亮 + cursor-pointer(行可点击场景)。 |
+
+#### 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 之间显示分割线。 |
+
 <!-- 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 依赖
 
@@ -47,6 +69,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

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

@@ -20,12 +20,15 @@ const meta: Meta<typeof Item> = {
     docs: {
       description: {
         component:
-          '通用列表项 / 卡片项 — 5 个语义槽组合(ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions),配 ItemGroup 纵向排列。shadcn 2025-10 新增,取代之前自实现的 List.Item(antd 老 List 在 v6 已 deprecated)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '通用列表项 / 卡片项 — 5 个语义槽组合（ItemMedia / ItemContent / ItemTitle / ItemDescription / ItemActions），配 ItemGroup 纵向排列。shadcn 2025-10 新增，取代之前自实现的 List.Item（antd 老 List 在 v6 已 deprecated）。',
       },
     },
   },
   argTypes: {
-    variant: { control: 'inline-radio', options: ['default', 'outline', 'muted'] },
+    variant: {
+      control: 'inline-radio',
+      options: ['default', 'outline', 'muted'],
+    },
     interactive: { control: 'boolean' },
   },
   args: { variant: 'default', interactive: false },

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

@@ -1,13 +1,14 @@
 ---
 id: kbd
 name: Kbd
+displayName: 键位展示
 type: component
 category: foundation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Kbd
+# Kbd 键位展示
 
 键位展示 — shadcn 2025-10 新增。语义化的 `<kbd>` 元素 + `KbdGroup` 组合容器,用于在 UI 中标注**快捷键**(`⌘K` / `Ctrl + Enter` / `Esc`)。常见于 Command Palette、Tooltip、文档 / 帮助提示。
 
@@ -22,20 +23,39 @@ package: "@teamix-evo/ui"
 - 引用代码片段 → 用 `<code>` / Typography Code(`<Kbd>` 语义是物理键位)
 - 普通行内强调 → 用 `<strong>` / Typography Text strong
 
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
+
+#### Kbd
+
+| 名称   | 类型                        | 默认值      | 必填 | 说明                                                          |
+| ------ | --------------------------- | ----------- | ---- | ------------------------------------------------------------- |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | –    | 尺寸 — 与文字行高匹配,大尺寸用于 Command Palette 等突出展示。 |
+
+#### KbdGroup
+
+| 名称        | 类型     | 默认值 | 必填 | 说明                                                  |
+| ----------- | -------- | ------ | ---- | ----------------------------------------------------- |
+| `separator` | `string` | `""`   | –    | 组合键之间的分隔符(如 `"+"` / `"→"`),留空时仅用 gap。 |
+
 <!-- auto:props:end -->
 
+## 依赖
+
+> 以下表格由 `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 依赖
 
@@ -44,6 +64,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

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

@@ -9,7 +9,7 @@ const meta: Meta<typeof Kbd> = {
     docs: {
       description: {
         component:
-          '键位展示 — 语义化 `<kbd>` 元素,标注快捷键(⌘K / Ctrl + Enter)。单键 + KbdGroup 组合容器,常用于 Command Palette、Tooltip、文档帮助。shadcn 2025-10 新增,antd 体系无对应原子。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '键位展示 — 语义化 `<kbd>` 元素，标注快捷键（⌘K / Ctrl + Enter）。单键 + KbdGroup 组合容器，常用于 Command Palette、Tooltip、文档帮助。antd 体系无对应原子。',
       },
     },
   },

package/src/components/kbd/kbd.tsx

@@ -4,11 +4,12 @@ import { cva, type VariantProps } from 'class-variance-authority';
 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)]',
   {
     variants: {
       size: {
-        sm: 'h-4 px-1 text-[10px]',
+        sm: 'h-4 px-1 text-xxs',
         default: 'h-5 px-1.5 text-xs',
         lg: 'h-6 px-2 text-sm',
       },

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

@@ -1,13 +1,14 @@
 ---
 id: label
 name: Label
+displayName: 标签
 type: component
 category: foundation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Label
+# 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 与目标控件**不直接相邻**的场景。
@@ -27,10 +28,12 @@ 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 后追加红色 `*`(语义来自 design destructive token), 配合 `aria-required` 在 input 上一起使用以保证可访问性。 |
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -38,13 +41,14 @@ 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 依赖
 
@@ -53,6 +57,7 @@ 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` / ...)。

package/src/components/masonry/masonry.meta.md

@@ -1,13 +1,14 @@
 ---
 id: masonry
 name: Masonry
+displayName: 瀑布流
 type: component
 category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Masonry
+# Masonry 瀑布流
 
 瀑布流 — antd 独有补足。**等价 antd `Masonry`**(v6.0 新)。基于 CSS `column-count` + `break-inside: avoid` 的纯 CSS 实现 — **0 JS、SSR 友好、自动按 children 高度填充列**。
 
@@ -23,25 +24,33 @@ package: "@teamix-evo/ui"
 - 严格视觉对齐(按"哪列最矮就填哪列")→ 用 JS-driven masonry(react-masonry-css)
 - 等宽等高数据流 → `List grid={{column:N}}` / `Item` + Tailwind grid
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `columns` | `number` | `3` | – | 列数(antd `columns` 并集) — 固定值或响应式断点配置 `{ default, sm, md, lg, xl }`。 **响应式注意**:本组件用 CSS `column-count`,断点匹配靠 Tailwind `@container` 不便, 简化为 fixed 列数。响应式建议直接在外层包 className(如 `md:columns-3 columns-2`)+ `columns={undefined}`。 |
-| `gap` | `number` | `16` | – | 列间距(像素)。 |
+
+| 名称      | 类型     | 默认值 | 必填 | 说明                                                                                                                                                                                                                                                                           |
+| --------- | -------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `columns` | `number` | `3`    | –    | 列数(antd `columns` 并集) — 固定值或响应式断点配置 `{ default, sm, md, lg, xl }`。 **响应式注意**:本组件用 CSS `column-count`,断点匹配靠 Tailwind `@container` 不便, 简化为 fixed 列数。响应式建议直接在外层包 className(如 `md:columns-3 columns-2`)+ `columns={undefined}`。 |
+| `gap`     | `number` | `16`   | –    | 列间距(像素)。                                                                                                                                                                                                                                                                 |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add masonry` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/masonry/masonry.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Masonry> = {
     docs: {
       description: {
         component:
-          '瀑布流 — CSS column-count + break-inside: avoid 的 0 JS 实现(图片墙 / 资讯卡片流 / Dashboard 卡片墙)。等价 antd `Masonry`(v6.0 新)。响应式建议外层 className 控制(`md:columns-3`)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '瀑布流 — CSS column-count + break-inside: avoid 的 0 JS 实现(图片墙 / 资讯卡片流 / Dashboard 卡片墙)。等价 antd `Masonry`(v6.0 新)。响应式建议外层 className 控制。',
       },
     },
   },
@@ -55,7 +55,9 @@ export const ColorfulPhotos: Story = {
           className="rounded-md bg-muted text-center text-xs text-muted-foreground"
           style={{
             height: c.h,
-            background: `linear-gradient(135deg, hsl(${(c.id * 30) % 360}, 60%, 70%), hsl(${(c.id * 30 + 60) % 360}, 60%, 50%))`,
+            background: `linear-gradient(135deg, hsl(${
+              (c.id * 30) % 360
+            }, 60%, 70%), hsl(${(c.id * 30 + 60) % 360}, 60%, 50%))`,
           }}
         >
           <span className="block py-2 text-white/90">photo {c.id + 1}</span>

package/src/components/masonry/masonry.tsx

@@ -44,6 +44,7 @@ const Masonry = React.forwardRef<HTMLDivElement, MasonryProps>(
         {items.map((child, i) => (
           <div
             key={i}
+            // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- runtime CSS var driven by `gap` prop; consumes per-instance var, not tokenizable.
             className="mb-[var(--masonry-gap)] break-inside-avoid"
             style={{ ['--masonry-gap' as string]: `${gap}px` }}
           >