@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/general/tag/README.md

@@ -0,0 +1,319 @@
+# Tag Component
+
+A compact label / status pill. Renders text with optional color theme (1–12), three shapes (border / round / borderless), three sizes, and an optional remove (×) icon that appears on hover.
+
+## Features
+
+- **Three shapes**: `border` (subtle outline), `round` (pill, stronger outline), `borderless`
+- **Three sizes**: `small`, `middle` (default), `big`
+- **12 color themes**: built-in g1–g12 palette via CSS variables; each tint auto-derives its background and border via `color-mix`
+- **Optional remove icon**: × icon shown only on hover; fires `ondelete` on click
+- **Theme aware**: outer wrapper exposes `data-theme="{theme}"` for dark/light scoping
+- **Built with Svelte 5 runes**: `$props()` + `$derived()` (no `$effect`)
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Tag from '@ticatec/uniface-element/Tag';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Tag from '@ticatec/uniface-element/Tag';
+
+  function handleDelete(id) {
+    console.log('removed tag id:', id);
+  }
+</script>
+
+<!-- Default: bordered, middle size, removable -->
+<Tag text="Basic" />
+
+<!-- With explicit props -->
+<Tag text=" removable " color="2" variant="round" ondelete={handleDelete} />
+
+<!-- Pure label, no × icon -->
+<Tag text="Status: pending" color="4" removable={false} />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `text` | `string \| undefined` | `undefined` | Label text rendered inside the tag |
+| `size` | `'small' \| 'middle' \| 'big'` | `'middle'` | Tag size (`small` ≈ 20px tall, `middle` ≈ 28px, `big` ≈ 30px) |
+| `variant` | `'borderless' \| 'border' \| 'round'` | `'border'` | Visual shape. `border` = subtle 10% outline; `round` = pill with 50% outline; `borderless` = no border |
+| `removable` | `boolean` | `true` | When `true`, renders a × icon on hover that fires `ondelete` |
+| `color` | `string \| undefined` | `undefined` | Color theme key `'1'`–`'12'`. Rendered as class `color-g{color}`. Empty / whitespace → default (g0). |
+| `data` | `any` | `undefined` | Arbitrary payload. **Only `data.id` is read** — it's passed to `ondelete` when the × icon is clicked. |
+| `ondelete` | `(id: any) => void` | `undefined` | Fired when × is clicked. **Receives `data.id`, not `data` itself.** |
+| `theme` | `string \| undefined` | `undefined` | Set on the outer wrapper as `data-theme`. Use for dark/light scope via CSS attribute selectors. |
+| `style` | `string \| undefined` | `undefined` | Inline CSS on the outer wrapper |
+| `class` | `string \| undefined` | `undefined` | **Currently unused.** The prop is declared but not rendered into any class slot. Don't rely on it. |
+
+> **`ondelete` signature gotcha**: the callback receives `data?.id`, not `data`. If you need the full data object, close over it in your handler: `ondelete={() => removeTag(tag)}` and ignore the argument.
+
+## Events
+
+| Event | Signature | Description |
+|-------|-----------|-------------|
+| `ondelete` | `(id: any) => void` | Fires when the × icon is clicked. The handler also calls `event.preventDefault()` and `event.stopPropagation()` so the click doesn't bubble. The argument is `data?.id` (whatever you passed in via the `data` prop, dotted with `id`). |
+
+## Basic Examples
+
+### Default Tags
+
+```svelte
+<div style="display: flex; gap: 8px; flex-wrap: wrap;">
+  <Tag text="Default" />
+  <Tag text="Technology" />
+  <Tag text="Design" />
+  <Tag text="Development" />
+</div>
+```
+
+### Sizes
+
+```svelte
+<div style="display: flex; gap: 16px; align-items: center;">
+  <Tag text="Small"  size="small" />
+  <Tag text="Middle" size="middle" />
+  <Tag text="Big"    size="big" />
+</div>
+```
+
+### Variants
+
+```svelte
+<div style="display: flex; gap: 8px;">
+  <Tag text="Borderless" variant="borderless" />
+  <Tag text="Border"     variant="border" />     <!-- default -->
+  <Tag text="Round"      variant="round" />
+</div>
+```
+
+### Color Palette (g1–g12)
+
+```svelte
+<div style="display: flex; gap: 8px; flex-wrap: wrap;">
+  <Tag text="g1"  color="1"  removable={false} />
+  <Tag text="g2"  color="2"  removable={false} />
+  <Tag text="g3"  color="3"  removable={false} />
+  <Tag text="g4"  color="4"  removable={false} />
+  <Tag text="g5"  color="5"  removable={false} />
+  <Tag text="g6"  color="6"  removable={false} />
+  <Tag text="g7"  color="7"  removable={false} />
+  <Tag text="g8"  color="8"  removable={false} />
+  <Tag text="g9"  color="9"  removable={false} />
+  <Tag text="g10" color="10" removable={false} />
+  <Tag text="g11" color="11" removable={false} />
+  <Tag text="g12" color="12" removable={false} />
+</div>
+```
+
+## Detailed Examples
+
+### Removable Tag List
+
+Each tag binds its full object via `data`. The handler ignores the `id` argument and closes over the object directly, which is cleaner than relying on the `data.id` quirk:
+
+```svelte
+<script>
+  import Tag from '@ticatec/uniface-element/Tag';
+
+  let tags = $state([
+    { id: 1, text: 'JavaScript', color: '1' },
+    { id: 2, text: 'Svelte',     color: '5' },
+    { id: 3, text: 'TypeScript', color: '9' }
+  ]);
+
+  function removeTag(tag) {
+    tags = tags.filter(t => t.id !== tag.id);
+  }
+</script>
+
+<div style="display: flex; gap: 8px; flex-wrap: wrap;">
+  {#each tags as tag (tag.id)}
+    <Tag
+      text={tag.text}
+      color={tag.color}
+      data={tag}
+      ondelete={() => removeTag(tag)}
+    />
+  {/each}
+</div>
+```
+
+> Hover a tag — the × icon fades in at the top-right.
+
+### Status Indicators (non-removable)
+
+```svelte
+<script>
+  import Tag from '@ticatec/uniface-element/Tag';
+
+  const items = [
+    { label: 'Online',   count: 1240, color: '2'  },
+    { label: 'Pending',  count: 45,   color: '4'  },
+    { label: 'Error',    count: 12,   color: '3'  },
+    { label: 'Draft',    count: 7,    color: '12' }
+  ];
+</script>
+
+<div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 12px;">
+  {#each items as item}
+    <div style="padding: 12px; border: 1px solid #e5e7eb; border-radius: 8px;">
+      <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 4px;">
+        <strong>{item.label}</strong>
+        <Tag text={item.label} color={item.color} size="small" variant="round" removable={false} />
+      </div>
+      <div style="font-size: 22px; font-weight: 700;">{item.count}</div>
+    </div>
+  {/each}
+</div>
+```
+
+## Color Reference
+
+| Key | Variable | Typical use |
+|-----|----------|-------------|
+| 1 | `--uniface-tag-g1-color` (blue) | primary, links |
+| 2 | `--uniface-tag-g2-color` (green) | success |
+| 3 | `--uniface-tag-g3-color` (red) | error |
+| 4 | `--uniface-tag-g4-color` (yellow) | warning |
+| 5 | `--uniface-tag-g5-color` (pink) | highlight |
+| 6 | `--uniface-tag-g6-color` (cyan) | info |
+| 7 | `--uniface-tag-g7-color` (orange) | alert |
+| 8 | `--uniface-tag-g8-color` (amber) | in-progress |
+| 9 | `--uniface-tag-g9-color` (indigo) | secondary |
+| 10 | `--uniface-tag-g10-color` (purple) | premium |
+| 11 | `--uniface-tag-g11-color` (lime) | new |
+| 12 | special | neutral — uses `--uniface-tag-g12-bg` / `--uniface-tag-g12-border` directly (no `color-mix`), so set both to override |
+
+For g1–g11, the background and border are auto-derived from the color via `color-mix(in srgb, var 10%, transparent)` and `color-mix(in srgb, var 50%, transparent)`. You only need to set the `--uniface-tag-gN-color` variable to re-theme.
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="uniface-tag" style="..." data-theme="...">
+  <div class="{size} {variant} {colorClass}" class:removable>
+    <span>{text}</span>
+    <!-- only when removable={true} -->
+    <i class="icon_google_clear uniface-remove-icon" aria-hidden="true"></i>
+  </div>
+</div>
+```
+
+### Built-in classes & states
+
+| Class | When applied |
+|-------|--------------|
+| `.uniface-tag` | Always (outer wrapper) |
+| `.small` / `.middle` / `.big` | From `size` prop |
+| `.borderless` / `.border` / `.round` | From `variant` prop |
+| `.color` + `.color-g{N}` | When `color` is non-empty |
+| `.removable` | When `removable={true}` |
+
+### Remove icon visibility
+
+The × icon is **hidden by default** and only appears on hover:
+
+```css
+.uniface-tag > div:hover .uniface-remove-icon { opacity: 1; }
+.uniface-tag > div:not(:hover) .uniface-remove-icon {
+  opacity: 0;
+  pointer-events: none;
+}
+```
+
+Implication: on touch devices, the × is effectively unreachable because there's no hover state. If you need always-visible removal on mobile, override the CSS or render your own button next to the tag.
+
+### CSS Custom Properties
+
+```css
+:root {
+  /* Base (no color prop) */
+  --uniface-tag-g0-color: #374151;
+
+  /* g1–g11: each derives bg + border from its color via color-mix */
+  --uniface-tag-g1-color:  #0061FF;
+  --uniface-tag-g2-color:  #2DC071;
+  --uniface-tag-g3-color:  #FF4D4F;
+  --uniface-tag-g4-color:  #FFBF00;
+  --uniface-tag-g5-color:  #EB2F96;
+  --uniface-tag-g6-color:  #13C2C2;
+  --uniface-tag-g7-color:  #FA541C;
+  --uniface-tag-g8-color:  #FA8C16;
+  --uniface-tag-g9-color:  #2F54EB;
+  --uniface-tag-g10-color: #722ED1;
+  --uniface-tag-g11-color: #A0D911;
+
+  /* g12 is special: bg/border are set explicitly, no color-mix */
+  --uniface-tag-g12-color:  #374151;
+  --uniface-tag-g12-bg:     #F8FAFC;
+  --uniface-tag-g12-border: #E2E8F0;
+
+  /* Geometry */
+  --uniface-tag-margin: 12px;
+  --uniface-tag-height: 28px;        /* middle */
+  --uniface-tag-height-sm: 20px;     /* small */
+  --uniface-tag-height-bg: 30px;     /* big */
+  --uniface-tag-font-size: 12px;
+  --uniface-tag-action-color: var(--uniface-default-text-color, #374151);
+
+  /* Inherited tokens */
+  --uniface-radius: 4px;
+  --uniface-radius-xl: 12px;
+}
+```
+
+### Dark Theme
+
+Scope via `data-theme`:
+
+```css
+[data-theme='dark'] {
+  --uniface-tag-g0-color: #e5e7eb;
+  /* override g1–g12 as needed; color-mix still applies for g1–g11 */
+}
+```
+
+```svelte
+<Tag text="Hello" theme="dark" />
+```
+
+## Accessibility
+
+- The × icon is `<i aria-hidden="true">` with a `click` handler — **not keyboard accessible**. There's no `tabindex`, `role`, or `keydown` handler. Keyboard users cannot remove a tag through the icon alone.
+- If keyboard removal matters, wrap the tag in your own keyboard-accessible container (e.g. a `<button>`), or build a custom tag.
+- The outer `<div>` has no role; screen readers will announce the `text` content as plain text.
+- For status semantics (success / error / etc.), color is the only signal — pair with a visually-hidden label or rely on the `text` content to convey meaning, since none of the color classes carry an ARIA semantic.
+
+## Behavior Notes
+
+- The × icon's `onclick` calls `event.preventDefault()` and `event.stopPropagation()` after firing `ondelete`, so parent click handlers won't see the event.
+- `color` is treated as a string and concatenated into `color-g${color}`. Passing `color={1}` (number) still works because of template-string coercion, but passing `color="azure"` would generate a `color-gazure` class that doesn't exist.
+- Empty / whitespace-only `color` skips the color class entirely (falls back to `--uniface-tag-g0-color`).
+
+## Best Practices
+
+1. **Pass the full object via `data`, ignore the `ondelete` argument.** Because the callback receives `data.id`, closing over the object in your handler is less surprising than relying on the id: `ondelete={() => remove(tag)}`.
+2. **Use `removable={false}` for status indicators.** Otherwise the × appears on hover and implies the status is dismissable.
+3. **Keep colors semantically consistent** across the app — g2 always means success, g3 always means error, etc.
+4. **Don't rely on hover for primary actions on mobile.** The × icon is hover-gated; on touch devices consider an alternative UI.
+5. **For very long tag lists, use `{#each ... (key)}` with a stable key** so Svelte can diff efficiently.
+
+## Related Components
+
+- [Button](../button/README.md) — standard button
+- [IconButton](../button/IconButton_README.md) — round icon button

package/dist/general/tag/README_CN.md

@@ -0,0 +1,319 @@
+# Tag 标签组件
+
+一个紧凑的标签 / 状态胶囊。渲染文本，可选 1–12 号颜色主题、三种形状（border / round / borderless）、三种尺寸，以及悬停才出现的 × 移除图标。
+
+## 功能特性
+
+- **三种形状**：`border`（细描边）、`round`（胶囊形 + 较粗描边）、`borderless`
+- **三种尺寸**：`small`、`middle`（默认）、`big`
+- **12 号颜色主题**：内置 g1–g12 调色板，背景与边框由 `color-mix` 从主色自动派生
+- **可选 × 移除图标**：仅在悬停时显示，点击触发 `ondelete`
+- **主题感知**：外层 wrapper 暴露 `data-theme="{theme}"`，便于明暗主题作用域
+- **基于 Svelte 5 runes**：`$props()` + `$derived()`（无 `$effect`）
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import Tag from '@ticatec/uniface-element/Tag';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Tag from '@ticatec/uniface-element/Tag';
+
+  function handleDelete(id) {
+    console.log('被移除标签的 id:', id);
+  }
+</script>
+
+<!-- 默认：边框 + middle 尺寸 + 可移除 -->
+<Tag text="基本" />
+
+<!-- 显式指定全部 props -->
+<Tag text="可移除" color="2" variant="round" ondelete={handleDelete} />
+
+<!-- 纯标签，无 × -->
+<Tag text="状态：待处理" color="4" removable={false} />
+```
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `text` | `string \| undefined` | `undefined` | 标签内文字 |
+| `size` | `'small' \| 'middle' \| 'big'` | `'middle'` | 尺寸（`small` ≈ 20px 高、`middle` ≈ 28px、`big` ≈ 30px） |
+| `variant` | `'borderless' \| 'border' \| 'round'` | `'border'` | 视觉形状。`border` = 10% 透明度细描边；`round` = 胶囊 + 50% 描边；`borderless` = 无边框 |
+| `removable` | `boolean` | `true` | 为 `true` 时悬停显示 × 图标，点击触发 `ondelete` |
+| `color` | `string \| undefined` | `undefined` | 颜色主题键 `'1'`–`'12'`，渲染为 `color-g{color}` 类。空 / 纯空格 → 默认（g0） |
+| `data` | `any` | `undefined` | 任意负载。**只读 `data.id`** —— × 被点击时把这个 id 传给 `ondelete` |
+| `ondelete` | `(id: any) => void` | `undefined` | × 点击时触发。**收到的是 `data.id`，不是 `data` 本身** |
+| `theme` | `string \| undefined` | `undefined` | 设置到外层 wrapper 的 `data-theme`，配合 CSS 属性选择器做明暗主题 |
+| `style` | `string \| undefined` | `undefined` | 外层 wrapper 的内联 CSS |
+| `class` | `string \| undefined` | `undefined` | **当前未使用。** prop 声明了但模板里没用到，不要依赖它 |
+
+> **`ondelete` 签名陷阱**：回调收到的是 `data?.id`，不是 `data`。需要完整对象时，在 handler 里闭包捕获：`ondelete={() => removeTag(tag)}`，忽略入参即可。
+
+## 事件
+
+| 事件 | 签名 | 描述 |
+|------|------|------|
+| `ondelete` | `(id: any) => void` | × 被点击时触发。handler 内部会调 `event.preventDefault()` 和 `event.stopPropagation()`，点击不会冒泡。入参是 `data?.id`（即你通过 `data` prop 传入的对象的 `.id` 字段） |
+
+## 基本示例
+
+### 默认标签
+
+```svelte
+<div style="display: flex; gap: 8px; flex-wrap: wrap;">
+  <Tag text="默认" />
+  <Tag text="技术" />
+  <Tag text="设计" />
+  <Tag text="开发" />
+</div>
+```
+
+### 尺寸
+
+```svelte
+<div style="display: flex; gap: 16px; align-items: center;">
+  <Tag text="Small"  size="small" />
+  <Tag text="Middle" size="middle" />
+  <Tag text="Big"    size="big" />
+</div>
+```
+
+### 形状
+
+```svelte
+<div style="display: flex; gap: 8px;">
+  <Tag text="Borderless" variant="borderless" />
+  <Tag text="Border"     variant="border" />     <!-- 默认 -->
+  <Tag text="Round"      variant="round" />
+</div>
+```
+
+### 颜色调色板（g1–g12）
+
+```svelte
+<div style="display: flex; gap: 8px; flex-wrap: wrap;">
+  <Tag text="g1"  color="1"  removable={false} />
+  <Tag text="g2"  color="2"  removable={false} />
+  <Tag text="g3"  color="3"  removable={false} />
+  <Tag text="g4"  color="4"  removable={false} />
+  <Tag text="g5"  color="5"  removable={false} />
+  <Tag text="g6"  color="6"  removable={false} />
+  <Tag text="g7"  color="7"  removable={false} />
+  <Tag text="g8"  color="8"  removable={false} />
+  <Tag text="g9"  color="9"  removable={false} />
+  <Tag text="g10" color="10" removable={false} />
+  <Tag text="g11" color="11" removable={false} />
+  <Tag text="g12" color="12" removable={false} />
+</div>
+```
+
+## 详细示例
+
+### 可移除标签列表
+
+每个 Tag 通过 `data` 绑定完整对象。handler 忽略入参、直接闭包捕获对象，比依赖 `data.id` 的怪行为更直观：
+
+```svelte
+<script>
+  import Tag from '@ticatec/uniface-element/Tag';
+
+  let tags = $state([
+    { id: 1, text: 'JavaScript', color: '1' },
+    { id: 2, text: 'Svelte',     color: '5' },
+    { id: 3, text: 'TypeScript', color: '9' }
+  ]);
+
+  function removeTag(tag) {
+    tags = tags.filter(t => t.id !== tag.id);
+  }
+</script>
+
+<div style="display: flex; gap: 8px; flex-wrap: wrap;">
+  {#each tags as tag (tag.id)}
+    <Tag
+      text={tag.text}
+      color={tag.color}
+      data={tag}
+      ondelete={() => removeTag(tag)}
+    />
+  {/each}
+</div>
+```
+
+> 鼠标悬停标签，右上角的 × 会淡入显示。
+
+### 状态指示器（不可移除）
+
+```svelte
+<script>
+  import Tag from '@ticatec/uniface-element/Tag';
+
+  const items = [
+    { label: '在线',   count: 1240, color: '2'  },
+    { label: '待处理', count: 45,   color: '4'  },
+    { label: '错误',   count: 12,   color: '3'  },
+    { label: '草稿',   count: 7,    color: '12' }
+  ];
+</script>
+
+<div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 12px;">
+  {#each items as item}
+    <div style="padding: 12px; border: 1px solid #e5e7eb; border-radius: 8px;">
+      <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 4px;">
+        <strong>{item.label}</strong>
+        <Tag text={item.label} color={item.color} size="small" variant="round" removable={false} />
+      </div>
+      <div style="font-size: 22px; font-weight: 700;">{item.count}</div>
+    </div>
+  {/each}
+</div>
+```
+
+## 颜色参考
+
+| 键 | 变量 | 典型用途 |
+|----|------|---------|
+| 1 | `--uniface-tag-g1-color`（蓝） | 主要、链接 |
+| 2 | `--uniface-tag-g2-color`（绿） | 成功 |
+| 3 | `--uniface-tag-g3-color`（红） | 错误 |
+| 4 | `--uniface-tag-g4-color`（黄） | 警告 |
+| 5 | `--uniface-tag-g5-color`（粉） | 高亮 |
+| 6 | `--uniface-tag-g6-color`（青） | 信息 |
+| 7 | `--uniface-tag-g7-color`（橙） | 警报 |
+| 8 | `--uniface-tag-g8-color`（琥珀） | 进行中 |
+| 9 | `--uniface-tag-g9-color`（靛蓝） | 次要 |
+| 10 | `--uniface-tag-g10-color`（紫） | 高级 |
+| 11 | `--uniface-tag-g11-color`（酸橙） | 新内容 |
+| 12 | 特殊 | 中性 —— 直接用 `--uniface-tag-g12-bg` / `--uniface-tag-g12-border`（不走 `color-mix`），要换肤得两个都设 |
+
+g1–g11 的背景和边框都是从主色通过 `color-mix(in srgb, var 10%, transparent)` 和 `color-mix(in srgb, var 50%, transparent)` 自动派生的，所以只需设 `--uniface-tag-gN-color` 即可重新主题化。
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="uniface-tag" style="..." data-theme="...">
+  <div class="{size} {variant} {colorClass}" class:removable>
+    <span>{text}</span>
+    <!-- removable={true} 时才有 -->
+    <i class="icon_google_clear uniface-remove-icon" aria-hidden="true"></i>
+  </div>
+</div>
+```
+
+### 内置类与状态
+
+| 类 | 何时应用 |
+|----|---------|
+| `.uniface-tag` | 总有（外层 wrapper） |
+| `.small` / `.middle` / `.big` | 来自 `size` |
+| `.borderless` / `.border` / `.round` | 来自 `variant` |
+| `.color` + `.color-g{N}` | `color` 非空时 |
+| `.removable` | `removable={true}` 时 |
+
+### × 图标的可见性
+
+× 图标**默认隐藏**，仅悬停时出现：
+
+```css
+.uniface-tag > div:hover .uniface-remove-icon { opacity: 1; }
+.uniface-tag > div:not(:hover) .uniface-remove-icon {
+  opacity: 0;
+  pointer-events: none;
+}
+```
+
+含义：触屏设备没有 hover 态，× 实际上点不到。如果需要在移动端可删除，要么覆盖 CSS，要么在 Tag 旁边自己渲染一个按钮。
+
+### CSS 自定义属性
+
+```css
+:root {
+  /* 基色（无 color prop 时） */
+  --uniface-tag-g0-color: #374151;
+
+  /* g1–g11：背景与边框由 color-mix 从主色自动派生 */
+  --uniface-tag-g1-color:  #0061FF;
+  --uniface-tag-g2-color:  #2DC071;
+  --uniface-tag-g3-color:  #FF4D4F;
+  --uniface-tag-g4-color:  #FFBF00;
+  --uniface-tag-g5-color:  #EB2F96;
+  --uniface-tag-g6-color:  #13C2C2;
+  --uniface-tag-g7-color:  #FA541C;
+  --uniface-tag-g8-color:  #FA8C16;
+  --uniface-tag-g9-color:  #2F54EB;
+  --uniface-tag-g10-color: #722ED1;
+  --uniface-tag-g11-color: #A0D911;
+
+  /* g12 特殊：bg/border 显式设置，不走 color-mix */
+  --uniface-tag-g12-color:  #374151;
+  --uniface-tag-g12-bg:     #F8FAFC;
+  --uniface-tag-g12-border: #E2E8F0;
+
+  /* 几何 */
+  --uniface-tag-margin: 12px;
+  --uniface-tag-height: 28px;        /* middle */
+  --uniface-tag-height-sm: 20px;     /* small */
+  --uniface-tag-height-bg: 30px;     /* big */
+  --uniface-tag-font-size: 12px;
+  --uniface-tag-action-color: var(--uniface-default-text-color, #374151);
+
+  /* 继承的令牌 */
+  --uniface-radius: 4px;
+  --uniface-radius-xl: 12px;
+}
+```
+
+### 暗色主题
+
+通过 `data-theme` 作用域：
+
+```css
+[data-theme='dark'] {
+  --uniface-tag-g0-color: #e5e7eb;
+  /* 按需覆盖 g1–g12；g1–g11 仍然走 color-mix */
+}
+```
+
+```svelte
+<Tag text="你好" theme="dark" />
+```
+
+## 无障碍访问
+
+- × 图标是 `<i aria-hidden="true">` 加 `click` handler —— **键盘不可达**。没有 `tabindex`、`role`、`keydown`。键盘用户单独通过这个图标删不了标签
+- 如果键盘删除很重要，要么用你自己的可键盘访问容器（如 `<button>`）包一层，要么自建一个 tag 组件
+- 外层 `<div>` 没有 role，屏幕阅读器会把 `text` 当纯文本朗读
+- 状态语义（成功 / 错误等）只靠颜色传达 —— 配合 visually-hidden 标签，或确保 `text` 内容本身能表达含义，因为颜色类不带 ARIA 语义
+
+## 行为说明
+
+- × 的 `onclick` 在触发 `ondelete` 后会调 `event.preventDefault()` 和 `event.stopPropagation()`，父级 click handler 看不到这次点击
+- `color` 作为字符串拼成 `color-g${color}`。传 `color={1}`（数字）由于模板字符串强转也能工作，但传 `color="azure"` 会生成不存在的 `color-gazure` 类
+- 空 / 纯空格的 `color` 会跳过颜色类（fallback 到 `--uniface-tag-g0-color`）
+
+## 最佳实践
+
+1. **完整对象经 `data` 传，忽略 `ondelete` 入参**。回调收到的是 `data.id`，闭包捕获对象更不绕：`ondelete={() => remove(tag)}`
+2. **状态指示器用 `removable={false}`**。否则悬停出现的 × 暗示这个状态可以被关闭
+3. **颜色语义全应用统一** —— g2 永远是成功、g3 永远是错误
+4. **不要在移动端把核心操作放在 hover 上**。× 是 hover gating 的，触屏要另想 UI
+5. **长列表用 `{#each ... (key)}` 配稳定 key**，让 Svelte 高效 diff
+
+## 相关组件
+
+- [Button](../button/README_CN.md) —— 标准按钮
+- [IconButton](../button/IconButton_README_CN.md) —— 圆形图标按钮