{"id":"fa67a418-e281-43fd-8fcb-7a3685969d5e","shortId":"hjct67","kind":"skill","title":"css-debug","tagline":"Use this skill to diagnose CSS and frontend layout issues such as positioning, overflow clipping, Tailwind class conflicts, z-index stacking, and React rendering visibility problems.","description":"# CSS Debug Skill\n\ncss-debug\ntrue\n\n## 使用场景\n\n当用户遇到以下问题时使用此 skill：\n- CSS 定位问题（元素位置不正确、被裁剪、溢出等）\n- React 组件渲染问题\n- Tailwind CSS 类不生效\n- 绝对定位/相对定位问题\n- Flexbox/Grid 布局问题\n- z-index 层叠问题\n\n## 调试步骤\n\n### 1. 收集信息\n\n首先向用户询问或获取：\n- 浏览器开发者工具中的 HTML 结构\n- 相关元素的 computed styles\n- 父容器的 CSS 属性（特别是 position、overflow、display）\n- 截图（如果有的话）\n\n### 2. 常见问题检查清单\n\n#### 绝对定位内容被裁剪\n```\n问题：position: absolute 的元素被父容器裁剪\n检查：\n- [ ] 父容器是否有 overflow: hidden 或 overflow: auto\n- [ ] 祖先容器是否有 overflow: hidden\n- [ ] 父容器是否设置了 position: relative\n- [ ] 元素的 top/left/right/bottom 值是否超出父容器\n\n解决方案：\n1. 将 overflow: hidden 改为 overflow: visible\n2. 或将绝对定位元素移到更外层的容器\n3. 或使用 fixed 定位（相对于视口）\n```\n\n#### 元素位置偏移\n```\n问题：元素位置与预期不符\n检查：\n- [ ] positionX/positionY 或 left/top 值是否正确\n- [ ] 最近的 position: relative 祖先是哪个\n- [ ] 是否有 margin/padding 影响\n- [ ] transform 是否影响定位上下文\n\n解决方案：\n1. 确认定位参考点是正确的祖先元素\n2. 检查 CSS 单位（px vs % vs rem）\n3. 使用浏览器检查器的\"元素选择\"功能定位问题\n```\n\n#### 内容不显示\n```\n问题：React 组件渲染但内容不可见\n检查：\n- [ ] 元素是否有 width/height（可能为 0）\n- [ ] opacity 是否为 0\n- [ ] visibility 是否为 hidden\n- [ ] display 是否为 none\n- [ ] z-index 是否被其他元素遮挡\n- [ ] color 是否与背景色相同\n\n解决方案：\n1. 在开发者工具中检查 Computed 面板\n2. 临时添加边框或背景色调试：border: 1px solid red\n3. 检查条件渲染逻辑\n```\n\n#### Tailwind 类不生效\n```\n问题：Tailwind CSS 类没有应用\n检查：\n- [ ] 类名拼写是否正确\n- [ ] 是否被更高优先级的样式覆盖\n- [ ] 动态类名是否正确生成（字符串拼接问题）\n- [ ] tailwind.config.js 中 content 配置是否包含该文件\n\n解决方案：\n1. 使用 !important 临时测试：!overflow-visible\n2. 检查 className 是否正确传递\n3. 使用内联 style 作为备选方案\n```\n\n### 3. 浏览器调试命令\n\n在浏览器控制台运行：\n\n```javascript\n// 高亮所有绝对定位元素\ndocument.querySelectorAll('[style*=\"position: absolute\"]').forEach(el => {\n el.style.outline = '2px solid red';\n console.log(el, getComputedStyle(el));\n});\n\n// 查找 overflow: hidden 的容器\ndocument.querySelectorAll('*').forEach(el => {\n const style = getComputedStyle(el);\n if (style.overflow === 'hidden' || style.overflowX === 'hidden' || style.overflowY === 'hidden') {\n el.style.outline = '2px dashed blue';\n console.log('overflow-hidden:', el);\n }\n});\n\n// 检查元素的完整 computed 样式\nconst el = document.querySelector('.your-selector');\nconsole.table({\n position: getComputedStyle(el).position,\n overflow: getComputedStyle(el).overflow,\n display: getComputedStyle(el).display,\n width: getComputedStyle(el).width,\n height: getComputedStyle(el).height,\n top: getComputedStyle(el).top,\n left: getComputedStyle(el).left,\n});\n\n// 查找定位祖先\nfunction findPositionedAncestor(el) {\n let current = el.parentElement;\n while (current) {\n const position = getComputedStyle(current).position;\n if (position !== 'static') {\n console.log('Positioned ancestor:', current, 'position:', position);\n return current;\n }\n current = current.parentElement;\n }\n console.log('No positioned ancestor found, using viewport');\n return null;\n}\nfindPositionedAncestor(document.querySelector('.your-selector'));\n```\n\n### 4. React DevTools 检查\n\n1. 打开 React DevTools\n2. 选择问题组件\n3. 检查：\n - props 是否正确传递\n - state 是否包含预期数据\n - 条件渲染的条件是否满足\n\n### 5. 常用修复模式\n\n#### 修复绝对定位被裁剪\n\n```tsx\n// 问题代码\n\n\n// 解决方案 1: 移除 overflow-hidden\n\n ...\n
\n\n// 解决方案 2: 条件性 overflow\nconst hasAbsoluteContent = blocks.some(b => b.props?.positionX !== undefined);\n\n ...\n
\n\n// 解决方案 3: 分离容器\n\n
\n {/* 需要裁剪的内容 */}\n
\n
\n {/* 绝对定位内容 */}\n
\n