@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/radio-group/radio-group.meta.md

@@ -1,20 +1,21 @@
 ---
 id: radio-group
 name: RadioGroup
+displayName: 单选组
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# RadioGroup
+# RadioGroup 单选组
 
 单选组 — Radix RadioGroup,**两种渲染**:
 
-| variant | 形态 | 适用 |
-| --- | --- | --- |
-| `default` | 圆点 + 文字(shadcn 风格) | 表单 / 设置面板 |
-| `button` | 按钮组(antd Radio.Button 并集) | 视图切换 / 时间区间切换 / 紧凑工具栏 |
+| variant   | 形态                           | 适用                                 |
+| --------- | ------------------------------ | ------------------------------------ |
+| `default` | 圆点 + 文字(shadcn 风格)       | 表单 / 设置面板                      |
+| `button`  | 按钮组(antd Radio.Button 并集) | 视图切换 / 时间区间切换 / 紧凑工具栏 |
 
 ## When to use
 
@@ -35,7 +36,15 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
+| `value` | `string` | – | – | 受控选中值(等价 antd `value`,Radix 命名一致)。 与 `defaultValue` 二选一,不同时传。 |
+| `defaultValue` | `string` | – | – | 非受控初始选中值。 |
+| `onValueChange` | `(value: string) => void` | – | – | 选中变化回调 — Radix 命名,等价 antd `onChange(value)`。 |
+| `disabled` | `boolean` | `false` | – | 整组禁用(灰化所有 Item / Button + 不响应交互)。 |
+| `required` | `boolean` | `false` | – | 表单必填 — 设置 HTML 原生 `required`,表单层校验依赖此值。 |
+| `name` | `string` | – | – | 表单字段名(原生 `<input name>`,提交表单时使用;同组所有 Item 共用)。 |
+| `orientation` | `'horizontal' \| 'vertical'` | `"vertical"` | – | 排列方向(键盘导航方向也跟随此值)。 |
 | `variant` | `'default' \| 'button'` | `"default"` | – | 渲染样式 — `default` 经典圆点;`button` 渲染为按钮组(antd `Radio.Button` 并集)。 |
+| `options` | `RadioGroupOption[]` | – | – | 选项数据源(数据驱动模式,与 CheckboxGroup `options` 对齐)。 传入后内部自动渲染 `RadioGroupItem` / `RadioGroupButton`,无需 `children`. 当同时存在 `children` 与 `options` 时,`children` 优先。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -68,6 +77,7 @@ pnpm add @radix-ui/react-radio-group@^1.2.0 lucide-react@^0.460.0
 - **必须有 default 选中项**:用户进入页面看到全部未选会困惑;用 `defaultValue` 给一个合理初值
 - **每项必关联 Label**:`<RadioGroupItem id="r1" value="a" /> + <Label htmlFor="r1">A</Label>` 或包裹模式
 - **value 唯一稳定**:不要用 index,变化时 controlled diff 失败
+- **横向排列固定 16px(组件内置 `gap-4`)**:对齐《Teamix UI 表单设计规范》§3.1 规则 3 "checkbox/radio 横向 16px";不要手动加 `gap-3` / `space-x-2` 等覆盖。纵向自动用 `gap-2`(8px,紧凑列表)。
 
 ## Examples
 
@@ -100,4 +110,66 @@ import { Label } from '@/components/ui/label';
   <RadioGroupButton value="month">月</RadioGroupButton>
   <RadioGroupButton value="year">年</RadioGroupButton>
 </RadioGroup>
+
+// 数据驱动模式(对齐 CheckboxGroup)
+<RadioGroup
+  options={[
+    { label: '苹果', value: 'apple' },
+    { label: '香蕉', value: 'banana' },
+    { label: '橘子', value: 'orange', disabled: true },
+  ]}
+  defaultValue="apple"
+/>
+
+// 数据驱动 + 按钮模式
+<RadioGroup
+  variant="button"
+  options={[
+    { label: '日', value: 'day' },
+    { label: '周', value: 'week' },
+    { label: '月', value: 'month' },
+  ]}
+  defaultValue="month"
+/>
 ```
+
+## Radio 形态 — 旧库 API → 新映射
+
+> 决策:**不新增独立组件**,直接用 `RadioGroup` + `RadioGroupItem` / `RadioGroupButton` 承接 cloud-design `Radio` / `Radio.Group` 全部用法。本章节是从旧库平滑迁移的查表索引,与 [上面的 Props 表](#props) 互补。
+
+### 命名映射
+
+| cloud-design 旧库                         | `@teamix-evo/ui`                                       | 说明                                                                |
+| ----------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------- |
+| `Radio` + `Radio.Group`                   | `RadioGroup` + `RadioGroupItem` / `RadioGroupButton`   | 父子拆分导出,shadcn 风格                                            |
+| `Radio.Group shape="button"`              | `<RadioGroup variant="button">` + `<RadioGroupButton>` | `shape` → `variant`(Radix 语义)                                     |
+| `Radio.Group direction="hor\|ver"`        | `<RadioGroup orientation="horizontal\|vertical">`      | 完整单词,Radix 原生 prop                                            |
+| `Radio.Group dataSource=[{label,value}]`  | `<RadioGroup options={[{label,value}]}>`               | `dataSource` → `options`(对齐 antd / CheckboxGroup)                 |
+| `Radio.Group value / onChange`            | `<RadioGroup value onValueChange>`                     | Radix 命名:`onValueChange(val: string)`                             |
+| `Radio.Group defaultValue`                | `<RadioGroup defaultValue>`                            | 同名                                                                |
+| `Radio.Group disabled`                    | `<RadioGroup disabled>`                                | 整组禁用                                                            |
+| `Radio.Group size="small\|medium\|large"` | Radix 无内置 size;可通过 className 调整                | 新库不内置 size — 按钮模式固定 h-9,圆点模式固定 size-4,满足多数场景 |
+
+### Breaking Changes(从旧库迁移时需改写)
+
+1. `Radio` → `RadioGroupItem`(import + 命名)
+2. `Radio.Group` → `RadioGroup`(独立 named export)
+3. `shape="button"` → `variant="button"`(子项同步换成 `RadioGroupButton`)
+4. `direction` → `orientation`(取值从 `hor/ver` 改为 `horizontal/vertical`)
+5. `dataSource` → `options`(签名一致)
+6. `onChange(value)` → `onValueChange(value)` (Radix 命名)
+
+### 不修复 / 后续工序清单
+
+- **按钮模式圆角**(2px → 4px):报告 §2.2,归 `@teamix-evo/tokens` 后续工序
+- **按钮模式选中视觉**(old: 品牌色边框+浅蓝底 vs new: 品牌色填充+白字):报告 §5 已标注 "新库更现代,设计确认后保留",**不修复**
+- **disabled opacity vs 灰色**:全局策略,**不修复**
+- **size prop**:新库不内置 size(Radix 无此 prop),圆点 `size-4` / 按钮 `h-9` 已覆盖多数场景;如业务确有 size 需求,属于二级 slot 后续添加
+
+### Radio 专项 AI 生成纪律
+
+- **形态由父级 `variant` + 子项组件共同决定**:default → `RadioGroupItem`,button → `RadioGroupButton`,**不要混用**
+- **数据驱动 `options` 模式与 children 互斥**:同时传时 children 优先;统一用一种写法
+- **必须有初始选中**:用 `defaultValue` 给一个合理初值(用户进入页面看到全未选会困惑)
+- **`value` 稳定唯一**:options[].value 不要用 index / 动态 ID;类同 CheckboxGroup 约束
+- **Radix `onValueChange(val: string)`**:单参数字符串,**不要按旧库习惯**期待事件对象

package/src/components/radio-group/radio-group.stories.tsx

@@ -1,15 +1,16 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { RadioGroup, RadioGroupItem, RadioGroupButton } from './radio-group';
+import type { RadioGroupOption } from './radio-group';
 
 const meta: Meta<typeof RadioGroup> = {
-  title: '表单与输入 · Form/RadioGroup',
+  title: '数据录入 · Data Entry/RadioGroup',
   component: RadioGroup,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '单选组 — 在一组互斥选项中选中唯一一个。Radix RadioGroup 实现 + antd Radio 的并集能力：同时提供默认的点选型 `RadioGroupItem` 与按钮型 `RadioGroupButton`（对齐 antd `Radio.Button`），通过 `variant` prop 切换。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '单选组 — 在一组互斥选项中选中唯一一个。Radix RadioGroup 实现 + antd Radio 的并集能力：同时提供默认的点选型 `RadioGroupItem` 与按钮型 `RadioGroupButton`（对齐 antd `Radio.Button`），通过 `variant` prop 切换。',
       },
     },
   },
@@ -75,3 +76,38 @@ export const Disabled: Story = {
     </div>
   ),
 };
+
+// ─── 数据驱动 options 模式(与 CheckboxGroup 对齐)──────────────────
+
+const fruitOptions: RadioGroupOption[] = [
+  { label: '苹果', value: 'apple' },
+  { label: '香蕉', value: 'banana' },
+  { label: '橘子', value: 'orange', disabled: true },
+];
+
+/**
+ * 数据驱动 — 对齐 cloud-design `Radio.Group dataSource` / antd `Radio.Group options`。
+ * 传入 `options` prop 即可,内部自动渲染 `RadioGroupItem` + Label。
+ */
+export const OptionsGroup: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <RadioGroup options={fruitOptions} defaultValue="apple" />,
+};
+
+/**
+ * 数据驱动 + 按钮模式 — `variant="button"` + `options`。
+ */
+export const OptionsButtonGroup: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <RadioGroup
+      variant="button"
+      options={[
+        { label: '日', value: 'day' },
+        { label: '周', value: 'week' },
+        { label: '月', value: 'month' },
+      ]}
+      defaultValue="month"
+    />
+  ),
+};

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

@@ -4,35 +4,149 @@ import { Circle } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 
+// ─── RadioGroupOption(数据驱动模式,对齐 CheckboxGroup)────────────────
+
+export interface RadioGroupOption {
+  label: React.ReactNode;
+  value: string;
+  disabled?: boolean;
+}
+
 export interface RadioGroupProps
-  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>,
+    | 'value'
+    | 'defaultValue'
+    | 'onValueChange'
+    | 'disabled'
+    | 'required'
+    | 'name'
+    | 'orientation'
+    | 'dir'
+    | 'loop'
+  > {
+  /**
+   * 受控选中值(等价 antd `value`,Radix 命名一致)。
+   * 与 `defaultValue` 二选一,不同时传。
+   */
+  value?: string;
+  /** 非受控初始选中值。 */
+  defaultValue?: string;
+  /**
+   * 选中变化回调 — Radix 命名,等价 antd `onChange(value)`。
+   */
+  onValueChange?: (value: string) => void;
+  /**
+   * 整组禁用(灰化所有 Item / Button + 不响应交互)。
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * 表单必填 — 设置 HTML 原生 `required`,表单层校验依赖此值。
+   * @default false
+   */
+  required?: boolean;
+  /** 表单字段名(原生 `<input name>`,提交表单时使用;同组所有 Item 共用)。 */
+  name?: string;
+  /**
+   * 排列方向(键盘导航方向也跟随此值)。
+   * @default "vertical"
+   */
+  orientation?: 'horizontal' | 'vertical';
   /**
    * 渲染样式 — `default` 经典圆点;`button` 渲染为按钮组(antd `Radio.Button` 并集)。
    * @default "default"
    */
   variant?: 'default' | 'button';
+  /**
+   * 选项数据源(数据驱动模式,与 CheckboxGroup `options` 对齐)。
+   * 传入后内部自动渲染 `RadioGroupItem` / `RadioGroupButton`,无需 `children`.
+   * 当同时存在 `children` 与 `options` 时,`children` 优先。
+   */
+  options?: RadioGroupOption[];
 }
 
 const RadioGroup = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Root>,
   RadioGroupProps
->(({ className, variant = 'default', ...props }, ref) => (
-  <RadioGroupPrimitive.Root
-    ref={ref}
-    data-variant={variant}
-    className={cn(
-      variant === 'button'
-        ? 'inline-flex divide-x divide-input overflow-hidden rounded-md border border-input shadow-sm'
-        : 'grid gap-2',
-      className,
-    )}
-    {...props}
-  />
-));
+>(({ className, variant = 'default', orientation = 'vertical', options, children, ...props }, ref) => {
+  // children 优先;仅当无 children 且传入 options 时内部渲染
+  const content =
+    children ||
+    (options &&
+      options.map((opt) =>
+        variant === 'button' ? (
+          <RadioGroupButton
+            key={opt.value}
+            value={opt.value}
+            disabled={opt.disabled}
+          >
+            {opt.label}
+          </RadioGroupButton>
+        ) : (
+          <div key={opt.value} className="flex items-center gap-2 text-xs">
+            <RadioGroupItem
+              value={opt.value}
+              id={`rg-opt-${opt.value}`}
+              disabled={opt.disabled}
+            />
+            <label
+              htmlFor={`rg-opt-${opt.value}`}
+              className={cn(
+                (opt.disabled || props.disabled) &&
+                  'cursor-not-allowed opacity-60',
+              )}
+            >
+              {opt.label}
+            </label>
+          </div>
+        ),
+      ));
+
+  return (
+    <RadioGroupPrimitive.Root
+      ref={ref}
+      data-variant={variant}
+      data-orientation={orientation}
+      orientation={orientation}
+      className={cn(
+        variant === 'button'
+          ? 'inline-flex divide-x divide-input overflow-hidden rounded-md border border-input shadow-sm'
+          : // 默认形态:横向 16px (gap-4, 对齐规范 §3.1 规则 3 "checkbox/radio 横向 16px"),
+            // 纵向 8px (gap-2, 紧凑列表)
+            orientation === 'horizontal'
+            ? 'flex flex-wrap gap-4'
+            : 'grid gap-2',
+        className,
+      )}
+      {...props}
+    >
+      {content}
+    </RadioGroupPrimitive.Root>
+  );
+});
 RadioGroup.displayName = RadioGroupPrimitive.Root.displayName;
 
 export interface RadioGroupItemProps
-  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> {}
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>,
+    'value' | 'disabled' | 'required' | 'id'
+  > {
+  /**
+   * 选项 value — 选中时把此值赋给 RadioGroup 的 `value`。
+   * **必填** — 每个 Item 必须有稳定唯一的 value(string)。
+   */
+  value: string;
+  /**
+   * 禁用此选项(整组 `disabled` 会覆盖单项的 `disabled={false}`)。
+   * @default false
+   */
+  disabled?: boolean;
+  /** 必填(透传 HTML required)。 */
+  required?: boolean;
+  /** id 属性,配合 `<label htmlFor>` 关联选项文字。 */
+  id?: string;
+}
 
 const RadioGroupItem = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Item>,
@@ -41,7 +155,7 @@ const RadioGroupItem = React.forwardRef<
   <RadioGroupPrimitive.Item
     ref={ref}
     className={cn(
-      'aspect-square size-4 rounded-full border border-primary text-primary shadow focus:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
+      'aspect-square size-4 cursor-pointer rounded-full border border-primary text-primary shadow focus:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
       className,
     )}
     {...props}
@@ -56,7 +170,24 @@ RadioGroupItem.displayName = RadioGroupPrimitive.Item.displayName;
 // ─── RadioGroupButton(Button-style item, antd `Radio.Button` 并集)───────
 
 export interface RadioGroupButtonProps
-  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item> {}
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>,
+    'value' | 'disabled' | 'required' | 'id'
+  > {
+  /**
+   * 选项 value — 选中时把此值赋给 RadioGroup 的 `value`。**必填**,稳定唯一。
+   */
+  value: string;
+  /**
+   * 禁用此选项(整组 `disabled` 会覆盖单项的 `disabled={false}`)。
+   * @default false
+   */
+  disabled?: boolean;
+  /** 必填(透传 HTML required)。 */
+  required?: boolean;
+  /** id 属性,通常无需手传(按钮组形态自身已含可点击区域)。 */
+  id?: string;
+}
 
 const RadioGroupButton = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Item>,
@@ -65,7 +196,7 @@ const RadioGroupButton = React.forwardRef<
   <RadioGroupPrimitive.Item
     ref={ref}
     className={cn(
-      'inline-flex h-9 cursor-pointer items-center justify-center px-4 text-sm font-medium transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:hover:bg-primary/90',
+      'inline-flex h-9 cursor-pointer items-center justify-center px-4 text-xs font-medium transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=checked]:text-primary-foreground data-[state=checked]:hover:bg-primary/90',
       className,
     )}
     {...props}

package/src/components/rate/rate.meta.md

@@ -1,13 +1,14 @@
 ---
 id: rate
 name: Rate
+displayName: 评分
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Rate
+# Rate 评分
 
 星级评分 — antd 独有补足。**等价 antd `Rate`**。支持半星(`allowHalf`)、再次点击清零(`allowClear`)、自定义图标(`character`)、只读展示(`disabled`)。
 
@@ -22,6 +23,8 @@ package: "@teamix-evo/ui"
 - 二元选择(喜欢 / 不喜欢)→ `Toggle` / `Button` 配 icon
 - 多档定量评分(0~100)→ `Slider`
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -31,11 +34,13 @@ package: "@teamix-evo/ui"
 | `allowHalf` | `boolean` | `false` | – | 允许半星(antd `allowHalf` 并集) — 启用后单星可点击左半 / 右半。 |
 | `allowClear` | `boolean` | `true` | – | 允许再次点击同值清零(antd `allowClear` 并集)。 |
 | `disabled` | `boolean` | – | – | 禁用(只展示)。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸(影响星图大小)。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸(影响星图大小)。 |
 | `character` | `React.ReactNode` | – | – | 自定义图标(antd `character` 并集) — 默认 `lucide-react` 的 `Star`。 |
 | `onChange` | `(value: number) => void` | – | – | value 变化回调。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -61,6 +66,8 @@ pnpm add lucide-react@^0.460.0
 - **`allowClear` 默认 true** — 与 antd 一致;关闭后用户无法清空评分,只能改值
 - **`character` 自定义图标**:必须是 `React.isValidElement` 节点,组件会在选中态注入 `fill="currentColor"`;**不要**传字符串
 - **大评分场景**(`count > 7`)视觉拥挤,建议改用 `Slider` + 数字展示
+- **尺寸与 cloud-design 对齐**:`sm/default/lg` = 16/20/24px,与其他表单表一致的密度作业
+- **半星渲染分两层**:底层 `text-muted-foreground/30` 描边空星 · 上层 `clipPath: inset(0 50% 0 0)` 裁切到左半边 + `text-warning` 填充;**不要**反过来(会丢失右半边描边)
 
 ## Examples
 
@@ -85,3 +92,27 @@ const [v, setV] = React.useState(0);
 // 只读
 <Rate disabled value={4.5} allowHalf />
 ```
+
+## Rating 形态 — 旧库 API → 新库映射
+
+> 旧库(Teamix 1.0 / `@alifd/next.Rating`)→ 新库 `Rate`(对齐 antd 命名)。能力**全部并集已实现**,只有少量低频 prop 不修复。
+
+| 旧库 API | 新库 API | 备注 |
+| --- | --- | --- |
+| 组件名 `Rating` | `Rate` | 对齐 antd 命名 |
+| `count` | `count` | 同名 |
+| `value` / `defaultValue` | `value` / `defaultValue` | 同名 |
+| `onChange` | `onChange` | 同名 |
+| `allowHalf` | `allowHalf` | ✅ 已实现 — 半星裁切渲染(clipPath) |
+| `readOnly` | `disabled` | 只展示场景用 `disabled` 实现(antd 当前版本也只有 disabled) |
+| `size="small\|medium\|large"` | `size="sm\|md\|lg"` | 三档对应 16/20/24px |
+| `character` 自定义图标 | `character` | ✅ 已实现 — 默认 `lucide.Star`,可传任意 ReactNode |
+| `showGrade` 文案展示 | 不修复 | 外部组合 `<Text>` 更灵活,P2 |
+| `onHoverChange` 悬浮值回调 | 不修复 | 低频,P2 |
+| `isPreview` / `renderPreview` | `disabled` 替代 | 旧库低频 API,直接用 disabled |
+
+### 不修复 / 后续工序清单
+
+- **`showGrade` 文案展示**(P2):用 `<Rate value={4} disabled /> <Text>4.5 / 5</Text>` 外部组合更灵活
+- **`onHoverChange` 悬浮回调**(P2):低频,业务侧用 `onMouseEnter` 事件捕获 thumb 位置自管
+- **`isPreview` / `renderPreview`**:报告 §5 已列入"保留新库优势",`disabled` 已能替代,**不修复**

package/src/components/rate/rate.stories.tsx

@@ -1,17 +1,17 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Heart } from 'lucide-react';
 import { Rate } from './rate';
 
 const meta: Meta<typeof Rate> = {
-  title: '表单与输入 · Form/Rate',
+  title: '数据录入 · Data Entry/Rate',
   component: Rate,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '星级评分 — 评论 / 商品评分 / 偏好满意度。支持半星 + 再次点击清零 + 自定义图标 + 只读展示。等价 antd `Rate`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '星级评分 — 评论 / 商品评分 / 偏好满意度。支持半星 + 再次点击清零 + 自定义图标 + 只读展示。等价 antd `Rate`。',
       },
     },
   },
@@ -22,7 +22,13 @@ const meta: Meta<typeof Rate> = {
     disabled: { control: 'boolean' },
     size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
   },
-  args: { count: 5, allowHalf: false, allowClear: true, disabled: false, size: 'default' },
+  args: {
+    count: 5,
+    allowHalf: false,
+    allowClear: true,
+    disabled: false,
+    size: 'default',
+  },
 };
 
 export default meta;
@@ -64,7 +70,9 @@ export const ReadOnly: Story = {
   render: () => (
     <div className="flex items-center gap-2">
       <Rate disabled value={4.5} allowHalf size="sm" />
-      <span className="text-sm text-muted-foreground">4.5 / 5 (1,287 评价)</span>
+      <span className="text-sm text-muted-foreground">
+        4.5 / 5 (1,287 评价)
+      </span>
     </div>
   ),
 };

package/src/components/rate/rate.tsx

@@ -4,7 +4,10 @@ import { Star } from 'lucide-react';
 import { cn } from '@/utils/cn';
 
 export interface RateProps
-  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  extends Omit<
+    React.HTMLAttributes<HTMLDivElement>,
+    'onChange' | 'defaultValue'
+  > {
   /**
    * 总星数(antd `count` 并集)。
    * @default 5
@@ -30,7 +33,7 @@ export interface RateProps
    * 尺寸(影响星图大小)。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
   /**
    * 自定义图标(antd `character` 并集) — 默认 `lucide-react` 的 `Star`。
    */
@@ -39,10 +42,12 @@ export interface RateProps
   onChange?: (value: number) => void;
 }
 
+// 与 cloud-design Rating small/medium/large = 16/20/24 对齐,使用三档以调与其他表单控件一致的视觉密度。
 const sizeMap = {
   sm: 'size-4',
+  md: 'size-5',
   default: 'size-5',
-  lg: 'size-7',
+  lg: 'size-6',
 } as const;
 
 const Rate = React.forwardRef<HTMLDivElement, RateProps>(
@@ -54,7 +59,7 @@ const Rate = React.forwardRef<HTMLDivElement, RateProps>(
       allowHalf = false,
       allowClear = true,
       disabled = false,
-      size = 'default',
+      size = 'md',
       character,
       onChange,
       className,
@@ -77,6 +82,10 @@ const Rate = React.forwardRef<HTMLDivElement, RateProps>(
 
     const Icon = character ?? <Star className={cn(sizeMap[size])} />;
 
+    // 未选中的底色 — 使用 `text-muted-foreground/30` 与 cloud-design 空星描边一致
+    const inactiveClass = 'text-muted-foreground/30';
+    const activeClass = 'text-warning';
+
     return (
       <div
         ref={ref}
@@ -128,18 +137,36 @@ const Rate = React.forwardRef<HTMLDivElement, RateProps>(
               ) : null}
 
               {filledFull ? (
-                <span className="text-amber-400">{React.isValidElement(Icon) ? React.cloneElement(Icon as React.ReactElement<{ fill?: string }>, { fill: 'currentColor' }) : Icon}</span>
+                <span className={activeClass}>
+                  {React.isValidElement(Icon)
+                    ? React.cloneElement(
+                        Icon as React.ReactElement<{ fill?: string }>,
+                        { fill: 'currentColor' },
+                      )
+                    : Icon}
+                </span>
               ) : filledHalf ? (
-                <span className="relative inline-block text-amber-400">
-                  <span className="absolute inset-0 overflow-hidden" style={{ clipPath: 'inset(0 50% 0 0)' }}>
+                <span className="relative inline-block">
+                  {/* 底层:描边空星(完整轮廓,取代 muted-foreground/40 深度运动) */}
+                  <span className={inactiveClass}>{Icon}</span>
+                  {/* 上层:裁切到左半边 + 填充 currentColor */}
+                  <span
+                    className={cn(
+                      'absolute inset-0 overflow-hidden',
+                      activeClass,
+                    )}
+                    style={{ clipPath: 'inset(0 50% 0 0)' }}
+                  >
                     {React.isValidElement(Icon)
-                      ? React.cloneElement(Icon as React.ReactElement<{ fill?: string }>, { fill: 'currentColor' })
+                      ? React.cloneElement(
+                          Icon as React.ReactElement<{ fill?: string }>,
+                          { fill: 'currentColor' },
+                        )
                       : Icon}
                   </span>
-                  <span className="text-muted-foreground/40">{Icon}</span>
                 </span>
               ) : (
-                <span className="text-muted-foreground/40">{Icon}</span>
+                <span className={inactiveClass}>{Icon}</span>
               )}
             </span>
           );

package/src/components/resizable/resizable.meta.md

@@ -1,13 +1,14 @@
 ---
 id: resizable
 name: Resizable
+displayName: 可拖拽分栏
 type: component
 category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Resizable
+# Resizable 可拖拽分栏
 
 可拖拽分栏 — 基于 [`react-resizable-panels`](https://react-resizable-panels.vercel.app/),桌面应用 / 编辑器风格(VS Code、Figma、Slack)。
 对应 antd `Splitter`(v5.16+)的核心场景。
@@ -25,10 +26,14 @@ package: "@teamix-evo/ui"
 - 临时分栏 → `Sheet` / `Drawer`
 - 卡片网格 → CSS Grid
 
+## Props
+
 <!-- auto:props:begin -->
 _(组件无 `<Name>Props` interface — props 详见 [`resizable.tsx`](./resizable.tsx))_
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -47,8 +52,6 @@ pnpm add react-resizable-panels@^2.0.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 子组件:`ResizablePanelGroup`(`direction="horizontal" | "vertical"`)/ `ResizablePanel`(`defaultSize / minSize / maxSize` 百分比)/ `ResizableHandle`(分隔条,`withHandle` 显示握把)。
-
 ## AI 生成纪律
 
 - **`PanelGroup` 必给容器固定尺寸**:height / width 不能 0(否则面板无可分配空间)