02 CSS
  ├─ 前置：01 HTML（DOM 结构）
  ├─ 紧接着：05 浏览器原理（渲染管线细节）
  ├─ 交叉：11 性能（渲染成本）、16 可视化（Canvas/SVG 与 CSS 的分工）
  └─ 长期：17 设计系统（令牌与主题）

┌─────────────────────────────────┐  ← margin（外边距，透明，不参与背景）
│ ┌─────────────────────────────┐ │  ← border（边框）
│ │ ┌─────────────────────────┐ │ │  ← padding（内边距）
│ │ │        content          │ │ │  ← 内容区
│ │ └─────────────────────────┘ │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘

/* 默认值：width 只算 content，加 padding/border 会变宽 */
.box-a {
  box-sizing: content-box;
  width: 100px;
  padding: 10px;
  border: 1px solid;
}
/* 实际占宽 = 100 + 20 + 2 = 122px */

/* 推荐：全局设为 border-box，width 就是最终宽度 */
*,
*::before,
*::after {
  box-sizing: border-box;
}
.box-b {
  width: 100px;
  padding: 10px;
  border: 1px solid;
}
/* 实际占宽 = 100px，内容区 = 78px */

a:link    { }  /* 未访问 */
a:visited { }  /* 已访问 */
a:hover   { }  /* 悬停 */
a:active  { }  /* 按下 */

.child {
  color: inherit;   /* 强制继承父级计算值 */
  color: initial;   /* 恢复成规范定义的初始值（注意不是浏览器默认样式） */
  color: unset;     /* 可继承属性=inherit，不可继承=initial */
  color: revert;    /* 回退到浏览器默认样式（常用于重置第三方样式） */
}

/* transform / filter / perspective / will-change 也会创建包含块 */
.parent {
  transform: translateZ(0);
}
.child {
  position: absolute; /* 现在相对 .parent 定位，而不是更外层的 relative */
}

.row {
  display: flex;
  gap: 12px;              /* 推荐：比 margin 拼接更可控 */
  align-items: center;    /* 交叉轴对齐 */
  justify-content: space-between; /* 主轴分布 */
  flex-wrap: wrap;        /* 允许换行 */
}

.item { flex: 1; }      /* = flex: 1 1 0%   可放大、可缩小、基准为 0 */
.item { flex: auto; }   /* = flex: 1 1 auto 基准为内容宽度 */
.item { flex: none; }   /* = flex: 0 0 auto 不伸缩 */

.flex-item {
  flex: 1;
  min-width: 0; /* 允许收缩到比内容更窄，配合 text-overflow 才能生效 */
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}

.parent { font-size: 16px; }
.parent .child { font-size: 1.5em; }      /* 24px */
.parent .child .grand { font-size: 1.5em; } /* 36px，不是 24px */

/* 错误：iOS Safari 地址栏展开时 100vh 过大，底部按钮被截 */
.hero { height: 100vh; }

/* 正确：dvh 跟随动态视口 */
.hero { height: 100dvh; }

.card {
  /* 颜色写法演进：rgb → hsl → oklch（感知均匀，适合生成配色） */
  background: linear-gradient(135deg, #5ec8f5, #a78bfa);
  color: oklch(0.65 0.18 250); /* 亮度更接近人眼感知 */
  border: 1px solid rgb(255 255 255 / 0.12); /* 现代语法：空格分隔 + 斜杠透明度 */
}

/* 多重背景，先写的在上层 */
.hero {
  background-image: url(overlay.png), linear-gradient(#000, #000);
  background-size: cover, auto;
}

.btn {
  transition: transform 0.2s ease, opacity 0.2s ease;
}
.btn:hover {
  transform: translateY(-2px) scale(1.02);
  opacity: 0.9;
}

/* 方案一：用 @starting-style（新特性） */
.dialog {
  opacity: 0;
  transform: translateY(8px);
  transition: opacity 0.2s, transform 0.2s;
}
.dialog.open {
  opacity: 1;
  transform: none;
}
@starting-style {
  .dialog.open { opacity: 0; transform: translateY(8px); }
}

/* 方案二：display 过渡（新版 Chrome 支持 allow-discrete） */
.el {
  transition: opacity 0.2s, display 0.2s allow-discrete;
}

/* 移动优先：先写小屏，再用 min-width 逐步增强 */
.card { padding: 12px; }

@media (min-width: 768px) {
  .card { padding: 20px; }
}
@media (min-width: 1200px) {
  .card { padding: 28px; }
}

@media (prefers-color-scheme: dark) { /* 跟随系统暗色 */ }
@media (prefers-reduced-motion: reduce) { /* 用户要求减少动效 */ }

/* 全局统一，避免逐个组件心算 padding */
*, *::before, *::after { box-sizing: border-box; }

/* 1. :is() 取内部最高特异性 */
:is(#app, .panel) .title { }   /* 特异性等于 #app .title（0,1,1,0） */

/* 2. :where() 特异性恒为 0，适合写「可被覆盖的默认样式」 */
:where(.panel) .title { }      /* (0,0,1,0) */

/* 3. :not() 取内部参数的最高特异性 */
.btn:not(#submit) { }          /* (0,1,1,0) —— 比 .btn 高，容易意外胜出 */

/* 组件内部彻底隔离继承影响 */
.widget { all: revert-layer; }

/* 正确的最小 sticky 写法 */
.toolbar {
  position: sticky;
  top: 0;                 /* 阈值必须有 */
  z-index: 10;            /* 与浮层共存时必加 */
  background: #fff;       /* 否则内容会从底下透出 */
}

/* 让文字可以省略，必须同时处理三项 */
.ellipsis {
  min-width: 0;           /* 解除 min-content 下限 */
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

子项 A 权重 = 1 × 200 = 200
子项 B 权重 = 3 × 200 = 600
A 收缩 = 100 × 200/800 = 25  → 175px
B 收缩 = 100 × 600/800 = 75  → 125px

.hero {
  min-height: 100svh;     /* 首屏稳定，不被地址栏截断 */
}

.sheet {
  height: 100dvh;         /* 弹层跟随可视区，避免底部按钮被遮 */
  padding-bottom: env(safe-area-inset-bottom);
}

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">

/* 文字渐变的安全写法：不支持时退回纯色，保证可读 */
.gradient-text {
  color: #1677ff;
  background-image: linear-gradient(90deg, #1677ff, #722ed1);
  -webkit-background-clip: text;
  background-clip: text;
}

@supports (background-clip: text) or (-webkit-background-clip: text) {
  .gradient-text {
    color: transparent;
  }
}

/**
 * 在动画前后动态提升合成层，避免长期占用显存。
 * @param {HTMLElement} el
 */
async function animateWithHint(el) {
  el.style.willChange = 'transform';
  el.style.transform = 'translateX(0)';

  await el.animate(
    [{ transform: 'translateX(-24px)' }, { transform: 'translateX(0)' }],
    { duration: 240, easing: 'cubic-bezier(.2,.8,.2,1)' },
  ).finished;

  el.style.willChange = 'auto';
}

/* 方案 1：用 opacity + visibility 代替 display */
.fade { transition: opacity .2s, visibility .2s; }

/* 方案 2：用 @starting-style 让「首次出现」也有过渡（现代浏览器） */
.dialog[open] { opacity: 1; transition: opacity .2s; }
@starting-style { .dialog[open] { opacity: 0; } }

/* 方案 3：用 Web Animations API 在 JS 里编排入场/出场 */

/* 移动优先：默认单列，够宽再变两列 */
.grid { display: grid; grid-template-columns: 1fr; }

@media (min-width: 40em) {
  .grid { grid-template-columns: repeat(2, 1fr); }
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

.dashboard {
  display: grid;
  grid-template-columns: 240px 1fr;      /* 侧边栏 + 主区域 */
  grid-template-rows: 64px 1fr;
  grid-template-areas:
    "sidebar header"
    "sidebar main";
  gap: 16px;
  min-height: 100dvh;
}

.header  { grid-area: header; }
.sidebar { grid-area: sidebar; }
.main    { grid-area: main; }

.cards {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: 16px;
}

/* 1. flex-basis 与 width 的优先级 */
.item { width: 200px; flex-basis: 100px; } /* 主轴尺寸用 flex-basis，width 在 row 方向被覆盖 */

/* 2. 单个子项独立对齐 */
.row { display: flex; align-items: flex-start; }
.row .special { align-self: flex-end; }

/* 3. 多行时的行间距与整体分布 */
.grid-like {
  display: flex;
  flex-wrap: wrap;
  align-content: space-between; /* 多行之间的分布 */
  gap: 12px;
}

/* 4. 顺序控制（谨慎使用：会改变读屏与 Tab 顺序） */
.item-last { order: 1; }

.bfc {
  overflow: auto;          /* 最常用 */
  display: flow-root;      /* 最干净，专门为此设计 */
  float: left;
  position: absolute;
  display: inline-block / flex / grid;
}

/* 1. 相邻兄弟：取较大值，不是相加 */
.a { margin-bottom: 20px; }
.b { margin-top: 30px; }   /* 间距 = 30px */

/* 2. 父子：父无 padding/border 时，子 margin 会「穿透」到父外 */
.parent { } 
.child { margin-top: 20px; } /* 父元素整体下移，而不是内部留白 */

/* 3. 空元素自身上下 margin 折叠 */

/* 4. 负 margin 参与计算（取和） */

/* 修复图片底部空隙的三种方式 */
img { display: block; }          /* 最常用 */
img { vertical-align: middle; }  /* 改变对齐基线 */
.parent { line-height: 0; }      /* 消除行高影响（副作用多） */

.stacking-context {
  position: relative; z-index: 0;  /* 显式 z-index 且非 auto */
  opacity: 0.99;                    /* 小于 1 */
  transform: translateZ(0);         /* 非 none */
  filter: blur(0);                  /* 非 none */
  will-change: transform;           /* 任意值 */
  isolation: isolate;               /* 专门用于创建隔离上下文 */
  contain: paint;
  display: flex/grid 且子元素 z-index 非 auto;
}

<div class="modal" style="z-index: 9999">弹窗</div>
<div class="card" style="transform: translateY(0)">
  <div class="badge" style="z-index: 10000">角标</div>
</div>

.card-wrapper {
  container-type: inline-size;   /* 开启容器查询：按宽度响应 */
  container-name: card;
}

.card { padding: 12px; }

@container card (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 120px 1fr;
    padding: 20px;
  }
}

/* 流体字号：视口变化时平滑缩放，避免断点跳变 */
.title { font-size: clamp(1.25rem, 1rem + 1.5vw, 2rem); }

/* 宽高比：图片/视频/占位符 */
.thumb { aspect-ratio: 16 / 9; object-fit: cover; }

/* 声明层级顺序：后面的层优先级更高 */
@layer reset, base, components, utilities;

@layer base {
  button { background: #eee; }
}

/* 第三方样式即使权重更高，也会被后面的层压过 */
@layer third-party {
  #app .btn { background: red !important; } /* 仍在 third-party 层内 */
}

:root {
  --color-primary: #1677ff;
  --space-4: 16px;
  --radius-md: 10px;
}

.button {
  background: var(--color-primary);
  padding: var(--space-4, 16px);   /* 第二个参数是回退值 */
  border-radius: var(--radius-md);
}

/* 作用域覆盖：局部换主题 */
.dark-panel {
  --color-primary: #69b1ff;
}

@property --angle {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}

.gradient-border {
  background: conic-gradient(from var(--angle), #5ec8f5, #a78bfa);
  transition: --angle 1s;   /* 注册类型后才能过渡 */
}

/* 字体加载策略 */
@font-face {
  font-family: 'Brand';
  src: url('/fonts/brand.woff2') format('woff2');
  font-display: swap;        /* 先用回退字体渲染，加载完替换（会有字体闪动） */
  unicode-range: U+4E00-9FFF; /* 只对中文范围生效，按语言拆分文件 */
}

/* optional：不阻塞、不闪动，但可能整页都用回退字体 */
@font-face {
  font-family: 'Body';
  src: url('/fonts/body.woff2') format('woff2');
  font-display: optional;
}

@font-face {
  font-family: 'Brand-fallback';
  src: local('Arial');
  size-adjust: 107%;
  ascent-override: 90%;
}

.clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.glass {
  backdrop-filter: blur(12px);   /* 好看，但与屏幕内容耦合，代价高 */
  background: rgb(255 255 255 / 0.1);
}

.mask {
  -webkit-mask-image: linear-gradient(#000, transparent); /* 遮罩也走合成 */
}

.shape {
  clip-path: polygon(0 0, 100% 0, 100% 85%, 0 100%);
}

/* auto-fill：保留空轨道，卡片靠左排，右侧留白 */
grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));

/* auto-fit：空轨道塌缩，卡片拉伸填满 */
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));

.layout {
  display: grid;
  grid-template-areas:
    "header header"
    "nav    main"
    "footer footer";
  grid-template-columns: 200px minmax(0, 1fr);
}

@media (max-width: 48em) {
  .layout {
    grid-template-areas:
      "header"
      "main"
      "nav"
      "footer";
    grid-template-columns: minmax(0, 1fr);
  }
}

/* 症状：弹层 z-index: 9999 仍被 z-index: 1 的侧栏盖住 */
.sidebar { position: relative; z-index: 1; transform: translateZ(0); } /* 创建了上下文 */
.modal   { position: fixed;  z-index: 9999; }  /* 若 .modal 在 .sidebar 内部，永远盖不上去 */

/* 修法：把弹层挂到 body，或用 isolation 明确分层 */

.card-wrap {
  container-type: inline-size;   /* 开启尺寸查询，inline-size 最常用 */
  container-name: card;
}

@container card (min-width: 360px) {
  .card { display: grid; grid-template-columns: 120px 1fr; }
}

@property --angle {
  syntax: '<angle>';
  inherits: false;
  initial-value: 0deg;
}

.loader {
  background: conic-gradient(from var(--angle), #1677ff, transparent);
  animation: spin 1s linear infinite;
}

@keyframes spin {
  to { --angle: 360deg; }
}

/* 用本地字体做尺寸对齐，减少换字体的抖动 */
@font-face {
  font-family: 'BrandFallback';
  src: local('PingFang SC'), local('Microsoft YaHei');
  size-adjust: 105%;
}

/* 想让弹窗覆盖全屏，必须挂在 body 下或用 portal */
/* 如果父级有 transform，fixed 会退化成相对父级 */
.modal-root { position: fixed; inset: 0; } /* inset = top/right/bottom/left 简写 */

.text-box {
  line-height: 1.5;        /* 行盒高度 = 1.5 × font-size */
  vertical-align: middle;  /* 相对父级基线对齐 */
}

/* :has() —— 父选择器，能根据子元素状态改变父级 */
.card:has(img:hover) { box-shadow: 0 8px 24px rgb(0 0 0 / 0.2); }
.form:has(input:invalid) .submit { opacity: 0.5; }

/* :is() / :where() —— 简化选择器，:where 权重为 0 */
:where(h1, h2, h3) { margin-block: 0; }   /* 不增加权重，方便覆盖 */
:is(.dark, .high-contrast) .card { border-color: currentColor; }

/* subgrid —— 子网格共享父网格轨道，解决嵌套对齐 */
.layout { display: grid; grid-template-columns: repeat(3, 1fr); }
.layout .panel { display: grid; grid-template-columns: subgrid; grid-column: span 3; }

/* @scope —— 限定样式作用域，减少命名冲突 */
@scope (.card) to (.card__footer) {
  img { border-radius: 8px; }
}

/**
 * 注册一个绘制工作单元：画波浪背景。
 */
class WavePainter {
  /**
   * @param {CanvasRenderingContext2D} ctx 绘制上下文
   * @param {Array<{width: number, height: number}>} geometry 元素几何信息
   */
  paint(ctx, geometry) {
    ctx.fillStyle = '#5ec8f5';
    ctx.beginPath();
    ctx.moveTo(0, geometry.height * 0.7);
    for (let x = 0; x <= geometry.width; x += 10) {
      ctx.lineTo(x, geometry.height * 0.7 + Math.sin(x / 30) * 8);
    }
    ctx.lineTo(geometry.width, geometry.height);
    ctx.lineTo(0, geometry.height);
    ctx.fill();
  }
}

// @ts-ignore —— paintWorklet 不在标准 TS DOM 类型中
CSS.paintWorklet.addModule('/wave-painter.js');

.wave {
  background: paint(wave);
}

/* 阻止滚动穿透：弹窗打开时锁住背景 */
body.modal-open { overflow: hidden; }

/* 更精准：只阻止链式滚动 */
.sheet { overscroll-behavior: contain; }

/* 滚动吸附轮播 */
.carousel {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
}
.carousel > * { scroll-snap-align: start; }

/* 跳过屏外渲染：长页面首屏优化利器 */
.section {
  content-visibility: auto;
  contain-intrinsic-size: 0 600px; /* 占位高度，避免滚动条跳变 */
}

/* 限制重排范围 */
.widget { contain: layout paint; }

// 错误：每次循环都读一次布局，浏览器必须立刻重算
for (const el of items) {
  el.style.width = `${el.offsetWidth + 10}px`; // 读 → 写 → 读 → 写
}

// 正确：先批量读，再批量写
const widths = items.map((el) => el.offsetWidth);
items.forEach((el, i) => {
  el.style.width = `${widths[i] + 10}px`;
});

primitive（原始值）      semantic（语义）             component（组件）
--blue-500: #1677ff  →  --color-primary: var(--blue-500)  →  --button-bg: var(--color-primary)
--gray-900: #111     →  --text-primary: var(--gray-900)  →  --button-text: var(--color-white)

:root {
  --color-primary: var(--blue-500);
  --color-bg: var(--gray-50);
}

[data-theme='dark'] {
  --color-primary: var(--blue-300);
  --color-bg: var(--gray-950);
}

/* 高对比模式 */
@media (forced-colors: active) {
  .button { border: 1px solid ButtonText; }
}

@media print {
  .no-print { display: none; }
  .card { break-inside: avoid; }   /* 避免卡片被分页切断 */
  a[href]::after { content: " (" attr(href) ")"; } /* 打印时显示链接地址 */
}

/**
 * 打印元素到根的祖先链，标出可能改变包含块的属性，用于排查 fixed 定位跑偏。
 * @param {HTMLElement} el
 */
function traceContainingBlock(el) {
  /** 会改变包含块的属性名 */
  const triggers = ['transform', 'filter', 'perspective', 'backdropFilter', 'contain', 'willChange'];
  let node = el.parentElement;

  while (node && node !== document.documentElement) {
    const style = getComputedStyle(node);
    const hits = triggers.filter((name) => {
      const value = style[name];
      return value && value !== 'none' && value !== 'normal';
    });

    if (hits.length) {
      console.log(node, '→', hits.map((k) => `${k}: ${style[k]}`).join('; '));
    }
    node = node.parentElement;
  }
}

┌─────────────────────────┐  ← 行盒顶部
│   ↑ 字体升部              │
│   ───── 基线 ─────        │  ← 图片底边对齐这里
│   ↓ 字体降部（约 0.2em）   │  ← 这就是「图片下面那条缝」
└─────────────────────────┘

/* 图片底部间隙的三种修法，按推荐度排序 */
img { display: block; }                 /* 1. 退出行内布局，最彻底 */
img { vertical-align: middle; }         /* 2. 改参照基线，仍有小数偏差 */
.container { font-size: 0; }            /* 3. 消灭降部空间，副作用大 */

/* 表单有错误时整块变红，无需给父元素加类 */
.field:has(input:user-invalid) {
  border-color: #ff4d4f;
  background: #fff2f0;
}

/* 卡片内有图片时取消内边距，实现「图满宽」 */
.card:has(> img) { padding-top: 0; }

@scope (.article) to (.comment) {
  p { margin-block: 1em; }   /* 只作用于 .article 内、.comment 外的 p */
}

.carousel {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;      /* mandatory 强制停靠，proximity 更宽松 */
  scroll-padding-inline: 16px;        /* 让吸附点避开容器内边距 */
  scrollbar-width: none;              /* 隐藏滚动条但保留滚动 */
}

.carousel > .item {
  flex: 0 0 80%;
  scroll-snap-align: center;
}

.long-list > .section {
  content-visibility: auto;
  contain-intrinsic-size: auto 320px;   /* 估算高度，减少滚动条抖动 */
}

/* 第一层：原始值（palette），只定义，不在组件里直接用 */
:root {
  --blue-6: #1677ff;
  --gray-1: #ffffff;
  --gray-9: #1f1f1f;
}

/* 第二层：语义（semantic），随主题切换 */
:root {
  --color-bg: var(--gray-1);
  --color-text: var(--gray-9);
  --color-primary: var(--blue-6);
  color-scheme: light;
}

[data-theme='dark'] {
  --color-bg: #141414;
  --color-text: #e6e6e6;
  color-scheme: dark;
}

/* 第三层：组件（component），只引用语义层 */
.button {
  background: var(--color-primary);
  color: #fff;
}

:root { color-scheme: light dark; }
.card { background: light-dark(#fff, #1f1f1f); }

@supports selector(:has(*)) {
  .card:has(img) { padding: 0; }
}
@supports not (backdrop-filter: blur(1px)) {
  .glass { background: rgb(20 24 32 / 0.95); }
}

Figma 变量
   ↓ 导出（Tokens Studio / 自研脚本）
tokens.json（primitive / semantic / component）
   ↓ 生成
Web CSS 变量 / 小程序变量 / RN 常量 / 暗色主题包

/* 高对比模式下保证边框可见 */
@media (forced-colors: active) {
  .card { border: 1px solid CanvasText; }
  .icon { forced-color-adjust: none; } /* 谨慎使用 */
}

/* 渐进增强的标准骨架：先给所有人可用的基础样式，再给支持者增强 */
.card { display: flex; flex-direction: column; }

@supports (container-type: inline-size) {
  .card-wrap { container-type: inline-size; }
  @container (min-width: 30em) {
    .card { flex-direction: row; }
  }
}

/* 用 @layer 固定覆盖顺序，从根上消灭 !important 军备竞赛 */
@layer reset, base, layout, components, utilities;

body (grid)
├─ header (sticky, 64px)
├─ .layout (grid: 240px 1fr)
│  ├─ aside (可折叠 → 64px)
│  └─ main (flex column, gap 16px)
│     ├─ .metrics (grid auto-fit minmax(240px,1fr))
│     └─ .table-wrap (overflow auto, 固定表头 sticky)
└─ .fab (position fixed)

:root {
  --space-1: 4px;  --space-2: 8px;
  --space-3: 12px; --space-4: 16px;
  --space-6: 24px;
  --radius-card: 12px;
  --color-bg: #0b0e14;
  --color-surface: #10141d;
  --color-border: #242b3a;
  --color-text: #e6e9f0;
  --color-text-dim: #9aa4b8;
}

.table-wrap { max-height: 420px; overflow: auto; }
.table-wrap thead th {
  position: sticky;
  top: 0;
  background: var(--color-surface); /* 必须有不透明背景，否则内容会透出来 */
  z-index: 1;
}

aside {
  width: 240px;
  transition: width 0.2s ease;
  overflow: hidden;   /* 折叠时内容不溢出 */
}
aside.collapsed { width: 64px; }

/**
 * 检查页面上是否存在不在 4px 栅格上的间距，用于还原验收前的自动扫描。
 * 只做提示，不自动修复——很多偏差是刻意的光学修正。
 */
function auditSpacingGrid(root = document.body) {
  /** 4px 栅格，容忍 1px 的光学修正 */
  const GRID = 4;
  const TOLERANCE = 1;
  const offenders = [];

  root.querySelectorAll('*').forEach((el) => {
    const style = getComputedStyle(el);
    ['marginTop', 'marginLeft', 'paddingTop', 'paddingLeft'].forEach((prop) => {
      const value = parseFloat(style[prop]);
      if (!value) return;
      if (Math.abs(value % GRID) > TOLERANCE) {
        offenders.push({ el, prop, value });
      }
    });
  });

  return offenders;
}

/* 方案 A：Grid（现代首选，最简单） */
.layout {
  display: grid;
  grid-template-columns: 200px minmax(0, 1fr) 200px;
  gap: 16px;
}

/* minmax(0, 1fr) 防止长内容把中间列撑破 */

/* 方案 B：Flex（兼容好） */
.layout { display: flex; }
.side { flex: 0 0 200px; }
.main { flex: 1 1 auto; min-width: 0; } /* min-width: 0 是关键 */

/* 方案 C：圣杯布局（float + 负 margin，中间列 DOM 在前） */
.layout { padding: 0 200px; overflow: hidden; }
.main, .left, .right { float: left; }
.main { width: 100%; }
.left { width: 200px; margin-left: -100%; position: relative; left: -200px; }
.right { width: 200px; margin-left: -200px; position: relative; right: -200px; }

/* 利用 border 交界处的斜边：相邻边框各占一半，内容区为 0 时形成三角形 */
.triangle {
  width: 0;
  height: 0;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
  border-bottom: 8px solid #1677ff;
}

/* tooltip：用伪元素做箭头，配合绝对定位 */
.tooltip { position: relative; }
.tooltip::after {
  content: '';
  position: absolute;
  left: 50%;
  top: 100%;
  transform: translateX(-50%);
  border: 6px solid transparent;
  border-top-color: #333;
}

/* 1) 布局：auto-fit + minmax，无需媒体查询断点 */
.cards {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(260px, 100%), 1fr));
  gap: var(--space-4);
}

/* 2) 主题：语义 token，组件不写死颜色 */
:root {
  --color-bg: #fff;
  --color-text: #1f1f1f;
  --color-border: rgba(0, 0, 0, 0.08);
}
[data-theme='dark'] {
  --color-bg: #141414;
  --color-text: #e6e6e6;
  --color-border: rgba(255, 255, 255, 0.12);
}
.card {
  background: var(--color-bg);
  color: var(--color-text);
  border: 1px solid var(--color-border);
}

/* 3) 长列表：跳过屏外渲染，注意占位高度避免滚动条抖动 */
.card-section {
  content-visibility: auto;
  contain-intrinsic-size: 320px;
}

/* 4) 移动端 1px：伪元素缩放，避免高 DPR 下变粗 */
.hairline { position: relative; }
.hairline::after {
  content: '';
  position: absolute;
  inset: 0;
  border: 1px solid var(--color-border);
  transform: scale(0.5);
  transform-origin: 0 0;
  width: 200%;
  height: 200%;
  pointer-events: none;
}

/* 5) 安全区 */
.page { padding-bottom: calc(16px + env(safe-area-inset-bottom)); }

/* 方案 A：Grid 行内拉伸 + 卡片自身 flex 列 */
.cards {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: 16px;
}
.card {
  display: flex;
  flex-direction: column;
  height: 100%; /* 关键：让卡片填满网格行高 */
}
.card__body {
  flex: 1; /* 正文吸收剩余空间，把按钮推到底 */
}
.card__actions {
  margin-top: auto; /* 双保险：即使 body 没设 flex，也能贴底 */
}

/* 父容器声明可查询维度；inline-size 只关心宽度，避免循环依赖 */
.card-wrap {
  container-type: inline-size;
  container-name: card;
}

.card {
  padding: clamp(12px, 2cqi + 8px, 24px);
  font-size: clamp(14px, 1.6cqi + 10px, 18px);
}

/* 同一组件在侧栏与主区域表现不同，不需要页面级断点 */
@container card (min-width: 420px) {
  .card__media {
    float: left;
    width: 40%;
    margin-right: 16px;
  }
}

/* 问题：弹窗 z-index: 9999 仍被侧边栏盖住 */
.layout__aside {
  transform: translateZ(0); /* 无意中创建了层叠上下文 */
}

/* 修复一：去掉不必要的 transform，或改为不影响层叠的写法 */
.layout__aside {
  transform: none;
}

/* 修复二：若必须保留，则把弹窗挂到 body 下（Portal），脱离该上下文 */
.modal-root {
  position: fixed;
  inset: 0;
  z-index: 1000;
}

/* 修复三：用 isolation 显式圈定层级，避免全局数字竞赛 */
.layout {
  isolation: isolate;
}

/**
 * 找出导致页面横向溢出的元素。
 * 思路：从可疑节点开始，判断其右边界是否超出根元素内容区。
 * @param {HTMLElement} [root=document.documentElement]
 * @returns {Array<{ el: Element, right: number }>} 溢出的元素及右边界坐标
 */
function findHorizontalOverflow(root = document.documentElement) {
  const limit = root.clientWidth;
  const result = [];

  // 只遍历元素节点，避免文本节点带来的噪音
  root.querySelectorAll('*').forEach((el) => {
    const rect = el.getBoundingClientRect();
    if (rect.width === 0 && rect.height === 0) return;      // 跳过不可见元素
    if (rect.right > limit + 1) {                            // 1px 容差，抗亚像素
      result.push({ el, right: Math.round(rect.right) });
    }
  });

  return result;
}

/**
 * 打印某个元素上「谁在生效」：遍历样式表规则，筛出匹配该元素的规则。
 * 注意：getComputedStyle 只给最终值，无法告诉你是哪条规则生效的。
 * @param {Element} el 目标元素
 * @param {string} property 例如 'color'、'margin-top'
 */
function traceCascade(el, property) {
  const matched = [];

  for (const sheet of document.styleSheets) {
    let rules;
    try {
      // 跨域样式表访问 cssRules 会抛 SecurityError，必须捕获
      rules = sheet.cssRules;
    } catch {
      continue;
    }

    const walk = (list) => {
      for (const rule of list) {
        if (rule.cssRules) {          // @media / @supports / @layer 需要递归
          walk(rule.cssRules);
          continue;
        }
        if (!rule.selectorText) continue;
        if (!el.matches(rule.selectorText)) continue;

        const value = rule.style.getPropertyValue(property);
        if (value) matched.push({ selector: rule.selectorText, value });
      }
    };

    walk(rules);
  }

  return matched;
}