| name | ui-debug-methodology |
| description | UI/前端问题调试方法论。当遇到 CSS、布局、组件行为等 UI 问题时，强制执行"先观察后动手"的调试流程，避免盲目尝试。 |
UI 问题调试方法论
核心原则：先理解机制，后动手修改。
当 UI 行为不符合预期时，禁止立即修改代码。必须先完成以下调试流程。
触发条件
当遇到以下情况时，必须激活本 skill 的调试流程：
- UI 行为不符合预期
- CSS/样式不生效
- 组件交互有问题（拖拽、点击、hover 等）
- 布局错乱
- 第一次尝试修复失败后
强制流程
┌─────────────────────────────────────────────────────────────┐
│ UI 问题调试流程 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. 观察现象 用 DevTools 检查实际 DOM 和样式 │
│ │ │
│ ▼ │
│ 2. 理解机制 搞清楚组件/CSS 的工作原理 │
│ │ │
│ ▼ │
│ 3. 定位根因 找到真正控制行为的代码/配置 │
│ │ │
│ ▼ │
│ 4. 最小修复 只改必要的部分 │
│ │ │
│ ▼ │
│ 5. 验证 测试所有场景 │
│ │ │
│ └──── 失败 ────▶ 回到步骤 1，不要继续打补丁 │
│ │
└─────────────────────────────────────────────────────────────┘
Step 1: 观察现象
必须使用 DevTools 或 Playwright，而不是猜测。
检查清单
| 检查项 | 方法 |
|---|
| 实际的 DOM 结构 | Elements 面板 |
| Computed styles | 查看 width/height/min-width/max-width 等 |
| 样式来源 | 看是哪个 CSS 规则在生效 |
| 是否有覆盖 | 查看被划掉的样式 |
| 布局模式 | table-layout / display / flex / grid |
| 事件是否触发 | Console 加 log 或 breakpoint |
使用 Playwright 检查（AI Agent 执行）
当作为 AI Agent 调试时，使用 Playwright 获取运行时信息：
const style = await page.$eval('selector', el => {
const computed = window.getComputedStyle(el);
return {
width: computed.width,
minWidth: computed.minWidth,
maxWidth: computed.maxWidth,
display: computed.display,
position: computed.position,
tableLayout: computed.tableLayout
};
});
const html = await page.$eval('selector', el => el.outerHTML);
const isVisible = await page.isVisible('selector');
await page.screenshot({ path: 'debug-before.png' });
关键：先拿到实际数据，再做判断。不要基于代码猜测运行时状态。
Step 2: 理解机制
在动手前，必须能回答以下问题：
- 这个组件/CSS 属性的工作原理是什么？
- 哪些因素会影响它的行为？
- 我要修改的代码，在整个流程中扮演什么角色？
常见机制陷阱
| 场景 | 陷阱 | 真相 |
|---|
| Ant Design Table 列宽 | 以为 <th> 的 width 控制列宽 | 实际由 <colgroup> + scroll.x 控制 |
scroll.x: 'max-content' | 以为只是让表格可横向滚动 | 实际让浏览器忽略 width，根据内容计算 |
| Flexbox 子元素宽度 | 设置了 width 但不生效 | 需要同时设置 flex-shrink: 0 |
CSS position: absolute | 以为相对于父元素 | 实际相对于最近的 position: relative 祖先 |
transform | 只是视觉变换 | 会影响 position: fixed 子元素的定位 |
z-index 不生效 | 以为值越大越靠前 | 需要在同一个 stacking context 中比较 |
overflow: hidden | 只影响自身 | 会创建新的 BFC，影响子元素布局 |
如果不熟悉机制
- 先查官方文档（MDN、组件库文档）
- 搜索 "X not working" / "X width ignored" 等关键词
- 检查组件库源码
- 创建最小复现 demo
Step 3: 定位根因
问自己：是我的代码问题，还是框架/机制问题？
二分法排除
- 移除可疑代码，看问题是否消失
- 创建最小复现，逐步添加代码直到问题出现
- 检查是否有其他 CSS/JS 在干扰
常见根因类型
| 类型 | 示例 | 修复方向 |
|---|
| 配置问题 | scroll.x: 'max-content' 导致列宽失效 | 修改配置 |
| CSS 优先级 | 全局样式覆盖了组件样式 | 提高优先级或改选择器 |
| 组件 API 误用 | 用错了 prop 或 callback 签名 | 查文档，改用法 |
| 机制不匹配 | 想用 CSS 控制，但实际由 JS 控制 | 改用正确的控制方式 |
| 第三方库限制 | 库不支持这种用法 | 换方案或 fork |
Step 4: 最小修复
只改必要的部分，不引入新复杂度。
原则
- 能用原生实现就不引入库
- 能改配置就不改代码
- 能改一处就不改多处
- 改完能解释清楚为什么这样改
反模式（禁止）
| 反模式 | 问题 |
|---|
| 引入新库解决小问题 | 增加依赖，可能带来新问题 |
到处加 !important | 掩盖问题，后续更难维护 |
| 在多个地方加补丁 | 说明没找到根因 |
| 改了生效但不知道为什么 | 下次还会踩坑 |
用 as any / @ts-ignore 绕过类型错误 | 隐藏真实问题 |
Step 5: 验证
测试所有场景，不只是出问题的那个。
验证清单
失败后的处理
如果验证失败，回到 Step 1 重新观察。
禁止：
- 继续在当前方向打补丁
- 猜测 "可能是这个原因"
- 没观察就尝试下一个修复
案例：Ant Design Table 可拖拽列宽
❌ 错误路径（实际发生的）
问题：拖拽列宽时，某些列往左拖不动
尝试 1：用 react-resizable 库 → 失败
尝试 2：设置 minWidth/maxWidth → 失败
尝试 3：改 CSS table-layout → 失败
尝试 4：改 transform → 失败
...（反复折腾 N 次）
最终：改 scroll.x → 成功
✅ 正确路径（应该这样做）
1. 观察：DevTools 检查 <th> 的 computed width
→ 发现 width 确实在变，但视觉没变
2. 理解：搜索 "ant design table column width not working"
→ 发现 scroll.x: 'max-content' 会让浏览器忽略 width
3. 定位：scroll.x 是根因
4. 修复：scroll.x 改成列宽总和
5. 验证：所有列都能正常拖拽
总耗时：10 分钟（而不是 N 小时）
禁止事项
- 禁止不观察就动手改代码
- 禁止不理解机制就引入新库
- 禁止修复失败后继续猜测打补丁
- 禁止改了生效但说不清为什么
- 禁止跳过验证步骤直接提交
速查表
UI 问题 → DevTools 观察 → 理解机制 → 定位根因 → 最小修复 → 验证
↑ |
└────────── 失败则回到这里 ──────────────┘
