sky-ui-kit 0.1.10 → 0.1.11

package/README.md

@@ -2,7 +2,7 @@
 
 ## AI 接入入口：先选择使用方式
 
-当用户要求安装、引入 sky-ui-kit 时，请先读取当前安装包的 llms.txt 和 [HTML / Vue 接入判断](docs/HTML-INTEGRATION.md)，检查项目及真实 exports。只需外观时使用正式 HTML 样式接口（新版容器 sky-html 内原生控件自动换肤，data-sky-native="off" 局部退出）；需要交互时使用真实 Vue 组件，HTML 项目可局部挂载。需求不明确时先询问，接入后合并项目 AGENTS.md 规则，不能把 npm install 或仅加载 CSS 报告为完整组件接入。
+当用户要求引入 sky-ui-kit 时，先读取当前安装包的 llms.txt 和 [原生 HTML 接入与迁移](docs/HTML-INTEGRATION.md)，检查项目和真实 exports。原生 HTML 路线统一库支持的控件样式，保留原 DOM、事件和表单行为，无需 Vue。仅在用户明确需要真实 Vue 组件时，才选择 Vue 直接接入或局部挂载。目标不明确时询问；接入后合并项目 AGENTS.md 规则，按实际视觉状态和业务行为验收，不能只以安装成功或 CSS 已加载作为完成依据。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -18,10 +18,10 @@ HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。
 
 当前实际使用清单见 [COMPONENT-USAGE.md](docs/COMPONENT-USAGE.md)，逐模块替换、图标 Vite 配置、路由/地图薄适配、主题与验证方案见 [ADAPTATION.md](docs/ADAPTATION.md)。图标页面与 AI 文档共用 src/icon-setup-examples.ts。更新参考项目后在库目录运行 `node scripts/audit-project.mjs "D:\Work\01-项目code\一体化平台\webv1"` 与 `node scripts/scan-component-usage.mjs "D:\Work\01-项目code\一体化平台\webv1"`，再生成 AI 文档；这些脚本只读取原项目。
 
-## 本地运行
+## 库维护者本地运行
 
 ```powershell
-cd D:\sky-ui-kit
+cd <组件库检出目录>
 npm install
 npm run dev
 ```
@@ -69,7 +69,7 @@ ProjectMenu 从原 Header 和 SideMenu 提取独立菜单样式，仅展示横
 
 ## 接入其他项目
 
-无需导入 useThemeStore，也无需安装 Pinia。直接引入 Element Plus CSS 与库 CSS，项目已有的同名变量优先；未定义的变量采用库默认值。详细优先级及暗色规则见 [CSS-THEME.md](docs/CSS-THEME.md)。
+以下为 Vue 组件路线；原生 HTML 使用 [HTML 接入指南](docs/HTML-INTEGRATION.md)，不需要 Element Plus CSS 或 Vue。Vue 路线无需导入 useThemeStore，也无需安装 Pinia，按顺序引入 Element Plus CSS 与库 CSS，项目已有的同名变量优先；未定义的变量采用库默认值。详细优先级及暗色规则见 [CSS-THEME.md](docs/CSS-THEME.md)。
 
 ```ts
 import 'element-plus/dist/index.css'
@@ -87,21 +87,14 @@ npm run build
 npm pack --dry-run
 ```
 
-`site-dist/` 是可部署的预览网站，`dist/` 是 npm 库产物。npm 包仅包含库产物、主题 store 源文件与 README，不包含预览网站及原业务代码。
-
-## 核对完成后发布
-
-当前 `private: true` 用于防止未审核主题发布。包名已确定为 `sky-ui-kit`，尚未核验 npm 名称可用性。发布前确认包名或 npm scope、版本、代码及字体授权、许可证，并将 `private` 删除或改为 false。若使用 scope，保持接入示例与最终包名一致。
-
-```sh
-npm login
-npm run typecheck
-npm pack --dry-run
-npm publish --access public
-```
-
-`prepack` 会自动构建。不要把 npm token 写入此目录。本次仅准备预览及包结构，等待样式核对后再发布。
+`site-dist/` 是可部署的预览网站，`dist/` 是 npm 库产物。npm 包包含 dist 库产物、包内 AI/API/迁移文档、HTML 示例及 README；不包含预览网站、主题 store 运行时或原业务代码。
 
+## 当前发布状态与维护发布流程
+
+当前发布版本为 0.1.11，package.json 未设置 private 限制。HTML 按需样式和数字增强入口从 0.1.10 提供；0.1.11 包含相对链接修复、透明地图覆盖层及旧页面迁移文档和示例。已安装的 0.1.10 需升级后获得修订。
+
+消费项目无需执行库构建或发布操作。维护者仅在明确获得发布授权后，更新版本、运行 npm run docs:ai、类型检查和构建，核对包内文件后再发布。prepack 会生成文档并构建，不应把它当成纯检查命令。早期未发布状态见 [开发历史归档](docs/RELEASE-HISTORY.md)。
+
 ## 样式隔离
 
 默认 style.css 只给库组件作用域设置样式，作用域之外的原生 Element Plus 不受库 CSS 覆盖。主动整站换肤才额外导入 global.css。浮层、局部变量和默认 teleported 差异见 [CSS-THEME.md](docs/CSS-THEME.md)。开发验证页：[样式隔离验证](http://127.0.0.1:5180/isolation.html)。
@@ -113,6 +106,4 @@ npm publish --access public
 包内提供 llms.txt、llms-full.txt、components.json 和 docs/AI-GUIDE.md、docs/COMPONENT-API.md。让 AI 工具读取 node_modules/sky-ui-kit/llms.txt 开始，再按链接读取详细 API。文档不会随 npm install 自动进入 AI 上下文。项目组件 API 根据源码生成，Ui 基础组件关联 Element Plus 官方 API 和类型声明。
 
 
-## 0.1.7 正式安装与样式
-
-通过 npm 安装 sky-ui-kit，main.ts 依次引入 element-plus/dist/index.css 和 sky-ui-kit/style.css，包内已包含默认主题和组件样式，不依赖开发者电脑、原业务项目或远程样式服务。CSS 变量允许运行时主题覆盖。图标资源可从 sky-ui-kit/icons 显式注册，或由应用提供 sprite；SvgIcon 不再自动携带图库。按组件入口见 docs/ON-DEMAND.md。
+早期 0.1.7 安装说明已移至 [开发历史归档](docs/RELEASE-HISTORY.md)。

package/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "sky-ui-kit",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "elementPlusVersion": "2.14.7",
   "setup": {
     "cssOnce": [

package/docs/AI-CHANGELOG.md

@@ -517,3 +517,13 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 ## 0.1.10 发布内容
 
 包含 HTML 按需主题/面板/按钮/输入样式、数字输入增强脚本、原生选择与上传样式、22 项表单验收目录及 AI 接入规则。发布前重新生成文档和构建，并检查包内出口。浏览器视觉验收及独立消费业务项目测试仍由用户继续完成。
+
+## 2026-11-04：0.1.10 原生 HTML 迁移文档修订（未发布）
+
+修正 AI 指南相对链接及 README 发布状态；新增透明地图覆盖层/主题面板/body 浮层示例，补齐旧页面 CSS 皮肤移除、布局保留和逐状态验收。迁移前后共用布局及业务脚本，不要求 Vue、不增加业务项目专用全局覆盖。详见 [HTML 迁移](HTML-INTEGRATION.md)和[迁移后示例](../examples/html/migration/after.html)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。
+
+本轮验证：相对链接检查覆盖源码文档、生成 AI 文档及 npm files 清单；迁移前后 DOM 检查覆盖相同 ID、查询/重置、地图点击监听、弹窗事件接线和主题同步。弹窗方法使用测试替身，未验证实际焦点、地图拖拽、布局或视觉状态。没有改动库样式代码或业务消费项目，版本仍为 0.1.10，修订尚未发布。
+
+## 0.1.11 发布内容
+
+修正 AI 指南及合并文档相对链接，更新 README 当前发布状态并归档历史说明。原生 HTML 路线明确保留 DOM/事件/表单且无需 Vue；新增透明地图覆盖层、独立浮层主题、旧皮肤移除及前后迁移示例。发布检查包括生成文档、相对链接/包内路径、类型和库构建；未进行浏览器视觉或真实地图验收。

package/docs/AI-GUIDE.md

@@ -2,7 +2,7 @@
 
 ## AI 接入入口：先选择使用方式
 
-当用户要求安装、引入 sky-ui-kit 时，请先读取当前安装包的 llms.txt 和 [HTML / Vue 接入判断](docs/HTML-INTEGRATION.md)，检查项目及真实 exports。只需外观时使用正式 HTML 样式接口（新版容器 sky-html 内原生控件自动换肤，data-sky-native="off" 局部退出）；需要交互时使用真实 Vue 组件，HTML 项目可局部挂载。需求不明确时先询问，接入后合并项目 AGENTS.md 规则，不能把 npm install 或仅加载 CSS 报告为完整组件接入。
+当用户要求引入 sky-ui-kit 时，先读取当前安装包的 llms.txt 和 [原生 HTML 接入与迁移](HTML-INTEGRATION.md)，检查项目和真实 exports。原生 HTML 路线统一库支持的控件样式，保留原 DOM、事件和表单行为，无需 Vue。仅在用户明确需要真实 Vue 组件时，才选择 Vue 直接接入或局部挂载。目标不明确时询问；接入后合并项目 AGENTS.md 规则，按实际视觉状态和业务行为验收，不能只以安装成功或 CSS 已加载作为完成依据。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -319,7 +319,10 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 ### 快速开始：团队 AI 读取提示
 
 ```text
-请先读取 node_modules/sky-ui-kit/llms.txt，并按索引读取：
+请先读取 node_modules/sky-ui-kit/llms.txt，确认当前项目目标：
+- 原生 HTML：先读 docs/HTML-INTEGRATION.md，保留现有 DOM、业务事件和表单，仅接入支持的控件样式；不要求 Vue。
+- 地图悬浮面板：透明覆盖层保留布局，主题放在实际面板及独立浮层；清理旧控件皮肤并按状态验收。
+- 明确需要真实 Vue 组件时，才按以下 Vue 索引读取：
 - components.json：当前已安装版本的公开组件与 API 清单
 - docs/AI-GUIDE.md：使用规则和完整示例
 - docs/AI-CHANGELOG.md：模块变更及接入影响
@@ -330,7 +333,9 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 - docs/ADAPTATION.md：逐模块替换、Vite 图标配置、主题及业务适配方案
 
 请依据当前已安装包的版本与文档生成代码，不要虚构组件名称或 API。
-公共 CSS 仅在 main.ts 引入一次；业务请求、路由、权限由应用接入。
+CSS 在当前项目公共入口只引入一次（HTML 可使用 link；Vue 使用 main.ts）。
+不能只以安装成功或 CSS 已加载作为视觉接入完成依据；按默认/悬停/聚焦/禁用/选中和原业务行为核对。
+业务请求、路由、权限由应用接入。
 ```
 
 ### 图标安装：内置与自有资源

package/docs/CSS-THEME.md

@@ -310,3 +310,7 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 ### HTML 原生多选列表外观调整
 
 多选/size 列表设置可覆盖的 220px 宽度、选项留白和主题选中背景，补充悬停、选项禁用、整组禁用和高对比度规则；保留 size 与原生多选语义，不修改单选系统弹出菜单。第 10 项示例增加滚动及多选操作说明。未进行浏览器视觉验证。
+
+## 2026-11-04：0.1.10 原生 HTML 迁移文档修订（未发布）
+
+修正 AI 指南相对链接及 README 发布状态；新增透明地图覆盖层/主题面板/body 浮层示例，补齐旧页面 CSS 皮肤移除、布局保留和逐状态验收。迁移前后共用布局及业务脚本，不要求 Vue、不增加业务项目专用全局覆盖。详见 [HTML 迁移](HTML-INTEGRATION.md)和[迁移后示例](../examples/html/migration/after.html)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。

package/docs/HTML-INTEGRATION.md

@@ -1,69 +1,121 @@
-# HTML 样式与 AI 接入流程
+# 原生 HTML 样式接入与旧页面迁移
 
-## 状态与选择
+## 目标、版本与路线
 
-html/*.css 按需入口从 0.1.10 提供。0.1.9 已提供完整 model-workspace.css 与原生控件适配；不要声称 0.1.9 支持新增拆分入口。
-用户说“引入 sky-ui-kit”时，先检查项目及当前安装包 exports，再询问需要外观还是完整交互。需求明确时不重复询问。
-- 仅外观：本文的 HTML 接入，HTML、服务端模板和 Vue 原生元素均可使用。
-- Vue 完整组件：读取 AI-GUIDE.md、components.json、COMPONENT-API.md 和 CSS-THEME.md。
-- HTML 完整交互：需要局部挂载真实 Vue 组件，不能把加载 CSS 报告为组件接入完成。
+本路线适用于已有 HTML/JavaScript 页面、服务端模板以及 Vue 页面中的原生元素：统一库支持的控件表面样式，保留原 DOM、id/name/data 属性、监听器、表单提交和业务行为。不要求迁移 Vue，也不因页面包含查询、校验、弹窗等交互而切换技术栈。
+只有用户明确需要真实 UiSelect 等 Vue 组件及其组件 API 时，才考虑 [Vue 接入](AI-GUIDE.md)或局部挂载；这是可选路线。
 
-## 安装和按需入口
+0.1.10 已包含 html/*.css、html/number.js 和下列 CSS/JS 能力；文档与迁移示例修订从 0.1.11 提供，已安装的 0.1.10 文档不会随仓库更新。
 
-纯 HTML 只消费 CSS，不需要 Vue/Element Plus 运行时。npm 默认可能自动安装 peerDependencies；独立的 CSS 资源下载目录可用 npm install --legacy-peer-deps sky-ui-kit@指定版本，已有 Vue 工程不要借此绕过依赖检查。
+## 安装和资源部署
 
-| 包出口 | 顺序 | 用途 |
+~~~sh
+npm install sky-ui-kit@0.1.11
+~~~
+
+纯 HTML 运行时不依赖 Vue/Element Plus。npm 可能自动安装 peerDependencies；仅用于下载静态 CSS 的独立目录可选择 npm install --legacy-peer-deps sky-ui-kit@0.1.11，不应以此绕过已有 Vue 项目的依赖检查。
+
+| 出口 | 作用 | 顺序 |
 |---|---|---|
-| sky-ui-kit/html/theme.css | 第一，必需 | 主题、字体和局部基础规则 |
-| sky-ui-kit/html/panel.css | 主题之后，可选 | 内容区、标题、面板头/正文/底部 |
-| sky-ui-kit/html/button.css | 主题之后，可选 | 原生 button / input 按钮及 data-variant 状态 |
-| sky-ui-kit/html/input.css | 主题之后，可选 | 文本输入、select、textarea |
+| sky-ui-kit/html/theme.css | 主题变量、字体、主题边界 | 必需，第一 |
+| sky-ui-kit/html/panel.css | 面板结构及工作区布局 | 可选，主题后 |
+| sky-ui-kit/html/button.css | button、input 按钮 | 可选，主题后 |
+| sky-ui-kit/html/input.css | 输入、选择、复选/单选、文件按钮 | 可选，主题后 |
+| sky-ui-kit/html/number.css + number.js | 数字输入增减增强 | 可选，输入样式后 |
+
+带构建工具的项目在唯一公共入口 import 所需出口。纯静态网站从安装包 dist/html 复制所需文件到 static/vendor/sky-ui-kit/html，随网站部署，不把 node_modules URL 或开发者磁盘路径写进线上页面。不要加载 Element Plus CSS、style.css 或 global.css。完整 model-workspace.css 与前四项共享实现，选一种方式，不重复加载。
+
+本轮完整示例位于 [迁移前](../examples/html/migration/before.html)和[迁移后](../examples/html/migration/after.html)，同目录的 layout.css、business.js 两边共用。示例从包内 dist 读取 CSS，复制到网站时调整 href，不能只复制 HTML 而遗漏依赖。示例不请求远程地图服务，地图位置是布局占位，用于检查透明覆盖和点击穿透；真实地图仍由消费项目负责。
+
+## 透明地图覆盖层与浮层
+
+0.1.10 的 sky-html 会设置背景。不要不加判断地把它加在覆盖整幅地图的透明固定层上；也不要为此修改 --color-bg 为 transparent，后者会影响控件和浮层派生色。
+
+推荐让地图和 #workspace 保留原结构与透明布局，仅在实际面板上使用 sky-html：
+
+~~~html
+<div id="map"><!-- 原有地图实例与业务 --></div>
+<div id="workspace" class="map-overlay">
+  <section class="query-position sky-html sky-model-panel" data-theme="light">
+    <header class="sky-model-panel__header"><h2>查询</h2></header>
+    <form class="sky-model-panel__body"><label>名称 <input name="name"></label></form>
+  </section>
+</div>
+<!-- body 下的独立浮层自行设置主题边界，不依赖兄弟面板继承 -->
+<dialog id="details" class="dialog-position">
+  <section class="sky-html sky-model-panel" data-theme="light">详情内容</section>
+</dialog>
+~~~
+
+~~~css
+/* 业务布局：保留原来的固定定位、层级、点击穿透，不是控件皮肤。 */
+.map-overlay { position: fixed; inset: 0; background: transparent; pointer-events: none; }
+.query-position { position: absolute; top: 24px; left: 24px; width: min(360px, calc(100% - 48px)); pointer-events: auto; }
+~~~
+
+若确实需要让整个透明覆盖层成为共同主题容器，可在原布局类中明确保留背景：
+
+~~~html
+<div id="workspace" class="map-overlay sky-html" data-theme="light">...</div>
+~~~
+~~~css
+/* 与库同等或更高优先级，仅保留透明布局；不复制按钮/输入框皮肤。 */
+.map-overlay.sky-html { background: transparent; }
+~~~
+
+两种方式任选其一，不修改库默认背景，不新增 #workspace 全局覆盖。浮层在主题容器内时自然继承；移动到 body 后须在其实际内容容器上新增 sky-html 和相同 data-theme，并将应用自定义公共主题变量设置在公共祖先（例如 html），或明确复制到两个边界。不要复制私有 --userssite-* 计算结果。明暗切换要同步所有主题边界；局部面板变量不会自动传给兄弟浮层。
+
+保留原定位、z-index、pointer-events、overflow 和弹窗 showModal/关闭逻辑；CSS 接入不会新增焦点管理、遮罩、定位或业务行为。检查父容器 overflow 是否裁剪浮层。把 sky-html 用在 body 是普通整页换肤的可选方案，不能作为所有 HTML 页面的要求。
 
-完整 model-workspace.css 与上述四项共享源码，选一种方式，不重复加载。CSS 按需指实际只引入选中的文件，不是 JS tree-shaking。
-纯静态站将包内 dist/html 所需文件复制到 static/vendor/sky-ui-kit/html，并修改 link 路径；发布时随网站部署。包内 examples/html/index.html 为完整示例，可直接打开，要求安装包含这些 dist 文件的新发布版本。不得引用开发者磁盘路径或在生产依赖 node_modules URL。
-有构建工具的项目在唯一公共入口依次 import 对应出口。原有业务 CSS 在前，库样式在后；原样式有更高优先级、内联声明或 !important 时需逐项核对，加载顺序不能保证覆盖。不要无差别删除旧样式。
+## 旧页面迁移前后：删除皮肤，保留布局和行为
 
-## HTML 结构和状态契约
+完整前后示例共享同一份 [布局](../examples/html/migration/layout.css)和[业务脚本](../examples/html/migration/business.js)。迁移前额外加载 [旧控件皮肤](../examples/html/migration/legacy-controls.css)；迁移后移除该文件，新增库 CSS、主题容器、面板结构类及按钮语义。已有 DOM 节点与事件 ID 保留，未重新渲染业务控件。
 
-容器使用 class="sky-html"，data-theme="light" 或 "dark"；内部原生控件自动换肤，无需逐个添加控件类。整页可在 body 添加 sky-html。旧的 sky-model-workspace + data-native-controls 入口继续兼容。建议圈定需要换肤的区域，不包围地图画布或混合 Vue/Element Plus 控件的整个页面。
-面板使用 sky-model-panel，其头、正文、底部分别为 sky-model-panel__header / __body / __footer；页面内容区 sky-model-workspace__content。结构与完整示例一致。
-保留原 id、name、data 属性、事件绑定和表单语义，只新增作用域及结构类。button 必须保留正确的 type，data-variant="primary" / "danger" 表示主按钮 / 危险操作；旧 primary/accent 类仍兼容，disabled 为原生禁用。输入支持 required、readonly、disabled、placeholder、hover/focus-visible 和 aria-invalid="true" / :user-invalid 错误边框，不在页面首次打开时将所有必填输入标红。错误文字由业务提供并用 aria-describedby 关联，不新增校验 JS。
-样式接口没有 Vue props、emits 或 slots。查询、重置、校验及提交行为由原页面/浏览器负责；示例脚本只展示事件，不提供接口请求。checkbox/radio 使用主题皮肤，range/file/color/image 不提供专用皮肤，hidden 不应用控件样式，select 下拉选项由浏览器绘制，不承诺与 Vue 选择器一致。
+| 原规则类型 | 迁移处理 |
+|---|---|
+| #searchForm button、.query-position input 的背景/颜色/边框/圆角/字号/高度/内阴影 | 移除这些皮肤声明，交由库负责 |
+| :hover、:focus、:disabled、:checked、option:checked 等旧状态皮肤 | 同时移除，不能只改默认状态 |
+| 内联 style 的控件皮肤、!important 覆盖 | 从元素或旧规则删除，保留布局声明 |
+| position/inset/z-index/pointer-events、网格/列宽/gap、地图尺寸 | 继续保留在业务布局文件 |
+| 混合布局与皮肤的规则 | 按声明拆开：留下定位/布局，删除控件皮肤，不删除整条业务规则 |
+| 地图色带、阈值、图表配色、第三方地图内部 UI | 保留业务实现；必要时显式退出 |
 
-## 主题、字体和浮层
+示意：旧规则 #searchForm button { position:relative; background:#333; border:2px solid #777; } 只保留 position:relative；不能在库后面再写一套“更像 Vue”的 button 规则。
 
-HTML 控件与 Vue 共用 scoped-theme.css 私有主题变量；面板保持 ModelWorkspace 布局。字体与 Vue 共用 --userssite-font-family-sans / --font-family-sans，不包含字体文件，也不自动下载字体；不同系统字体可能存在差异。HTML 外观不等于每个 Ui 组件的 DOM 或交互。
-主题边界内可用 style 或后加载的类覆盖 --color-primary、--color-panel、--color-text、--color-border；明暗通过 data-theme 控制，不使用 theme-dark。
-此路线不引入 Element Plus CSS、style.css 或 global.css。局部主题不会自动传给 body 浮层；原页面浮层应放在主题容器内，或独立设置相同主题边界。不会附加焦点管理、遮罩、定位或弹窗逻辑。
+旧 CSS 在前、库 CSS 在后只是加载约定，并不保证覆盖高优先级选择器、内联样式或 !important。使用开发者工具检查控件的 Styles/Computed：查 border/background/color/font/height/outline/box-shadow 的获胜规则；切换 :hover/:focus，并实际设置 disabled/checked/aria-invalid。追溯到旧声明后移除该皮肤来源，不继续叠加选择器或 !important。不能删除的第三方控件使用 data-sky-native="off"，并在验收中列为例外。
 
-## 写入消费项目 AGENTS.md
+## 控件、状态和能力边界
 
-接入后合并以下规则，保留已有内容，不重复追加：
+sky-html 内原生控件自动换肤，不必逐个增加控件类。面板没有原生 HTML 对应物，使用 sky-model-panel、__header、__body、__footer 结构类；不把所有 div/section 变成面板。
 
-> 本项目使用 sky-ui-kit 的 HTML 样式模式。先读取当前安装包 llms.txt 和 docs/HTML-INTEGRATION.md，核对 exports；只使用该版本实际提供的 CSS 入口和结构类；新版 HTML 模式仅给容器添加 sky-html，原生控件自动换肤，不给每个控件补类。基础主题必需，其余按需引入。保留原 DOM 标识及业务事件，不通过仿写组件内部 CSS 实现外观。需要完整组件交互时明确切换到真实 Vue 组件方案。升级后重新核对文档和实际出口。
+保留 button 的 type，data-variant="primary" / "danger" 控制语义；旧 primary/accent 类兼容。readonly/disabled/required 保留浏览器语义。错误输入使用 aria-invalid="true"，错误文字 data-sky-error，并通过 aria-describedby 关联；库不实现校验业务。不会在首次加载时把所有必填项标红。
 
-包内文档不会自动进入所有 AI 工具上下文；README 和项目规则提供发现入口，不能保证所有工具自动执行。
+select 单选系统菜单、日期/时间弹层、文件窗口的外观及键盘行为存在浏览器差异，不承诺与 Vue 完全相同。多选支持 size，默认列表宽 220px，可用 --sky-select-list-width 调整，Ctrl/Command/Shift 遵循系统行为。checkbox/radio 提供主题皮肤；file-selector-button 已主题化；range/color/image 仍由浏览器绘制，hidden 不应用控件皮肤。
 
-## 验证范围
+数字增强是独立的可选原生 JS：加载 number.css，从 sky-ui-kit/html/number.js 导入 enhanceNumbers，DOM 就绪后调用。原 input 保持 id/name/事件，stepUp/stepDown 读取 min/max/step；发生变化后派发 input/change。返回函数用于清理，动态新增字段需再次初始化；step=any 禁用按钮，不提供长按重复。
 
-本次只进行文档生成和静态/类型检查，不构建、打包、发布或浏览器验证。示例网站展示当前源码；新增入口需安装 0.1.10 或更新版本。水库调度消费项目尚未修改，旧页面选择器冲突和视觉效果待用户验证。
+字体与 Vue 共享主题字体栈，但包不带字体文件；跨系统存在字形差异。公共主题变量应在公共祖先定义，默认高度 32px、圆角 4px，可通过 control-height-m、radius-s、font-size-body 调整。控件状态与主题规范共用不等于每个原生控件和 Vue 的像素/交互一致。
 
-## 自动换肤与局部退出
+## 局部退出
 
-给单个控件或第三方区域添加 data-sky-native="off"，该节点及全部后代都不会匹配按钮/输入样式；里面再次出现 sky-html 也不重新开启。容器外元素不受影响。Element Plus 的 el- 类节点及后代、MapLibre/Mapbox 地图内部控件自动排除；其他第三方组件请显式退出。
-退出仅阻止控件皮肤，不撤销祖先继承的字体、颜色、变量；需要完全独立时放到主题容器之外。
+data-sky-native="off" 使节点及其后代退出控件皮肤；内层 sky-html 不重新启用。Element Plus 和地图内部控件有排除规则，未知第三方区域需显式退出。退出不撤销继承的字体/颜色/主题变量；完全独立区域放在主题容器外。
 
-面板没有原生 HTML 控件，不自动给 div/section 加外观。使用已有 sky-model-panel 结构类，保留原 .panel 等类和事件，检查旧选择器冲突。不新增覆盖业务 .panel 的全局规则。完整示例见包内 examples/html/index.html。
+## 消费项目 AGENTS.md
 
-错误文案显式标记 data-sky-error，并用 aria-describedby 关联输入；不能自动把所有 span 识别为错误。默认控件高度 32px、圆角 4px，服从与 Vue 一致的 control-height-m、radius-s、font-size-body 覆盖。主题复制不包含字体二进制。仅承诺主题与控件表面规范一致，尚未完成浏览器视觉对照验证。
+合并以下规则并保留原有内容；文档路径相对安装包根目录：
 
-## HTML 表单控件逐项验收模块
+> 本项目采用 sky-ui-kit 原生 HTML 样式路线。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
 
-网站新增独立“HTML 表单控件”导航，22 项按编号定位，每项包含真实原生标签、可操作状态、可复制代码及当前页核对标记。目录与生成文档共享 src/html-form-catalog.ts，详见 HTML-FORM-CATALOG.md。滑块/颜色/上传仍为原生外观；复杂 Vue 组件没有等价原生标签，不宣称实现对应交互。仅做类型和文档检查，等待用户逐项核对。
+## 验收：视觉和业务均通过才完成
 
-## 原生数字增强、选择与文件输入
+1. 默认：字体、尺寸、圆角、内边距与库 HTML 示例一致；地图可见，面板位置和层级正确。
+2. 悬停：按钮、输入、可用选项使用主题色；禁用元素无可操作悬停表现。
+3. 聚焦：鼠标与 Tab 聚焦为单层输入边框，键盘焦点可辨识，错误仍保留危险色。
+4. 禁用/只读：外观正确，字段不可编辑，fieldset 禁用也生效。
+5. 选中：checkbox/radio/option 的选中与禁用选中状态正确；系统渲染差异列为限制。
+6. 业务：原查询、重置、提交、表单验证、地图点击/拖动、文件 change 及弹窗开关仍工作；不重复注册监听器。
+7. 浮层：与面板主题一致，明暗同步，未被裁剪或透明覆盖层遮挡。
 
-数字框可额外加载 html/number.css，并从 sky-ui-kit/html/number.js 导入 enhanceNumbers，在 DOM 就绪后执行，返回函数用于卸载。静态站复制 number.js/number.css 到同一静态目录，通过 module 脚本导入；保持原 input 的 id/name/监听器，步进使用浏览器 stepUp/stepDown，变化后派发 input/change。step=any 不启用按钮；不实现长按重复。
-select 单选弹出菜单仍由系统绘制，多选使用 size 行数和可滚动列表。file 输入仅美化文件按钮，不替换系统窗口、不发起上传。此前“上传保留原外观”的说明由此更新覆盖。
+记录浏览器/系统、包版本、各状态结果、冲突来源及剩余例外；对照 [逐项目录](HTML-FORM-CATALOG.md)。安装成功、文件存在或 CSS 加载成功只证明资源接入，不能证明视觉和交互已完成。
 
-多选 select 使用列表皮肤，默认宽度 220px，可通过 --sky-select-list-width 覆盖；size 控制可见行数，最小约三行。选项选中、不可选及整组禁用沿用原生属性。Ctrl/Command/Shift 操作遵循系统规则，option 样式支持因浏览器而异，不承诺等同 Vue 浮层。
+本轮修订检查了相对链接、示例结构/脚本和类型，并在授权发布流程中构建、核对安装包。未进行浏览器视觉验证或修改业务消费项目；地图占位示例不等于真实地图引擎集成验证。安装 0.1.11 或更新版本可获得本轮文档修订。

package/docs/INTEGRATION.md

@@ -214,3 +214,7 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 ### 原生控件自动换肤调整（未发布）
 
 新增 sky-html 容器入口，按需样式直接匹配原生 button/input/select/textarea；支持 data-sky-native="off" 本身及后代退出、Element Plus/地图内部控件排除，保留旧工作区 opt-in。主题默认低优先级，特殊按钮使用 data-variant，支持只读、禁用、错误及焦点状态；面板继续使用明确结构类，不覆盖所有 div。示例网站展示完整原生 HTML 状态及退出区域，详见 HTML-INTEGRATION.md。
+
+## 2026-11-04：0.1.10 原生 HTML 迁移文档修订（未发布）
+
+修正 AI 指南相对链接及 README 发布状态；新增透明地图覆盖层/主题面板/body 浮层示例，补齐旧页面 CSS 皮肤移除、布局保留和逐状态验收。迁移前后共用布局及业务脚本，不要求 Vue、不增加业务项目专用全局覆盖。详见 [HTML 迁移](HTML-INTEGRATION.md)和[迁移后示例](../examples/html/migration/after.html)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。

package/docs/RELEASE-HISTORY.md

@@ -0,0 +1,12 @@
+# 开发历史归档
+
+本文件记录过去的开发阶段，不是当前安装说明。
+
+初始快照曾通过 private: true 阻止未审核发布，当时包名尚未核验；这些描述已失效，不适用于已发布的 sky-ui-kit@0.1.10，当前 package.json 不含该限制。
+早期包结构曾携带主题 store 相关文件，现行接入不需要主题 store/Pinia。当前包以 package.json 的 files/exports 和包内文档为准。
+
+当前接入见 [README](../README.md)、[HTML 迁移](HTML-INTEGRATION.md)；组件迭代记录见 [AI 变更记录](AI-CHANGELOG.md)。
+
+## 历史：0.1.7 正式安装与样式
+
+通过 npm 安装 sky-ui-kit，main.ts 依次引入 element-plus/dist/index.css 和 sky-ui-kit/style.css，包内已包含默认主题和组件样式，不依赖开发者电脑、原业务项目或远程样式服务。CSS 变量允许运行时主题覆盖。图标资源可从 sky-ui-kit/icons 显式注册，或由应用提供 sprite；SvgIcon 不再自动携带图库。按组件入口见 [按需引入](ON-DEMAND.md)。

package/examples/html/migration/after.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>原生地图悬浮面板 · 迁移后</title>
+<!-- 包内示例相对 dist 路径；部署时将资源复制到网站静态目录并更新 href。 -->
+<link rel="stylesheet" href="../../../dist/html/theme.css">
+<link rel="stylesheet" href="../../../dist/html/panel.css">
+<link rel="stylesheet" href="../../../dist/html/button.css">
+<link rel="stylesheet" href="../../../dist/html/input.css">
+<link rel="stylesheet" href="./layout.css">
+</head>
+<body>
+<div id="map"><p id="mapStatus">地图布局占位，点击此背景可核对穿透（不加载地图引擎）。</p></div>
+<!-- 透明地图覆盖层不添加 sky-html。业务定位和穿透规则不变。 -->
+<div id="workspace">
+<section class="query-position sky-html sky-model-panel" data-demo-theme data-theme="light">
+<header class="sky-model-panel__header"><h1>水库查询</h1><button id="theme" type="button">切换主题</button></header>
+<form id="searchForm" class="form-layout sky-model-panel__body">
+<label class="field-layout" for="name">名称<input id="name" name="name" required placeholder="请输入名称"></label>
+<label class="field-layout" for="province">省份<select id="province" name="province" multiple size="3"><option selected>湖北</option><option>湖南</option><option>四川</option></select></label>
+<label><input name="enabled" type="checkbox" checked>仅显示可用项</label>
+<label>只读编码<input name="code" value="363" readonly></label>
+<div class="actions-layout"><button type="submit" data-variant="primary">查询</button><button type="reset">重置</button><button type="button" disabled>禁用操作</button></div>
+<output id="status" aria-live="polite">等待查询</output>
+</form>
+<footer class="sky-model-panel__footer"><button id="openDetails" type="button">打开 body 浮层</button></footer>
+</section>
+</div>
+<dialog id="details" class="dialog-position">
+<!-- 浮层与查询面板是兄弟节点，明确使用自己的主题边界并同步 data-theme。 -->
+<section class="sky-html sky-model-panel" data-demo-theme data-theme="light">
+<header class="sky-model-panel__header"><h2>独立浮层</h2></header>
+<div class="sky-model-panel__body"><label>备注<input name="notes" placeholder="原生浮层输入"></label></div>
+<footer class="sky-model-panel__footer"><button id="closeDetails" type="button">关闭</button></footer>
+</section>
+</dialog>
+<script src="./business.js"></script>
+</body></html>

package/examples/html/migration/before.html

@@ -0,0 +1,34 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>原生地图悬浮面板 · 迁移前</title>
+<link rel="stylesheet" href="./legacy-controls.css">
+<link rel="stylesheet" href="./layout.css">
+</head>
+<body>
+<div id="map"><p id="mapStatus">地图布局占位，点击此背景可核对穿透（不加载地图引擎）。</p></div>
+<!-- 透明地图覆盖层不添加 sky-html。业务定位和穿透规则不变。 -->
+<div id="workspace">
+<section class="query-position" data-demo-theme data-theme="light">
+<header><h1>水库查询</h1><button id="theme" type="button">切换主题</button></header>
+<form id="searchForm" class="form-layout">
+<label class="field-layout" for="name">名称<input id="name" name="name" required placeholder="请输入名称"></label>
+<label class="field-layout" for="province">省份<select id="province" name="province" multiple size="3"><option selected>湖北</option><option>湖南</option><option>四川</option></select></label>
+<label><input name="enabled" type="checkbox" checked>仅显示可用项</label>
+<label>只读编码<input name="code" value="363" readonly></label>
+<div class="actions-layout"><button type="submit">查询</button><button type="reset">重置</button><button type="button" disabled>禁用操作</button></div>
+<output id="status" aria-live="polite">等待查询</output>
+</form>
+<footer><button id="openDetails" type="button">打开 body 浮层</button></footer>
+</section>
+</div>
+<dialog id="details" class="dialog-position">
+<!-- 浮层与查询面板是兄弟节点，明确使用自己的主题边界并同步 data-theme。 -->
+<section class="legacy-dialog" data-demo-theme data-theme="light">
+<header><h2>独立浮层</h2></header>
+<div><label>备注<input name="notes" placeholder="原生浮层输入"></label></div>
+<footer><button id="closeDetails" type="button">关闭</button></footer>
+</section>
+</dialog>
+<script src="./business.js"></script>
+</body></html>

package/examples/html/migration/business.js

@@ -0,0 +1,18 @@
+/* 两个页面共用原生业务监听器，不创建/替换业务 DOM，不依赖 Vue。 */
+const form = document.getElementById('searchForm');
+const status = document.getElementById('status');
+form.addEventListener('submit', event => {
+ event.preventDefault();
+ const data = new FormData(form);
+ status.textContent = '查询：' + data.get('name') + '；已选省份：' + data.getAll('province').join('、');
+});
+form.addEventListener('reset', () => { status.textContent = '查询条件已重置'; });
+document.getElementById('map').addEventListener('click', () => { document.getElementById('mapStatus').textContent = '地图背景仍可点击'; });
+const dialog = document.getElementById('details');
+document.getElementById('openDetails').addEventListener('click', () => { dialog.showModal(); });
+document.getElementById('closeDetails').addEventListener('click', () => { dialog.close(); });
+document.getElementById('theme').addEventListener('click', () => {
+ const panels = document.querySelectorAll('[data-demo-theme]');
+ const next = panels[0].dataset.theme === 'dark' ? 'light' : 'dark';
+ panels.forEach(panel => { panel.dataset.theme = next; });
+});

package/examples/html/migration/layout.css

@@ -0,0 +1,9 @@
+/* 迁移前后原样保留的业务布局，不负责控件皮肤。 */
+body { margin:0; }
+#map { position:fixed; inset:0; display:grid; place-items:center; background:repeating-linear-gradient(35deg,#b5d6c2 0 60px,#b9dbe8 60px 120px); }
+#workspace { position:fixed; inset:0; background:transparent; pointer-events:none; }
+.query-position { position:absolute; inset:24px auto auto 24px; width:min(360px,calc(100% - 48px)); pointer-events:auto; }
+.form-layout { display:grid; gap:16px; }
+.field-layout { display:grid; gap:6px; }
+.actions-layout { display:flex; flex-wrap:wrap; gap:12px; }
+.dialog-position { width:min(420px,calc(100% - 48px)); padding:0; border:0; }

package/examples/html/migration/legacy-controls.css

@@ -0,0 +1,8 @@
+/* 旧皮肤：迁移后移除该文件，不用更强的选择器继续覆盖。 */
+.query-position { background:#eee; border:2px solid #555; padding:14px; }
+#searchForm input, #searchForm select { background:#ddd; color:#222; border:2px solid #555; border-radius:0; padding:4px; }
+#searchForm input:focus { outline:3px solid orange; }
+#searchForm button, #openDetails, #closeDetails { background:#333; color:white; border:2px solid #777; border-radius:0; height:28px; }
+#searchForm button:hover { background:#555; }
+#searchForm button:disabled { background:#999; color:#ccc; }
+#searchForm input:checked { accent-color:orange; }

package/llms-full.txt

@@ -1,10 +1,10 @@
 # sky-ui-kit
 
-> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.10. AI tools must explicitly load these files.
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.11. AI tools must explicitly load these files.
 
 ## Documentation
 
-- [HTML and AI onboarding](docs/HTML-INTEGRATION.md): choose appearance or real components before setup; HTML needs no Element Plus CSS.
+- [HTML and AI onboarding](docs/HTML-INTEGRATION.md): native HTML migration retaining existing interactions, transparent map overlays and optional Vue route.
 
 - [Consumers](docs/CONSUMERS.md): shared project convention and local integration.
 - [AI guide](docs/AI-GUIDE.md): setup, examples, icon/event bindings and limits.
@@ -25,13 +25,13 @@
 
 ## 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.
+Native HTML: read docs/HTML-INTEGRATION.md first, retain DOM/events/forms, load supported html/*.css once, preserve transparent map overlays and remove conflicting legacy control skins. Vue is optional only when real Vue components are requested. Vue component route: import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts, and check components.json before using exports. Verify visual states and existing behavior; installing or loading CSS alone is not completion.
 
 # sky-ui-kit：AI 使用指南
 
 ## AI 接入入口：先选择使用方式
 
-当用户要求安装、引入 sky-ui-kit 时，请先读取当前安装包的 llms.txt 和 [HTML / Vue 接入判断](docs/HTML-INTEGRATION.md)，检查项目及真实 exports。只需外观时使用正式 HTML 样式接口（新版容器 sky-html 内原生控件自动换肤，data-sky-native="off" 局部退出）；需要交互时使用真实 Vue 组件，HTML 项目可局部挂载。需求不明确时先询问，接入后合并项目 AGENTS.md 规则，不能把 npm install 或仅加载 CSS 报告为完整组件接入。
+当用户要求引入 sky-ui-kit 时，先读取当前安装包的 llms.txt 和 [原生 HTML 接入与迁移](docs/HTML-INTEGRATION.md)，检查项目和真实 exports。原生 HTML 路线统一库支持的控件样式，保留原 DOM、事件和表单行为，无需 Vue。仅在用户明确需要真实 Vue 组件时，才选择 Vue 直接接入或局部挂载。目标不明确时询问；接入后合并项目 AGENTS.md 规则，按实际视觉状态和业务行为验收，不能只以安装成功或 CSS 已加载作为完成依据。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -299,7 +299,7 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 ```
 预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
 
-HTML 表单逐项示例见 [验收目录](HTML-FORM-CATALOG.md)，网站独立导航按编号核对；原生与 Vue 的边界见各项说明。
+HTML 表单逐项示例见 [验收目录](docs/HTML-FORM-CATALOG.md)，网站独立导航按编号核对；原生与 Vue 的边界见各项说明。
 
 <!-- GENERATED EXAMPLES -->
 
@@ -348,7 +348,10 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 ### 快速开始：团队 AI 读取提示
 
 ```text
-请先读取 node_modules/sky-ui-kit/llms.txt，并按索引读取：
+请先读取 node_modules/sky-ui-kit/llms.txt，确认当前项目目标：
+- 原生 HTML：先读 docs/HTML-INTEGRATION.md，保留现有 DOM、业务事件和表单，仅接入支持的控件样式；不要求 Vue。
+- 地图悬浮面板：透明覆盖层保留布局，主题放在实际面板及独立浮层；清理旧控件皮肤并按状态验收。
+- 明确需要真实 Vue 组件时，才按以下 Vue 索引读取：
 - components.json：当前已安装版本的公开组件与 API 清单
 - docs/AI-GUIDE.md：使用规则和完整示例
 - docs/AI-CHANGELOG.md：模块变更及接入影响
@@ -359,7 +362,9 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 - docs/ADAPTATION.md：逐模块替换、Vite 图标配置、主题及业务适配方案
 
 请依据当前已安装包的版本与文档生成代码，不要虚构组件名称或 API。
-公共 CSS 仅在 main.ts 引入一次；业务请求、路由、权限由应用接入。
+CSS 在当前项目公共入口只引入一次（HTML 可使用 link；Vue 使用 main.ts）。
+不能只以安装成功或 CSS 已加载作为视觉接入完成依据；按默认/悬停/聚焦/禁用/选中和原业务行为核对。
+业务请求、路由、权限由应用接入。
 ```
 
 ### 图标安装：内置与自有资源
@@ -3268,7 +3273,7 @@ const message = ref('等待配置')
 
 ## 2026-10-13：一体机本地开发接入
 
-新增四个工作台组件和 MapTools.items。工作台 CSS 在 .sky-workbench 下隔离，使用库主题变量；应用消费本地 0.1.3-dev.0，未发布。详情见 [消费项目记录](CONSUMERS.md)。
+新增四个工作台组件和 MapTools.items。工作台 CSS 在 .sky-workbench 下隔离，使用库主题变量；应用消费本地 0.1.3-dev.0，未发布。详情见 [消费项目记录](docs/CONSUMERS.md)。
 
 ## 2026-10-13：顶部菜单修复（0.1.3-dev.1）
 
@@ -3575,7 +3580,7 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 
 ## 2026-11-04：HTML 按需样式接入（未发布）
 
-新增 theme/panel/button/input 四个 CSS 出口，完整 model-workspace.css 与拆分入口共享源码；网站新增隔离 HTML 示例。外观模式保留原 DOM/事件，不能当作 Vue 组件接入。结构、安装、状态、主题、浮层及 AGENTS.md 规则见 [HTML 接入](HTML-INTEGRATION.md)。仅生成文档和静态检查，未构建、发布或浏览器验证；历史“CSS 未拆分”对 Vue style.css 仍成立。
+新增 theme/panel/button/input 四个 CSS 出口，完整 model-workspace.css 与拆分入口共享源码；网站新增隔离 HTML 示例。外观模式保留原 DOM/事件，不能当作 Vue 组件接入。结构、安装、状态、主题、浮层及 AGENTS.md 规则见 [HTML 接入](docs/HTML-INTEGRATION.md)。仅生成文档和静态检查，未构建、发布或浏览器验证；历史“CSS 未拆分”对 Vue style.css 仍成立。
 
 ### 原生控件自动换肤调整（未发布）
 
@@ -3609,6 +3614,16 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 
 包含 HTML 按需主题/面板/按钮/输入样式、数字输入增强脚本、原生选择与上传样式、22 项表单验收目录及 AI 接入规则。发布前重新生成文档和构建，并检查包内出口。浏览器视觉验收及独立消费业务项目测试仍由用户继续完成。
 
+## 2026-11-04：0.1.10 原生 HTML 迁移文档修订（未发布）
+
+修正 AI 指南相对链接及 README 发布状态；新增透明地图覆盖层/主题面板/body 浮层示例，补齐旧页面 CSS 皮肤移除、布局保留和逐状态验收。迁移前后共用布局及业务脚本，不要求 Vue、不增加业务项目专用全局覆盖。详见 [HTML 迁移](docs/HTML-INTEGRATION.md)和[迁移后示例](examples/html/migration/after.html)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。
+
+本轮验证：相对链接检查覆盖源码文档、生成 AI 文档及 npm files 清单；迁移前后 DOM 检查覆盖相同 ID、查询/重置、地图点击监听、弹窗事件接线和主题同步。弹窗方法使用测试替身，未验证实际焦点、地图拖拽、布局或视觉状态。没有改动库样式代码或业务消费项目，版本仍为 0.1.10，修订尚未发布。
+
+## 0.1.11 发布内容
+
+修正 AI 指南及合并文档相对链接，更新 README 当前发布状态并归档历史说明。原生 HTML 路线明确保留 DOM/事件/表单且无需 Vue；新增透明地图覆盖层、独立浮层主题、旧皮肤移除及前后迁移示例。发布检查包括生成文档、相对链接/包内路径、类型和库构建；未进行浏览器视觉或真实地图验收。
+
 # 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.
@@ -5951,7 +5966,7 @@ SvgIcon 样式仅作用于 scoped 的 .sky-svg-icon，不覆盖原生 ElIcon 或
 
 ## 2026-10-13：一体机本地开发接入
 
-新增四个工作台组件和 MapTools.items。工作台 CSS 在 .sky-workbench 下隔离，使用库主题变量；应用消费本地 0.1.3-dev.0，未发布。详情见 [消费项目记录](CONSUMERS.md)。
+新增四个工作台组件和 MapTools.items。工作台 CSS 在 .sky-workbench 下隔离，使用库主题变量；应用消费本地 0.1.3-dev.0，未发布。详情见 [消费项目记录](docs/CONSUMERS.md)。
 
 ## 2026-10-13：顶部菜单修复（0.1.3-dev.1）
 
@@ -6167,7 +6182,7 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 
 ## 2026-11-04：HTML 按需样式接入（未发布）
 
-新增 theme/panel/button/input 四个 CSS 出口，完整 model-workspace.css 与拆分入口共享源码；网站新增隔离 HTML 示例。外观模式保留原 DOM/事件，不能当作 Vue 组件接入。结构、安装、状态、主题、浮层及 AGENTS.md 规则见 [HTML 接入](HTML-INTEGRATION.md)。仅生成文档和静态检查，未构建、发布或浏览器验证；历史“CSS 未拆分”对 Vue style.css 仍成立。
+新增 theme/panel/button/input 四个 CSS 出口，完整 model-workspace.css 与拆分入口共享源码；网站新增隔离 HTML 示例。外观模式保留原 DOM/事件，不能当作 Vue 组件接入。结构、安装、状态、主题、浮层及 AGENTS.md 规则见 [HTML 接入](docs/HTML-INTEGRATION.md)。仅生成文档和静态检查，未构建、发布或浏览器验证；历史“CSS 未拆分”对 Vue style.css 仍成立。
 
 ### 原生控件自动换肤调整（未发布）
 
@@ -6193,6 +6208,10 @@ HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue
 
 多选/size 列表设置可覆盖的 220px 宽度、选项留白和主题选中背景，补充悬停、选项禁用、整组禁用和高对比度规则；保留 size 与原生多选语义，不修改单选系统弹出菜单。第 10 项示例增加滚动及多选操作说明。未进行浏览器视觉验证。
 
+## 2026-11-04：0.1.10 原生 HTML 迁移文档修订（未发布）
+
+修正 AI 指南相对链接及 README 发布状态；新增透明地图覆盖层/主题面板/body 浮层示例，补齐旧页面 CSS 皮肤移除、布局保留和逐状态验收。迁移前后共用布局及业务脚本，不要求 Vue、不增加业务项目专用全局覆盖。详见 [HTML 迁移](docs/HTML-INTEGRATION.md)和[迁移后示例](examples/html/migration/after.html)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。
+
 # 按需引入
 
 下一次发布后支持独立组件路径：
@@ -6234,7 +6253,7 @@ import { MapSideMenu } from 'sky-ui-kit/components/MapSideMenu'
 
 ## 2026-11-04：HTML 按需样式接入（未发布）
 
-新增 theme/panel/button/input 四个 CSS 出口，完整 model-workspace.css 与拆分入口共享源码；网站新增隔离 HTML 示例。外观模式保留原 DOM/事件，不能当作 Vue 组件接入。结构、安装、状态、主题、浮层及 AGENTS.md 规则见 [HTML 接入](HTML-INTEGRATION.md)。仅生成文档和静态检查，未构建、发布或浏览器验证；历史“CSS 未拆分”对 Vue style.css 仍成立。
+新增 theme/panel/button/input 四个 CSS 出口，完整 model-workspace.css 与拆分入口共享源码；网站新增隔离 HTML 示例。外观模式保留原 DOM/事件，不能当作 Vue 组件接入。结构、安装、状态、主题、浮层及 AGENTS.md 规则见 [HTML 接入](docs/HTML-INTEGRATION.md)。仅生成文档和静态检查，未构建、发布或浏览器验证；历史“CSS 未拆分”对 Vue style.css 仍成立。
 
 ### 原生控件自动换肤调整（未发布）
 
@@ -6600,75 +6619,127 @@ metricslab降水播放轴使用TemplateLayout.timeline插槽；timelineLeft/time
 
 2026-10-20：media-ui最新用户约定仅消费npm sky-ui-kit@0.1.6，开发和交付均移除源码alias；库能力后续需发布可安装版本后应用再升级。
 
-# HTML 样式与 AI 接入流程
+# 原生 HTML 样式接入与旧页面迁移
+
+## 目标、版本与路线
+
+本路线适用于已有 HTML/JavaScript 页面、服务端模板以及 Vue 页面中的原生元素：统一库支持的控件表面样式，保留原 DOM、id/name/data 属性、监听器、表单提交和业务行为。不要求迁移 Vue，也不因页面包含查询、校验、弹窗等交互而切换技术栈。
+只有用户明确需要真实 UiSelect 等 Vue 组件及其组件 API 时，才考虑 [Vue 接入](docs/AI-GUIDE.md)或局部挂载；这是可选路线。
 
-## 状态与选择
+0.1.10 已包含 html/*.css、html/number.js 和下列 CSS/JS 能力；文档与迁移示例修订从 0.1.11 提供，已安装的 0.1.10 文档不会随仓库更新。
 
-html/*.css 按需入口从 0.1.10 提供。0.1.9 已提供完整 model-workspace.css 与原生控件适配；不要声称 0.1.9 支持新增拆分入口。
-用户说“引入 sky-ui-kit”时，先检查项目及当前安装包 exports，再询问需要外观还是完整交互。需求明确时不重复询问。
-- 仅外观：本文的 HTML 接入，HTML、服务端模板和 Vue 原生元素均可使用。
-- Vue 完整组件：读取 AI-GUIDE.md、components.json、COMPONENT-API.md 和 CSS-THEME.md。
-- HTML 完整交互：需要局部挂载真实 Vue 组件，不能把加载 CSS 报告为组件接入完成。
+## 安装和资源部署
 
-## 安装和按需入口
+~~~sh
+npm install sky-ui-kit@0.1.11
+~~~
 
-纯 HTML 只消费 CSS，不需要 Vue/Element Plus 运行时。npm 默认可能自动安装 peerDependencies；独立的 CSS 资源下载目录可用 npm install --legacy-peer-deps sky-ui-kit@指定版本，已有 Vue 工程不要借此绕过依赖检查。
+纯 HTML 运行时不依赖 Vue/Element Plus。npm 可能自动安装 peerDependencies；仅用于下载静态 CSS 的独立目录可选择 npm install --legacy-peer-deps sky-ui-kit@0.1.11，不应以此绕过已有 Vue 项目的依赖检查。
 
-| 包出口 | 顺序 | 用途 |
+| 出口 | 作用 | 顺序 |
 |---|---|---|
-| sky-ui-kit/html/theme.css | 第一，必需 | 主题、字体和局部基础规则 |
-| sky-ui-kit/html/panel.css | 主题之后，可选 | 内容区、标题、面板头/正文/底部 |
-| sky-ui-kit/html/button.css | 主题之后，可选 | 原生 button / input 按钮及 data-variant 状态 |
-| sky-ui-kit/html/input.css | 主题之后，可选 | 文本输入、select、textarea |
+| sky-ui-kit/html/theme.css | 主题变量、字体、主题边界 | 必需，第一 |
+| sky-ui-kit/html/panel.css | 面板结构及工作区布局 | 可选，主题后 |
+| sky-ui-kit/html/button.css | button、input 按钮 | 可选，主题后 |
+| sky-ui-kit/html/input.css | 输入、选择、复选/单选、文件按钮 | 可选，主题后 |
+| sky-ui-kit/html/number.css + number.js | 数字输入增减增强 | 可选，输入样式后 |
 
-完整 model-workspace.css 与上述四项共享源码，选一种方式，不重复加载。CSS 按需指实际只引入选中的文件，不是 JS tree-shaking。
-纯静态站将包内 dist/html 所需文件复制到 static/vendor/sky-ui-kit/html，并修改 link 路径；发布时随网站部署。包内 examples/html/index.html 为完整示例，可直接打开，要求安装包含这些 dist 文件的新发布版本。不得引用开发者磁盘路径或在生产依赖 node_modules URL。
-有构建工具的项目在唯一公共入口依次 import 对应出口。原有业务 CSS 在前，库样式在后；原样式有更高优先级、内联声明或 !important 时需逐项核对，加载顺序不能保证覆盖。不要无差别删除旧样式。
+带构建工具的项目在唯一公共入口 import 所需出口。纯静态网站从安装包 dist/html 复制所需文件到 static/vendor/sky-ui-kit/html，随网站部署，不把 node_modules URL 或开发者磁盘路径写进线上页面。不要加载 Element Plus CSS、style.css 或 global.css。完整 model-workspace.css 与前四项共享实现，选一种方式，不重复加载。
 
-## HTML 结构和状态契约
+本轮完整示例位于 [迁移前](examples/html/migration/before.html)和[迁移后](examples/html/migration/after.html)，同目录的 layout.css、business.js 两边共用。示例从包内 dist 读取 CSS，复制到网站时调整 href，不能只复制 HTML 而遗漏依赖。示例不请求远程地图服务，地图位置是布局占位，用于检查透明覆盖和点击穿透；真实地图仍由消费项目负责。
 
-容器使用 class="sky-html"，data-theme="light" 或 "dark"；内部原生控件自动换肤，无需逐个添加控件类。整页可在 body 添加 sky-html。旧的 sky-model-workspace + data-native-controls 入口继续兼容。建议圈定需要换肤的区域，不包围地图画布或混合 Vue/Element Plus 控件的整个页面。
-面板使用 sky-model-panel，其头、正文、底部分别为 sky-model-panel__header / __body / __footer；页面内容区 sky-model-workspace__content。结构与完整示例一致。
-保留原 id、name、data 属性、事件绑定和表单语义，只新增作用域及结构类。button 必须保留正确的 type，data-variant="primary" / "danger" 表示主按钮 / 危险操作；旧 primary/accent 类仍兼容，disabled 为原生禁用。输入支持 required、readonly、disabled、placeholder、hover/focus-visible 和 aria-invalid="true" / :user-invalid 错误边框，不在页面首次打开时将所有必填输入标红。错误文字由业务提供并用 aria-describedby 关联，不新增校验 JS。
-样式接口没有 Vue props、emits 或 slots。查询、重置、校验及提交行为由原页面/浏览器负责；示例脚本只展示事件，不提供接口请求。checkbox/radio 使用主题皮肤，range/file/color/image 不提供专用皮肤，hidden 不应用控件样式，select 下拉选项由浏览器绘制，不承诺与 Vue 选择器一致。
+## 透明地图覆盖层与浮层
 
-## 主题、字体和浮层
+0.1.10 的 sky-html 会设置背景。不要不加判断地把它加在覆盖整幅地图的透明固定层上；也不要为此修改 --color-bg 为 transparent，后者会影响控件和浮层派生色。
 
-HTML 控件与 Vue 共用 scoped-theme.css 私有主题变量；面板保持 ModelWorkspace 布局。字体与 Vue 共用 --userssite-font-family-sans / --font-family-sans，不包含字体文件，也不自动下载字体；不同系统字体可能存在差异。HTML 外观不等于每个 Ui 组件的 DOM 或交互。
-主题边界内可用 style 或后加载的类覆盖 --color-primary、--color-panel、--color-text、--color-border；明暗通过 data-theme 控制，不使用 theme-dark。
-此路线不引入 Element Plus CSS、style.css 或 global.css。局部主题不会自动传给 body 浮层；原页面浮层应放在主题容器内，或独立设置相同主题边界。不会附加焦点管理、遮罩、定位或弹窗逻辑。
+推荐让地图和 #workspace 保留原结构与透明布局，仅在实际面板上使用 sky-html：
 
-## 写入消费项目 AGENTS.md
+~~~html
+<div id="map"><!-- 原有地图实例与业务 --></div>
+<div id="workspace" class="map-overlay">
+  <section class="query-position sky-html sky-model-panel" data-theme="light">
+    <header class="sky-model-panel__header"><h2>查询</h2></header>
+    <form class="sky-model-panel__body"><label>名称 <input name="name"></label></form>
+  </section>
+</div>
+<!-- body 下的独立浮层自行设置主题边界，不依赖兄弟面板继承 -->
+<dialog id="details" class="dialog-position">
+  <section class="sky-html sky-model-panel" data-theme="light">详情内容</section>
+</dialog>
+~~~
 
-接入后合并以下规则，保留已有内容，不重复追加：
+~~~css
+/* 业务布局：保留原来的固定定位、层级、点击穿透，不是控件皮肤。 */
+.map-overlay { position: fixed; inset: 0; background: transparent; pointer-events: none; }
+.query-position { position: absolute; top: 24px; left: 24px; width: min(360px, calc(100% - 48px)); pointer-events: auto; }
+~~~
 
-> 本项目使用 sky-ui-kit 的 HTML 样式模式。先读取当前安装包 llms.txt 和 docs/HTML-INTEGRATION.md，核对 exports；只使用该版本实际提供的 CSS 入口和结构类；新版 HTML 模式仅给容器添加 sky-html，原生控件自动换肤，不给每个控件补类。基础主题必需，其余按需引入。保留原 DOM 标识及业务事件，不通过仿写组件内部 CSS 实现外观。需要完整组件交互时明确切换到真实 Vue 组件方案。升级后重新核对文档和实际出口。
+若确实需要让整个透明覆盖层成为共同主题容器，可在原布局类中明确保留背景：
 
-包内文档不会自动进入所有 AI 工具上下文；README 和项目规则提供发现入口，不能保证所有工具自动执行。
+~~~html
+<div id="workspace" class="map-overlay sky-html" data-theme="light">...</div>
+~~~
+~~~css
+/* 与库同等或更高优先级，仅保留透明布局；不复制按钮/输入框皮肤。 */
+.map-overlay.sky-html { background: transparent; }
+~~~
 
-## 验证范围
+两种方式任选其一，不修改库默认背景，不新增 #workspace 全局覆盖。浮层在主题容器内时自然继承；移动到 body 后须在其实际内容容器上新增 sky-html 和相同 data-theme，并将应用自定义公共主题变量设置在公共祖先（例如 html），或明确复制到两个边界。不要复制私有 --userssite-* 计算结果。明暗切换要同步所有主题边界；局部面板变量不会自动传给兄弟浮层。
 
-本次只进行文档生成和静态/类型检查，不构建、打包、发布或浏览器验证。示例网站展示当前源码；新增入口需安装 0.1.10 或更新版本。水库调度消费项目尚未修改，旧页面选择器冲突和视觉效果待用户验证。
+保留原定位、z-index、pointer-events、overflow 和弹窗 showModal/关闭逻辑；CSS 接入不会新增焦点管理、遮罩、定位或业务行为。检查父容器 overflow 是否裁剪浮层。把 sky-html 用在 body 是普通整页换肤的可选方案，不能作为所有 HTML 页面的要求。
 
-## 自动换肤与局部退出
+## 旧页面迁移前后：删除皮肤，保留布局和行为
 
-给单个控件或第三方区域添加 data-sky-native="off"，该节点及全部后代都不会匹配按钮/输入样式；里面再次出现 sky-html 也不重新开启。容器外元素不受影响。Element Plus 的 el- 类节点及后代、MapLibre/Mapbox 地图内部控件自动排除；其他第三方组件请显式退出。
-退出仅阻止控件皮肤，不撤销祖先继承的字体、颜色、变量；需要完全独立时放到主题容器之外。
+完整前后示例共享同一份 [布局](examples/html/migration/layout.css)和[业务脚本](examples/html/migration/business.js)。迁移前额外加载 [旧控件皮肤](examples/html/migration/legacy-controls.css)；迁移后移除该文件，新增库 CSS、主题容器、面板结构类及按钮语义。已有 DOM 节点与事件 ID 保留，未重新渲染业务控件。
 
-面板没有原生 HTML 控件，不自动给 div/section 加外观。使用已有 sky-model-panel 结构类，保留原 .panel 等类和事件，检查旧选择器冲突。不新增覆盖业务 .panel 的全局规则。完整示例见包内 examples/html/index.html。
+| 原规则类型 | 迁移处理 |
+|---|---|
+| #searchForm button、.query-position input 的背景/颜色/边框/圆角/字号/高度/内阴影 | 移除这些皮肤声明，交由库负责 |
+| :hover、:focus、:disabled、:checked、option:checked 等旧状态皮肤 | 同时移除，不能只改默认状态 |
+| 内联 style 的控件皮肤、!important 覆盖 | 从元素或旧规则删除，保留布局声明 |
+| position/inset/z-index/pointer-events、网格/列宽/gap、地图尺寸 | 继续保留在业务布局文件 |
+| 混合布局与皮肤的规则 | 按声明拆开：留下定位/布局，删除控件皮肤，不删除整条业务规则 |
+| 地图色带、阈值、图表配色、第三方地图内部 UI | 保留业务实现；必要时显式退出 |
 
-错误文案显式标记 data-sky-error，并用 aria-describedby 关联输入；不能自动把所有 span 识别为错误。默认控件高度 32px、圆角 4px，服从与 Vue 一致的 control-height-m、radius-s、font-size-body 覆盖。主题复制不包含字体二进制。仅承诺主题与控件表面规范一致，尚未完成浏览器视觉对照验证。
+示意：旧规则 #searchForm button { position:relative; background:#333; border:2px solid #777; } 只保留 position:relative；不能在库后面再写一套“更像 Vue”的 button 规则。
 
-## HTML 表单控件逐项验收模块
+旧 CSS 在前、库 CSS 在后只是加载约定，并不保证覆盖高优先级选择器、内联样式或 !important。使用开发者工具检查控件的 Styles/Computed：查 border/background/color/font/height/outline/box-shadow 的获胜规则；切换 :hover/:focus，并实际设置 disabled/checked/aria-invalid。追溯到旧声明后移除该皮肤来源，不继续叠加选择器或 !important。不能删除的第三方控件使用 data-sky-native="off"，并在验收中列为例外。
 
-网站新增独立“HTML 表单控件”导航，22 项按编号定位，每项包含真实原生标签、可操作状态、可复制代码及当前页核对标记。目录与生成文档共享 src/html-form-catalog.ts，详见 HTML-FORM-CATALOG.md。滑块/颜色/上传仍为原生外观；复杂 Vue 组件没有等价原生标签，不宣称实现对应交互。仅做类型和文档检查，等待用户逐项核对。
+## 控件、状态和能力边界
+
+sky-html 内原生控件自动换肤，不必逐个增加控件类。面板没有原生 HTML 对应物，使用 sky-model-panel、__header、__body、__footer 结构类；不把所有 div/section 变成面板。
+
+保留 button 的 type，data-variant="primary" / "danger" 控制语义；旧 primary/accent 类兼容。readonly/disabled/required 保留浏览器语义。错误输入使用 aria-invalid="true"，错误文字 data-sky-error，并通过 aria-describedby 关联；库不实现校验业务。不会在首次加载时把所有必填项标红。
+
+select 单选系统菜单、日期/时间弹层、文件窗口的外观及键盘行为存在浏览器差异，不承诺与 Vue 完全相同。多选支持 size，默认列表宽 220px，可用 --sky-select-list-width 调整，Ctrl/Command/Shift 遵循系统行为。checkbox/radio 提供主题皮肤；file-selector-button 已主题化；range/color/image 仍由浏览器绘制，hidden 不应用控件皮肤。
+
+数字增强是独立的可选原生 JS：加载 number.css，从 sky-ui-kit/html/number.js 导入 enhanceNumbers，DOM 就绪后调用。原 input 保持 id/name/事件，stepUp/stepDown 读取 min/max/step；发生变化后派发 input/change。返回函数用于清理，动态新增字段需再次初始化；step=any 禁用按钮，不提供长按重复。
+
+字体与 Vue 共享主题字体栈，但包不带字体文件；跨系统存在字形差异。公共主题变量应在公共祖先定义，默认高度 32px、圆角 4px，可通过 control-height-m、radius-s、font-size-body 调整。控件状态与主题规范共用不等于每个原生控件和 Vue 的像素/交互一致。
+
+## 局部退出
+
+data-sky-native="off" 使节点及其后代退出控件皮肤；内层 sky-html 不重新启用。Element Plus 和地图内部控件有排除规则，未知第三方区域需显式退出。退出不撤销继承的字体/颜色/主题变量；完全独立区域放在主题容器外。
+
+## 消费项目 AGENTS.md
+
+合并以下规则并保留原有内容；文档路径相对安装包根目录：
+
+> 本项目采用 sky-ui-kit 原生 HTML 样式路线。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
 
-## 原生数字增强、选择与文件输入
+## 验收：视觉和业务均通过才完成
 
-数字框可额外加载 html/number.css，并从 sky-ui-kit/html/number.js 导入 enhanceNumbers，在 DOM 就绪后执行，返回函数用于卸载。静态站复制 number.js/number.css 到同一静态目录，通过 module 脚本导入；保持原 input 的 id/name/监听器，步进使用浏览器 stepUp/stepDown，变化后派发 input/change。step=any 不启用按钮；不实现长按重复。
-select 单选弹出菜单仍由系统绘制，多选使用 size 行数和可滚动列表。file 输入仅美化文件按钮，不替换系统窗口、不发起上传。此前“上传保留原外观”的说明由此更新覆盖。
+1. 默认：字体、尺寸、圆角、内边距与库 HTML 示例一致；地图可见，面板位置和层级正确。
+2. 悬停：按钮、输入、可用选项使用主题色；禁用元素无可操作悬停表现。
+3. 聚焦：鼠标与 Tab 聚焦为单层输入边框，键盘焦点可辨识，错误仍保留危险色。
+4. 禁用/只读：外观正确，字段不可编辑，fieldset 禁用也生效。
+5. 选中：checkbox/radio/option 的选中与禁用选中状态正确；系统渲染差异列为限制。
+6. 业务：原查询、重置、提交、表单验证、地图点击/拖动、文件 change 及弹窗开关仍工作；不重复注册监听器。
+7. 浮层：与面板主题一致，明暗同步，未被裁剪或透明覆盖层遮挡。
 
-多选 select 使用列表皮肤，默认宽度 220px，可通过 --sky-select-list-width 覆盖；size 控制可见行数，最小约三行。选项选中、不可选及整组禁用沿用原生属性。Ctrl/Command/Shift 操作遵循系统规则，option 样式支持因浏览器而异，不承诺等同 Vue 浮层。
+记录浏览器/系统、包版本、各状态结果、冲突来源及剩余例外；对照 [逐项目录](docs/HTML-FORM-CATALOG.md)。安装成功、文件存在或 CSS 加载成功只证明资源接入，不能证明视觉和交互已完成。
+
+本轮修订检查了相对链接、示例结构/脚本和类型，并在授权发布流程中构建、核对安装包。未进行浏览器视觉验证或修改业务消费项目；地图占位示例不等于真实地图引擎集成验证。安装 0.1.11 或更新版本可获得本轮文档修订。
 
 ## 完整 HTML 示例
 
@@ -6942,3 +7013,140 @@ document.getElementById('theme').addEventListener('click', () => { const root =
 ```html
 <button type="button">已换肤</button><div data-sky-native="off"><button type="button">退出换肤</button><input placeholder="退出换肤" aria-label="退出换肤"></div>
 ```
+
+## HTML 迁移示例：before.html
+
+~~~html
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>原生地图悬浮面板 · 迁移前</title>
+<link rel="stylesheet" href="./legacy-controls.css">
+<link rel="stylesheet" href="./layout.css">
+</head>
+<body>
+<div id="map"><p id="mapStatus">地图布局占位，点击此背景可核对穿透（不加载地图引擎）。</p></div>
+<!-- 透明地图覆盖层不添加 sky-html。业务定位和穿透规则不变。 -->
+<div id="workspace">
+<section class="query-position" data-demo-theme data-theme="light">
+<header><h1>水库查询</h1><button id="theme" type="button">切换主题</button></header>
+<form id="searchForm" class="form-layout">
+<label class="field-layout" for="name">名称<input id="name" name="name" required placeholder="请输入名称"></label>
+<label class="field-layout" for="province">省份<select id="province" name="province" multiple size="3"><option selected>湖北</option><option>湖南</option><option>四川</option></select></label>
+<label><input name="enabled" type="checkbox" checked>仅显示可用项</label>
+<label>只读编码<input name="code" value="363" readonly></label>
+<div class="actions-layout"><button type="submit">查询</button><button type="reset">重置</button><button type="button" disabled>禁用操作</button></div>
+<output id="status" aria-live="polite">等待查询</output>
+</form>
+<footer><button id="openDetails" type="button">打开 body 浮层</button></footer>
+</section>
+</div>
+<dialog id="details" class="dialog-position">
+<!-- 浮层与查询面板是兄弟节点，明确使用自己的主题边界并同步 data-theme。 -->
+<section class="legacy-dialog" data-demo-theme data-theme="light">
+<header><h2>独立浮层</h2></header>
+<div><label>备注<input name="notes" placeholder="原生浮层输入"></label></div>
+<footer><button id="closeDetails" type="button">关闭</button></footer>
+</section>
+</dialog>
+<script src="./business.js"></script>
+</body></html>
+
+~~~
+
+## HTML 迁移示例：after.html
+
+~~~html
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>原生地图悬浮面板 · 迁移后</title>
+<!-- 包内示例相对 dist 路径；部署时将资源复制到网站静态目录并更新 href。 -->
+<link rel="stylesheet" href="../../../dist/html/theme.css">
+<link rel="stylesheet" href="../../../dist/html/panel.css">
+<link rel="stylesheet" href="../../../dist/html/button.css">
+<link rel="stylesheet" href="../../../dist/html/input.css">
+<link rel="stylesheet" href="./layout.css">
+</head>
+<body>
+<div id="map"><p id="mapStatus">地图布局占位，点击此背景可核对穿透（不加载地图引擎）。</p></div>
+<!-- 透明地图覆盖层不添加 sky-html。业务定位和穿透规则不变。 -->
+<div id="workspace">
+<section class="query-position sky-html sky-model-panel" data-demo-theme data-theme="light">
+<header class="sky-model-panel__header"><h1>水库查询</h1><button id="theme" type="button">切换主题</button></header>
+<form id="searchForm" class="form-layout sky-model-panel__body">
+<label class="field-layout" for="name">名称<input id="name" name="name" required placeholder="请输入名称"></label>
+<label class="field-layout" for="province">省份<select id="province" name="province" multiple size="3"><option selected>湖北</option><option>湖南</option><option>四川</option></select></label>
+<label><input name="enabled" type="checkbox" checked>仅显示可用项</label>
+<label>只读编码<input name="code" value="363" readonly></label>
+<div class="actions-layout"><button type="submit" data-variant="primary">查询</button><button type="reset">重置</button><button type="button" disabled>禁用操作</button></div>
+<output id="status" aria-live="polite">等待查询</output>
+</form>
+<footer class="sky-model-panel__footer"><button id="openDetails" type="button">打开 body 浮层</button></footer>
+</section>
+</div>
+<dialog id="details" class="dialog-position">
+<!-- 浮层与查询面板是兄弟节点，明确使用自己的主题边界并同步 data-theme。 -->
+<section class="sky-html sky-model-panel" data-demo-theme data-theme="light">
+<header class="sky-model-panel__header"><h2>独立浮层</h2></header>
+<div class="sky-model-panel__body"><label>备注<input name="notes" placeholder="原生浮层输入"></label></div>
+<footer class="sky-model-panel__footer"><button id="closeDetails" type="button">关闭</button></footer>
+</section>
+</dialog>
+<script src="./business.js"></script>
+</body></html>
+
+~~~
+
+## HTML 迁移示例：layout.css
+
+~~~css
+/* 迁移前后原样保留的业务布局，不负责控件皮肤。 */
+body { margin:0; }
+#map { position:fixed; inset:0; display:grid; place-items:center; background:repeating-linear-gradient(35deg,#b5d6c2 0 60px,#b9dbe8 60px 120px); }
+#workspace { position:fixed; inset:0; background:transparent; pointer-events:none; }
+.query-position { position:absolute; inset:24px auto auto 24px; width:min(360px,calc(100% - 48px)); pointer-events:auto; }
+.form-layout { display:grid; gap:16px; }
+.field-layout { display:grid; gap:6px; }
+.actions-layout { display:flex; flex-wrap:wrap; gap:12px; }
+.dialog-position { width:min(420px,calc(100% - 48px)); padding:0; border:0; }
+
+~~~
+
+## HTML 迁移示例：legacy-controls.css
+
+~~~css
+/* 旧皮肤：迁移后移除该文件，不用更强的选择器继续覆盖。 */
+.query-position { background:#eee; border:2px solid #555; padding:14px; }
+#searchForm input, #searchForm select { background:#ddd; color:#222; border:2px solid #555; border-radius:0; padding:4px; }
+#searchForm input:focus { outline:3px solid orange; }
+#searchForm button, #openDetails, #closeDetails { background:#333; color:white; border:2px solid #777; border-radius:0; height:28px; }
+#searchForm button:hover { background:#555; }
+#searchForm button:disabled { background:#999; color:#ccc; }
+#searchForm input:checked { accent-color:orange; }
+
+~~~
+
+## HTML 迁移示例：business.js
+
+~~~js
+/* 两个页面共用原生业务监听器，不创建/替换业务 DOM，不依赖 Vue。 */
+const form = document.getElementById('searchForm');
+const status = document.getElementById('status');
+form.addEventListener('submit', event => {
+ event.preventDefault();
+ const data = new FormData(form);
+ status.textContent = '查询：' + data.get('name') + '；已选省份：' + data.getAll('province').join('、');
+});
+form.addEventListener('reset', () => { status.textContent = '查询条件已重置'; });
+document.getElementById('map').addEventListener('click', () => { document.getElementById('mapStatus').textContent = '地图背景仍可点击'; });
+const dialog = document.getElementById('details');
+document.getElementById('openDetails').addEventListener('click', () => { dialog.showModal(); });
+document.getElementById('closeDetails').addEventListener('click', () => { dialog.close(); });
+document.getElementById('theme').addEventListener('click', () => {
+ const panels = document.querySelectorAll('[data-demo-theme]');
+ const next = panels[0].dataset.theme === 'dark' ? 'light' : 'dark';
+ panels.forEach(panel => { panel.dataset.theme = next; });
+});
+
+~~~

package/llms.txt

@@ -1,10 +1,10 @@
 # sky-ui-kit
 
-> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.10. AI tools must explicitly load these files.
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.11. AI tools must explicitly load these files.
 
 ## Documentation
 
-- [HTML and AI onboarding](docs/HTML-INTEGRATION.md): choose appearance or real components before setup; HTML needs no Element Plus CSS.
+- [HTML and AI onboarding](docs/HTML-INTEGRATION.md): native HTML migration retaining existing interactions, transparent map overlays and optional Vue route.
 
 - [Consumers](docs/CONSUMERS.md): shared project convention and local integration.
 - [AI guide](docs/AI-GUIDE.md): setup, examples, icon/event bindings and limits.
@@ -25,6 +25,6 @@
 
 ## 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.
+Native HTML: read docs/HTML-INTEGRATION.md first, retain DOM/events/forms, load supported html/*.css once, preserve transparent map overlays and remove conflicting legacy control skins. Vue is optional only when real Vue components are requested. Vue component route: import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts, and check components.json before using exports. Verify visual states and existing behavior; installing or loading CSS alone is not completion.
 
 - [HTML form checklist](docs/HTML-FORM-CATALOG.md): individual native control examples and verification limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sky-ui-kit",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Vue UI components compatible with Element Plus and the project theme",
   "type": "module",
   "files": [
@@ -28,7 +28,8 @@
     "docs/MODEL-WORKSPACE.md",
     "docs/HTML-INTEGRATION.md",
     "examples/html",
-    "docs/HTML-FORM-CATALOG.md"
+    "docs/HTML-FORM-CATALOG.md",
+    "docs/RELEASE-HISTORY.md"
   ],
   "exports": {
     ".": {
@@ -72,7 +73,8 @@
     "prepack": "npm run docs:ai && npm run build:package",
     "build:package": "vite build --config vite.package.config.ts && node scripts/build-package.mjs && vue-tsc -p tsconfig.package.json",
     "docs:ai": "node scripts/generate-ai-docs.mjs",
-    "components:sync": "node scripts/sync-element-plus.mjs"
+    "components:sync": "node scripts/sync-element-plus.mjs",
+    "docs:check-links": "node scripts/check-doc-links.mjs"
   },
   "peerDependencies": {
     "@element-plus/icons-vue": "^2.3.2",