sky-ui-kit 0.1.9 → 0.1.10

package/llms-full.txt

@@ -1,9 +1,11 @@
 # sky-ui-kit
 
-> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.9. AI tools must explicitly load these files.
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.10. 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.
+
 - [Consumers](docs/CONSUMERS.md): shared project convention and local integration.
 - [AI guide](docs/AI-GUIDE.md): setup, examples, icon/event bindings and limits.
 - [Component API](docs/COMPONENT-API.md): props, defaults, events, slots and types.
@@ -26,6 +28,12 @@
 Import element-plus/dist/index.css then sky-ui-kit/style.css once in main.ts. Import components from sky-ui-kit. No package theme store. Check components.json before using any export.
 
 # sky-ui-kit：AI 使用指南
+
+## 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 报告为完整组件接入。
+
+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 的浮层仍由组件自身管理层级。预览“模拟模块遮挡”可核对重叠交互；完全被覆盖的部分不接收鼠标，应从模块可见区域移入。
 
@@ -291,6 +299,8 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 ```
 预览入口：MapPageLayout布局演示，点击“查看紧凑尺寸”比较右栏宽度、边距与面板内边距。其他组件参数与默认值可在生成API查询。当前未构建、打包、发布或浏览器验证，用户预览确认后自行发版。
 
+HTML 表单逐项示例见 [验收目录](HTML-FORM-CATALOG.md)，网站独立导航按编号核对；原生与 Vue 的边界见各项说明。
+
 <!-- GENERATED EXAMPLES -->
 
 ### 快速开始：安装最新正式版本
@@ -3563,6 +3573,42 @@ 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 接入规则。发布前重新生成文档和构建，并检查包内出口。浏览器视觉验收及独立消费业务项目测试仍由用户继续完成。
+
 # 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.
@@ -6119,6 +6165,34 @@ ManagementResourceLayout默认按VFit保持结构，不在700px阈值自动切
 ```
 预览入口：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 项示例增加滚动及多选操作说明。未进行浏览器视觉验证。
+
 # 按需引入
 
 下一次发布后支持独立组件路径：
@@ -6158,6 +6232,14 @@ import { MapSideMenu } from 'sky-ui-kit/components/MapSideMenu'
 
 主入口文件从约 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。
+
 # 模型工作区统一主题
 
 参考四个项目实际样式：分布式水文模型 hydrogrid/frontend/src/styles/workspace-theme.css；水资源配置 app/static/workspace-theme.css；新安江 static/style.css 后段覆盖；LSTM前端预报模型Git/web_ui_prototype.html 的 light/dark token。新安江前段旧深色规则不是最终主题。
@@ -6517,3 +6599,346 @@ metricslab降水播放轴使用TemplateLayout.timeline插槽；timelineLeft/time
 2026-10-16：metricslab用户使用范围用SpatialScopeInput reservoirOnly，默认draw、目标reservoir，保存regionCodes为空，必填水库名称及有效面；旧行政区授权编辑须补水库边界，不自动将行政区面认作水库。
 
 2026-10-20：media-ui最新用户约定仅消费npm sky-ui-kit@0.1.6，开发和交付均移除源码alias；库能力后续需发布可安装版本后应用再升级。
+
+# HTML 样式与 AI 接入流程
+
+## 状态与选择
+
+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 只消费 CSS，不需要 Vue/Element Plus 运行时。npm 默认可能自动安装 peerDependencies；独立的 CSS 资源下载目录可用 npm install --legacy-peer-deps sky-ui-kit@指定版本，已有 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 |
+
+完整 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 结构和状态契约
+
+容器使用 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 选择器一致。
+
+## 主题、字体和浮层
+
+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 浮层；原页面浮层应放在主题容器内，或独立设置相同主题边界。不会附加焦点管理、遮罩、定位或弹窗逻辑。
+
+## 写入消费项目 AGENTS.md
+
+接入后合并以下规则，保留已有内容，不重复追加：
+
+> 本项目使用 sky-ui-kit 的 HTML 样式模式。先读取当前安装包 llms.txt 和 docs/HTML-INTEGRATION.md，核对 exports；只使用该版本实际提供的 CSS 入口和结构类；新版 HTML 模式仅给容器添加 sky-html，原生控件自动换肤，不给每个控件补类。基础主题必需，其余按需引入。保留原 DOM 标识及业务事件，不通过仿写组件内部 CSS 实现外观。需要完整组件交互时明确切换到真实 Vue 组件方案。升级后重新核对文档和实际出口。
+
+包内文档不会自动进入所有 AI 工具上下文；README 和项目规则提供发现入口，不能保证所有工具自动执行。
+
+## 验证范围
+
+本次只进行文档生成和静态/类型检查，不构建、打包、发布或浏览器验证。示例网站展示当前源码；新增入口需安装 0.1.10 或更新版本。水库调度消费项目尚未修改，旧页面选择器冲突和视觉效果待用户验证。
+
+## 自动换肤与局部退出
+
+给单个控件或第三方区域添加 data-sky-native="off"，该节点及全部后代都不会匹配按钮/输入样式；里面再次出现 sky-html 也不重新开启。容器外元素不受影响。Element Plus 的 el- 类节点及后代、MapLibre/Mapbox 地图内部控件自动排除；其他第三方组件请显式退出。
+退出仅阻止控件皮肤，不撤销祖先继承的字体、颜色、变量；需要完全独立时放到主题容器之外。
+
+面板没有原生 HTML 控件，不自动给 div/section 加外观。使用已有 sky-model-panel 结构类，保留原 .panel 等类和事件，检查旧选择器冲突。不新增覆盖业务 .panel 的全局规则。完整示例见包内 examples/html/index.html。
+
+错误文案显式标记 data-sky-error，并用 aria-describedby 关联输入；不能自动把所有 span 识别为错误。默认控件高度 32px、圆角 4px，服从与 Vue 一致的 control-height-m、radius-s、font-size-body 覆盖。主题复制不包含字体二进制。仅承诺主题与控件表面规范一致，尚未完成浏览器视觉对照验证。
+
+## HTML 表单控件逐项验收模块
+
+网站新增独立“HTML 表单控件”导航，22 项按编号定位，每项包含真实原生标签、可操作状态、可复制代码及当前页核对标记。目录与生成文档共享 src/html-form-catalog.ts，详见 HTML-FORM-CATALOG.md。滑块/颜色/上传仍为原生外观；复杂 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 输入仅美化文件按钮，不替换系统窗口、不发起上传。此前“上传保留原外观”的说明由此更新覆盖。
+
+多选 select 使用列表皮肤，默认宽度 220px，可通过 --sky-select-list-width 覆盖；size 控制可见行数，最小约三行。选项选中、不可选及整组禁用沿用原生属性。Ctrl/Command/Shift 操作遵循系统规则，option 样式支持因浏览器而异，不承诺等同 Vue 浮层。
+
+## 完整 HTML 示例
+
+```html
+<!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>
+
+```
+
+# 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/llms.txt

@@ -1,9 +1,11 @@
 # sky-ui-kit
 
-> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.9. AI tools must explicitly load these files.
+> Vue 3 components compatible with Element Plus, project menus, timeline and map tools. Version 0.1.10. 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.
+
 - [Consumers](docs/CONSUMERS.md): shared project convention and local integration.
 - [AI guide](docs/AI-GUIDE.md): setup, examples, icon/event bindings and limits.
 - [Component API](docs/COMPONENT-API.md): props, defaults, events, slots and types.
@@ -24,3 +26,5 @@
 ## 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.
+
+- [HTML form checklist](docs/HTML-FORM-CATALOG.md): individual native control examples and verification limits.