lingee-ui 0.0.8 → 0.0.10

package/skill/AGENTS-SNIPPET.md

@@ -2,22 +2,24 @@
 
 > **本文件由 `packages/lingee-ui/scripts/gen-skill.mjs` 自动生成，禁止手工编辑。**
 > 供根 `AGENTS.md` 引用，避免手写清单随组件库迭代脱节。
-> 组件库 `0.0.8` ｜ 图标库 `1.0.16`
+> 组件库 `0.0.10` ｜ 图标库 `1.0.16`
 
-## 可用组件（37）
+## 可用组件（39）
 
 | 组件 | 名称 | 说明 |
 |------|------|------|
 | `Alert` | 消息通知 | 消息提示组件，用于页面中展示重要的提示信息。 |
 | `Avatar`、`AvatarGroup` | 头像 | 头像组件，用于展示用户头像或图标，支持图片、文字、默认图标三种形态。 |
 | `Button` | 按钮 | 用于触发一个操作，是用户与系统交互的基础元素。 |
+| `Carousel`、`CarouselItem` | 轮播容器 | 水平轮播容器，用于在一屏内循环展示一组内容，支持自动播放、拖拽切换与圆点指示器。 |
 | `Checkbox`、`CheckboxGroup` | 多选框 | 在一组选项中进行多项选择。 |
 | `ColorPicker` | 颜色选择器 | 用于选择颜色值的交互组件。 |
 | `DatePicker` | 日期选择器 | 用于选择日期的输入组件。 |
 | `Dialog` | 弹出窗 | 模态对话框，用于需要用户确认或填写信息的场景。支持声明式和命令式两种调用方式。 |
 | `Divider` | 分割线 | 用于分隔内容区块，使页面结构更清晰。 |
 | `Drawer` | 抽屉 | 从屏幕边缘滑出的浮层面板，用于承载表单或详情内容。 |
-| `Dropdown` +13 个子组件 | 下拉菜单 | 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。 |
+| `Dropdown` +14 个子组件 | 下拉菜单 | 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。 |
+| `EllipsisTooltip` | 省略提示 | 单行省略文本，仅在真正被截断时才悬停显示完整内容。 |
 | `Empty`、`EmptyCard` | 空状态 | 当目标区域无数据时展示的空状态占位图，引导用户进行下一步操作。 |
 | `Flex` | 弹性布局 | 弹性布局容器，用于快速搭建横向/纵向排列，避免为简单布局单独写样式文件。 |
 | `Form` | 表单 | 数据录入和校验组件，支持垂直、水平、行内布局。 |
@@ -30,7 +32,7 @@
 | `RangePicker` | 日期范围选择器 | 用于选择日期范围的输入组件。 |
 | `ScrollArea`、`ScrollBar` | 自定义滚动区域 | 自定义样式的滚动容器组件，提供美观的滚动条体验。 |
 | `Select` | 选择器 | 下拉选择器，支持单选、多选、搜索和远程加载。 |
-| `Sidebar` +14 个子组件 | 侧边栏 | 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。 |
+| `Sidebar` +26 个子组件 | 侧边栏 | 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。 |
 | `Skeleton` | 骨架屏 | 在数据加载完成前通过占位图形展示页面结构，降低用户等待焦虑。 |
 | `Slider` | 数值滑块 | 滑动输入器，用于在数值区间内进行选择。 |
 | `Spin` | 加载中 | 用于页面和区域的加载中状态指示器。 |
@@ -63,28 +65,28 @@
 
 按 CSS 属性选前缀：`color`/`fill`/`stroke` → `fg`，`background` → `bg`，`border-color`/`outline` → `border`。
 
-亮暗变量名相同，`data-theme="dark"` 自动切换。色值列供**反查**（设计稿色值找 Token）与**比对**（少数 Token 亮暗语义不对称）使用，**业务代码禁止硬编码色值或引用 primitives**。
+亮暗变量名相同，`data-theme="dark"` 自动切换。色值列供**反查**（设计稿色值找 Token）与**比对**（少数 Token 亮暗语义不对称）使用，**不要把色值直接写进业务代码**。表里查不到所需颜色时可写硬编码（加注释标明来源），但**任何情况都不得引用 primitives**。
 
-### ⚠️ 命名异常的 Token（照抄，不要纠正）
+### ⚠️ 已废弃的错拼 Token
 
-设计源文件里的错拼，已被组件库使用不能改。按「正确」拼写会静默失效（CSS 变量不存在不报错，颜色直接丢失）：
+早期从设计源文件带入的拼写错误，现已提供正确拼写。错拼名仅作兼容别名保留（与正确名同值），**后续版本会移除**，新代码一律用左列：
 
-| 实际可用 | 说明 |
-|---------|------|
-| `--lg-g-fg-color-indigo-defauit` | ~~`--lg-g-fg-color-indigo-default`~~ |
-| `--lg-g-fg-color-lime-defauit` | ~~`--lg-g-fg-color-lime-default`~~ |
-| `--lg-g-fg-color-violet-defauit` | ~~`--lg-g-fg-color-violet-default`~~ |
-| `--lg-g-bg-color-emeraid-translucent-soft` | ~~`--lg-g-bg-color-emerald-translucent-soft`~~ |
-| `--lg-g-fg-color-black-aint` | 片段 `aint` 非标准命名，照抄即可 |
+| 正确拼写（用这个） | 已废弃 |
+|-------------------|--------|
+| `--lg-g-fg-color-black-faint` | ~~`--lg-g-fg-color-black-aint`~~ |
+| `--lg-g-fg-color-indigo-default` | ~~`--lg-g-fg-color-indigo-defauit`~~ |
+| `--lg-g-fg-color-lime-default` | ~~`--lg-g-fg-color-lime-defauit`~~ |
+| `--lg-g-fg-color-violet-default` | ~~`--lg-g-fg-color-violet-defauit`~~ |
+| `--lg-g-bg-color-emerald-translucent-soft` | ~~`--lg-g-bg-color-emeraid-translucent-soft`~~ |
 
-#### 前景色 fg（34）
+#### 前景色 fg（47）
 
 | Token | 亮色 | 暗色 |
 |-------|------|------|
 | `--lg-g-fg-color-white-heavy` | `#FFFFFF` | `#FFFFFF` |
 | `--lg-g-fg-color-white-dark` | `#FFFFFF` | `rgba(255, 255, 255, 0.28)` |
 | `--lg-g-fg-color-black-moderate` | `rgba(0, 0, 0, 0.18)` | `rgba(255, 255, 255, 0.18)` |
-| `--lg-g-fg-color-black-aint` | `rgba(0, 0, 0, 0.28)` | `rgba(255, 255, 255, 0.28)` |
+| `--lg-g-fg-color-black-faint` | `rgba(0, 0, 0, 0.28)` | `rgba(255, 255, 255, 0.28)` |
 | `--lg-g-fg-color-black-default` | `rgba(0, 0, 0, 0.46)` | `rgba(255, 255, 255, 0.46)` |
 | `--lg-g-fg-color-black-muted` | `rgba(0, 0, 0, 0.64)` | `rgba(255, 255, 255, 0.64)` |
 | `--lg-g-fg-color-black-strong` | `rgba(0, 0, 0, 0.82)` | `rgba(255, 255, 255, 0.82)` |
@@ -107,16 +109,29 @@
 | `--lg-g-fg-color-amber-default` | `#E28800` | `#E28800` |
 | `--lg-g-fg-color-teal-default` | `#00BFB8` | `#00BFB8` |
 | `--lg-g-fg-color-purple-default` | `#7F2AF3` | `#7F2AF3` |
-| `--lg-g-fg-color-indigo-defauit` | `#4343F5` | `#4343F5` |
+| `--lg-g-fg-color-indigo-default` | `#4343F5` | `#4343F5` |
 | `--lg-g-fg-color-yellow-default` | `#D1A600` | `#D1A600` |
 | `--lg-g-fg-color-cyan-default` | `#0083D4` | `#0083D4` |
 | `--lg-g-fg-color-pink-default` | `#ED1165` | `#ED1165` |
 | `--lg-g-fg-color-fuchsia-default` | `#ED1DB9` | `#ED1DB9` |
 | `--lg-g-fg-color-emerald-default` | `#009D72` | `#009D72` |
-| `--lg-g-fg-color-lime-defauit` | `#5FBA04` | `#5FBA04` |
-| `--lg-g-fg-color-violet-defauit` | `#572FF7` | `#572FF7` |
+| `--lg-g-fg-color-lime-default` | `#5FBA04` | `#5FBA04` |
+| `--lg-g-fg-color-violet-default` | `#572FF7` | `#572FF7` |
+| `--lg-g-fg-color-warning-low` | `#FF8D42` | `#FF8D42` |
+| `--lg-g-fg-color-success-low` | `#08CC50` | `#08CC50` |
+| `--lg-g-fg-color-amber-low` | `#FFB200` | `#FFB200` |
+| `--lg-g-fg-color-teal-low` | `#00E5E5` | `#00E5E5` |
+| `--lg-g-fg-color-purple-low` | `#8F40FF` | `#8F40FF` |
+| `--lg-g-fg-color-indigo-low` | `#5155F6` | `#5155F6` |
+| `--lg-g-fg-color-yellow-low` | `#FFE500` | `#FFE500` |
+| `--lg-g-fg-color-cyan-low` | `#00A3F4` | `#00A3F4` |
+| `--lg-g-fg-color-pink-low` | `#FF246D` | `#FF246D` |
+| `--lg-g-fg-color-fuchsia-low` | `#F858D0` | `#F858D0` |
+| `--lg-g-fg-color-emerald-low` | `#08C787` | `#08C787` |
+| `--lg-g-fg-color-lime-low` | `#74D70B` | `#74D70B` |
+| `--lg-g-fg-color-violet-low` | `#7858F9` | `#7858F9` |
 
-#### 背景色 bg（92）
+#### 背景色 bg（99）
 
 | Token | 亮色 | 暗色 |
 |-------|------|------|
@@ -201,7 +216,7 @@
 | `--lg-g-bg-color-indigo-faint` | `#F5F6FF` | `rgba(81, 85, 246, 0.03)` |
 | `--lg-g-bg-color-indigo-faint-dark` | `#F5F6FF` | `#222327` |
 | `--lg-g-bg-color-gray-subtle` | `#F7F8FA` | `#F7F8FA` |
-| `--lg-g-bg-color-emeraid-translucent-soft` | `rgba(8, 199, 135, 0.08)` | `rgba(8, 199, 135, 0.08)` |
+| `--lg-g-bg-color-emerald-translucent-soft` | `rgba(8, 199, 135, 0.08)` | `rgba(8, 199, 135, 0.08)` |
 | `--lg-g-bg-color-emerald-default` | `#009D72` | `#009D72` |
 | `--lg-g-bg-color-lime-translucent-soft` | `rgba(116, 215, 11, 0.08)` | `rgba(116, 215, 11, 0.08)` |
 | `--lg-g-bg-color-lime-default` | `#5FBA04` | `#5FBA04` |
@@ -211,9 +226,16 @@
 | `--lg-g-bg-color-violet-default` | `#572FF7` | `#572FF7` |
 | `--lg-g-bg-color-fuchsia-translucent-soft` | `rgba(248, 88, 208, 0.08)` | `rgba(248, 88, 208, 0.08)` |
 | `--lg-g-bg-color-fuchsia-default` | `#ED1DB9` | `#ED1DB9` |
-| `--lg-g-bg-color-page-default` | `#F7F7FA` | `#1A1A1A` |
+| `--lg-g-bg-color-page-default` | `#F7F7FA` | `#191A1B` |
+| `--lg-g-bg-color-white` | `#FAFAFA` | `#191A1B` |
+| `--lg-g-bg-color-navigation` | `#F1F1F6` | `#191A1B` |
+| `--lg-g-bg-color-white-tabs` | `#FFFFFF` | `rgba(255, 255, 255, 0.28)` |
+| `--lg-g-bg-color-white-default` | `rgba(255, 255, 255, 0.46)` | `rgba(0, 0, 0, 0.46)` |
+| `--lg-g-bg-color-success-translucent-subtle` | `rgba(8, 204, 80, 0.06)` | `rgba(8, 204, 80, 0.06)` |
+| `--lg-g-bg-color-blue-translucent-subtle` | `rgba(77, 137, 255, 0.06)` | `rgba(77, 137, 255, 0.06)` |
+| `--lg-g-bg-color-blue-translucent-muted` | `rgba(77, 137, 255, 0.12)` | `rgba(77, 137, 255, 0.28)` |
 
-#### 边框色 border（27）
+#### 边框色 border（42）
 
 | Token | 亮色 | 暗色 |
 |-------|------|------|
@@ -244,6 +266,21 @@
 | `--lg-g-border-color-blue-translucent-soft` | `rgba(77, 137, 255, 0.08)` | `rgba(77, 137, 255, 0.08)` |
 | `--lg-g-border-color-blue-subtle` | `#E4EEFF` | `#183F96` |
 | `--lg-g-border-color-blue-default` | `#2970FF` | `#2970FF` |
+| `--lg-g-border-color-black-default` | `rgba(0, 0, 0, 0.46)` | `rgba(255, 255, 255, 0.46)` |
+| `--lg-g-border-color-warning-translucent-muted` | `rgba(255, 119, 0, 0.12)` | `rgba(255, 119, 0, 0.12)` |
+| `--lg-g-border-color-danger-translucent-muted` | `rgba(255, 41, 59, 0.12)` | `rgba(255, 41, 59, 0.12)` |
+| `--lg-g-border-color-success-translucent-muted` | `rgba(8, 204, 80, 0.12)` | `rgba(8, 204, 80, 0.12)` |
+| `--lg-g-border-color-blue-translucent-default` | `rgba(77, 137, 255, 0.12)` | `rgba(77, 137, 255, 0.12)` |
+| `--lg-g-border-color-amber-default` | `#E28800` | `#E28800` |
+| `--lg-g-border-color-teal-default` | `#00BFB8` | `#00BFB8` |
+| `--lg-g-border-color-emerald-default` | `#009D72` | `#009D72` |
+| `--lg-g-border-color-lime-default` | `#5FBA04` | `#5FBA04` |
+| `--lg-g-border-color-cyan-default` | `#0083D4` | `#0083D4` |
+| `--lg-g-border-color-purple-default` | `#7F2AF3` | `#7F2AF3` |
+| `--lg-g-border-color-indigo-default` | `#4343F5` | `#4343F5` |
+| `--lg-g-border-color-violet-default` | `#572FF7` | `#572FF7` |
+| `--lg-g-border-color-fuchsia-default` | `#ED1DB9` | `#ED1DB9` |
+| `--lg-g-border-color-pink-default` | `#ED1165` | `#ED1165` |
 #### 其他（3）
 
 | Token | 亮色 | 暗色 |

package/skill/SKILL.md

@@ -2,17 +2,17 @@
 name: lingee-ui-usage
 description: 使用 lingee-ui 组件库与 lingee-icon 图标库开发 React 界面。当需要编写含按钮、表单、弹窗、表格、下拉、页签、图标等 UI 的 React/TypeScript 代码，或需要查询 lingee-ui 组件 API、Design Token 语义变量、可用图标名时触发。关键词：lingee-ui、lingee-icon、组件库、图标库、Design Token、语义变量、lg- 前缀、UI 组件。
 metadata:
-  lingeeUi: "0.0.8"
+  lingeeUi: "0.0.10"
   lingeeIcon: "1.0.16"
   generatedBy: "gen-skill.mjs"
 ---
 
 # lingee-ui 组件库使用技能
 
-Kingdee Lingee 设计体系的 React 组件库（37 个组件）与图标库（967 个图标）。
+Kingdee Lingee 设计体系的 React 组件库（39 个组件）与图标库（968 个图标）。
 本技能面向**消费方项目**，只覆盖「如何用」，不含组件库内部开发约定。
 
-- 组件库版本 `0.0.8` ｜ 图标库版本 `1.0.16`
+- 组件库版本 `0.0.10` ｜ 图标库版本 `1.0.16`
 - 组件在线预览：https://kingdee.github.io/lingee-ui/
 - 图标在线预览：https://kingdee.github.io/lingee-icon/
 
@@ -44,7 +44,7 @@ import "lingee-ui/styles.css";        // 必须，否则组件完全无样式
 import { LingeeProvider } from "lingee-ui";
 
 createRoot(el).render(
-  <LingeeProvider locale="zh-CN">
+  <LingeeProvider>
     <App />
   </LingeeProvider>,
 );
@@ -59,13 +59,15 @@ createRoot(el).render(
 | `Alert` | 消息通知 | 消息提示组件，用于页面中展示重要的提示信息。 | `alert.md` | — |
 | `Avatar`、`AvatarGroup` | 头像 | 头像组件，用于展示用户头像或图标，支持图片、文字、默认图标三种形态。 | `avatar.md` | — |
 | `Button` | 按钮 | 用于触发一个操作，是用户与系统交互的基础元素。 | `button.md` | ✓ |
+| `Carousel`、`CarouselItem` | 轮播容器 | 水平轮播容器，用于在一屏内循环展示一组内容，支持自动播放、拖拽切换与圆点指示器。 | `carousel.md` | — |
 | `Checkbox`、`CheckboxGroup` | 多选框 | 在一组选项中进行多项选择。 | `checkbox.md` | — |
 | `ColorPicker` | 颜色选择器 | 用于选择颜色值的交互组件。 | `color-picker.md` | — |
 | `DatePicker` | 日期选择器 | 用于选择日期的输入组件。 | `date-picker.md` | — |
 | `Dialog` | 弹出窗 | 模态对话框，用于需要用户确认或填写信息的场景。支持声明式和命令式两种调用方式。 | `dialog.md` | — |
 | `Divider` | 分割线 | 用于分隔内容区块，使页面结构更清晰。 | `divider.md` | — |
 | `Drawer` | 抽屉 | 从屏幕边缘滑出的浮层面板，用于承载表单或详情内容。 | `drawer.md` | — |
-| `Dropdown` +13 个子组件 | 下拉菜单 | 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。 | `dropdown.md` | — |
+| `Dropdown` +14 个子组件 | 下拉菜单 | 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。 | `dropdown.md` | — |
+| `EllipsisTooltip` | 省略提示 | 单行省略文本，仅在真正被截断时才悬停显示完整内容。 | `ellipsis-tooltip.md` | — |
 | `Empty`、`EmptyCard` | 空状态 | 当目标区域无数据时展示的空状态占位图，引导用户进行下一步操作。 | `empty.md` | — |
 | `Flex` | 弹性布局 | 弹性布局容器，用于快速搭建横向/纵向排列，避免为简单布局单独写样式文件。 | `flex.md` | — |
 | `Form` | 表单 | 数据录入和校验组件，支持垂直、水平、行内布局。 | `form.md` | — |
@@ -78,7 +80,7 @@ createRoot(el).render(
 | `RangePicker` | 日期范围选择器 | 用于选择日期范围的输入组件。 | `range-picker.md` | — |
 | `ScrollArea`、`ScrollBar` | 自定义滚动区域 | 自定义样式的滚动容器组件，提供美观的滚动条体验。 | `scroll-area.md` | — |
 | `Select` | 选择器 | 下拉选择器，支持单选、多选、搜索和远程加载。 | `select.md` | — |
-| `Sidebar` +14 个子组件 | 侧边栏 | 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。 | `sidebar.md` | — |
+| `Sidebar` +26 个子组件 | 侧边栏 | 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。 | `sidebar.md` | — |
 | `Skeleton` | 骨架屏 | 在数据加载完成前通过占位图形展示页面结构，降低用户等待焦虑。 | `skeleton.md` | — |
 | `Slider` | 数值滑块 | 滑动输入器，用于在数值区间内进行选择。 | `slider.md` | — |
 | `Spin` | 加载中 | 用于页面和区域的加载中状态指示器。 | `spin.md` | — |
@@ -132,16 +134,15 @@ import { Search, Trash } from "lingee-icon";
 图标默认 `size="1em"`、`color="currentColor"`，即随父级字号与文字颜色走，
 所以**优先用 CSS 控制颜色**而不是传 `color` prop。
 
-完整 Props 见 `references/setup.md`，967 个图标的名称与中文语义索引见 `references/icons.md`。
+完整 Props 见 `references/setup.md`，968 个图标的名称与中文语义索引见 `references/icons.md`。
 选图标时必须从索引中查找，**不要凭猜测写图标名**，也不要从 `@ant-design/icons`、`lucide-react` 等其他库引入。
 
-## 颜色：只用语义 Token
+## 颜色：优先用语义 Token
 
-三条铁律：
+两条铁律：
 
-1. **禁止硬编码色值**（`#495DFF`、`rgb(...)`、`red`），也禁止在 tsx 中写 hex/rgb
-2. **禁止使用 primitives 色板变量**（`--lg-primary-600`、`--lg-black-82`），它们不随暗色模式切换
-3. 只用语义层 `--lg-g-*` 变量，按 CSS 属性选前缀：
+1. **禁止使用 primitives 色板变量**（`--lg-primary-600`、`--lg-black-82`），它们不随暗色模式切换，这条没有例外
+2. 优先用语义层 `--lg-g-*` 变量，按 CSS 属性选前缀：
 
 | CSS 属性 | Token 前缀 |
 |----------|-----------|
@@ -156,7 +157,7 @@ import { Search, Trash } from "lingee-icon";
 | 文本-标题/正文 | `var(--lg-g-fg-color-black-strong)` | `rgba(0, 0, 0, 0.82)` |
 | 文本-次要 | `var(--lg-g-fg-color-black-muted)` | `rgba(0, 0, 0, 0.64)` |
 | 文本-辅助说明 | `var(--lg-g-fg-color-black-default)` | `rgba(0, 0, 0, 0.46)` |
-| 文本-禁用/占位 | `var(--lg-g-fg-color-black-aint)` | `rgba(0, 0, 0, 0.28)` |
+| 文本-禁用/占位 | `var(--lg-g-fg-color-black-faint)` | `rgba(0, 0, 0, 0.28)` |
 | 文本-品牌色 | `var(--lg-g-fg-color-primary-default)` | `#495DFF` |
 | 文本-危险 | `var(--lg-g-fg-color-danger-default)` | `#F12234` |
 | 文本-白色 | `var(--lg-g-fg-color-white-heavy)` | `#FFFFFF` |
@@ -175,23 +176,33 @@ import { Search, Trash } from "lingee-icon";
 
 暗色模式给 `<html>` 加 `data-theme="dark"` 即自动切换，无需额外处理。
 
-### 命名异常的 Token
+### 已废弃的错拼 Token
 
-以下 Token 名在设计源文件里拼错了，但已被组件库使用**不能改**。按正确拼写写出来的变量不存在，
-CSS 不报错、颜色直接丢失，属于极难排查的静默失效：
+以下 Token 早期从设计源文件带入了拼写错误，现已提供正确拼写。错拼名作为兼容别名保留、与正确名同值，
+但**会在后续版本移除**。改动存量代码时顺手换成正确名：
 
-- `var(--lg-g-fg-color-indigo-defauit)` ← 照抄，不要写成 `--lg-g-fg-color-indigo-default`
-- `var(--lg-g-fg-color-lime-defauit)` ← 照抄，不要写成 `--lg-g-fg-color-lime-default`
-- `var(--lg-g-fg-color-violet-defauit)` ← 照抄，不要写成 `--lg-g-fg-color-violet-default`
-- `var(--lg-g-bg-color-emeraid-translucent-soft)` ← 照抄，不要写成 `--lg-g-bg-color-emerald-translucent-soft`
-- `var(--lg-g-fg-color-black-aint)` ← 片段 `aint` 命名不规范，照抄即可
+- `var(--lg-g-fg-color-black-faint)` ← 用这个，不要写 `--lg-g-fg-color-black-aint`
+- `var(--lg-g-fg-color-indigo-default)` ← 用这个，不要写 `--lg-g-fg-color-indigo-defauit`
+- `var(--lg-g-fg-color-lime-default)` ← 用这个，不要写 `--lg-g-fg-color-lime-defauit`
+- `var(--lg-g-fg-color-violet-default)` ← 用这个，不要写 `--lg-g-fg-color-violet-defauit`
+- `var(--lg-g-bg-color-emerald-translucent-soft)` ← 用这个，不要写 `--lg-g-bg-color-emeraid-translucent-soft`
+
+在旧代码里看到错拼名不要照抄延用，也不要把两者当成不同的 Token。
+
+### 硬编码色值的允许场景
+
+语义层覆盖不到时可以写硬编码，但只限这两种情况：
+
+- **Token 表里查不到所需颜色** —— 写硬编码并加注释标明来源（如设计稿标注值），同时告知用户缺口
+- **任何主题下都不变的装饰性颜色** —— 如品牌插画、固定配色的图表系列色
+
+其余场景一律用语义 Token。**注意**：查不到 Token 时可以硬编码，但**不能自行新增 `--lg-g-*` 变量、也不能退回 primitives**。
 
 ### 拿设计稿色值找 Token
 
 设计稿给的是 hex 时，到 `references/tokens.md` 搜该 hex，表格含亮/暗两列最终色值，可直接反查。
-**搜不到不等于可以硬编码** —— 应向用户说明缺口并等设计确认，不要自行新增变量、也不要退回 primitives。
 
-全量 156 个语义 Token 见 `references/tokens.md`。
+全量 191 个语义 Token 见 `references/tokens.md`。
 
 ## 查阅详细 API
 

package/skill/VERSION.json

@@ -1,7 +1,7 @@
 {
-  "lingeeUi": "0.0.8",
+  "lingeeUi": "0.0.10",
   "lingeeIcon": "1.0.16",
-  "componentCount": 37,
-  "iconCount": 967,
-  "sourceHash": "d9af1a1faa2b5317"
+  "componentCount": 39,
+  "iconCount": 968,
+  "sourceHash": "8acc37347347b8a2"
 }

package/skill/references/components/carousel.md

@@ -0,0 +1,93 @@
+# Carousel 轮播容器
+
+水平轮播容器，用于在一屏内循环展示一组内容，支持自动播放、拖拽切换与圆点指示器。
+
+- 导入：`import { Carousel, CarouselItem } from "lingee-ui";`
+- 可用类型：`CarouselProps`, `CarouselItemProps`, `CarouselApi`, `CarouselDotsPlacement`
+
+## 最小示例
+
+```tsx
+import { Carousel } from "lingee-ui";
+
+const slides = ["Slide 1", "Slide 2", "Slide 3"];
+
+export default function BasicDemo() {
+  return (
+    <Carousel autoplay loop style={{ borderRadius: 24, overflow: "hidden" }}>
+      {slides.map((label) => (
+        <Carousel.Item key={label}>
+          <div
+            style={{
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              height: 200,
+              background: "var(--lg-g-bg-color-primary-translucent-soft)",
+              color: "var(--lg-g-fg-color-primary-default)",
+              fontSize: 32,
+              fontWeight: 600,
+            }}
+          >
+            {label}
+          </div>
+        </Carousel.Item>
+      ))}
+    </Carousel>
+  );
+}
+```
+
+## API
+
+### Carousel
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `children` | 轮播项，需为 `Carousel.Item` | `ReactNode` | - |
+| `loop` | 是否循环轮播 | `boolean` | `true` |
+| `autoplay` | 是否开启自动轮播 | `boolean` | `false` |
+| `autoplayDelay` | 自动轮播间隔（ms），建议 3000 ~ 6000 | `number` | `4000` |
+| `stopOnMouseEnter` | 鼠标移入时暂停，移出恢复 | `boolean` | `true` |
+| `stopOnInteraction` | 手动交互后彻底停止自动轮播 | `boolean` | `false` |
+| `draggable` | 是否允许拖拽 / 滑动切换 | `boolean` | `true` |
+| `slidesPerView` | 每屏展示的轮播项数量 | `number` | `1` |
+| `gap` | 轮播项之间的间距（px） | `number` | `0` |
+| `defaultIndex` | 初始选中序号（0 开始） | `number` | `0` |
+| `dots` | 是否展示圆点指示器 | `boolean` | `true` |
+| `dotsPlacement` | 指示器位置 | `"inside" \| "outside"` | `"inside"` |
+| `dotsGlassy` | 指示器是否使用半透明毛玻璃胶囊底 | `boolean` | `false` |
+| `arrows` | 是否展示左右箭头 | `boolean` | `false` |
+| `onChange` | 选中项变化回调 | `(index: number) => void` | - |
+| `apiRef` | 获取轮播实例 | `Ref<CarouselApi>` | - |
+| `className` | 自定义类名 | `string` | - |
+| `style` | 自定义样式 | `CSSProperties` | - |
+
+### Carousel.Item
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `children` | 轮播项内容 | `ReactNode` | - |
+| `className` | 自定义类名 | `string` | - |
+| `style` | 自定义样式 | `CSSProperties` | - |
+
+### CarouselApi
+
+| 方法 | 说明 | 类型 |
+|------|------|------|
+| `scrollTo` | 跳转到指定序号，`jump` 为 `true` 时不播放过渡 | `(index: number, jump?: boolean) => void` |
+| `scrollPrev` | 上一张 | `() => void` |
+| `scrollNext` | 下一张 | `() => void` |
+| `canScrollPrev` | 是否可向前翻页（`loop` 下恒为 `true`） | `() => boolean` |
+| `canScrollNext` | 是否可向后翻页（`loop` 下恒为 `true`） | `() => boolean` |
+| `selectedIndex` | 当前选中序号 | `() => number` |
+| `count` | 总页数 | `() => number` |
+| `play` | 启动自动轮播 | `() => void` |
+| `stop` | 暂停自动轮播 | `() => void` |
+| `reInit` | 重新初始化 | `() => void` |
+
+## 注意事项
+
+- 圆角需设置在 `Carousel` 根节点上，内部 viewport 通过 `border-radius: inherit` 继承裁剪
+- `autoplayDelay` 变化不会自动应用到已挂载的实例，如需动态切换请配合 `key` 强制重挂载
+- 内容色彩复杂导致圆点对比度不足时，开启 `dotsGlassy` 增加胶囊底

package/skill/references/components/dropdown.md

@@ -2,8 +2,8 @@
 
 向下弹出的操作菜单列表，支持图标、分组、危险操作、子菜单等。
 
-- 导入：`import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownLabel, DropdownSeparator, DropdownGroup, DropdownSub, DropdownSubTrigger, DropdownSubContent, DropdownButton } from "lingee-ui";`
-- 可用类型：`DropdownProps`, `DropdownTriggerProps`, `DropdownContentProps`, `DropdownItemProps`, `DropdownCheckboxItemProps`, `DropdownRadioGroupProps`, `DropdownRadioItemProps`, `DropdownLabelProps`, `DropdownSeparatorProps`, `DropdownGroupProps`, `DropdownSubProps`, `DropdownSubTriggerProps`, `DropdownSubContentProps`, `DropdownItemData`, `DropdownMenuItemData`, `DropdownSeparatorData`, `DropdownLabelData`, `DropdownButtonProps`
+- 导入：`import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownLabel, DropdownSeparator, DropdownGroup, DropdownStatus, DropdownSub, DropdownSubTrigger, DropdownSubContent, DropdownButton } from "lingee-ui";`
+- 可用类型：`DropdownEllipsisTooltip`, `DropdownProps`, `DropdownTriggerProps`, `DropdownContentProps`, `DropdownItemProps`, `DropdownCheckboxItemProps`, `DropdownRadioGroupProps`, `DropdownRadioItemProps`, `DropdownLabelProps`, `DropdownSeparatorProps`, `DropdownGroupProps`, `DropdownStatusProps`, `DropdownStatusType`, `DropdownStatusText`, `DropdownSubProps`, `DropdownSubTriggerProps`, `DropdownSubContentProps`, `DropdownItemData`, `DropdownMenuItemData`, `DropdownSeparatorData`, `DropdownLabelData`, `DropdownButtonProps`
 
 ## 最小示例
 
@@ -38,8 +38,62 @@ export default function BasicDemo() {
 | `modal` | 是否为模态弹出 | `boolean` | `true` |
 | `disabled` | 是否禁用 | `boolean` | `false` |
 | `selectedKeys` | 选中项 key 数组（显示勾选） | `string[]` | - |
+| `loading` | 加载中，面板显示加载占位 | `boolean` | `false` |
+| `loadError` | 加载失败，面板显示失败占位（优先级低于 `loading`） | `boolean` | `false` |
+| `onRetry` | 失败占位的重试回调，传入后占位可点击 | `() => void` | - |
+| `statusText` | 覆盖三态文案，未传的键走语言包 | `DropdownStatusText` | - |
+| `loadingContent` | 自定义加载中内容 | `ReactNode` | - |
+| `errorContent` | 自定义失败内容 | `ReactNode` | - |
+| `emptyContent` | 自定义空态内容 | `ReactNode` | - |
+| `dropdownRender` | 包裹菜单内容 | `(menu: ReactNode) => ReactNode` | - |
+| `header` | 固定头部内容 | `ReactNode` | - |
+| `footer` | 固定底部内容 | `ReactNode` | - |
 | `children` | 触发器元素 | `ReactNode` | - |
 
+### DropdownStatus
+
+面板内三态占位。`items` 模式下由 Dropdown 自动渲染，Compound Component 模式需手动使用。
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `status` | 占位状态 | `"loading" \| "empty" \| "error"` | - |
+| `description` | 覆盖该状态的默认文案 | `ReactNode` | 取自语言包 |
+| `onRetry` | 重试回调，仅 `status="error"` 生效 | `() => void` | - |
+| `className` | 额外类名 | `string` | - |
+
+### DropdownSubTrigger
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `icon` | 前缀图标 | `ReactNode` | - |
+| `disabled` | 是否禁用 | `boolean` | `false` |
+| `onMouseEnter` | 鼠标进入回调，在内部展开子菜单后执行，可用于懒加载数据 | `MouseEventHandler` | - |
+| `ellipsisTooltip` | 文本溢出时悬浮显示完整内容，见 [长文本溢出提示](#长文本溢出提示) | `boolean \| ReactNode` | - |
+| `children` | 触发项内容 | `ReactNode` | - |
+
+### DropdownSubContent
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `side` | 弹出方向 | `"top" \| "bottom" \| "left" \| "right"` | `"right"` |
+| `align` | 对齐方式 | `"start" \| "center" \| "end"` | `"start"` |
+| `sideOffset` | 侧向偏移 | `number` | `8` |
+| `style.maxHeight` | 覆盖面板高度上限 | `number \| string` | `346` |
+| `children` | 子菜单内容 | `ReactNode` | - |
+
+子菜单与主面板同口径限高：默认上限 346px（10 个菜单项），并始终与视口可用空间取较小值，超出部分由内置 ScrollArea 滚动。选项数量不受控的场景（如租户列表）无需额外处理。
+
+承载设计高度更大的自定义面板时才需抬高上限，传 `style={{ maxHeight: ... }}` 或在类名上改 `--lg-dropdown-sub-max-height`：
+
+```less
+.myCustomSubPanel {
+  // 写面板实际需要的高度，不要写 100vh
+  --lg-dropdown-sub-max-height: 420px;
+}
+```
+
+给一个具体像素值而非 `100vh`：视口兜底依赖 Radix 注入的 `--radix-popover-content-available-height`，该变量在未测量完或降级路径下为空，此时若上限也是 `100vh`，`min()` 两边同值，兜底就失效了。
+
 ### DropdownContent
 
 | 属性 | 说明 | 类型 | 默认值 |
@@ -63,8 +117,33 @@ export default function BasicDemo() {
 | `icon` | 前缀图标 | `ReactNode` | - |
 | `description` | 副标题描述（显示在主文本下方） | `ReactNode` | - |
 | `selected` | 是否选中（显示勾选） | `boolean` | `false` |
+| `ellipsisTooltip` | 文本溢出时悬浮显示完整内容，详见下方章节 | `boolean \| ReactNode` | - |
 | `children` | 菜单项内容 | `ReactNode` | - |
 
+### 长文本溢出提示
+
+面板宽度默认随内容撑开，长文案会把浮层顶出屏幕。给菜单项传 `ellipsisTooltip` 后文本带最大宽度（240px）并单行截断，**仅在真正被截断时**悬浮显示完整内容 —— 未截断不弹，不会出现重复可见文字的干扰提示。
+
+```tsx
+{/* true：取 children 作为提示内容 */}
+<DropdownItem ellipsisTooltip>{tenantName}</DropdownItem>
+
+{/* children 是 JSX 时显式传纯文本，否则整块 JSX 会被塞进浮层 */}
+<DropdownItem ellipsisTooltip={file.name}>
+  <span>{file.name}</span><Tag>new</Tag>
+</DropdownItem>
+```
+
+`DropdownItem` / `DropdownRadioItem` / `DropdownCheckboxItem` / `DropdownSubTrigger` 均支持，`items` 快捷模式在数据项上同名传入即可。
+
+不传该属性时行为与此前完全一致（不限宽、不打点、不弹提示），故存量菜单无需改动。限宽可通过 `--lg-dropdown-label-max-width` 调整：
+
+```less
+.my-menu {
+  --lg-dropdown-label-max-width: 320px;
+}
+```
+
 ## DropdownButton 触发器按钮
 
 统一的下拉触发器按钮组件，提供两种视觉态：

package/skill/references/components/ellipsis-tooltip.md

@@ -0,0 +1,44 @@
+# EllipsisTooltip 省略提示
+
+单行省略文本，仅在真正被截断时才悬停显示完整内容。
+
+- 导入：`import { EllipsisTooltip } from "lingee-ui";`
+- 可用类型：`EllipsisTooltipProps`
+
+## 最小示例
+
+```tsx
+import { EllipsisTooltip } from "lingee-ui";
+
+const LONG_TEXT =
+  "A rather long single-line text that gets clipped and reveals its full content on hover";
+
+export default function BasicDemo() {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12, width: 240 }}>
+      {/* Clipped: hover reveals the full text */}
+      <EllipsisTooltip content={LONG_TEXT}>{LONG_TEXT}</EllipsisTooltip>
+
+      {/* Not clipped: no tooltip, so it never repeats visible content */}
+      <EllipsisTooltip content="Short text">Short text</EllipsisTooltip>
+    </div>
+  );
+}
+```
+
+## API
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `content` | 提示内容，为空时不弹出 | `ReactNode` | - |
+| `children` | 文本内容 | `ReactNode` | - |
+| `as` | 容器标签 | `"span" \| "div"` | `"span"` |
+| `ellipsis` | 是否自带单行省略样式 | `boolean` | `true` |
+| `threshold` | 触发阈值（0~1），文本宽度超过 `容器宽度 × threshold` 时弹出 | `number` | `1` |
+| `maxLength` | 提示内容最大字符数，超出截断 | `number` | `2000` |
+| `anchorClassName` | 祖先 className，浮层最大宽度对齐该祖先 | `string` | - |
+| `getPopupContainer` | 浮层挂载容器，接收触发节点 | `(node: HTMLElement) => HTMLElement` | - |
+| `placement` | 弹出方向 | `TooltipPlacement` | `"top"` |
+| `maxWidth` | 浮层最大宽度（px），`anchorClassName` 命中时以后者为准 | `number` | `280` |
+
+其余属性透传给 `Tooltip`（`delayDuration`、`sideOffset`、`arrow` 等）。

package/skill/references/components/empty.md

@@ -34,9 +34,10 @@ export default function BasicDemo() {
 | `status` | 状态，决定默认图标与无障碍语义 | `"loading" \| "empty" \| "error"` | - |
 | `description` | 描述文案 | `ReactNode` | - |
 | `icon` | 覆盖默认图标；传 `null` 不渲染图标 | `ReactNode \| null` | 按 `status` 取 |
-| `variant` | 布局：`block` 区块级 / `inline` 行内轻量 | `"block" \| "inline"` | `"block"` |
+| `size` | 尺寸，语义同 `Empty`，透传给内部 `Empty` | `"sm" \| "md" \| "lg"` | `"sm"` |
+| `variant` | 留白密度：`block` 区块级 / `inline` 行内轻量 | `"block" \| "inline"` | `"block"` |
 | `spacing` | 留白档位。`loose` 为顶部大留白（列表级空态） | `"none" \| "normal" \| "loose"` | `"normal"` |
-| `onRetry` | 重试回调。仅 `status="error"` 生效，传入后整体可点击 | `() => void` | - |
+| `onRetry` | 重试回调。仅 `status="error"` 生效，传入后整体可点击，并自动追加主题色「重试」 | `() => void` | - |
 | `className` | 自定义类名 | `string` | - |
 | `style` | 自定义内联样式 | `CSSProperties` | - |
 

package/skill/references/components/select.md

@@ -46,6 +46,7 @@ export default function BasicDemo() {
 | `allowClear` | 是否可清空 | `boolean` | `false` |
 | `loading` | 是否加载中 | `boolean` | `false` |
 | `loadError` | 是否加载失败 | `boolean` | `false` |
+| `onRetry` | 加载失败后的重试回调。传入后失败缺省态可点击并追加「重试」 | `() => void` | - |
 | `size` | 尺寸 | `"sm" \| "md" \| "lg"` | `"md"` |
 | `suffixIcon` | 后缀图标 | `ReactNode` | - |
 | `maxTagCount` | 多选模式最多显示 Tag 数 | `number` | - |

package/skill/references/components/sidebar.md

@@ -2,8 +2,8 @@
 
 侧边栏复合组件，提供根容器、页签、导航项、分组、列表项、占位项与底栏，通过 Sidebar.xxx 组合使用。
 
-- 导入：`import { Sidebar, SidebarRoot, SidebarHeader, SidebarTabBar, SidebarNavItem, SidebarCollapsibleNavItem, SidebarGroupHeader, SidebarListItem, SidebarCollapsibleListItem, SidebarFooter, SidebarFooterMenuStaticRow, SidebarFooterBadge, SidebarUsageBar, SidebarUsagePanel, SidebarUsagePanelSection } from "lingee-ui";`
-- 可用类型：`SidebarRootProps`, `SidebarHeaderProps`, `SidebarTabBarProps`, `SidebarTabItem`, `SidebarNavItemProps`, `SidebarCollapsibleNavItemProps`, `SidebarCollapsibleNavItemChild`, `SidebarGroupHeaderProps`, `SidebarListItemProps`, `SidebarIndicatorType`, `SidebarCollapsibleListItemProps`, `SidebarCaretPlacement`, `SidebarFooterProps`, `SidebarFooterMenuStaticRowProps`, `SidebarFooterBadgeProps`, `SidebarUsageBarProps`, `SidebarUsageTone`, `SidebarUsagePanelProps`, `SidebarUsagePanelSectionProps`
+- 导入：`import { Sidebar, SidebarRoot, SidebarHeader, SidebarTabBar, SidebarNavItem, SidebarCollapsibleNavItem, SidebarGroupHeader, SidebarListItem, SidebarCollapsibleListItem, SidebarFooter, SidebarFooterUser, SidebarFooterMenuStaticRow, SidebarFooterBadge, SidebarUsageBar, SidebarUsagePanel, SidebarUsagePanelSection, SidebarFeedbackModal, SidebarFeedbackSubmitPanel, SidebarFeedbackField, SidebarFeedbackFileWall, SidebarFeedbackHistoryPanel, SidebarFeedbackHistoryItem, SidebarFeedbackDetail, SidebarFeedbackAttachmentRow, SidebarFeedbackSimilarItem, SidebarAuthImage, formatFileSize } from "lingee-ui";`
+- 可用类型：`FeedbackAttachment`, `FeedbackStatus`, `FeedbackHistoryItem`, `FeedbackReply`, `FeedbackSimilarItem`, `FeedbackHistoryDetail`, `FeedbackTabKey`, `FeedbackFileWallItem`, `SidebarFeedbackModalProps`, `SidebarFeedbackSubmitPanelProps`, `SidebarFeedbackFieldProps`, `SidebarFeedbackFileWallProps`, `SidebarFeedbackHistoryPanelProps`, `SidebarFeedbackHistoryItemProps`, `SidebarFeedbackDetailProps`, `SidebarFeedbackAttachmentRowProps`, `SidebarFeedbackSimilarItemProps`, `SidebarAuthImageProps`, `SidebarRootProps`, `SidebarHeaderProps`, `SidebarTabBarProps`, `SidebarTabItem`, `SidebarNavItemProps`, `SidebarCollapsibleNavItemProps`, `SidebarCollapsibleNavItemChild`, `SidebarGroupHeaderProps`, `SidebarListItemProps`, `SidebarIndicatorType`, `SidebarCollapsibleListItemProps`, `SidebarCaretPlacement`, `SidebarFooterProps`, `SidebarFooterUserProps`, `SidebarFooterMenuStaticRowProps`, `SidebarFooterBadgeProps`, `SidebarUsageBarProps`, `SidebarUsageTone`, `SidebarUsagePanelProps`, `SidebarUsagePanelSectionProps`
 
 ## 最小示例
 
@@ -122,7 +122,7 @@ export default function BasicDemo() {
 | `onToggle` | 切换回调 | `() => void` | - |
 | `actions` | 右侧操作区插槽 | `ReactNode` | - |
 
-折叠箭头与操作区悬停显现，展开态箭头常显。
+折叠箭头与操作区均仅悬停显现，展开态也不常显。
 
 ### Sidebar.ListItem
 
@@ -152,14 +152,24 @@ export default function BasicDemo() {
 
 ### Sidebar.Footer
 
+继承 `Sidebar.FooterUser` 的全部属性（不传 `children` 时透传给内建用户区），另有：
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| `actions` | 右侧动作区插槽 | `ReactNode` | - |
+| `children` | 自定义左侧内容，传入时忽略 `avatar`/`name` 等 | `ReactNode` | - |
+
+### Sidebar.FooterUser
+
 | 属性 | 说明 | 类型 | 默认值 |
 |------|------|------|--------|
 | `avatar` | 头像插槽 | `ReactNode` | - |
 | `name` | 名称，为空时不渲染身份区 | `ReactNode` | - |
 | `nameSuffix` | 名称后插槽（套餐标签等） | `ReactNode` | - |
 | `menuOpen` | 菜单展开态，驱动触发区高亮与箭头旋转 | `boolean` | `false` |
+| `showCaret` | 是否显示展开箭头 | `boolean` | `false` |
+| `nameTooltip` | 姓名超长时 hover 出全称提示 | `boolean` | `true` |
 | `onTriggerClick` | 点击触发区，回传 `DOMRect` 供手动定位浮层 | `(rect: DOMRect) => void` | - |
-| `actions` | 右侧动作区插槽 | `ReactNode` | - |
 
 ### Sidebar.FooterMenuStaticRow