web-components

原生 Web（HTML/CSS/JS）

必需约束（不可妥协）

• 仅使用 HTML/CSS/JS（不使用框架）
• 使用模块化 JS（ESM）
• 优先采用小巧、专注的函数和纯工具函数
• 避免全局状态

适用场景（用户提出以下需求时）

• 原生 JS / 纯 HTML/CSS/JS / 静态页面 / 高效
• 不使用框架、React/Angular/Vue
• 直接在 DOM 中构建小型 UI 组件（模态框、标签页、下拉菜单、表单验证）
• 重构以移除框架依赖或降低 JS 复杂度

输出要求

• 避免遗漏导入或路径
• 避免使用 TODO 占位符
• 保持改动小巧、可测试且循序渐进

实现工作流

1）结构

• 优先采用以下结构：

  • src/ 源代码
  • public/ 静态文件（字体、图像等）
  • index.html 主入口
  • main.js 主 JS 入口
  • src/css/global.css 全局样式
  • src/components/ Web Components 文件夹
  • src/modules/ 可复用模块和工具模块 JS

• 每个模块只负责一件事（DOM 绑定、模块状态、渲染、API、工具函数等）

• 避免全局可变状态。如果需要状态，请将其封装在模块中，并仅暴露最少量的函数。

• 文件名始终遵循以下命名约定：

  • src/components/ 中的组件应使用 PascalCase。类名应与文件名一致。CSS 文件也应如此。
  • src/modules/ 中的模块应使用 camelCase。函数名应与文件名一致。

2）HTML 指南

• 在适用时使用语义化标签（<header>、<footer>、<article>、<main>、<nav>、<button>、<dialog> 等）
• 避免堆砌 div（仅保留必要元素）

3）DOM 指南

• 使用 CSSStyleSheet API 创建样式，而不是使用字符串模板。
• 优先使用 import 属性 with，而不是 new CSSStyleSheet()。优先使用 new CSSStyleSheet()，而不是纯字符串模板。
• 使用 querySelector*() API，而不是 getElement*() API。
• 使用 setHTMLUnsafe() / getHTML()，而不是 innerHTML。
• 添加元素时优先使用现代 DOM API：append()、prepend()、before()、after()。否则，优先使用 insertAdjacent*()，而不是旧版 API appendChild()。

4）CSS 指南

• 优先采用简单、易预测的命名方式
• 优先使用 @scope 规则，而不是 BEM 命名
• 使用 CSS 变量定义主题基础值和常用可复用数据
• 默认确保布局具有响应性（flex/grid）
• 优先使用特异性较低的 :where()，而不是 !important
• 使用 CSS 嵌套对相关区块类进行分组

5）Javascript 指南

• 使用 type="module" 和显式导入/导出
• 优先使用具名导入，而不是默认导入
• 优先采用纯工具函数和小型函数
• 对列表/动态 UI 使用事件委托
• 明确处理错误（网络故障、缺失的 DOM 节点、无效输入）
• 将拆分后的逻辑封装为小型类方法
• 为代码字符串模板添加 /* html */、/* css */ 或 /* svg */ 前缀

验证清单

完成工作时，请确保：

• 改动未导致控制台错误或警告
• 所有引用的资源都能正常加载（路径/导入）
• 检查导入项，确认它们确实在使用
• 功能可通过键盘操作，且无需框架运行时

建议脚本

• 添加使用 servor 本地服务器进行开发的 npm run dev 脚本