web-components

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Vanilla Web (HTML/CSS/JS)

原生Web开发（HTML/CSS/JS）

Required constraints (non-negotiables)

必须遵守的约束条件（不可协商）

HTML/CSS/JS only (no framework)
Use modular JS (ESM)
Prefer small, focused functions and pure utilities
Avoid global state

仅使用HTML/CSS/JS（无框架）
使用模块化JavaScript（ESM）
优先选择小巧、聚焦的函数和纯工具类
避免全局状态

When to activate this skill (user asks for)

何时启用该技能（用户需求场景）

Vanilla JS / plain HTML/CSS/JS / static page / efficient
no framework, no React/Angular/Vue
small UI components (modals, tabs, dropdown, form validation) built directly in the DOM
refactors to remove framework dependencies or reduce JS complexity

原生JS / 纯HTML/CSS/JS / 静态页面 / 高性能实现
不使用框架，无需React/Angular/Vue
直接基于DOM构建小型UI组件（模态框、标签页、下拉菜单、表单验证）
重构代码以移除框架依赖或降低JavaScript复杂度

Output expectations

输出要求

Avoid missing imports or paths
Avoid TODO placeholders
Keep changes small, testable, and incremental

避免缺失导入或路径错误
避免留下TODO占位符
保持修改内容小巧、可测试且增量式推进

Implementation workflow

实现工作流程

1) Structure

1) 项目结构

Prefer this structure:
- ```
src/
```
  source code
- ```
public/
```
  static files (fonts, images, etc...)
- ```
index.html
```
  main entrypoint
- ```
main.js
```
  main JS entrypoint
- ```
src/css/global.css
```
  global styles
- ```
src/components/
```
  webcomponents folder
- ```
src/modules/
```
  reusable and utilities modules JS
Each module does one thing (DOM wiring, module state, rendering, API, utilities...)
Avoid global mutable state. If state is needed, encapsulate it in a module and expose minimal functions.
Use always this name convention for filenames:
- ```
src/components/
```
  components should use PascalCase. Class name should match with filename. Same with css files.
- ```
src/modules/
```
  modules should use camelCase. Function names should match with filename.

优先采用以下结构：
- ```
src/
```
  源代码目录
- ```
public/
```
  静态文件目录（字体、图片等）
- ```
index.html
```
  主入口文件
- ```
main.js
```
  JavaScript主入口文件
- ```
src/css/global.css
```
  全局样式文件
- ```
src/components/
```
  Web组件目录
- ```
src/modules/
```
  可复用工具类模块目录
每个模块仅负责单一功能（DOM关联、模块状态、渲染、API调用、工具类等）
避免全局可变状态。若确需状态，将其封装在模块内部，并仅暴露必要的函数。
文件名需严格遵循以下命名规范：
- ```
src/components/
```
  下的组件需使用大驼峰命名法（PascalCase）。类名需与文件名一致，CSS文件同理。
- ```
src/modules/
```
  下的模块需使用小驼峰命名法（camelCase）。函数名需与文件名一致。

2) HTML guidelines

2) HTML规范

Use semantic tags (

<header>

<footer>

<article>

<main>

<nav>

<button>

<dialog>

, etc... where applicable)

Avoid soup of divs (reduce to essential elements)

使用语义化标签（如
```
<header>
```
、
```
<footer>
```
、
```
<article>
```
、
```
<main>
```
、
```
<nav>
```
、
```
<button>
```
、
```
<dialog>
```
等，按需使用）
避免过多嵌套的div标签（仅保留必要元素）

3) DOM guidelines

3) DOM操作规范

Use
```
CSSStyleSheet
```
API for create styles instead string templates.
Prefer
```
import
```
attributes
```
with
```
over
```
new CSSStyleSheet()
```
. Prefer
```
new CSSStyleSheet()
```
over plain string templates.
Use
```
querySelector*()
```
API instead
```
getElement*()
```
API.
Use
```
setHTMLUnsafe()
```
/
```
getHTML()
```
instead
```
innerHTML
```
.

Prefer modern DOM API for add elements:

append()

prepend()

before()

after()

. Else,

insertAdjacent*()

over old API

appendChild()

使用
```
CSSStyleSheet
```
API创建样式，而非字符串模板
优先使用带
```
with
```
属性的
```
import
```
，其次是
```
new CSSStyleSheet()
```
，避免使用纯字符串模板
使用
```
querySelector*()
```
API替代
```
getElement*()
```
API
使用
```
setHTMLUnsafe()
```
/
```
getHTML()
```
替代
```
innerHTML
```
优先使用现代DOM API添加元素：
```
append()
```
、
```
prepend()
```
、
```
before()
```
、
```
after()
```
。若无法使用，则选择
```
insertAdjacent*()
```
而非旧API
```
appendChild()
```

4) CSS guidelines

4) CSS规范

Prefer simple, predictable naming
Prefer
```
@scope
```
rules instead BEM naming
Use CSS variables for theme primitives and very common reusable data
Keep layout responsive by default (flex/grid)
Prefer
```
:where()
```
low specificity over
```
!important
```
Use CSS nesting for group related-block classes

优先使用简洁、可预测的命名
优先使用
```
@scope
```
规则替代BEM命名法
使用CSS变量定义主题基础样式和通用可复用数据
默认保持布局响应式（使用flex/grid）
优先使用低特异性的
```
:where()
```
替代
```
!important
```
使用CSS嵌套对相关区块类进行分组

5) Javascript guidelines

5) JavaScript规范

Use
```
type="module"
```
and explicit imports/exports
Prefer naming imports over default imports
Prefer pure utilities and small functions
Use event delegation for lists/dynamics UIs
Handle errors explicity (network failures, missing DOM nodes, invalid inputs)
Create small class methods for split logic
Prefix code string template with
```
/* html */
```
,
```
/* css */
```
or
```
/* svg */
```

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

Verification checklist

验证清单

When finishing work, ensure:

No console errors/warnings caused by changes
All referenced assets resolve (paths/imports)
Review the imported items to check if they are being used
Feature works with keyboard and without requiring a framework runtime

完成工作后，需确保：

变更未导致控制台出现错误/警告
所有引用的资源路径/导入都能正常解析
检查已导入的项是否被实际使用
功能可通过键盘操作，且无需框架运行时支持

Suggested scripts

建议脚本

Add a
```
npm run dev
```
using
```
servor
```
local server development

添加
```
npm run dev
```
命令，使用
```
servor
```
作为本地开发服务器