UI 问题调试方法论

核心原则：先理解机制，后动手修改。

当 UI 行为不符合预期时，禁止立即修改代码。必须先完成以下调试流程。

触发条件

当遇到以下情况时，必须激活本 skill 的调试流程：

1. UI 行为不符合预期
2. CSS/样式不生效
3. 组件交互有问题（拖拽、点击、hover 等）
4. 布局错乱
5. 第一次尝试修复失败后

强制流程

┌─────────────────────────────────────────────────────────────┐
│                    UI 问题调试流程                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 观察现象        用 DevTools 检查实际 DOM 和样式          │
│       │                                                     │
│       ▼                                                     │
│  2. 理解机制        搞清楚组件/CSS 的工作原理                │
│       │                                                     │
│       ▼                                                     │
│  3. 定位根因        找到真正控制行为的代码/配置              │
│       │                                                     │
│       ▼                                                     │
│  4. 最小修复        只改必要的部分                          │
│       │                                                     │
│       ▼                                                     │
│  5. 验证            测试所有场景                            │
│       │                                                     │
│       └──── 失败 ────▶ 回到步骤 1，不要继续打补丁           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step 1: 观察现象

必须使用 DevTools 或 Playwright，而不是猜测。

检查清单

使用 Playwright 检查（AI Agent 执行）

当作为 AI Agent 调试时，使用 Playwright 获取运行时信息：

// 获取元素的 computed style
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
  };
});

// 获取实际 DOM 结构
const html = await page.$eval('selector', el => el.outerHTML);

// 检查元素是否可见
const isVisible = await page.isVisible('selector');

// 截图对比
await page.screenshot({ path: 'debug-before.png' });

关键：先拿到实际数据，再做判断。不要基于代码猜测运行时状态。

Step 2: 理解机制

在动手前，必须能回答以下问题：

1. 这个组件/CSS 属性的工作原理是什么？
2. 哪些因素会影响它的行为？
3. 我要修改的代码，在整个流程中扮演什么角色？

常见机制陷阱