@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,92 @@
+---
+id: button-group
+name: ButtonGroup
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# ButtonGroup
+
+按钮组 — shadcn 2025-10 新增,**等价 antd `Space.Compact`**(v6 替代旧 `Button.Group`)。把多个按钮 / 输入框"粘"在一起共享边线,用于 Split Button、Toolbar、Input + Button 拼装等场景。配 `ButtonGroupText` 渲染只读 addon 文本。
+
+## When to use
+
+- Split Button(主操作 + 右侧下拉箭头)
+- Toolbar(同语义按钮集合,如 "上一页 / 下一页 / 跳转")
+- Input + 按钮拼装(搜索框、单位选择)
+- 多档切换显示(配 `Toggle` 也可,但 ToggleGroup 更专精)
+
+## When NOT to use
+
+- 互斥单选切换 → `ToggleGroup`(语义更强)
+- 不相干的按钮 → 普通 `Button` + flex gap
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 排列方向。 |
+| `attached` | `boolean` | `true` | – | 是否把按钮"粘"在一起去除边距(antd `Space.Compact` 等价行为)— `false` 时按钮间留 8px gap。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add button-group` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`attached=true`(默认)子项之间边线共享**:第一项 / 最后一项保留外侧圆角,中间项去除圆角;**不要**在内部再设 `rounded`
+- **混用 Input + Button**:把 Input 直接放进 ButtonGroup,它的 `rounded-md` 也会被组件圈圆角(无需特殊处理)
+- **`ButtonGroupText`** 用于只读 addon(`https://` 前缀、`/月` 后缀);**不要**把它当按钮点击
+- **vertical 模式** 适合工具栏侧边小集合,horizontal 是默认推荐
+- **不要**在 ButtonGroup 内放 spinner / icon-only 与文字按钮混排时,高度需要靠 button `size` 对齐 — 子项尺寸应一致
+
+## Examples
+
+```tsx
+import { ButtonGroup, ButtonGroupText } from '@/components/ui/button-group';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { ChevronDown } from 'lucide-react';
+
+// Split button
+<ButtonGroup>
+  <Button>保存</Button>
+  <Button variant="default" size="icon" icon={<ChevronDown />} aria-label="更多" />
+</ButtonGroup>
+
+// Toolbar
+<ButtonGroup>
+  <Button variant="outline">上一页</Button>
+  <Button variant="outline">1 / 10</Button>
+  <Button variant="outline">下一页</Button>
+</ButtonGroup>
+
+// 带 addon 文本
+<ButtonGroup>
+  <ButtonGroupText>https://</ButtonGroupText>
+  <Input defaultValue="example.com" className="rounded-l-none" />
+  <Button>访问</Button>
+</ButtonGroup>
+
+// 不粘连(留间距)
+<ButtonGroup attached={false}>
+  <Button variant="outline">取消</Button>
+  <Button>确定</Button>
+</ButtonGroup>
+```

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

@@ -0,0 +1,90 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ChevronDown } from 'lucide-react';
+import { ButtonGroup, ButtonGroupText } from './button-group';
+import { Button } from '@/components/button/button';
+import { Input } from '@/components/input/input';
+
+const meta: Meta<typeof ButtonGroup> = {
+  title: '表单与输入 · Form/ButtonGroup',
+  component: ButtonGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '按钮组 — 把多个按钮 / 输入框粘在一起共享边线(Split Button、Toolbar、Input + Button 拼装)。配 ButtonGroupText 渲染只读 addon。shadcn 2025-10 新增,等价 antd `Space.Compact`(v6 替代旧 `Button.Group`)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    orientation: { control: 'inline-radio', options: ['horizontal', 'vertical'] },
+    attached: { control: 'boolean' },
+  },
+  args: { orientation: 'horizontal', attached: true },
+};
+
+export default meta;
+type Story = StoryObj<typeof ButtonGroup>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">左</Button>
+      <Button variant="outline">中</Button>
+      <Button variant="outline">右</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const SplitButton: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup>
+      <Button>保存</Button>
+      <Button size="icon" icon={<ChevronDown />} aria-label="更多保存选项" />
+    </ButtonGroup>
+  ),
+};
+
+export const Pager: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup>
+      <Button variant="outline">上一页</Button>
+      <Button variant="outline">1 / 10</Button>
+      <Button variant="outline">下一页</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const InputAddon: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup>
+      <ButtonGroupText>https://</ButtonGroupText>
+      <Input defaultValue="example.com" className="rounded-l-none" />
+      <Button>访问</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const Vertical: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup orientation="vertical">
+      <Button variant="outline">编辑</Button>
+      <Button variant="outline">复制</Button>
+      <Button variant="outline">删除</Button>
+    </ButtonGroup>
+  ),
+};
+
+export const NotAttached: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ButtonGroup attached={false}>
+      <Button variant="outline">取消</Button>
+      <Button>确定</Button>
+    </ButtonGroup>
+  ),
+};

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

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+const buttonGroupVariants = cva('inline-flex isolate', {
+  variants: {
+    orientation: {
+      horizontal:
+        'flex-row [&>*:not(:first-child)]:rounded-l-none [&>*:not(:last-child)]:rounded-r-none [&>*:not(:first-child)]:-ml-px hover:[&>*]:z-10 focus-visible:[&>*]:z-10',
+      vertical:
+        'flex-col [&>*:not(:first-child)]:rounded-t-none [&>*:not(:last-child)]:rounded-b-none [&>*:not(:first-child)]:-mt-px hover:[&>*]:z-10 focus-visible:[&>*]:z-10',
+    },
+    attached: {
+      true: '',
+      false: 'gap-2',
+    },
+  },
+  defaultVariants: { orientation: 'horizontal', attached: true },
+});
+
+export interface ButtonGroupProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof buttonGroupVariants> {
+  /**
+   * 排列方向。
+   * @default "horizontal"
+   */
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * 是否把按钮"粘"在一起去除边距(antd `Space.Compact` 等价行为)— `false` 时按钮间留 8px gap。
+   * @default true
+   */
+  attached?: boolean;
+}
+
+/**
+ * 按钮组容器 — shadcn 2025-10 新增。语义类似 antd `Space.Compact`(v6 替代旧 `Button.Group`):
+ * 把多个 `Button` / `Input` 包在一起共享边线,典型场景:
+ *   - Split button(左主操作 + 右下拉箭头)
+ *   - Toolbar(同语义按钮集合)
+ *   - Input + 按钮拼装(`<Input/><Button>搜索</Button>`)
+ *
+ * 内部不限定子组件类型 — 任何带 `rounded-md` 的元素都会被组件圈圆角。
+ */
+const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
+  ({ orientation, attached, className, ...props }, ref) => (
+    <div
+      ref={ref}
+      role="group"
+      className={cn(buttonGroupVariants({ orientation, attached }), className)}
+      {...props}
+    />
+  ),
+);
+ButtonGroup.displayName = 'ButtonGroup';
+
+// ─── ButtonGroupText(antd-style addon text)──────────────────────────────
+
+const ButtonGroupText = React.forwardRef<
+  HTMLSpanElement,
+  React.HTMLAttributes<HTMLSpanElement>
+>(({ className, ...props }, ref) => (
+  <span
+    ref={ref}
+    className={cn(
+      'inline-flex h-9 select-none items-center border border-input bg-muted px-3 text-sm text-muted-foreground',
+      className,
+    )}
+    {...props}
+  />
+));
+ButtonGroupText.displayName = 'ButtonGroupText';
+
+export { ButtonGroup, ButtonGroupText, buttonGroupVariants };

package/src/components/calendar/calendar.meta.md

@@ -0,0 +1,118 @@
+---
+id: calendar
+name: Calendar
+type: component
+category: form
+since: 0.1.0
+package: '@teamix-evo/ui'
+---
+
+# Calendar
+
+日期选择面板 — 基于 [`react-day-picker`](https://react-day-picker.js.org/),与 design tokens 对齐。
+**两种用法**:
+
+1. **inline**(裸 Calendar):嵌入页面或 Card
+2. **配 Popover** → `DatePicker`(单日)/ `DateRangePicker`(范围)
+
+## When to use
+
+- 日期 / 范围选择(配 `DatePicker`)
+- 日历视图(展示日程 / 假期 / 数据热力)
+- 月份导航器
+
+## When NOT to use
+
+- 时间选择 → 配 `Input type="time"` 或自定义 TimePicker
+- 模糊时间("近 7 天") → `Select` + 预设范围
+- 仅显示日期 → `<time>` 配 `date-fns`
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `className` | `string` | – | – | 容器 className。组件内部默认带 `p-3`,会与传入值自动 merge。 |
+| `classNames` | `DayPickerProps['classNames']` | – | – | 覆盖底层 react-day-picker 的 classNames slots(深度自定义日格 / 表头 / 导航等)。 |
+| `showOutsideDays` | `boolean` | `true` | – | 是否显示当月范围外的日期(灰色填充,占位补齐周表格)。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add calendar` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add react-day-picker@^9.0.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 react-day-picker `<DayPicker>` props(`mode` / `selected` / `onSelect` / `disabled` / `fromYear` / `toYear` / `numberOfMonths` 等)。完整 API:[react-day-picker.js.org](https://react-day-picker.js.org/)。
+
+## AI 生成纪律
+
+- **`mode` 必传**:`'single'` / `'multiple'` / `'range'` 三选一,API 不同(`selected` 类型不同)
+- **disabled 日期**:用 `disabled={(date) => date < startOfDay(new Date())}` 而非自己过滤
+- **`fromYear` / `toYear` 限制可选范围**:不设置时年份下拉无界
+- **多日期范围**:`mode="range"` 时 `selected` 是 `{ from?: Date, to?: Date }`
+- **无障碍自带**:react-day-picker 完整 ARIA + 键盘导航,不要自行覆盖
+- **`classNames` 必须用 react-day-picker v9 的 slot key**:本组件依赖 `react-day-picker@^9`。v9 重命名了所有 slot,**v8 老 key 完全失效**(默认渲染会塌掉成 `<table>` 原生样式)。常见映射:
+  - `caption` → `month_caption`
+  - `nav_button` / `nav_button_previous` / `nav_button_next` → `button_previous` / `button_next`(`nav` 为容器)
+  - `table` → `month_grid`
+  - `head_row` / `head_cell` → `weekdays` / `weekday`
+  - `row` → `week`
+  - `cell` / `day` → `day`(td 外壳)/ `day_button`(真正的按钮)
+  - `day_selected` / `day_today` / `day_outside` / `day_disabled` / `day_hidden` / `day_range_*` → 去 `day_` 前缀:`selected` / `today` / `outside` / `disabled` / `hidden` / `range_*`
+- **nav 是 `<Months>` 直接子元素,与 `<Month>` 平级**(默认 `navLayout`):若 `nav` 用 absolute 定位横跨容器顶部覆盖到 caption 区域,**必须给 nav 加 `z-10`**,否则源码顺序在后的 `month_caption` 会盖住翻月按钮导致点击失效;同时 `month_caption` 不要自行加 `relative`(会创建 stacking context 反而把 nav 压在下面)
+- **状态类(selected/today/range\_\*)作用在 `day_button` 上,不是 `day` 外壳**:视觉态(背景色/圆角)需直接写到对应 slot;`day` 外壳负责 range 段连续背景,用 `[&:has([data-selected])]` / `[data-range-*]` 这种 v9 data attribute 选择器
+
+## Examples
+
+```tsx
+import { Calendar } from '@/components/ui/calendar';
+import * as React from 'react';
+
+// 单日
+const [date, setDate] = React.useState<Date | undefined>();
+<Calendar mode="single" selected={date} onSelect={setDate} />;
+
+// 多选
+const [days, setDays] = React.useState<Date[]>([]);
+<Calendar mode="multiple" selected={days} onSelect={setDays} />;
+
+// 范围
+const [range, setRange] = React.useState<{ from?: Date; to?: Date }>();
+<Calendar
+  mode="range"
+  selected={range}
+  onSelect={setRange}
+  numberOfMonths={2}
+/>;
+
+// 限制范围 + 禁用过去
+import { startOfDay } from 'date-fns';
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  disabled={(d) => d < startOfDay(new Date())}
+  fromYear={2020}
+  toYear={2030}
+/>;
+```

package/src/components/calendar/calendar.stories.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import type { DateRange } from 'react-day-picker';
+import { Calendar } from './calendar';
+
+const meta: Meta<typeof Calendar> = {
+  title: '表单与输入 · Form/Calendar',
+  component: Calendar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '日历 — 内联日期选择面板。基于 [`react-day-picker@9`](https://daypicker.dev/) + design tokens，支持 `mode="single" | "multiple" | "range"` 三种选择模式、年份 / 月份导航、`disabled` 函数式禁用、`numberOfMonths` 多月并排；通常配 `Popover` 包装为 `DatePicker`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Calendar>;
+
+export const Single: Story = {
+  render: () => {
+    const [date, setDate] = React.useState<Date | undefined>(new Date());
+    return (
+      <Calendar
+        mode="single"
+        selected={date}
+        onSelect={setDate}
+        className="rounded-md border"
+      />
+    );
+  },
+};
+
+export const Multiple: Story = {
+  render: () => {
+    const [days, setDays] = React.useState<Date[] | undefined>([]);
+    return (
+      <Calendar
+        mode="multiple"
+        selected={days}
+        onSelect={setDays}
+        className="rounded-md border"
+      />
+    );
+  },
+};
+
+export const Range: Story = {
+  render: () => {
+    const [range, setRange] = React.useState<DateRange | undefined>({
+      from: new Date(),
+      to: new Date(Date.now() + 7 * 24 * 3600 * 1000),
+    });
+    return (
+      <Calendar
+        mode="range"
+        selected={range}
+        onSelect={setRange}
+        numberOfMonths={2}
+        className="rounded-md border"
+      />
+    );
+  },
+};

package/src/components/calendar/calendar.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react';
+import {
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ChevronUp,
+} from 'lucide-react';
+import { DayPicker, type DayPickerProps } from 'react-day-picker';
+
+import { cn } from '@/utils/cn';
+import { buttonVariants } from '@/components/button/button';
+
+/**
+ * Calendar 自身的可定制属性(ui 层包装)。
+ * 底层完整 props 透传至 [`DayPicker`](https://daypicker.dev/),
+ * 包括 `mode` / `selected` / `onSelect` / `numberOfMonths` / `disabled` / `initialFocus` 等。
+ */
+export interface CalendarProps {
+  /**
+   * 容器 className。组件内部默认带 `p-3`,会与传入值自动 merge。
+   */
+  className?: string;
+  /**
+   * 覆盖底层 react-day-picker 的 classNames slots(深度自定义日格 / 表头 / 导航等)。
+   */
+  classNames?: DayPickerProps['classNames'];
+  /**
+   * 是否显示当月范围外的日期(灰色填充,占位补齐周表格)。
+   * @default true
+   */
+  showOutsideDays?: boolean;
+}
+
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  ...props
+}: CalendarProps & DayPickerProps) {
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn('p-3', className)}
+      classNames={{
+        root: 'w-fit',
+        months: 'flex flex-col sm:flex-row gap-4 relative',
+        month: 'flex flex-col gap-4',
+        month_caption: 'flex justify-center pt-1 items-center h-7 w-full',
+        caption_label: 'text-sm font-medium',
+        nav: 'absolute inset-x-1 top-1 z-10 flex items-center justify-between',
+        button_previous: cn(
+          buttonVariants({ variant: 'outline', size: 'icon' }),
+          'size-7 bg-transparent p-0 opacity-50 hover:opacity-100',
+        ),
+        button_next: cn(
+          buttonVariants({ variant: 'outline', size: 'icon' }),
+          'size-7 bg-transparent p-0 opacity-50 hover:opacity-100',
+        ),
+        month_grid: 'w-full border-collapse',
+        weekdays: 'flex',
+        weekday:
+          'text-muted-foreground rounded-md w-8 font-normal text-[0.8rem]',
+        week: 'flex w-full mt-2',
+        day: cn(
+          'relative p-0 text-center text-sm focus-within:relative focus-within:z-20',
+          '[&:has([data-selected])]:bg-accent',
+          '[&:has([data-selected])]:first:rounded-l-md [&:has([data-selected])]:last:rounded-r-md',
+          '[&:has([data-range-start])]:rounded-l-md [&:has([data-range-end])]:rounded-r-md',
+          '[&:not(:has([data-range-middle]))]:[&:has([data-selected])]:rounded-md',
+        ),
+        day_button: cn(
+          buttonVariants({ variant: 'ghost' }),
+          'size-8 p-0 font-normal aria-selected:opacity-100',
+        ),
+        range_start: 'day-range-start',
+        range_end: 'day-range-end',
+        range_middle:
+          'aria-selected:bg-accent aria-selected:text-accent-foreground',
+        selected:
+          'bg-primary text-primary-foreground hover:bg-primary hover:text-primary-foreground focus:bg-primary focus:text-primary-foreground rounded-md',
+        today: 'bg-accent text-accent-foreground rounded-md',
+        outside:
+          'day-outside text-muted-foreground aria-selected:text-muted-foreground',
+        disabled: 'text-muted-foreground opacity-50',
+        hidden: 'invisible',
+        ...classNames,
+      }}
+      components={{
+        Chevron: ({ orientation, className: chevronClassName, ...rest }) => {
+          const Icon =
+            orientation === 'left'
+              ? ChevronLeft
+              : orientation === 'up'
+              ? ChevronUp
+              : orientation === 'down'
+              ? ChevronDown
+              : ChevronRight;
+          return <Icon {...rest} className={cn('size-4', chevronClassName)} />;
+        },
+      }}
+      {...props}
+    />
+  );
+}
+Calendar.displayName = 'Calendar';
+
+export { Calendar };

package/src/components/card/card.meta.md

@@ -0,0 +1,117 @@
+---
+id: card
+name: Card
+type: component
+category: layout
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Card
+
+卡片容器 — shadcn 组合式(`Card / Header / Title / Description / Content / Footer`)+ antd 并集(`hoverable / loading / Cover / Actions / Meta / extra`)。
+**单卡覆盖列表项 / 详情卡 / 资源卡 / 媒体卡多种形态**。
+
+## When to use
+
+- 列表项 / 网格卡片(产品 / 服务 / 用户)
+- 详情页的分块容器
+- 仪表板小部件(配 Header.extra 放刷新按钮)
+- 媒体卡(`<CardCover>` 顶部图片)
+
+## When NOT to use
+
+- 整屏页面背景 → 用普通 div + spacing
+- 简单文字提示 → `Alert` / `Badge`
+- 浮层 → `Popover` / `HoverCard`
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `hoverable` | `boolean` | `false` | – | 鼠标 hover 时的视觉反馈(antd `hoverable` 并集) — 阴影升级 + 微交互。 |
+| `loading` | `boolean` | `false` | – | 加载态(antd `loading` 并集) — 整卡渲染为骨架屏占位,不展示 children。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add card` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `skeleton` | component | 骨架屏 — shadcn pulse 单元素 + antd Avatar/Image/Button/Input/Paragraph 子家族,自动 motion-reduce |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+> 子组件:`Card`(主容器)/ `CardHeader`(支持 `extra`)/ `CardTitle` / `CardDescription` / `CardContent` / `CardFooter` / `CardCover`(顶部封面)/ `CardActions`(底部分隔操作栏)/ `CardMeta`(avatar + title + description 行)。
+
+## AI 生成纪律
+
+- **`hoverable` 仅用于可点击卡**:配 `onClick` 或包 `<Link>`,不能 hover 起视觉但点了无反应
+- **`loading` 整卡替换为骨架**:`children` 在 loading 时不渲染,**不要**手动嵌套 Skeleton
+- **`extra` 放轻量按钮**:刷新 / 更多 / 切换;**不要**塞主操作(放 CardFooter 更醒目)
+- **`<CardCover>` 顶部对齐**:必须是 Card 的第一个子元素(避免上方圆角穿帮)
+- **`<CardActions items>` 数组用法**:item 可以是文本 / 图标按钮;数组长度不超过 4
+
+## Examples
+
+```tsx
+import {
+  Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter,
+  CardCover, CardActions, CardMeta,
+} from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Heart, Share, MessageSquare, MoreHorizontal } from 'lucide-react';
+
+// 基础
+<Card>
+  <CardHeader extra={<Button size="icon" variant="ghost"><MoreHorizontal /></Button>}>
+    <CardTitle>项目名称</CardTitle>
+    <CardDescription>项目简介一行...</CardDescription>
+  </CardHeader>
+  <CardContent>主体内容</CardContent>
+  <CardFooter className="justify-end gap-2">
+    <Button variant="outline">取消</Button>
+    <Button>确认</Button>
+  </CardFooter>
+</Card>
+
+// hoverable
+<Card hoverable onClick={() => navigate('/x')}>
+  <CardContent>...</CardContent>
+</Card>
+
+// loading
+<Card loading />
+
+// 媒体卡(antd 风格)
+<Card hoverable>
+  <CardCover>
+    <img src="/cover.jpg" alt="" />
+  </CardCover>
+  <CardContent className="pt-4">
+    <CardMeta
+      avatar={<Avatar><AvatarImage src="..." /><AvatarFallback>A</AvatarFallback></Avatar>}
+      title="作者"
+      description="发布时间"
+    />
+  </CardContent>
+  <CardActions items={[
+    <span><Heart className="inline size-4" /> 12</span>,
+    <span><Share className="inline size-4" /> 4</span>,
+    <span><MessageSquare className="inline size-4" /> 8</span>,
+  ]} />
+</Card>
+```