纯html+css组件库必须具备命名空间、设计令牌和自闭合结构三要素：类名强制前缀如.c-button，css变量统一管理间距颜色，html结构独立可移植且禁用泛化类名与px单位。
纯 HTML + CSS 的组件库不是“复制粘贴就能用”的代码块集合，而是必须能独立存在、样式不泄漏、结构可预测、主题可切换的界面单元。没有框架兜底时，松散结构、类名冲突、px 固定值、全局样式污染，是默认状态。
组件必须带命名空间前缀，且结构自闭合
没 Shadow DOM 时，CSS 泄漏是头号风险。所有类名必须加统一前缀，比如 .c-button、.c-card__footer、.c-modal--small，禁用 .header、.content 这类泛化名。
每个组件的 HTML 必须能单独复制进任意页面并正常渲染：
<div class="c-card"> <div class="c-card__header"><h3>标题</h3></div> <div class="c-card__body"><p>正文内容</p><div class="aritcle_card flexRow artxards"> <div class="artcardd flexRow"> <a class="aritcle_card_img" rel="nofollow" href="/xiazai/skill5806" title="html-deploy"><img src="https://img.php.cn/upload/skill/000/000/081/179066538882434.jpg" alt="html-deploy" onerror="this.onerror='';this.src='/static/lhimages/moren/morentu.png'" ></a> <div class="aritcle_card_info flexColumn"> <a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="overflowclass">html-deploy</a> <p class="overflowclass">使用 htmlcode.fun 将 HTML 内容或文件部署到网页，适用于用户要求“部署到网页”“托管此 HTML”“生成此前端...的实时链接”等场景。</p> </div> <a rel="nofollow" href="/xiazai/skill5806" title="html-deploy" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a> </div> </div></div> <div class="c-card__footer"><button class="c-button">操作</button></div> </div>
- 不用
<section></section>或<article></article>包裹组件——语义不准确，且无法通过类名精准定位样式作用域 - 不用
<div class="card">——缺少前缀，极易与项目其他样式冲突 <li>按钮必须用 <code><button></button>标签，不能用<div role="button"> 代替，否则表单提交、键盘焦点、无障碍支持全失效 <h3>CSS 必须用设计令牌，禁用 px 和 !important</h3> <p>颜色、间距、圆角这些值不能写死在选择器里，得统一抽成 CSS 自定义属性：</p> <pre class="brush:php;toolbar:false;">:root { --c-space-xs: 0.25rem; --c-space-md: 1rem; --c-color-primary: #0066cc; --c-radius: 0.375rem; }</pre> <ul> <li> <code>padding: var(--c-space-md);✅ —— 可被主题覆盖 -
margin-left: 8px;❌ —— 移动端缩放失效，高 DPR 屏幕显示模糊 -
font-size: clamp(1rem, 4vw, 1.25rem);✅ —— 响应式字号，不依赖 JS - 所有组件内距、边框、阴影都必须基于变量，禁用
!important—— 它会锁死下游覆盖能力，让深色模式或品牌定制无法生效
HTML 模板不能靠服务端 include，得用 JS 加载或
GitHub Pages、Netlify 等静态托管环境不解析 @@include、<?php include ?> 或 EJS 模板语法。把 nav.html 当作片段直接写进主 HTML，浏览器只会当普通文本渲染。
- 推荐方案：用
<template id="c-nav"></template>包裹结构，JS 中用document.getElementById('c-nav').content.cloneNode(true)插入 - 次选方案：组件 JS 文件里用字符串模板或
fetch('./components/c-nav.html')动态加载（注意 CORS 和缓存） - 绝对避免：在 HTML 中写
<!--#include file="nav.html"-->或类似 Apache SSI 语法——本地开发能跑，上线就空白
真正难的不是写几个按钮卡片，而是让每个组件在任意上下文里都“守规矩”：不抢焦点、不撑破容器、不污染 :root、不依赖外部 JS 初始化。命名空间、设计令牌、自闭合结构，三者缺一不可；漏掉任何一个，组件库就会在三个月后变成维护噩梦。
