sky-ui-kit 0.1.10 → 0.1.12

package/README.md

@@ -1,8 +1,8 @@
 # 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 时，必须先读取[引导式接入流程](docs/START-HERE.md)，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 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.12，package.json 未设置 private 限制。HTML 按需样式和数字增强入口从 0.1.10 提供；0.1.12 增加先询问 HTML/Vue 的引导式接入流程；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.12",
   "elementPlusVersion": "2.14.7",
   "setup": {
     "cssOnce": [

package/docs/AI-CHANGELOG.md

@@ -517,3 +517,17 @@ 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；新增透明地图覆盖层、独立浮层主题、旧皮肤移除及前后迁移示例。发布检查包括生成文档、相对链接/包内路径、类型和库构建；未进行浏览器视觉或真实地图验收。
+
+## 0.1.12 引导式接入
+
+新增唯一 START-HERE.md 入口，要求先询问 HTML/JavaScript 或 Vue 并等待用户回答，再确认目标与范围；明确回答不重复问，不确定时只读检查后请用户确认。README、llms 生成源、AI/HTML/迁移/主题/按需指南及网站快速开始共用此规则。HTML 保留已有交互，Vue 为用户明确选择的路线。包不会自行弹出问答，需 AI 阅读文档后执行。

package/docs/AI-GUIDE.md

@@ -1,8 +1,8 @@
 # sky-ui-kit：AI 使用指南
 
-## 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 时，必须先读取[引导式接入流程](START-HERE.md)，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 Vue。按所选路线读取后续指南并合并项目 AGENTS.md；不能以安装成功或 CSS 已加载代替视觉及行为验收。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -319,18 +319,13 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 ### 快速开始：团队 AI 读取提示
 
 ```text
-请先读取 node_modules/sky-ui-kit/llms.txt，并按索引读取：
-- components.json：当前已安装版本的公开组件与 API 清单
-- docs/AI-GUIDE.md：使用规则和完整示例
-- docs/AI-CHANGELOG.md：模块变更及接入影响
-- docs/COMPONENT-API.md：属性、事件、插槽与类型
-- docs/CSS-THEME.md：主题变量、样式隔离与浮层限制
-- docs/INTEGRATION.md：原项目替换和业务接线
-- docs/COMPONENT-USAGE.md：原项目实际使用的组件与调用位置
-- docs/ADAPTATION.md：逐模块替换、Vite 图标配置、主题及业务适配方案
-
-请依据当前已安装包的版本与文档生成代码，不要虚构组件名称或 API。
-公共 CSS 仅在 main.ts 引入一次；业务请求、路由、权限由应用接入。
+请读取 node_modules/sky-ui-kit/llms.txt 和 docs/START-HERE.md。
+请先问我这次接入 HTML/JavaScript 还是 Vue，等待我的回答，不要根据项目文件直接猜测。
+然后按我的选择询问页面范围和目标：HTML 保留现有 DOM/事件/表单，仅统一支持的控件样式；
+Vue 询问是使用真实组件还是仅给原生控件换肤。已经明确提供的信息不重复询问。
+我选择“不确定”时再检查项目并请我确认。回答前只做文档读取和只读检查，不执行路线相关配置。
+按所选路线查阅包内指南及真实 exports，保留已有项目规则并合并到 AGENTS.md。
+完成后报告状态外观、原有业务行为的验证结果与剩余限制，不把安装成功视为接入完成。
 ```
 
 ### 图标安装：内置与自有资源

package/docs/CSS-THEME.md

@@ -1,4 +1,6 @@
 # CSS 变量主题与样式隔离
+
+接入前必须先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 MapPageLayout 使用 --map-layout-layer-content/panel/legend/toolbar/focus/hover 统一区域层级。与原平台一致：content=1、panel=2、legend=3、toolbar=4、focus=5、hover=6，时间轴和右栏同样参与；hover 高于 focus；content 内部即使使用较大 z-index 也不跨越区域堆叠上下文。图例和底部外层允许内容溢出，避免浮层被父区域裁剪；内部滚动由业务组件负责。
 
@@ -310,3 +312,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,125 @@
-# 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 报告为组件接入完成。
+先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案再配置。本文是用户选择原生控件换肤后的实施指南，不用于 AI 自行选择技术路线。
 
-## 安装和按需入口
+## 目标、版本与路线
 
-纯 HTML 只消费 CSS，不需要 Vue/Element Plus 运行时。npm 默认可能自动安装 peerDependencies；独立的 CSS 资源下载目录可用 npm install --legacy-peer-deps sky-ui-kit@指定版本，已有 Vue 工程不要借此绕过依赖检查。
+本路线适用于已有 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 文档不会随仓库更新。
+
+## 安装和资源部署
+
+~~~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 样式路线，接入范围按本项目记录。后续新增接入先按 docs/START-HERE.md 确认未明确的路线及范围，不从项目结构自行猜测。先读当前安装包 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

@@ -1,4 +1,6 @@
 # 主题接入规则更新
+
+接入前必须先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 ## 新布局接入（源码尚未发布）
 
@@ -214,3 +216,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/ON-DEMAND.md

@@ -1,4 +1,6 @@
 # 按需引入
+
+接入前必须先按 [引导式接入流程](START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 下一次发布后支持独立组件路径：
 

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/docs/START-HERE.md

@@ -0,0 +1,55 @@
+# 引导式接入：先问用户，再配置
+
+这是 README、llms.txt 和各接入指南共用的唯一流程入口。规则从 0.1.12 提供。安装包不会自动向用户弹出问答，也不会自动进入所有 AI 上下文；AI 阅读此入口后应主动执行下面的问答。
+
+## 第一步：确认用户使用 HTML 还是 Vue
+
+当用户说“帮我引入 sky-ui-kit”或安装后要求接入时，先问：
+
+> 这次要接入的是哪一种页面？
+> 1. 原生 HTML / JavaScript 页面
+> 2. Vue 3 页面
+> 3. 我不确定，请帮我检查后说明
+
+等待用户回答，再执行路线相关的文件修改、样式加载或框架依赖安装。不要根据 package.json、扩展名或当前目录擅自替用户选择。可以先阅读包内文档、核对已安装版本和只读检查项目。
+用户在本次对话已明确回答 HTML/Vue 时，直接采用该答案，不重复询问；该答案来自用户，不是 AI 猜测。用户选择“不确定”时才检查项目，说明发现并请用户确认接入的具体页面类型；混合项目需确认目标页面。
+
+## 第二步：按答案询问接入目标
+
+HTML 用户：
+
+> 你希望在哪些地方使用统一样式？
+> 1. 先改一个现有页面或面板，保留原来的操作逻辑
+> 2. 整个现有站点换肤，保留原来的操作逻辑
+> 3. 创建一个新的原生 HTML 示例页面
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+HTML 的查询、表单校验、分页、弹窗等现有交互继续使用原业务 JS，不把“需要交互”解释为“必须迁移 Vue”。只有用户主动要求真实 Vue 组件能力时，才说明可选局部挂载及成本，并等待其选择。
+
+Vue 用户：
+
+> 你希望怎样使用这个包？
+> 1. 使用库实际导出的 Vue 组件开发或替换页面
+> 2. 仅给现有原生 HTML 控件统一样式，保留现有逻辑
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+答案已明确时不重复问；缺失答案不能通过等待超时自动补成默认选择。用户暂未回答时只做不依赖答案的读取工作。
+
+## 第三步：实施所选路线
+
+| 用户选择 | 阅读资料 | 实施要求 |
+|---|---|---|
+| HTML 或 Vue 中原生元素换肤 | [HTML 迁移](HTML-INTEGRATION.md)、[控件验收](HTML-FORM-CATALOG.md) | 保留 DOM/id/name/监听器/表单，按需 CSS，删除冲突旧皮肤、保留布局 |
+| Vue 真实组件 | [AI 指南](AI-GUIDE.md)、[真实出口](../components.json)、[API](COMPONENT-API.md)、[主题](CSS-THEME.md) | 核对 Vue/peerDependencies，按实际导出使用组件 |
+
+记录用户确认的页面、路线与范围，简要说明将引入的资源，再实施；不额外要求用户确认每个常规修改。遇到地图透明覆盖层、浮层、旧 CSS 冲突时按 HTML 指南处理，不改成不透明整页工作区，也不通过仿写控件皮肤覆盖。
+需要本地源码路径才能完成的指引应作为文档缺口报告；消费者只依赖当前安装包。
+
+## 第四步：记录项目规则并逐状态验收
+
+将用户选择、接入范围、包内入口、主题位置及验收规则合并到消费项目 AGENTS.md，保留已有规则，不重复追加。不自动创建消费项目不存在的 Vue 依赖或迁移技术栈。
+核对默认、悬停、聚焦、错误、只读、禁用、选中及浮层，检查查询/提交/重置/地图操作等原行为。区分已做的静态检查和用户/浏览器实际验证，列出系统 select/日期等浏览器差异；安装成功或 CSS 已加载不等于完成视觉接入。
+
+## 新聊天测试
+
+用户只说“帮我引入 sky-ui-kit”。期望 AI 先询问 HTML/Vue，等待回答；随后按所选路线询问范围并执行。不得直接注册 Vue、套上全页背景或把页面改成库组件。已明确的答案不再重复询问。

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,14 @@
 # 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.12. AI tools must explicitly load these files.
+
+## Mandatory onboarding
+
+Read [Start here](docs/START-HERE.md). Ask the user HTML/JavaScript or Vue FIRST and wait for their answer before route-specific edits or dependency configuration. Then ask scope and intended usage. Do not infer the route from project files. Reuse answers explicitly provided by the user; inspect only when they choose unsure, then ask them to confirm. HTML keeps existing DOM/events/forms and does not require Vue.
 
 ## 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 +29,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.
+After the required user Q&A in docs/START-HERE.md, native HTML: read docs/HTML-INTEGRATION.md, 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 接入入口：先选择使用方式
+## 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 时，必须先读取[引导式接入流程](docs/START-HERE.md)，先询问用户接入 HTML/JavaScript 还是 Vue，再询问页面范围及接入目标，等待回答后配置。不得仅根据项目文件猜测路线；用户在当前对话已经明确的答案不重复询问。HTML 换肤保留原 DOM、业务事件和表单，不要求 Vue。按所选路线读取后续指南并合并项目 AGENTS.md；不能以安装成功或 CSS 已加载代替视觉及行为验收。
 
 HTML 按需入口从 0.1.10 提供；0.1.9 使用完整 model-workspace.css。示例网站快速开始下方提供“HTML 按需样式接入”演示和完整可复制代码。
 
@@ -299,7 +303,7 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 ```
 预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
 
-HTML 表单逐项示例见 [验收目录](HTML-FORM-CATALOG.md)，网站独立导航按编号核对；原生与 Vue 的边界见各项说明。
+HTML 表单逐项示例见 [验收目录](docs/HTML-FORM-CATALOG.md)，网站独立导航按编号核对；原生与 Vue 的边界见各项说明。
 
 <!-- GENERATED EXAMPLES -->
 
@@ -348,18 +352,13 @@ function confirm() { UiMessage.success('当前站点：' + station.value) }
 ### 快速开始：团队 AI 读取提示
 
 ```text
-请先读取 node_modules/sky-ui-kit/llms.txt，并按索引读取：
-- components.json：当前已安装版本的公开组件与 API 清单
-- docs/AI-GUIDE.md：使用规则和完整示例
-- docs/AI-CHANGELOG.md：模块变更及接入影响
-- docs/COMPONENT-API.md：属性、事件、插槽与类型
-- docs/CSS-THEME.md：主题变量、样式隔离与浮层限制
-- docs/INTEGRATION.md：原项目替换和业务接线
-- docs/COMPONENT-USAGE.md：原项目实际使用的组件与调用位置
-- docs/ADAPTATION.md：逐模块替换、Vite 图标配置、主题及业务适配方案
-
-请依据当前已安装包的版本与文档生成代码，不要虚构组件名称或 API。
-公共 CSS 仅在 main.ts 引入一次；业务请求、路由、权限由应用接入。
+请读取 node_modules/sky-ui-kit/llms.txt 和 docs/START-HERE.md。
+请先问我这次接入 HTML/JavaScript 还是 Vue，等待我的回答，不要根据项目文件直接猜测。
+然后按我的选择询问页面范围和目标：HTML 保留现有 DOM/事件/表单，仅统一支持的控件样式；
+Vue 询问是使用真实组件还是仅给原生控件换肤。已经明确提供的信息不重复询问。
+我选择“不确定”时再检查项目并请我确认。回答前只做文档读取和只读检查，不执行路线相关配置。
+按所选路线查阅包内指南及真实 exports，保留已有项目规则并合并到 AGENTS.md。
+完成后报告状态外观、原有业务行为的验证结果与剩余限制，不把安装成功视为接入完成。
 ```
 
 ### 图标安装：内置与自有资源
@@ -3268,7 +3267,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 +3574,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 +3608,20 @@ 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；新增透明地图覆盖层、独立浮层主题、旧皮肤移除及前后迁移示例。发布检查包括生成文档、相对链接/包内路径、类型和库构建；未进行浏览器视觉或真实地图验收。
+
+## 0.1.12 引导式接入
+
+新增唯一 START-HERE.md 入口，要求先询问 HTML/JavaScript 或 Vue 并等待用户回答，再确认目标与范围；明确回答不重复问，不确定时只读检查后请用户确认。README、llms 生成源、AI/HTML/迁移/主题/按需指南及网站快速开始共用此规则。HTML 保留已有交互，Vue 为用户明确选择的路线。包不会自行弹出问答，需 AI 阅读文档后执行。
+
 # 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.
@@ -5881,6 +5894,8 @@ UiContainer 展示系统顶部/侧栏/内容和地图浮动区域示例。原 Ma
 | src/components/widgets/Legend.vue | 0 | 未发现直接引用，需检查间接 / 动态使用 | vue<br>vue-router |
 
 # CSS 变量主题与样式隔离
+
+接入前必须先按 [引导式接入流程](docs/START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 MapPageLayout 使用 --map-layout-layer-content/panel/legend/toolbar/focus/hover 统一区域层级。与原平台一致：content=1、panel=2、legend=3、toolbar=4、focus=5、hover=6，时间轴和右栏同样参与；hover 高于 focus；content 内部即使使用较大 z-index 也不跨越区域堆叠上下文。图例和底部外层允许内容溢出，避免浮层被父区域裁剪；内部滚动由业务组件负责。
 
@@ -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,7 +6208,13 @@ 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)。本轮仅文档、示例及生成器修订，未构建、发布或浏览器验证。
+
 # 按需引入
+
+接入前必须先按 [引导式接入流程](docs/START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案后再采用本文对应路线；不得从项目结构自行猜测。
 
 下一次发布后支持独立组件路径：
 
@@ -6234,7 +6255,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 +6621,131 @@ metricslab降水播放轴使用TemplateLayout.timeline插槽；timelineLeft/time
 
 2026-10-20：media-ui最新用户约定仅消费npm sky-ui-kit@0.1.6，开发和交付均移除源码alias；库能力后续需发布可安装版本后应用再升级。
 
-# HTML 样式与 AI 接入流程
+# 原生 HTML 样式接入与旧页面迁移
+
+## 开始前先完成接入问答
+
+先按 [引导式接入流程](docs/START-HERE.md)询问用户 HTML/Vue 和目标范围，等待答案再配置。本文是用户选择原生控件换肤后的实施指南，不用于 AI 自行选择技术路线。
+
+## 目标、版本与路线
 
-## 状态与选择
+本路线适用于已有 HTML/JavaScript 页面、服务端模板以及 Vue 页面中的原生元素：统一库支持的控件表面样式，保留原 DOM、id/name/data 属性、监听器、表单提交和业务行为。不要求迁移 Vue，也不因页面包含查询、校验、弹窗等交互而切换技术栈。
+只有用户明确需要真实 UiSelect 等 Vue 组件及其组件 API 时，才考虑 [Vue 接入](docs/AI-GUIDE.md)或局部挂载；这是可选路线。
 
-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 报告为组件接入完成。
+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 | 数字输入增减增强 | 可选，输入样式后 |
 
-完整 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 变成面板。
 
-数字框可额外加载 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 输入仅美化文件按钮，不替换系统窗口、不发起上传。此前“上传保留原外观”的说明由此更新覆盖。
+保留 button 的 type，data-variant="primary" / "danger" 控制语义；旧 primary/accent 类兼容。readonly/disabled/required 保留浏览器语义。错误输入使用 aria-invalid="true"，错误文字 data-sky-error，并通过 aria-describedby 关联；库不实现校验业务。不会在首次加载时把所有必填项标红。
 
-多选 select 使用列表皮肤，默认宽度 220px，可通过 --sky-select-list-width 覆盖；size 控制可见行数，最小约三行。选项选中、不可选及整组禁用沿用原生属性。Ctrl/Command/Shift 操作遵循系统规则，option 样式支持因浏览器而异，不承诺等同 Vue 浮层。
+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 样式路线，接入范围按本项目记录。后续新增接入先按 docs/START-HERE.md 确认未明确的路线及范围，不从项目结构自行猜测。先读当前安装包 llms.txt、docs/HTML-INTEGRATION.md、docs/HTML-FORM-CATALOG.md 并核对 exports。保留原 DOM、监听器、表单与地图行为；使用受支持的库控件皮肤，删除冲突的旧默认及状态皮肤声明，保留布局。透明地图覆盖层不得因主题变为实底；浮层主题边界明确设置。不得通过叠加仿写皮肤补丁实现一致性。只有明确需要真实 Vue 组件才选择可选 Vue 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
+
+## 验收：视觉和业务均通过才完成
+
+1. 默认：字体、尺寸、圆角、内边距与库 HTML 示例一致；地图可见，面板位置和层级正确。
+2. 悬停：按钮、输入、可用选项使用主题色；禁用元素无可操作悬停表现。
+3. 聚焦：鼠标与 Tab 聚焦为单层输入边框，键盘焦点可辨识，错误仍保留危险色。
+4. 禁用/只读：外观正确，字段不可编辑，fieldset 禁用也生效。
+5. 选中：checkbox/radio/option 的选中与禁用选中状态正确；系统渲染差异列为限制。
+6. 业务：原查询、重置、提交、表单验证、地图点击/拖动、文件 change 及弹窗开关仍工作；不重复注册监听器。
+7. 浮层：与面板主题一致，明暗同步，未被裁剪或透明覆盖层遮挡。
+
+记录浏览器/系统、包版本、各状态结果、冲突来源及剩余例外；对照 [逐项目录](docs/HTML-FORM-CATALOG.md)。安装成功、文件存在或 CSS 加载成功只证明资源接入，不能证明视觉和交互已完成。
+
+本轮修订检查了相对链接、示例结构/脚本和类型，并在授权发布流程中构建、核对安装包。未进行浏览器视觉验证或修改业务消费项目；地图占位示例不等于真实地图引擎集成验证。安装 0.1.11 或更新版本可获得本轮文档修订。
 
 ## 完整 HTML 示例
 
@@ -6942,3 +7019,196 @@ 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; });
+});
+
+~~~
+
+# 引导式接入：先问用户，再配置
+
+这是 README、llms.txt 和各接入指南共用的唯一流程入口。规则从 0.1.12 提供。安装包不会自动向用户弹出问答，也不会自动进入所有 AI 上下文；AI 阅读此入口后应主动执行下面的问答。
+
+## 第一步：确认用户使用 HTML 还是 Vue
+
+当用户说“帮我引入 sky-ui-kit”或安装后要求接入时，先问：
+
+> 这次要接入的是哪一种页面？
+> 1. 原生 HTML / JavaScript 页面
+> 2. Vue 3 页面
+> 3. 我不确定，请帮我检查后说明
+
+等待用户回答，再执行路线相关的文件修改、样式加载或框架依赖安装。不要根据 package.json、扩展名或当前目录擅自替用户选择。可以先阅读包内文档、核对已安装版本和只读检查项目。
+用户在本次对话已明确回答 HTML/Vue 时，直接采用该答案，不重复询问；该答案来自用户，不是 AI 猜测。用户选择“不确定”时才检查项目，说明发现并请用户确认接入的具体页面类型；混合项目需确认目标页面。
+
+## 第二步：按答案询问接入目标
+
+HTML 用户：
+
+> 你希望在哪些地方使用统一样式？
+> 1. 先改一个现有页面或面板，保留原来的操作逻辑
+> 2. 整个现有站点换肤，保留原来的操作逻辑
+> 3. 创建一个新的原生 HTML 示例页面
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+HTML 的查询、表单校验、分页、弹窗等现有交互继续使用原业务 JS，不把“需要交互”解释为“必须迁移 Vue”。只有用户主动要求真实 Vue 组件能力时，才说明可选局部挂载及成本，并等待其选择。
+
+Vue 用户：
+
+> 你希望怎样使用这个包？
+> 1. 使用库实际导出的 Vue 组件开发或替换页面
+> 2. 仅给现有原生 HTML 控件统一样式，保留现有逻辑
+> 请告诉我对应页面或目录；如果你已经提供，我会直接使用。
+
+答案已明确时不重复问；缺失答案不能通过等待超时自动补成默认选择。用户暂未回答时只做不依赖答案的读取工作。
+
+## 第三步：实施所选路线
+
+| 用户选择 | 阅读资料 | 实施要求 |
+|---|---|---|
+| HTML 或 Vue 中原生元素换肤 | [HTML 迁移](docs/HTML-INTEGRATION.md)、[控件验收](docs/HTML-FORM-CATALOG.md) | 保留 DOM/id/name/监听器/表单，按需 CSS，删除冲突旧皮肤、保留布局 |
+| Vue 真实组件 | [AI 指南](docs/AI-GUIDE.md)、[真实出口](components.json)、[API](docs/COMPONENT-API.md)、[主题](docs/CSS-THEME.md) | 核对 Vue/peerDependencies，按实际导出使用组件 |
+
+记录用户确认的页面、路线与范围，简要说明将引入的资源，再实施；不额外要求用户确认每个常规修改。遇到地图透明覆盖层、浮层、旧 CSS 冲突时按 HTML 指南处理，不改成不透明整页工作区，也不通过仿写控件皮肤覆盖。
+需要本地源码路径才能完成的指引应作为文档缺口报告；消费者只依赖当前安装包。
+
+## 第四步：记录项目规则并逐状态验收
+
+将用户选择、接入范围、包内入口、主题位置及验收规则合并到消费项目 AGENTS.md，保留已有规则，不重复追加。不自动创建消费项目不存在的 Vue 依赖或迁移技术栈。
+核对默认、悬停、聚焦、错误、只读、禁用、选中及浮层，检查查询/提交/重置/地图操作等原行为。区分已做的静态检查和用户/浏览器实际验证，列出系统 select/日期等浏览器差异；安装成功或 CSS 已加载不等于完成视觉接入。
+
+## 新聊天测试
+
+用户只说“帮我引入 sky-ui-kit”。期望 AI 先询问 HTML/Vue，等待回答；随后按所选路线询问范围并执行。不得直接注册 Vue、套上全页背景或把页面改成库组件。已明确的答案不再重复询问。

package/llms.txt

@@ -1,10 +1,14 @@
 # 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.12. AI tools must explicitly load these files.
+
+## Mandatory onboarding
+
+Read [Start here](docs/START-HERE.md). Ask the user HTML/JavaScript or Vue FIRST and wait for their answer before route-specific edits or dependency configuration. Then ask scope and intended usage. Do not infer the route from project files. Reuse answers explicitly provided by the user; inspect only when they choose unsure, then ask them to confirm. HTML keeps existing DOM/events/forms and does not require Vue.
 
 ## 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 +29,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.
+After the required user Q&A in docs/START-HERE.md, native HTML: read docs/HTML-INTEGRATION.md, 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.12",
   "description": "Vue UI components compatible with Element Plus and the project theme",
   "type": "module",
   "files": [
@@ -28,7 +28,9 @@
     "docs/MODEL-WORKSPACE.md",
     "docs/HTML-INTEGRATION.md",
     "examples/html",
-    "docs/HTML-FORM-CATALOG.md"
+    "docs/HTML-FORM-CATALOG.md",
+    "docs/RELEASE-HISTORY.md",
+    "docs/START-HERE.md"
   ],
   "exports": {
     ".": {
@@ -72,7 +74,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",