sky-ui-kit 0.1.9 → 0.1.11

package/docs/AI-CHANGELOG.md

@@ -481,3 +481,49 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 
 - 将当前布局、面板、尺寸适配与主题调整纳入新版，重新生成 AI 文档并检查组件包。发布结果以 npm 注册表为准。
 
+
+## 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 仍成立。
+
+### 原生控件自动换肤调整（未发布）
+
+新增 sky-html 容器入口，按需样式直接匹配原生 button/input/select/textarea；支持 data-sky-native="off" 本身及后代退出、Element Plus/地图内部控件排除，保留旧工作区 opt-in。主题默认低优先级，特殊按钮使用 data-variant，支持只读、禁用、错误及焦点状态；面板继续使用明确结构类，不覆盖所有 div。示例网站展示完整原生 HTML 状态及退出区域，详见 HTML-INTEGRATION.md。
+
+### HTML 控件未换肤修复
+
+此前 Element Plus 排除规则使用 class 包含 el-，误命中 sky-model-panel，导致整块面板内原生控件不应用样式。改为类名开头或空格后的 el- 前缀匹配，保留显式局部退出和第三方控件隔离。补充 DOM 选择器回归检查；未进行浏览器视觉验证。
+
+### HTML / Vue 控件视觉统一（未发布）
+
+HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue 共用字体、默认 32px 高度、4px 圆角、主色/危险色及派生状态色；危险按钮为实底，禁用状态不再整体透明。补充复选框、单选框及 data-sky-error 错误文案。HTML 示例同步网站根主题变量。只验证源码和 DOM 选择器，未进行浏览器像素对比；原生 select 弹出菜单、日期选择器仍由浏览器提供。
+
+## HTML 表单控件逐项验收模块
+
+网站新增独立“HTML 表单控件”导航，22 项按编号定位，每项包含真实原生标签、可操作状态、可复制代码及当前页核对标记。目录与生成文档共享 src/html-form-catalog.ts，详见 HTML-FORM-CATALOG.md。滑块/颜色/上传仍为原生外观；复杂 Vue 组件没有等价原生标签，不宣称实现对应交互。仅做类型和文档检查，等待用户逐项核对。
+
+### HTML 输入聚焦双框修复
+
+文本输入、select、textarea 聚焦时取消外扩 outline 和额外阴影，仅将已有边框改为主题主色；错误状态聚焦/悬停继续保持危险色。复选框、单选框的键盘焦点提示不变。未进行浏览器验证。
+
+### 原生数字、选择和上传控件完善（未发布）
+
+多选 select 恢复列表高度，保留系统弹出菜单；file-selector-button 使用共享主题及禁用/聚焦状态。新增可选 html/number.js 与 number.css，enhanceNumbers 保留原 input、min/max/step 与事件，返回清理函数；step=any 禁用增减，动态新增节点需再次初始化。验收第 8/10/20 项同步更新。未构建或浏览器验证。
+
+### HTML 原生多选列表外观调整
+
+多选/size 列表设置可覆盖的 220px 宽度、选项留白和主题选中背景，补充悬停、选项禁用、整组禁用和高对比度规则；保留 size 与原生多选语义，不修改单选系统弹出菜单。第 10 项示例增加滚动及多选操作说明。未进行浏览器视觉验证。
+
+## 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

@@ -1,4 +1,10 @@
 # sky-ui-kit：AI 使用指南
+
+## AI 接入入口：先选择使用方式
+
+当用户要求引入 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 按需样式接入”演示和完整可复制代码。
 
 MapPageLayout 沿用参考项目 D:/Work/01-项目code/一体化平台/webv1/src/components/layout/TemplateLayout.vue 的 1/2/3/4/5/6 层级约定，并补齐底部时间轴和右侧面板。层级按区域统一管理：鼠标移入 left/top/toolbar/right/legend/timeline 时提升整个区域到 hover 层，优先于 focus-within；子展开面板随所属区域一起提升，移出后恢复。普通 content 限定在底层独立堆叠上下文，透明工具间隙穿透地图。图例和时间轴外层不再 overflow:auto 裁剪浮层；长内容滚动由内部业务组件负责。Teleport 到 body 的浮层仍由组件自身管理层级。预览“模拟模块遮挡”可核对重叠交互；完全被覆盖的部分不接收鼠标，应从模块可见区域移入。
 
@@ -264,6 +270,8 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 ```
 预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
 
+HTML 表单逐项示例见 [验收目录](HTML-FORM-CATALOG.md)，网站独立导航按编号核对；原生与 Vue 的边界见各项说明。
+
 <!-- GENERATED EXAMPLES -->
 
 ### 快速开始：安装最新正式版本
@@ -311,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：模块变更及接入影响
@@ -322,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

@@ -282,3 +282,35 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 <MapPageLayout :right-panel-width="320" :edge="12" :gap="8" />
 ```
 预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
+
+## 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 仍成立。
+
+### 原生控件自动换肤调整（未发布）
+
+新增 sky-html 容器入口，按需样式直接匹配原生 button/input/select/textarea；支持 data-sky-native="off" 本身及后代退出、Element Plus/地图内部控件排除，保留旧工作区 opt-in。主题默认低优先级，特殊按钮使用 data-variant，支持只读、禁用、错误及焦点状态；面板继续使用明确结构类，不覆盖所有 div。示例网站展示完整原生 HTML 状态及退出区域，详见 HTML-INTEGRATION.md。
+
+### HTML 控件未换肤修复
+
+此前 Element Plus 排除规则使用 class 包含 el-，误命中 sky-model-panel，导致整块面板内原生控件不应用样式。改为类名开头或空格后的 el- 前缀匹配，保留显式局部退出和第三方控件隔离。补充 DOM 选择器回归检查；未进行浏览器视觉验证。
+
+### HTML / Vue 控件视觉统一（未发布）
+
+HTML 控件直接复用 scoped-theme.css 的 userssite 主题变量，与 Vue 共用字体、默认 32px 高度、4px 圆角、主色/危险色及派生状态色；危险按钮为实底，禁用状态不再整体透明。补充复选框、单选框及 data-sky-error 错误文案。HTML 示例同步网站根主题变量。只验证源码和 DOM 选择器，未进行浏览器像素对比；原生 select 弹出菜单、日期选择器仍由浏览器提供。
+
+### HTML 输入聚焦双框修复
+
+文本输入、select、textarea 聚焦时取消外扩 outline 和额外阴影，仅将已有边框改为主题主色；错误状态聚焦/悬停继续保持危险色。复选框、单选框的键盘焦点提示不变。未进行浏览器验证。
+
+### 原生数字、选择和上传控件完善（未发布）
+
+多选 select 恢复列表高度，保留系统弹出菜单；file-selector-button 使用共享主题及禁用/聚焦状态。新增可选 html/number.js 与 number.css，enhanceNumbers 保留原 input、min/max/step 与事件，返回清理函数；step=any 禁用增减，动态新增节点需再次初始化。验收第 8/10/20 项同步更新。未构建或浏览器验证。
+
+### 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-FORM-CATALOG.md

@@ -0,0 +1,225 @@
+# HTML 表单逐项验收目录
+
+由 src/html-form-catalog.ts 生成，与网站导航、示例共用。每项均待用户视觉验收；未进行浏览器验证。
+
+复制下列片段到 sky-html 容器，按顺序加载 html/theme.css、html/button.css、html/input.css；完整入口及版本限制见 HTML-INTEGRATION.md。
+
+## 1. 按钮
+
+网站锚点：#html-form-button
+
+核对默认、主要、危险、禁用；鼠标悬停、按下及 Tab 聚焦。
+
+```html
+<button type="button">默认</button> <button type="button" data-variant="primary">主要</button> <button type="button" data-variant="danger">危险</button> <button type="button" disabled>禁用</button>
+```
+
+## 2. 文本输入
+
+网站锚点：#html-form-text
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="text" placeholder="请输入" aria-label="文本输入"></label><label>只读 <input type="text" readonly aria-label="只读"></label><label>禁用 <input type="text" disabled aria-label="禁用"></label><label>错误 <input type="text" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 3. 密码输入
+
+网站锚点：#html-form-password
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="password" placeholder="请输入" aria-label="密码输入"></label><label>只读 <input type="password" readonly aria-label="只读"></label><label>禁用 <input type="password" disabled aria-label="禁用"></label><label>错误 <input type="password" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 4. 搜索输入
+
+网站锚点：#html-form-search
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="search" placeholder="请输入" aria-label="搜索输入"></label><label>只读 <input type="search" readonly aria-label="只读"></label><label>禁用 <input type="search" disabled aria-label="禁用"></label><label>错误 <input type="search" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 5. 邮箱输入
+
+网站锚点：#html-form-email
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="email" placeholder="请输入" aria-label="邮箱输入"></label><label>只读 <input type="email" readonly aria-label="只读"></label><label>禁用 <input type="email" disabled aria-label="禁用"></label><label>错误 <input type="email" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 6. 电话输入
+
+网站锚点：#html-form-tel
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="tel" placeholder="请输入" aria-label="电话输入"></label><label>只读 <input type="tel" readonly aria-label="只读"></label><label>禁用 <input type="tel" disabled aria-label="禁用"></label><label>错误 <input type="tel" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 7. 网址输入
+
+网站锚点：#html-form-url
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="url" placeholder="请输入" aria-label="网址输入"></label><label>只读 <input type="url" readonly aria-label="只读"></label><label>禁用 <input type="url" disabled aria-label="禁用"></label><label>错误 <input type="url" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 8. 数字输入
+
+网站锚点：#html-form-number
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>默认 <input type="number" placeholder="请输入" aria-label="数字输入"></label><label>只读 <input type="number" readonly aria-label="只读"></label><label>禁用 <input type="number" disabled aria-label="禁用"></label><label>错误 <input type="number" aria-invalid="true" aria-describedby="error"></label><span id="error" data-sky-error>输入格式不正确</span>
+```
+
+## 9. 多行输入
+
+网站锚点：#html-form-textarea
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label>说明 <textarea rows="3" placeholder="请输入说明"></textarea></label><textarea rows="3" readonly aria-label="只读">只读内容</textarea><textarea rows="3" disabled aria-label="禁用">禁用内容</textarea>
+```
+
+## 10. 下拉选择
+
+网站锚点：#html-form-select
+
+单选保持系统弹出菜单；多选展示默认、已选、不可选、整组禁用及滚动。列表与 Vue 共享主题色，原生 option 的细节渲染仍受浏览器限制。
+
+```html
+<label>单选 <select><option value="">请选择</option><option>湖北</option><option>湖南</option></select></label><label>禁用单选 <select disabled><option>禁用</option></select></label><label>多选列表 <select name="provinces" multiple size="4" aria-describedby="multi-help"><option selected>湖北</option><option>湖南</option><option selected>四川</option><option disabled>贵州（不可选）</option><option>云南</option><option>重庆</option></select></label><label>禁用多选 <select multiple size="4" disabled><option selected>湖北</option><option>湖南</option><option selected>四川</option><option>贵州</option></select></label><p id="multi-help">多选：按住 Ctrl（macOS 为 Command）点击；Shift 可连续选择，键盘操作遵循系统规则。</p>
+```
+
+## 11. 复选框
+
+网站锚点：#html-form-checkbox
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label><input type="checkbox">未选</label><label><input type="checkbox" checked>已选</label><label><input type="checkbox" disabled>禁用</label><label><input type="checkbox" checked disabled>选中禁用</label>
+```
+
+## 12. 单选框
+
+网站锚点：#html-form-radio
+
+核对默认、输入、禁用、键盘聚焦状态。
+
+```html
+<label><input type="radio" name="kind" value="a" checked>选项 A</label><label><input type="radio" name="kind" value="b">选项 B</label><label><input type="radio" disabled>禁用</label><label><input type="radio" checked disabled>选中禁用</label>
+```
+
+## 13. 日期
+
+网站锚点：#html-form-date
+
+仅统一输入表面，弹出选择器由浏览器提供；不同浏览器支持和交互存在差异。
+
+```html
+<label>默认 <input type="date"></label><label>禁用 <input type="date" disabled></label>
+```
+
+## 14. 时间
+
+网站锚点：#html-form-time
+
+仅统一输入表面，弹出选择器由浏览器提供；不同浏览器支持和交互存在差异。
+
+```html
+<label>默认 <input type="time"></label><label>禁用 <input type="time" disabled></label>
+```
+
+## 15. 日期时间
+
+网站锚点：#html-form-datetime-local
+
+仅统一输入表面，弹出选择器由浏览器提供；不同浏览器支持和交互存在差异。
+
+```html
+<label>默认 <input type="datetime-local"></label><label>禁用 <input type="datetime-local" disabled></label>
+```
+
+## 16. 月份
+
+网站锚点：#html-form-month
+
+仅统一输入表面，弹出选择器由浏览器提供；不同浏览器支持和交互存在差异。
+
+```html
+<label>默认 <input type="month"></label><label>禁用 <input type="month" disabled></label>
+```
+
+## 17. 周
+
+网站锚点：#html-form-week
+
+仅统一输入表面，弹出选择器由浏览器提供；不同浏览器支持和交互存在差异。
+
+```html
+<label>默认 <input type="week"></label><label>禁用 <input type="week" disabled></label>
+```
+
+## 18. 滑块
+
+网站锚点：#html-form-range
+
+当前保留浏览器原生外观，尚未与 Vue 对应控件统一；此项用于记录差距，不代表已完成。
+
+```html
+<label>默认 <input type="range"></label><label>禁用 <input type="range" disabled></label>
+```
+
+## 19. 颜色
+
+网站锚点：#html-form-color
+
+当前保留浏览器原生外观，尚未与 Vue 对应控件统一；此项用于记录差距，不代表已完成。
+
+```html
+<label>默认 <input type="color"></label><label>禁用 <input type="color" disabled></label>
+```
+
+## 20. 文件上传
+
+网站锚点：#html-form-file
+
+文件按钮使用共享主题；核对默认、悬停、键盘聚焦、禁用和选择后文件名。系统文件窗口与原生 change 事件保留，不包含上传请求。
+
+```html
+<label>默认 <input type="file"></label><label>禁用 <input type="file" disabled></label>
+```
+
+## 21. 表单提交与重置
+
+网站锚点：#html-form-form
+
+使用浏览器 required 校验及 reset；示例提交只显示结果，不发送请求。
+
+```html
+<form><label>必填名称 <input name="name" required></label><button type="submit" data-variant="primary">提交验证</button><button type="reset">重置</button><output aria-live="polite"></output></form>
+```
+
+## 22. 样式隔离与退出
+
+网站锚点：#html-form-isolation
+
+退出区域保留原生皮肤，仍可能继承祖先字体；不要将其当成样式失效。
+
+```html
+<button type="button">已换肤</button><div data-sky-native="off"><button type="button">退出换肤</button><input placeholder="退出换肤" aria-label="退出换肤"></div>
+```

package/docs/HTML-INTEGRATION.md

@@ -0,0 +1,121 @@
+# 原生 HTML 样式接入与旧页面迁移
+
+## 目标、版本与路线
+
+本路线适用于已有 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 按钮 | 可选，主题后 |
+| 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 页面的要求。
+
+## 旧页面迁移前后：删除皮肤，保留布局和行为
+
+完整前后示例共享同一份 [布局](../examples/html/migration/layout.css)和[业务脚本](../examples/html/migration/business.js)。迁移前额外加载 [旧控件皮肤](../examples/html/migration/legacy-controls.css)；迁移后移除该文件，新增库 CSS、主题容器、面板结构类及按钮语义。已有 DOM 节点与事件 ID 保留，未重新渲染业务控件。
+
+| 原规则类型 | 迁移处理 |
+|---|---|
+| #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 规则。
+
+旧 CSS 在前、库 CSS 在后只是加载约定，并不保证覆盖高优先级选择器、内联样式或 !important。使用开发者工具检查控件的 Styles/Computed：查 border/background/color/font/height/outline/box-shadow 的获胜规则；切换 :hover/:focus，并实际设置 disabled/checked/aria-invalid。追溯到旧声明后移除该皮肤来源，不继续叠加选择器或 !important。不能删除的第三方控件使用 data-sky-native="off"，并在验收中列为例外。
+
+## 控件、状态和能力边界
+
+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 路线。按视觉状态和原有业务行为验收，记录系统控件差异和未支持项。升级后重新核对当前包。
+
+## 验收：视觉和业务均通过才完成
+
+1. 默认：字体、尺寸、圆角、内边距与库 HTML 示例一致；地图可见，面板位置和层级正确。
+2. 悬停：按钮、输入、可用选项使用主题色；禁用元素无可操作悬停表现。
+3. 聚焦：鼠标与 Tab 聚焦为单层输入边框，键盘焦点可辨识，错误仍保留危险色。
+4. 禁用/只读：外观正确，字段不可编辑，fieldset 禁用也生效。
+5. 选中：checkbox/radio/option 的选中与禁用选中状态正确；系统渲染差异列为限制。
+6. 业务：原查询、重置、提交、表单验证、地图点击/拖动、文件 change 及弹窗开关仍工作；不重复注册监听器。
+7. 浮层：与面板主题一致，明暗同步，未被裁剪或透明覆盖层遮挡。
+
+记录浏览器/系统、包版本、各状态结果、冲突来源及剩余例外；对照 [逐项目录](HTML-FORM-CATALOG.md)。安装成功、文件存在或 CSS 加载成功只证明资源接入，不能证明视觉和交互已完成。
+
+本轮修订检查了相对链接、示例结构/脚本和类型，并在授权发布流程中构建、核对安装包。未进行浏览器视觉验证或修改业务消费项目；地图占位示例不等于真实地图引擎集成验证。安装 0.1.11 或更新版本可获得本轮文档修订。

package/docs/INTEGRATION.md

@@ -206,3 +206,15 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 <MapPageLayout :right-panel-width="320" :edge="12" :gap="8" />
 ```
 预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
+
+## 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 仍成立。
+
+### 原生控件自动换肤调整（未发布）
+
+新增 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

@@ -36,3 +36,11 @@ import { MapSideMenu } from 'sky-ui-kit/components/MapSideMenu'
 | SvgIcon | 1092502 / 364357 B | 2224 / 1163 B |
 
 主入口文件从约 1161 KB 降到 178 KB，但还有共享 chunk；不能只看入口文件判断网站下载量。上表已包含各示例引用的库共享代码。可选 icons.js 约 980 KB，npm 安装包仍包含它；网站不导入即可不进入组件依赖链。
+
+## 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 仍成立。
+
+### 原生控件自动换肤调整（未发布）
+
+新增 sky-html 容器入口，按需样式直接匹配原生 button/input/select/textarea；支持 data-sky-native="off" 本身及后代退出、Element Plus/地图内部控件排除，保留旧工作区 opt-in。主题默认低优先级，特殊按钮使用 data-variant，支持只读、禁用、错误及焦点状态；面板继续使用明确结构类，不覆盖所有 div。示例网站展示完整原生 HTML 状态及退出区域，详见 HTML-INTEGRATION.md。

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/index.html

@@ -0,0 +1,41 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>HTML 按需样式 · sky-ui-kit</title>
+<!-- 包内打开此示例时使用相对路径；部署时复制 dist/html 并调整 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">
+</head>
+<body>
+<div class="sky-html" data-theme="light">
+<main class="sky-model-workspace__content">
+<section class="sky-model-panel">
+<header class="sky-model-panel__header"><h2>水库查询 · 原生 HTML</h2><button id="theme" type="button">切换明暗</button></header>
+<form id="query">
+<div class="sky-model-panel__body"><label>水库名称 <input name="reservoir" placeholder="例如：三峡" required></label></div>
+<footer class="sky-model-panel__footer"><output id="result" aria-live="polite">等待查询</output><div><button type="reset">重置</button> <button data-variant="primary" type="submit">查询</button> <button disabled>禁用状态</button></div></footer>
+</form>
+<div class="sky-model-panel__body">
+<p><label>省份 <select name="province"><option>全部省份</option><option>湖北</option></select></label></p>
+<p><label>调度说明 <textarea name="notes" placeholder="沿用原生多行输入"></textarea></label></p>
+<p><label>只读编码 <input readonly value="363"></label> <label>禁用输入 <input disabled value="暂不可修改"></label></p>
+<p><label>错误状态 <input aria-invalid="true" aria-describedby="error" value="无效编码"></label> <span id="error" data-sky-error>请输入有效编码</span></p>
+<p><button type="button" data-variant="danger">危险操作</button> <input type="button" value="原生 input 按钮"></p>
+<p><label><input type="checkbox"> 与 Vue 主题一致的复选框</label></p>
+<div data-sky-native="off"><p>局部退出：以下控件不应用库的控件皮肤。</p><button type="button">原生按钮</button> <input aria-label="退出换肤的输入框" placeholder="保持原有外观"></div>
+</div>
+</section>
+</main>
+</div>
+<script>
+const form = document.getElementById('query');
+const result = document.getElementById('result');
+form.addEventListener('submit', event => { event.preventDefault(); result.textContent = '查询条件：' + new FormData(form).get('reservoir'); });
+form.addEventListener('reset', () => { result.textContent = '等待查询'; });
+document.getElementById('theme').addEventListener('click', () => { const root = document.querySelector('.sky-html'); root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark'; });
+</script>
+</body>
+</html>

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>