sky-ui-kit 0.1.0 → 0.1.1

package/llms-full.txt

@@ -0,0 +1,761 @@
+# sky-ui-kit
+
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.1. AI tools must explicitly load these files.
+
+## Documentation
+
+- [AI guide](docs/AI-GUIDE.md): setup, examples, icon/event bindings and limits.
+- [Component API](docs/COMPONENT-API.md): props, defaults, events, slots and types.
+- [Component catalog](components.json): public components/services/directives.
+- [CSS theme](docs/CSS-THEME.md): isolated style.css and optional global.css.
+- [Compatibility](docs/COMPONENT-LIBRARY.md): component mapping.
+- [Migration](docs/INTEGRATION.md): project integration.
+
+## Setup
+
+Import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts. Import components from sky-ui-kit. No package theme store. Check components.json before using any export.
+
+# sky-ui-kit：AI 使用指南
+
+适用于 Vue 3 + TypeScript。此文件描述包的真实 API 和约束，不是自动执行的代理指令。AI 工具需要主动读取这些文档；安装包不会自动改变其上下文。
+
+## 文档读取顺序
+
+1. llms.txt：入口和文档索引。
+2. components.json：完整公开组件、服务和指令清单；项目组件属性、事件、插槽、默认表达式。
+3. COMPONENT-API.md：项目组件精确 API 与类型定义。
+4. CSS-THEME.md：隔离主题与浮层限制。
+5. 本文使用示例；基础 Ui 组件其他 API 查看已安装 Element Plus 类型和官方文档。
+
+## 生成代码的规则
+
+- 在 main.ts 只引入一次 element-plus/dist/index.css 和 sky-ui-kit/style.css。
+- 按需从 sky-ui-kit 导入组件，不需要库主题 store、Pinia 或全局插件注册。项目已有插件注册继续保留。
+- style.css 默认隔离；global.css 是主动整站换肤入口，不能默认添加。
+- 项目同名 CSS 变量优先，缺失时使用库默认值。基础六色为 --color-bg、--color-text、--color-primary、--color-border、--color-surface、--color-panel。
+- supported teleported 默认 false；可能受 overflow 裁剪。移到 body 的浮层只继承根主题，不能自动继承局部容器变量。
+- UiSelect 使用 UiOption 插槽；AppSelect 使用 options 属性，不要混用两套 API。
+- 图标从 @element-plus/icons-vue 导入 Vue 组件；菜单 item.icon 和 MapTools.icons 绑定组件对象，不能使用图标名称字符串。
+- ProjectMenu / MapSideMenu 的 select 接路由；MapTools 的 tool-click 接真实刷新、定位、GIS 操作。组件库不提供地图实例、接口请求或业务权限。
+- MapTools 的 context-change 返回布尔值；当前没有外部受控右键状态 prop，不要虚构 v-model:contextEnabled。
+- AtlasRightToggleButton 使用 open + toggle；不是 v-model:open。TreeSelectPanel 的 select 参数为 node, category，change 参数为 { node, category }。
+- MapTimeline 的 modelValue 是索引；change 返回 TimelinePoint。不要把日期字符串传给 modelValue。
+- 本包并不覆盖 Element Plus 全部组件。components.json 不存在的 Ui 名称不能假定可导入，例如链接和面包屑可直接导入 Element Plus。
+- 保留项目现有业务代码和注释，先局部迁移核对，不能用组件示例替换整个业务页面。
+
+## 默认样式
+
+明亮六色：#ffffff / #1f2937 / #1677ff / #dbe3ef99 / #ffffffd9 / #ffffff。
+暗色六色：#08111f / #e6edf7 / #4da3ff / #39506f99 / #101b2dee / #0c1525。
+控件高度 small/medium/large：28/32/36px；字号正文14px；圆角4/8/12px；默认缩放1。
+默认暗色通过根节点 theme-dark 类启用；已定义的项目主题变量仍优先。
+
+## 实例方法与包装边界
+
+基础组件包装转发 attrs、事件、slots 与 ref 方法，增加 display:contents 容器。依赖直属子元素的布局 CSS 需要核对。ConfigProvider、Option、TableColumn、TabPane 保留原实现，以所属控件作为主题范围。命令式 UiMessage / UiMessageBox / UiNotification 自动合并专用浮层类。
+
+## 主题与业务示例
+
+以下完整代码由预览站示例生成；公共入口完成后，各页面不重复引入 CSS。
+
+<!-- GENERATED EXAMPLES -->
+
+### componentsExample
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  AppSelect, TreeSelectPanel, TimeRangeQuickSelect, MapTimeline
+} from 'sky-ui-kit'
+
+const station = ref('hankou')
+const region = ref<string | number | null>(null)
+const range = ref('24h')
+const frame = ref(6)
+const playing = ref(false)
+const options = [{ label: '汉口站', value: 'hankou' }, { label: '宜昌站', value: 'yichang' }]
+const categories = [{ type: 'region', label: '行政区', children: [{ id: 'hubei', label: '湖北省' }] }]
+const ranges = [{ key: '1h', label: '近1小时' }, { key: '24h', label: '近24小时' }]
+</script>
+
+<template>
+  <AppSelect v-model="station" :options="options" filterable clearable />
+  <TreeSelectPanel v-model="region" :categories="categories" close-on-select />
+  <TimeRangeQuickSelect v-model="range" :options="ranges" />
+  <MapTimeline v-model="frame" v-model:playing="playing"
+    start-time="2026-10-08T08:00:00+08:00" time-zone="Asia/Shanghai"
+    :past-steps="6" :future-steps="12" />
+</template>
+
+<!-- 这些组件保留 v-model 交互；可通过 @change 接收值变化。 -->
+```
+
+### mapToolsExample
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Grid, Operation, RefreshRight, Aim, Setting, DataAnalysis, Mouse } from '@element-plus/icons-vue'
+import { MapTools, UiCheckboxGroup, UiCheckbox, UiInput, UiButton } from 'sky-ui-kit'
+
+const activeTool = ref('layers')
+const contextEnabled = ref(false)
+const message = ref('')
+const layers = ref(['行政区划', '水系'])
+// icons 的键对应工具 key；可只传需要替换的图标。
+const icons = {
+  layers: Grid, module: Operation, refresh: RefreshRight, locate: Aim,
+  settings: Setting, analysis: DataAnalysis, context: Mouse
+}
+function onToolClick(key: string) {
+  message.value = '触发工具：' + key
+  if (key === 'refresh') {
+    // 在这里调用你的地图数据刷新函数。
+  } else if (key === 'locate') {
+    // 在这里调用 map.flyTo(...) 等地图定位 API。
+  }
+}
+function onContextChange(enabled: boolean) {
+  contextEnabled.value = enabled
+  // 在这里启用或关闭地图右键菜单。
+}
+</script>
+
+<template>
+  <MapTools v-model:active="activeTool" :icons="icons"
+    @tool-click="onToolClick" @context-change="onContextChange" />
+  <p>{{ message }} · 右键菜单：{{ contextEnabled ? '开启' : '关闭' }}</p>
+  <section v-if="activeTool">
+    <h3>{{ activeTool }} 工具面板</h3>
+    <UiCheckboxGroup v-if="activeTool === 'layers'" v-model="layers">
+      <UiCheckbox label="行政区划" />
+      <UiCheckbox label="水系" />
+    </UiCheckboxGroup>
+    <UiInput v-else placeholder="工具参数" />
+    <UiButton @click="activeTool = ''">关闭面板</UiButton>
+  </section>
+</template>
+
+<!-- 同一个面板工具再次点击会关闭；刷新与定位只触发事件，不改变面板。 -->
+<!-- MapTools 内部图标绑定：<component :is="icons[tool.key] || tool.icon" /> -->
+```
+
+### menuExample
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { House, DataAnalysis, Setting, Pouring, List } from '@element-plus/icons-vue'
+import { ProjectMenu, MapSideMenu } from 'sky-ui-kit'
+
+const active = ref('overview')
+const mapActive = ref('rain')
+const compact = ref(false)
+const message = ref('')
+// icon 字段绑定导入的 Vue 图标组件，不是图标名称字符串。
+const items = [
+  { key: 'overview', label: '概览', icon: House },
+  { key: 'data', label: '数据管理', icon: DataAnalysis },
+  { key: 'settings', label: '设置', icon: Setting, disabled: true }
+]
+const groups = [{ label: '工作空间', items }]
+const mapItems = [
+  { key: 'rain', label: '降水', icon: Pouring },
+  { key: 'water', label: '水库水位', icon: List }
+]
+function onSelect(item: { key: string; label: string }) {
+  message.value = '选中了：' + item.label
+  // 在这里接入 router.push(...) 或你的数据加载函数。
+}
+</script>
+
+<template>
+  <ProjectMenu v-model:active="active" :items="items" @select="onSelect" />
+  <ProjectMenu direction="vertical" v-model:active="active"
+    :groups="groups" @select="onSelect" />
+  <MapSideMenu title="实况(测站)" :items="mapItems"
+    v-model:active="mapActive" v-model:compact="compact" @select="onSelect" />
+  <p>{{ message }}</p>
+</template>
+
+<!-- 纵向菜单在每个菜单项的 icon 位置渲染图标；横向菜单为文字样式。 -->
+<!-- MapSideMenu 的搜索、分组收起和图标模式切换由组件内部完成。 -->
+```
+
+# Component API reference
+
+Generated from Vue/TypeScript source; defaultExpression is source text, not evaluated JSON. Types refer to declarations below. Unlisted props must not be invented. For Element Plus components use upstream documentation and shipped typings.
+
+## AppSelect
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| modelValue | AppSelectValue | false | undefined |
+| options | AppSelectOption[] | false | () => [] |
+| emptyLabel | string | false | '暂无可选项' |
+| popperClass | string | false | '' |
+| teleported | boolean | false | false |
+
+### Events
+
+- `update:modelValue` — `[value: AppSelectValue]`
+- `change` — `[value: AppSelectValue]`
+
+Slots: No declared content slots.
+
+```ts
+export type AppSelectValue = string | number | boolean | Record<string, unknown> | AppSelectValue[] | null | undefined
+export type AppSelectOption = {
+  label: string
+  value: AppSelectValue
+  disabled?: boolean
+} | string | number
+```
+
+## MapTimeline
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| modelValue | number | false | 0 |
+| startTime | TimelineTimeInput | false | () => new Date() |
+| points | TimelinePoint[] | false | () => [] |
+| steps | number | false | 24 |
+| pastSteps | number | false | undefined / no declared default |
+| futureSteps | number | false | undefined / no declared default |
+| interval | number | false | 1 |
+| unit | IntervalUnit | false | 'hour' |
+| playing | boolean | false | false |
+| speed | number | false | 1 |
+| speeds | number[] | false | () => [0.5, 1, 2, 4] |
+| internalPlayback | boolean | false | true |
+| pageSize | number | false | 24 |
+| loop | boolean | false | true |
+| minTime | TimelineTimeInput | false | undefined / no declared default |
+| maxTime | TimelineTimeInput | false | undefined / no declared default |
+| forecastCount | number | false | undefined / no declared default |
+| showScale | boolean | false | true |
+| showCurrentMarker | boolean | false | true |
+| timeZone | string | false | undefined / no declared default |
+
+### Events
+
+- `update:modelValue` — `[value: number]`
+- `update:startTime` — `[value: TimelineTimeInput]`
+- `update:playing` — `[value: boolean]`
+- `update:speed` — `[value: number]`
+- `change` — `[point: TimelinePoint]`
+- `play` — `[]`
+- `pause` — `[]`
+
+Slots: date-select
+
+```ts
+type IntervalUnit = 'minute' | 'hour' | 'day' | 'month' | 'year'
+type TimelineKind = 'observed' | 'forecast'
+type TimelineTimeInput = string | number | Date
+export interface TimelinePoint {
+  index: number
+  offset: number
+  time: Date
+  value: string
+  label: string
+  kind: TimelineKind
+  disabled?: boolean
+}
+```
+
+## TreeSelectPanel
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| modelValue | string &#124; number &#124; null | false | null |
+| categories | TreeSelectCategory[] | false | () => [] |
+| placeholder | string | false | '请选择行政区或流域' |
+| searchPlaceholder | string | false | '搜索名称' |
+| emptyText | string | false | '暂无树数据' |
+| fallbackTypeLabel | string | false | '行政区' |
+| popoverWidth | string &#124; number | false | 'calc(var(--cp-font-1) * 328)' |
+| defaultActiveType | string | false | '' |
+| defaultExpandAll | boolean | false | true |
+| closeOnSelect | boolean | false | false |
+| closeOnMouseLeave | boolean | false | false |
+| dark | boolean | false | false |
+
+### Events
+
+- `update:modelValue` — `[value: string | number | null]`
+- `change` — `[payload: { node: TreeSelectNode, category: TreeSelectCategory }]`
+- `select` — `[node: TreeSelectNode, category: TreeSelectCategory]`
+
+Slots: No declared content slots.
+
+```ts
+export interface TreeSelectNode {
+  id: string | number
+  label: string
+  tag?: string
+  disabled?: boolean
+  children?: TreeSelectNode[]
+  [key: string]: unknown
+}
+export interface TreeSelectCategory {
+  type: string
+  label: string
+  children: TreeSelectNode[]
+}
+```
+
+## TimeRangeQuickSelect
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| modelValue | string | true | undefined / no declared default |
+| options | TimeRangeQuickOption[] | true | undefined / no declared default |
+| ariaLabel | string | false | '时间范围快捷选择' |
+
+### Events
+
+- `update:modelValue` — `[value: string]`
+- `change` — `[option: TimeRangeQuickOption]`
+
+Slots: No declared content slots.
+
+```ts
+export type TimeRangeQuickOption = {
+  key: string
+  label: string
+  amount?: number
+  unit?: 'hour' | 'day'
+}
+```
+
+## ProjectMenu
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| direction | 'horizontal' &#124; 'vertical' | false | 'horizontal' |
+| active | string | false | '' |
+| items | ProjectMenuItem[] | false | () => [] |
+| groups | ProjectMenuGroup[] | false | () => [] |
+
+### Events
+
+- `update:active` — `[key: string]`
+- `select` — `[item: ProjectMenuItem]`
+
+Slots: No declared content slots.
+
+```ts
+export interface ProjectMenuItem { key: string; label: string; disabled?: boolean; icon?: Component }
+export interface ProjectMenuGroup { label: string; items: ProjectMenuItem[] }
+```
+
+## MapSideMenu
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| title | string | false | '实况(测站)' |
+| active | string | false | 'rain' |
+| dark | boolean | false | false |
+| compact | boolean | false | false |
+| items | MapMenuItem[] | false | () => [
+    { key: 'rain', label: '降水', icon: Pouring },
+    { key: 'reservoir-level', label: '水库水位', icon: List },
+    { key: 'reservoir-flow', label: '水库径流', icon: TrendCharts },
+    { key: 'river-level', label: '河道水位', icon: List },
+    { key: 'river-flow', label: '河道径流', icon: TrendCharts },
+    { key: 'temperature', label: '气温', icon: Sunny },
+    { key: 'wind', label: '风速', icon: WindPower }
+  ] |
+
+### Events
+
+- `update:active` — `[key: string]`
+- `update:compact` — `[value: boolean]`
+- `select` — `[item: MapMenuItem]`
+
+Slots: No declared content slots.
+
+```ts
+export interface MapMenuItem { key: string; label: string; icon?: Component }
+```
+
+## MapTools
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| active | string | false | 'layers' |
+| horizontal | boolean | false | false |
+| icons | Record<string, Component> | false | () => ({}) |
+
+### Events
+
+- `update:active` — `[key: string]`
+- `tool-click` — `[key: string]`
+- `context-change` — `[enabled: boolean]`
+
+Slots: No declared content slots.
+
+## AtlasMapTitle
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| title | string | true | undefined / no declared default |
+| subtitle | string | false | '' |
+| rightOpen | boolean | false | false |
+
+### Events
+
+No declared events.
+
+Slots: No declared content slots.
+
+## AtlasRightToggleButton
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| open | boolean | false | false |
+| openTitle | string | false | '展开右侧面板' |
+| closeTitle | string | false | '收起右侧面板' |
+
+### Events
+
+- `toggle` — `[]`
+
+Slots: No declared content slots.
+
+## ProcessDataTable
+
+### Props
+
+| Name | Type | Required | Default expression |
+|---|---|---|---|
+| times | string[] | true | undefined / no declared default |
+| series | { name: string; data: (number &#124; null)[] }[] | true | undefined / no declared default |
+| loading | boolean | false | undefined / no declared default |
+
+### Events
+
+No declared events.
+
+Slots: No declared content slots.
+
+## UiAlert
+
+Original: ElAlert. [API](https://element-plus.org/en-US/component/alert.html). See dist/components/element-plus.d.ts.
+
+## UiBadge
+
+Original: ElBadge. [API](https://element-plus.org/en-US/component/badge.html). See dist/components/element-plus.d.ts.
+
+## UiButton
+
+Original: ElButton. [API](https://element-plus.org/en-US/component/button.html). See dist/components/element-plus.d.ts.
+
+## UiButtonGroup
+
+Original: ElButtonGroup. [API](https://element-plus.org/en-US/component/button-group.html). See dist/components/element-plus.d.ts.
+
+## UiCard
+
+Original: ElCard. [API](https://element-plus.org/en-US/component/card.html). See dist/components/element-plus.d.ts.
+
+## UiCarousel
+
+Original: ElCarousel. [API](https://element-plus.org/en-US/component/carousel.html). See dist/components/element-plus.d.ts.
+
+## UiCarouselItem
+
+Original: ElCarouselItem. [API](https://element-plus.org/en-US/component/carousel-item.html). See dist/components/element-plus.d.ts.
+
+## UiCascader
+
+Original: ElCascader. [API](https://element-plus.org/en-US/component/cascader.html). See dist/components/element-plus.d.ts.
+
+## UiCheckbox
+
+Original: ElCheckbox. [API](https://element-plus.org/en-US/component/checkbox.html). See dist/components/element-plus.d.ts.
+
+## UiCol
+
+Original: ElCol. [API](https://element-plus.org/en-US/component/col.html). See dist/components/element-plus.d.ts.
+
+## UiCollapse
+
+Original: ElCollapse. [API](https://element-plus.org/en-US/component/collapse.html). See dist/components/element-plus.d.ts.
+
+## UiCollapseItem
+
+Original: ElCollapseItem. [API](https://element-plus.org/en-US/component/collapse-item.html). See dist/components/element-plus.d.ts.
+
+## UiColorPicker
+
+Original: ElColorPicker. [API](https://element-plus.org/en-US/component/color-picker.html). See dist/components/element-plus.d.ts.
+
+## UiConfigProvider
+
+Original: ElConfigProvider. [API](https://element-plus.org/en-US/component/config-provider.html). See dist/components/element-plus.d.ts.
+
+## UiDatePicker
+
+Original: ElDatePicker. [API](https://element-plus.org/en-US/component/date-picker.html). See dist/components/element-plus.d.ts.
+
+## UiDescriptions
+
+Original: ElDescriptions. [API](https://element-plus.org/en-US/component/descriptions.html). See dist/components/element-plus.d.ts.
+
+## UiDescriptionsItem
+
+Original: ElDescriptionsItem. [API](https://element-plus.org/en-US/component/descriptions-item.html). See dist/components/element-plus.d.ts.
+
+## UiDialog
+
+Original: ElDialog. [API](https://element-plus.org/en-US/component/dialog.html). See dist/components/element-plus.d.ts.
+
+## UiDrawer
+
+Original: ElDrawer. [API](https://element-plus.org/en-US/component/drawer.html). See dist/components/element-plus.d.ts.
+
+## UiDropdown
+
+Original: ElDropdown. [API](https://element-plus.org/en-US/component/dropdown.html). See dist/components/element-plus.d.ts.
+
+## UiDropdownItem
+
+Original: ElDropdownItem. [API](https://element-plus.org/en-US/component/dropdown-item.html). See dist/components/element-plus.d.ts.
+
+## UiDropdownMenu
+
+Original: ElDropdownMenu. [API](https://element-plus.org/en-US/component/dropdown-menu.html). See dist/components/element-plus.d.ts.
+
+## UiEmpty
+
+Original: ElEmpty. [API](https://element-plus.org/en-US/component/empty.html). See dist/components/element-plus.d.ts.
+
+## UiFooter
+
+Original: ElFooter. [API](https://element-plus.org/en-US/component/footer.html). See dist/components/element-plus.d.ts.
+
+## UiForm
+
+Original: ElForm. [API](https://element-plus.org/en-US/component/form.html). See dist/components/element-plus.d.ts.
+
+## UiFormItem
+
+Original: ElFormItem. [API](https://element-plus.org/en-US/component/form-item.html). See dist/components/element-plus.d.ts.
+
+## UiIcon
+
+Original: ElIcon. [API](https://element-plus.org/en-US/component/icon.html). See dist/components/element-plus.d.ts.
+
+## UiImage
+
+Original: ElImage. [API](https://element-plus.org/en-US/component/image.html). See dist/components/element-plus.d.ts.
+
+## UiInput
+
+Original: ElInput. [API](https://element-plus.org/en-US/component/input.html). See dist/components/element-plus.d.ts.
+
+## UiInputNumber
+
+Original: ElInputNumber. [API](https://element-plus.org/en-US/component/input-number.html). See dist/components/element-plus.d.ts.
+
+## UiMessage
+
+Original: ElMessage. [API](https://element-plus.org/en-US/component/message.html). See dist/components/element-plus.d.ts.
+
+## UiMessageBox
+
+Original: ElMessageBox. [API](https://element-plus.org/en-US/component/message-box.html). See dist/components/element-plus.d.ts.
+
+## UiNotification
+
+Original: ElNotification. [API](https://element-plus.org/en-US/component/notification.html). See dist/components/element-plus.d.ts.
+
+## UiOption
+
+Original: ElOption. [API](https://element-plus.org/en-US/component/option.html). See dist/components/element-plus.d.ts.
+
+## UiPagination
+
+Original: ElPagination. [API](https://element-plus.org/en-US/component/pagination.html). See dist/components/element-plus.d.ts.
+
+## UiPopconfirm
+
+Original: ElPopconfirm. [API](https://element-plus.org/en-US/component/popconfirm.html). See dist/components/element-plus.d.ts.
+
+## UiPopover
+
+Original: ElPopover. [API](https://element-plus.org/en-US/component/popover.html). See dist/components/element-plus.d.ts.
+
+## UiProgress
+
+Original: ElProgress. [API](https://element-plus.org/en-US/component/progress.html). See dist/components/element-plus.d.ts.
+
+## UiRadio
+
+Original: ElRadio. [API](https://element-plus.org/en-US/component/radio.html). See dist/components/element-plus.d.ts.
+
+## UiRadioGroup
+
+Original: ElRadioGroup. [API](https://element-plus.org/en-US/component/radio-group.html). See dist/components/element-plus.d.ts.
+
+## UiRate
+
+Original: ElRate. [API](https://element-plus.org/en-US/component/rate.html). See dist/components/element-plus.d.ts.
+
+## UiRow
+
+Original: ElRow. [API](https://element-plus.org/en-US/component/row.html). See dist/components/element-plus.d.ts.
+
+## UiScrollbar
+
+Original: ElScrollbar. [API](https://element-plus.org/en-US/component/scrollbar.html). See dist/components/element-plus.d.ts.
+
+## UiSelect
+
+Original: ElSelect. [API](https://element-plus.org/en-US/component/select.html). See dist/components/element-plus.d.ts.
+
+## UiSelectV2
+
+Original: ElSelectV2. [API](https://element-plus.org/en-US/component/select-v2.html). See dist/components/element-plus.d.ts.
+
+## UiSlider
+
+Original: ElSlider. [API](https://element-plus.org/en-US/component/slider.html). See dist/components/element-plus.d.ts.
+
+## UiSwitch
+
+Original: ElSwitch. [API](https://element-plus.org/en-US/component/switch.html). See dist/components/element-plus.d.ts.
+
+## UiTabPane
+
+Original: ElTabPane. [API](https://element-plus.org/en-US/component/tab-pane.html). See dist/components/element-plus.d.ts.
+
+## UiTable
+
+Original: ElTable. [API](https://element-plus.org/en-US/component/table.html). See dist/components/element-plus.d.ts.
+
+## UiTableColumn
+
+Original: ElTableColumn. [API](https://element-plus.org/en-US/component/table-column.html). See dist/components/element-plus.d.ts.
+
+## UiTabs
+
+Original: ElTabs. [API](https://element-plus.org/en-US/component/tabs.html). See dist/components/element-plus.d.ts.
+
+## UiTag
+
+Original: ElTag. [API](https://element-plus.org/en-US/component/tag.html). See dist/components/element-plus.d.ts.
+
+## UiTooltip
+
+Original: ElTooltip. [API](https://element-plus.org/en-US/component/tooltip.html). See dist/components/element-plus.d.ts.
+
+## UiTree
+
+Original: ElTree. [API](https://element-plus.org/en-US/component/tree.html). See dist/components/element-plus.d.ts.
+
+## UiTreeSelect
+
+Original: ElTreeSelect. [API](https://element-plus.org/en-US/component/tree-select.html). See dist/components/element-plus.d.ts.
+
+## UiUpload
+
+Original: ElUpload. [API](https://element-plus.org/en-US/component/upload.html). See dist/components/element-plus.d.ts.
+
+## UiCheckboxGroup
+
+Original: ElCheckboxGroup. [API](https://element-plus.org/en-US/component/checkbox-group.html). See dist/components/element-plus.d.ts.
+
+## UiRadioButton
+
+Original: ElRadioButton. [API](https://element-plus.org/en-US/component/radio-button.html). See dist/components/element-plus.d.ts.
+
+## UiDivider
+
+Original: ElDivider. [API](https://element-plus.org/en-US/component/divider.html). See dist/components/element-plus.d.ts.
+
+## vUiLoading
+
+Original: ElLoadingDirective. [API](https://element-plus.org/en-US/component/loading.html). See dist/components/element-plus.d.ts.
+
+
+# CSS 变量主题与样式隔离
+
+库不导出 useThemeStore，也不依赖使用方 Pinia。根入口和 /components 导出相同组件。
+
+## 默认：隔离模式
+
+```ts
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+import { UiButton, UiSelect, AppSelect } from 'sky-ui-kit'
+```
+
+style.css 不向 :root 写入主题或尺寸变量，不包含裸 .el-* 覆盖规则。组件自动创建 userssite-theme 作用域，Element Plus 适配规则只在这个范围内生效。原生 ElButton 等放在库组件作用域之外时保留原来的外观；放在库组件插槽内部时，会继承这个范围的主题，这是预期行为。
+
+库内部使用 --userssite-* 私有变量，以 var(--color-primary, 默认值) 等形式读取项目已有变量，不回写公共变量。项目只定义部分变量时，其余使用库默认值。无需主题 store。
+
+```css
+:root {
+  --color-primary: #1677ff;
+  --color-bg: #ffffff;
+  --color-text: #1f2937;
+  --color-panel: #ffffff;
+}
+```
+
+已有项目全局 CSS 若自行覆盖 --el-* 或 .el-*，其自身仍会影响原生 Element Plus；隔离模式不会撤销项目已有规则。尺寸读取项目 --cp-vfit-scale，未定义时为 1。
+
+## 浮层与兼容边界
+
+- UiSelect、日期选择、Popover 等支持 teleported 的组件默认 false，使浮层保留祖先主题；需要时可以显式设置 true。这样可能受祖先 overflow 裁剪，使用方需按布局选择。
+- 支持 popperClass、modalClass 的组件自动合并 userssite-theme，保留用户类名。弹窗、抽屉移到 body 时仍拥有隔离默认主题。
+- UiMessage、UiMessageBox、UiNotification 以及 vUiLoading 给其浮层加专用类；原生 ElMessage 和 v-loading 不自动套用库主题。
+- 挂到 body 的浮层读取 html / :root 的项目变量。只在局部容器定义的变量不会跨 Teleport 继承；需将共享主题放在根节点，或通过 Element Plus 的 append-to 指定有主题变量的目标容器。消息服务无局部容器主题上下文。
+- ConfigProvider、Option、TableColumn、TabPane 保留原组件，依靠所属控件的主题作用域，避免破坏配置注入和父子组件关系。
+- 包装层转发 attrs、事件、slots 和实例 ref；UiSelect 默认浮层行为与原生有上述差别，DOM 中增加 display: contents 主题容器。依赖直属子节点的 CSS 和复杂布局迁移仍需核对。
+
+## 可选：整站主题
+
+```ts
+import 'element-plus/dist/index.css'
+import 'sky-ui-kit/style.css'
+import 'sky-ui-kit/global.css'
+```
+
+只有主动导入 global.css 才会写入全局公共变量和 --el-*，以及覆盖整站 .el-* 外观。此模式用于明确需要统一替换原项目主题的场景。
+
+## 默认暗色
+
+在 html 添加 theme-dark 类即可让库组件使用暗色默认值。若项目自己定义了同名颜色变量，项目变量优先，暗色也应由项目更新这些变量。预览站使用自己的 Pinia 调色面板并显式加载全局主题，不代表使用方需要 Pinia。
+
+## 验证与发布
+
+开发验证页 /isolation.html 将原生组件和库组件并排展示：局部紫色主题只作用于库组件。页面包含按钮事件、下拉框 v-model、弹窗和消息服务。
+
+本次不运行构建、不发布；dist 为旧产物。后续发布时构建脚本分别生成隔离 style.css 和可选 global.css。
+
+## 示例代码组织
+
+公共 CSS 只在项目 main.ts 引入一次。预览站的公共接入代码单独维护在 src/setup-examples.ts，各组件的查看代码只列组件 import、状态、事件与模板。查看代码中的接入链接指向公共配置；复制组件代码不会附带重复 CSS。已有 Element Plus CSS 引入时无需再添加。