@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/tabs/tabs.tsx

@@ -6,95 +6,159 @@ import { cn } from '@/utils/cn';
 
 const Tabs = TabsPrimitive.Root;
 
-const tabsListVariants = cva('inline-flex items-center justify-center', {
+/**
+ * TabsList 的视觉风格 + 尺寸由 cva 表达；
+ * 同时通过 `TabsListContext` 把 variant / size 透传到 TabsTrigger,
+ * 使得消费者只需在 List 上声明一次。
+ */
+const tabsListVariants = cva('inline-flex items-center', {
   variants: {
-    type: {
-      line: 'border-b border-border w-full justify-start gap-4',
-      card: 'h-9 rounded-md bg-muted p-1 text-muted-foreground',
+    variant: {
+      // 下划线风格(antd 默认):整行 baseline border + 选中项底部 primary 高亮线
+      line: 'w-full justify-start gap-4 border-b border-border bg-transparent text-muted-foreground',
+      // 胶囊风格(吸收 Segmented):圆角容器 + muted 底色 + 选中项 background 白底 shadow
+      capsule:
+        'justify-center gap-1 rounded-lg bg-muted p-1 text-muted-foreground',
+    },
+    size: {
+      sm: '',
+      md: '',
+      lg: '',
     },
   },
-  defaultVariants: { type: 'card' },
+  compoundVariants: [
+    { variant: 'capsule', size: 'sm', class: 'h-8' },
+    { variant: 'capsule', size: 'md', class: 'h-9' },
+    { variant: 'capsule', size: 'lg', class: 'h-10' },
+  ],
+  defaultVariants: { variant: 'line', size: 'md' },
 });
 
 const tabsTriggerVariants = cva(
-  'inline-flex items-center justify-center whitespace-nowrap text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex cursor-pointer items-center justify-center gap-1.5 whitespace-nowrap font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
-      type: {
-        line: 'relative px-1 py-2 -mb-px border-b-2 border-transparent text-muted-foreground hover:text-foreground data-[state=active]:border-primary data-[state=active]:text-foreground',
-        card: 'rounded-sm px-3 py-1 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      variant: {
+        line: 'relative -mb-px border-b-2 border-transparent text-muted-foreground hover:text-foreground data-[state=active]:border-primary data-[state=active]:text-foreground',
+        capsule:
+          'rounded-md text-muted-foreground hover:text-foreground data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      },
+      size: {
+        sm: 'text-xs',
+        md: 'text-xs',
+        lg: 'text-sm',
       },
     },
-    defaultVariants: { type: 'card' },
+    compoundVariants: [
+      { variant: 'line', size: 'sm', class: 'px-1 py-1.5' },
+      { variant: 'line', size: 'md', class: 'px-1 py-2' },
+      { variant: 'line', size: 'lg', class: 'px-1 py-2.5' },
+      { variant: 'capsule', size: 'sm', class: 'px-2.5 py-1' },
+      { variant: 'capsule', size: 'md', class: 'px-3 py-1' },
+      { variant: 'capsule', size: 'lg', class: 'px-4 py-1.5' },
+    ],
+    defaultVariants: { variant: 'line', size: 'md' },
   },
 );
 
+type TabsVariant = NonNullable<
+  VariantProps<typeof tabsListVariants>['variant']
+>;
+type TabsSize = NonNullable<VariantProps<typeof tabsListVariants>['size']>;
+
+const TabsListContext = React.createContext<{
+  variant: TabsVariant;
+  size: TabsSize;
+}>({ variant: 'line', size: 'md' });
+
 export interface TabsListProps
   extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.List>,
     VariantProps<typeof tabsListVariants> {
   /**
-   * 视觉风格(antd `type` 并集)。`card` 是 shadcn 默认胶囊;`line` 是 antd 默认下划线。
-   * @default "card"
+   * 视觉风格(shadcn ∪ antd 并集 + 吸收 Segmented)。
+   * - `line`:下划线风格(antd 默认),适合页面级主导航 / 大区块切换。
+   * - `capsule`:胶囊风格(取代旧 `card`,吸收 Segmented),muted 底色 + 选中项白底 shadow,适合紧凑互斥单选(视图切换、时间区间)。
+   * @default "line"
    */
-  type?: 'line' | 'card';
+  variant?: TabsVariant;
   /**
-   * 右侧附加内容(antd `tabBarExtraContent` 并集);仅 `type="line"` 显式支持(布局灵活)。
+   * 尺寸(antd `size` 并集)。三档统一驱动 trigger 的字号与 padding。
+   * @default "md"
+   */
+  size?: TabsSize;
+  /**
+   * 右侧附加内容(antd `tabBarExtraContent` 并集);仅 `variant="line"` 显式支持(布局灵活)。
    * 用法:把节点放进来即可,组件用 `flex justify-between` 自动撑开。
    */
   extra?: React.ReactNode;
 }
 
-const TabsListContext = React.createContext<{ type: 'line' | 'card' }>({
-  type: 'card',
-});
-
 const TabsList = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.List>,
   TabsListProps
->(({ className, type = 'card', extra, children, ...props }, ref) => {
-  const list = (
-    <TabsPrimitive.List
-      ref={ref}
-      className={cn(tabsListVariants({ type }), className)}
-      {...props}
-    >
-      <TabsListContext.Provider value={{ type }}>
-        {children}
-      </TabsListContext.Provider>
-    </TabsPrimitive.List>
-  );
-  if (extra) {
-    return (
-      <div
-        className={cn(
-          'flex items-center justify-between',
-          type === 'line' && 'border-b border-border',
-        )}
+>(
+  (
+    { className, variant = 'line', size = 'md', extra, children, ...props },
+    ref,
+  ) => {
+    const list = (
+      <TabsPrimitive.List
+        ref={ref}
+        className={cn(tabsListVariants({ variant, size }), className)}
+        {...props}
       >
-        {React.cloneElement(list, {
-          className: cn(
-            tabsListVariants({ type }),
-            type === 'line' && 'border-b-0',
-            className,
-          ),
-        })}
-        <div className="shrink-0">{extra}</div>
-      </div>
+        <TabsListContext.Provider value={{ variant, size }}>
+          {children}
+        </TabsListContext.Provider>
+      </TabsPrimitive.List>
     );
-  }
-  return list;
-});
+    if (extra) {
+      return (
+        <div
+          className={cn(
+            'flex items-center justify-between',
+            variant === 'line' && 'border-b border-border',
+          )}
+        >
+          {React.cloneElement(list, {
+            className: cn(
+              tabsListVariants({ variant, size }),
+              variant === 'line' && 'border-b-0',
+              className,
+            ),
+          })}
+          <div className="shrink-0">{extra}</div>
+        </div>
+      );
+    }
+    return list;
+  },
+);
 TabsList.displayName = TabsPrimitive.List.displayName;
 
+/**
+ * `TabsTrigger` 也接受 `variant` / `size`,但仅用于显式覆盖来自 `TabsList`
+ * 的上下文(罕用)—— 通常在 `TabsList` 上声明一次即可。
+ * 类型用 inline 形式避免 gen:meta 候选优先匹配。
+ */
 const TabsTrigger = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Trigger>,
-  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
->(({ className, ...props }, ref) => {
-  const { type } = React.useContext(TabsListContext);
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger> & {
+    variant?: TabsVariant;
+    size?: TabsSize;
+  }
+>(({ className, variant, size, ...props }, ref) => {
+  const ctx = React.useContext(TabsListContext);
   return (
     <TabsPrimitive.Trigger
       ref={ref}
-      className={cn(tabsTriggerVariants({ type }), className)}
+      className={cn(
+        tabsTriggerVariants({
+          variant: variant ?? ctx.variant,
+          size: size ?? ctx.size,
+        }),
+        className,
+      )}
       {...props}
     />
   );
@@ -116,4 +180,11 @@ const TabsContent = React.forwardRef<
 ));
 TabsContent.displayName = TabsPrimitive.Content.displayName;
 
-export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants };
+export {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+  tabsListVariants,
+  tabsTriggerVariants,
+};

package/src/components/tag/tag.meta.md

@@ -1,36 +1,46 @@
 ---
 id: tag
 name: Tag
+displayName: 标签
 type: component
-category: foundation
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Tag
+# Tag 标签
 
-标签 — antd 独有补足。**与 Badge 区别**:Tag 偏向**用户可关闭的关键词标签**(分类 / 标签 / 筛选条件),支持 `closable` + 6 种语义色;Badge 偏向**状态徽标**(数字 / 红点 / 状态条)。
+标签 — antd 独有补足 + cloud-design 多彩并集。**与 Badge 区别**:Tag 偏向**用户可关闭的关键词标签**(分类 / 筛选条件 / 多彩分类),支持 `variant`(形态轴)× `color`(语义色轴,对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md))× `palette`(装饰色轴,9 预设 + 任意 CSS 值)的三轴正交组合,以及 `icon` / `size` / `closable`;Badge 偏向**状态徽标**(数字 / 红点 / 状态条)。
 
 ## When to use
 
-- 关键词 / 标签 / 分类(博客标签、用户兴趣)
-- 当前筛选条件展示(可关闭以移除条件)
-- 列表项的次级标签(优先级 / 类型)
+- 关键词 / 标签 / 分类(博客标签、用户兴趣) — 多彩分类用 `palette`
+- 当前筛选条件展示(可关闭以移除条件) — 配 `closable + onClose`
+- 列表项的次级标签(优先级 / 类型) — 状态语义用 `color`
+- 单选 / 多选筛选 chip — 用 `CheckableTag` / `CheckableTagGroup`
 
 ## When NOT to use
 
-- 状态指示 → `Badge`
+- 状态指示(运行中 / 已停止 + 数字) → `Badge`
 - 切换按钮 → `Toggle` / `ToggleGroup`
 - 选择类输入 → `Combobox` / `Select`
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'error' \| 'info'` | `"default"` | – | 语义颜色(antd `color` 并集) — 与 Badge 不同,Tag 偏向**用户可关闭的标签**(关键词 / 分类),Badge 偏向状态徽标。 |
+| `variant` | `'solid' \| 'outline' \| 'ghost'` | `"solid"` | – | 形态轴(对齐 [ADR 0021](../../../../docs/adr/0021-semantic-color-api-unification.md)): `solid` 实色背景 / `outline` 仅描边 / `ghost` 仅文字。 |
+| `color` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'destructive'` | `"default"` | – | 语义色 — 与组件状态绑定的调色板,5 档(填充背景类省略 `muted`,信息色用 `primary`, 不收 `info` — 见 ADR 0021)。装饰性类别区分请用 `palette`。 |
+| `size` | `'sm' \| 'md'` | `"md"` | – | 尺寸:`sm` 高 20px(更紧凑) / `md` 高 24px(默认)。 |
+| `palette` | `TagPalettePreset \| (string & {})` | – | – | **分类色 / 装饰色** — 与 `color`(语义色) 正交,用于纯装饰的类别区分(博客标签 / 项目分类 / ...)。 接受 9 种预设色 `'blue' \| 'cyan' \| 'green' \| 'orange' \| 'purple' \| 'red' \| 'magenta' \| 'lime' \| 'gold'` 或任意 CSS 颜色值(如 `'#FF5733'` / `'hsl(280 80% 60%)'` / `'var(--brand)'`)。 `palette` 存在时会**覆盖** `color` 的语义配色(派生 bg / border / text 三档), 但仍受 `variant` 控制形态:`solid` 12% bg + 35% border、`outline` 仅 solid 描边、`ghost` 仅文字。 装饰类别走 `palette`;状态语义走 `color`。两者同传时 `palette` 优先(因为它是显式装饰意图)。 |
+| `icon` | `React.ReactNode` | – | – | 标签文字左侧图标插槽(antd `icon` 并集)。推荐传 `lucide-react` icon。 与 `closable` 的关闭按钮不冲突 — icon 在左,X 在右。 |
 | `closable` | `boolean` | `false` | – | 显示关闭按钮(antd `closable` 并集)。 |
-| `onClose` | `() => void` | – | – | 关闭回调。 |
+| `onClose` | `() => void` | – | – | 关闭回调 — `closable` 触发时调用。建议父组件维护数组并在此回调中移除当前项。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -51,44 +61,99 @@ pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
 
 ## AI 生成纪律
 
-- **`color` 反映语义**:不要随便选 — `error` 仅用于真错误,`success` 仅用于已通过
-- **`closable` 必配 `onClose`**:让父组件知道哪个 tag 被移除,业务侧维护数组
-- **文字 ≤ 4 个汉字 / 8 字符**:过长的标签视觉破碎
-- **不要嵌套交互**:Tag 内不要放 Button / Link
-- **筛选条件场景**:配 `closable` 让用户一键移除条件
+- **`color`(语义) vs `palette`(装饰) 选轴明确**:状态/反馈/校验类信号 → `color`;纯类别区分(标签云 / 分类) → `palette`。**不要混用**两轴去拼颜色
+- **`variant` 是形态不是颜色**(ADR 0021):`solid` / `outline` / `ghost`,**禁止**回写 `variant="primary"` 等旧风格
+- **`color` 不收 `info` / `error` / `danger`**:对齐 ADR 0021;信息色用 `color="primary"`,失败用 `destructive`
+- **`palette` 优先级高于 `color`**:同时传时 palette 覆盖配色(实现:inline style > utility class)
+- **palette 自定义值要可访问**:任意 CSS 颜色字符串都可传,但要保证 12% 透明度背景下对比度可读;**对纯白 / 极浅色慎用 solid 形态**(转为 `outline` 或 `ghost`)
+- **`closable` 必配 `onClose`**:父组件维护数组并在回调中移除
+- **icon 来源固定** `lucide-react`(ESLint `icon-from-lucide` 阻塞)。**不要**内联 SVG 或引入其它 icon 库
+- **文字 ≤ 4 个汉字 / 8 字符**:过长视觉破碎,考虑改用 Description / Field
+- **不要嵌套交互**:Tag 内不要放 Button / Link;`closable` X 已是组件唯一交互
+- **圆角走 token**:`--radius-tag`(4px) 由组件内 inline style 注入,**不要**覆盖为其他档位
+- **不要把语义色硬塞进 palette**:`palette="red"` 不等于 `color="destructive"` — 前者是装饰红,后者是危险信号语义
 
 ## Examples
 
 ```tsx
-import { Tag } from '@/components/ui/tag';
+import { Tag, CheckableTagGroup } from '@/components/ui/tag';
+import { Hash, Star } from 'lucide-react';
 import * as React from 'react';
 
-// 基础
-<Tag>React</Tag>
-<Tag color="primary">Vue</Tag>
-<Tag color="success">已通过</Tag>
-<Tag color="warning">待审核</Tag>
-<Tag color="error">失败</Tag>
-
-// 可关闭
-const [tags, setTags] = React.useState(['React', 'Vue', 'Angular']);
-<div className="flex gap-2">
-  {tags.map((t) => (
-    <Tag
-      key={t}
-      color="primary"
-      closable
-      onClose={() => setTags(tags.filter((x) => x !== t))}
-    >
-      {t}
-    </Tag>
-  ))}
+// 1. 形态 × 语义色(三种 variant × 五档 color)
+<div className="flex flex-wrap gap-2">
+  <Tag>Default</Tag>
+  <Tag variant="outline" color="primary">Primary outline</Tag>
+  <Tag variant="ghost" color="success">Ghost success</Tag>
+  <Tag color="warning">Warning</Tag>
+  <Tag color="destructive">Destructive</Tag>
 </div>
 
-// 筛选条件
+// 2. 多彩分类(9 预设 + 任意 CSS 值)
 <div className="flex flex-wrap gap-2">
-  <Tag closable>状态: 运行中</Tag>
-  <Tag closable>类型: 服务</Tag>
-  <Tag closable>地区: 杭州</Tag>
+  <Tag palette="blue">React</Tag>
+  <Tag palette="green">Vue</Tag>
+  <Tag palette="orange">Svelte</Tag>
+  <Tag palette="purple">Solid</Tag>
+  <Tag palette="#ff66cc">Custom Pink</Tag>
 </div>
+
+// 3. icon + closable + size
+<div className="flex flex-wrap items-center gap-2">
+  <Tag size="sm" icon={<Hash />}>small + icon</Tag>
+  <Tag icon={<Star />} closable onClose={() => alert('closed')}>
+    favorite
+  </Tag>
+</div>
+
+// 4. CheckableTagGroup(单/多选 chip)
+const [picked, setPicked] = React.useState<string[]>(['react']);
+<CheckableTagGroup
+  value={picked}
+  onChange={setPicked}
+  options={[
+    { label: 'React', value: 'react' },
+    { label: 'Vue', value: 'vue' },
+    { label: 'Angular', value: 'angular' },
+  ]}
+/>
 ```
+
+## Tag 形态 — 旧库 API → 新映射
+
+> 本节对齐 cloud-design (Teamix 1.0 hybridcloud) Tag / Tag.Closeable / Tag.Selectable / Tag.Group → 新库 Tag + CheckableTag + CheckableTagGroup 的迁移路径。
+
+### 组件拆合
+
+| 旧库             | 新库                                   | 说明                             |
+| ---------------- | -------------------------------------- | -------------------------------- |
+| `Tag`            | `Tag`                                  | 基础标签，直接对应               |
+| `Tag.Closeable`  | `Tag closable onClose={fn}`            | 合并为 `closable` prop           |
+| `Tag.Selectable` | `CheckableTag`                         | 重命名                           |
+| `Tag.Group`      | `div className="flex flex-wrap gap-2"` | 无需专用容器，flex gap 替代      |
+| —                | `CheckableTagGroup`                    | 新库独有，data-driven 多选标签组 |
+
+### Props / 值映射
+
+| 旧库                            | 新库                              | 备注                          |
+| ------------------------------- | --------------------------------- | ----------------------------- |
+| `type="normal"`                 | `variant="solid" color="default"` | 默认形态                      |
+| `type="primary"`                | `variant="solid" color="primary"` | 主色填充                      |
+| `color="blue"` (预设色)         | `palette="blue"`                  | 装饰色走 palette 轴           |
+| `color="red"` (预设色)          | `palette="red"`                   | 同上                          |
+| `size="small"`                  | `size="sm"`                       | 高 20px                       |
+| `size="medium"`                 | `size="md"`                       | 高 24px（默认）               |
+| `closable` (Tag.Closeable 专属) | `closable` (Tag prop)             | 统一到 Tag                    |
+| `onClose` 返回 false 阻止       | 外部受控(不渲染)                  | 父组件 state 管理             |
+| `closeArea="tag"`               | —                                 | 不迁移，固定 X 按钮区域       |
+| `animation` / `afterAppear`     | —                                 | 不迁移(CSS transition 已内置) |
+
+### 不迁移清单（保留新库优势）
+
+| 旧库能力                      | 理由                                  |
+| ----------------------------- | ------------------------------------- |
+| `closeArea="tag"` 整体可关闭  | 新库固定 X 按钮交互，语义更清晰       |
+| `onClose` 返回 false 阻止关闭 | 新库用外部受控模式替代                |
+| `animation` / `afterAppear`   | 过渡已由 CSS `transition-colors` 覆盖 |
+| `Tag.Group` 容器组件          | flex gap 布局更灵活，无需专用容器     |
+| `hoverUnchangable`            | 由 `variant` 形态决定 hover 行为      |

package/src/components/tag/tag.stories.tsx

@@ -1,27 +1,68 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
-import { Tag } from './tag';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Hash, Star, Tag as TagIcon, Sparkles } from 'lucide-react';
+import { CheckableTagGroup, Tag } from './tag';
 
 const meta: Meta<typeof Tag> = {
-  title: '基础原语 · Foundation/Tag',
+  title: '数据展示 · Data Display/Tag',
   component: Tag,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '标签 — 用户可关闭的关键词 / 分类标签(分类、筛选条件、博客标签)。6 种语义色 + closable + onClose。OpenTrek tokens 适配,等价 antd Tag(与 Badge 互补,Badge 偏状态徽标)。',
+          '标签 —— 用户可关闭的关键词标签 / 多彩分类 chip(博客标签、筛选条件、项目分类、单选/多选 chip)。基于原生 `<span>` + cva 形态轴,合并 antd Tag(`closable` / `icon` / `CheckableTag.Group`)与 cloud-design WindColorfulTag(`palette` 多彩分类) 的并集能力:形态 `variant`(`solid`/`outline`/`ghost`) × 语义 `color`(对齐 ADR 0021,5 档不收 `info`/`error`) × 装饰 `palette`(9 预设 + 任意 CSS 值) × `size`(`sm`/`md`) × `icon` × `closable`。视觉走 OpenTrek semantic tokens,圆角走 `--radius-tag`,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
   argTypes: {
+    variant: {
+      control: 'inline-radio',
+      options: ['solid', 'outline', 'ghost'],
+    },
     color: {
       control: 'select',
-      options: ['default', 'primary', 'success', 'warning', 'error', 'info'],
+      options: ['default', 'primary', 'success', 'warning', 'destructive'],
+    },
+    size: {
+      control: 'inline-radio',
+      options: ['sm', 'md'],
+    },
+    palette: {
+      control: 'select',
+      options: [
+        undefined,
+        'blue',
+        'cyan',
+        'green',
+        'orange',
+        'purple',
+        'red',
+        'magenta',
+        'lime',
+        'gold',
+      ],
+    },
+    icon: {
+      control: 'select',
+      options: ['none', 'hash', 'star', 'tag', 'sparkles'],
+      mapping: {
+        none: undefined,
+        hash: <Hash />,
+        star: <Star />,
+        tag: <TagIcon />,
+        sparkles: <Sparkles />,
+      },
     },
     closable: { control: 'boolean' },
   },
-  args: { color: 'default', children: '标签', closable: false },
+  args: {
+    variant: 'solid',
+    color: 'default',
+    size: 'md',
+    closable: false,
+    children: '标签',
+  },
 };
 
 export default meta;
@@ -29,24 +70,129 @@ type Story = StoryObj<typeof Tag>;
 
 export const Playground: Story = {};
 
-export const Colors: Story = {
+export const SemanticColors: Story = {
+  name: '语义色 (color × variant)',
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex flex-wrap gap-2">
-      <Tag>Default</Tag>
-      <Tag color="primary">Primary</Tag>
-      <Tag color="success">Success</Tag>
-      <Tag color="warning">Warning</Tag>
-      <Tag color="error">Error</Tag>
-      <Tag color="info">Info</Tag>
+    <div className="flex flex-col gap-3">
+      {(['solid', 'outline', 'ghost'] as const).map((v) => (
+        <div key={v} className="flex flex-wrap items-center gap-2">
+          <span className="w-16 text-xs text-muted-foreground">{v}</span>
+          <Tag variant={v}>Default</Tag>
+          <Tag variant={v} color="primary">
+            Primary
+          </Tag>
+          <Tag variant={v} color="success">
+            Success
+          </Tag>
+          <Tag variant={v} color="warning">
+            Warning
+          </Tag>
+          <Tag variant={v} color="destructive">
+            Destructive
+          </Tag>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+export const Palette: Story = {
+  name: '多彩分类 (palette × variant)',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const presets = [
+      'blue',
+      'cyan',
+      'green',
+      'lime',
+      'gold',
+      'orange',
+      'red',
+      'magenta',
+      'purple',
+    ] as const;
+    return (
+      <div className="flex flex-col gap-3">
+        {(['solid', 'outline', 'ghost'] as const).map((v) => (
+          <div key={v} className="flex flex-wrap items-center gap-2">
+            <span className="w-16 text-xs text-muted-foreground">{v}</span>
+            {presets.map((p) => (
+              <Tag key={p} variant={v} palette={p}>
+                {p}
+              </Tag>
+            ))}
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+
+export const PaletteCustom: Story = {
+  name: '多彩分类 · 自定义 CSS 颜色',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      {/* eslint-disable teamix-evo/no-color-literal -- demo of custom palette accepting any CSS color string (hex / hsl / named); these are literals **as user input**, not styling decisions. */}
+      <Tag palette="#ff66cc">#ff66cc</Tag>
+      <Tag palette="hsl(280 80% 60%)">hsl(280 80% 60%)</Tag>
+      <Tag palette="teal">teal</Tag>
+      <Tag palette="var(--color-primary)">var(--color-primary)</Tag>
+      <Tag variant="outline" palette="rebeccapurple">
+        rebeccapurple
+      </Tag>
+      {/* eslint-enable teamix-evo/no-color-literal */}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  name: '尺寸',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-2">
+      <Tag size="sm">Small</Tag>
+      <Tag size="md">Medium</Tag>
+      <Tag size="sm" color="primary">
+        sm primary
+      </Tag>
+      <Tag size="md" color="success">
+        md success
+      </Tag>
+    </div>
+  ),
+};
+
+export const WithIcon: Story = {
+  name: 'icon 插槽',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-center gap-2">
+      <Tag icon={<Hash />}>topic</Tag>
+      <Tag icon={<Star />} color="warning">
+        featured
+      </Tag>
+      <Tag variant="outline" icon={<Sparkles />} palette="purple">
+        new
+      </Tag>
+      <Tag icon={<TagIcon />} closable onClose={() => undefined}>
+        with icon + closable
+      </Tag>
     </div>
   ),
 };
 
 export const Closable: Story = {
+  name: 'closable + 受控移除',
   parameters: { controls: { disable: true } },
   render: () => {
-    const [tags, setTags] = React.useState(['React', 'Vue', 'Angular', 'Svelte']);
+    const [tags, setTags] = React.useState([
+      'React',
+      'Vue',
+      'Angular',
+      'Svelte',
+    ]);
     return (
       <div className="flex flex-wrap gap-2">
         {tags.map((t) => (
@@ -65,9 +211,10 @@ export const Closable: Story = {
 };
 
 export const Filters: Story = {
+  name: '场景:筛选条件',
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex flex-wrap gap-2">
+    <div className="flex flex-wrap items-center gap-2">
       <span className="text-sm text-muted-foreground">已选筛选:</span>
       <Tag closable>状态: 运行中</Tag>
       <Tag closable>类型: 服务</Tag>
@@ -75,3 +222,29 @@ export const Filters: Story = {
     </div>
   ),
 };
+
+export const Checkable: Story = {
+  name: 'CheckableTagGroup',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [picked, setPicked] = React.useState<string[]>(['react']);
+    return (
+      <div className="flex flex-col gap-2">
+        <CheckableTagGroup
+          value={picked}
+          onChange={setPicked}
+          options={[
+            { label: 'React', value: 'react' },
+            { label: 'Vue', value: 'vue' },
+            { label: 'Angular', value: 'angular' },
+            { label: 'Svelte', value: 'svelte' },
+            { label: 'Solid', value: 'solid', disabled: true },
+          ]}
+        />
+        <span className="text-xs text-muted-foreground">
+          已选: {picked.join(', ') || '(空)'}
+        </span>
+      </div>
+    );
+  },
+};