htmlhint 配置须在构建前固化于项目根目录，自定义元素注册需同步早于 html 解析，结构校验需结合运行时 dom 断言与 axe-cli，observedattributes 必须严格匹配属性名大小写与连字符。
HTMLHint 配置必须在构建前固化，不能靠运行时动态加载
HTMLHint 的规则检查发生在构建或 CI 流程中，不是浏览器里执行的 JS 逻辑。一旦 .htmlhintrc 文件缺失、路径错误或被忽略，所有规则就形同虚设——你不会收到任何报错，只会默默放过 alt 缺失、id 重复、lang 缺失等关键问题。
常见错误现象：
本地 htmlhint index.html 检查通过，但 CI 中提示 “no config found”；
Vite 或 Webpack 构建后生成的 HTML 没被扫描，只扫了源码目录下的 .html 文件；
配置里写了 "attr-lowercase": true，但实际 HTML 中仍存在 CLASS="foo" 却没报警。
- 确保
.htmlhintrc放在项目根目录（与package.json同级），且文件名带点、全小写 - CI 脚本中显式指定路径：
npx htmlhint --config .htmlhintrc src/**/*.html，避免依赖默认查找逻辑 - 不要用
import()或动态fetch加载 HTML 片段再 lint —— HTMLHint 只处理静态文件，不解析 JS 渲染结果 - 若用 Vite 插件（如
vite-plugin-htmllint），确认插件版本兼容 Vite 5+，旧版可能跳过 SSR 生成的 HTML
自定义元素注册时机错位，导致 connectedCallback 永远不触发
浏览器解析 HTML 时，遇到 <ds-button></ds-button> 这类标签，会立刻创建 HTMLUnknownElement 实例。此时 JS 还没执行完，customElements.define() 就永远错过了这个节点——它不会“回填”，也不会重试。
常见错误现象：
页面里写了 <my-card data-title="test"></my-card>，但控制台无 connectedCallback 日志；
开发环境正常，生产构建后组件空白；
服务端渲染（SSR）返回的 HTML 在客户端 hydration 后仍无行为。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
-
customElements.define()必须同步执行，且在任何含自定义标签的 HTML 解析前完成 - 统一收口到一个入口文件（如
src/components/register.js），并在index.html中用<script defer></script>加载，或作为 ESM 模块顶层导入 - SSR 场景下务必加保护：
if (typeof window !== 'undefined') { customElements.define('my-card', MyCard); } - Webpack/Vite 构建时，禁止把自定义元素类拆包进异步 chunk（检查
splitChunks或dynamicImportToRequire配置）
HTML 结构校验不能只靠 Lint，必须结合运行时 DOM 断言
HTMLHint 能发现 <div> 缺闭合、<code><img> 少 alt，但它无法知道：某个 <header></header> 是否真被插入到 <main></main> 外层，某个 <nav></nav> 是否在语义上覆盖了全部导航区域。结构合理性得靠运行时验证。
常见错误现象：
SEO 工具报告 main 元素缺失或嵌套错误，但 HTMLHint 检查全绿；
无障碍检测（axe-core）提示 “landmark 不唯一”，但源码看着没问题；
组件复用时，<footer></footer> 被重复插入到同一页面多次。
- 在关键生命周期钩子（如 React 的
useEffect、Lit 的firstUpdated）里加断言：console.assert(document.querySelector('main'), 'missing main landmark') - 对可复用容器组件（如卡片、弹窗），用
document.querySelectorAll('footer').length 做防御性检查 - CI 中集成 axe-cli：
npx axe https://localhost:3000 --reporter=json --save=output.json，和 HTMLHint 形成互补 - 避免在
connectedCallback里直接操作全局 DOM（如document.body.append），改用 shadow DOM 或明确父容器传入
observedAttributes 写错一个字符，attributeChangedCallback 就彻底失效
attributeChangedCallback 不是通用监听器，它只响应 static get observedAttributes() 显式声明的属性名。大小写、连字符、拼写差一丁点，回调就不会触发——而且没有任何警告。
常见错误现象：<ds-input value="abc"></ds-input> 改成 <ds-input value="abc"></ds-input>，回调不触发；
JS 里调用 el.setAttribute('data-uid', '123')，但 observed 是 ['dataUid']；
首次渲染时属性值已存在，但 attributeChangedCallback 没执行（因为只响应变更，不响应初始值）。
-
observedAttributes返回的数组必须是纯字符串，且严格匹配 HTML 中的属性写法：'data-user-id'≠'dataUserId' - 首次渲染需手动读取：
this.value = this.getAttribute('value') || ''，放在constructor或connectedCallback中 - property 和 attribute 同步要双向维护：setter 里调用
this.setAttribute('value', val)，attribute 回调里更新 property - 避免监听
class或style—— 它们变更频繁，且浏览器内部优化机制会让回调不可靠
