css-debug

CSS Debug Skill

css-debug true

Use Cases

Use this skill when users encounter the following problems:

• CSS positioning issues (incorrect element position, being clipped, overflow, etc.)
• React component rendering issues
• Tailwind CSS classes not taking effect
• Absolute positioning/relative positioning issues
• Flexbox/Grid layout issues
• z-index stacking issues

Debugging Steps

1. Gather Information

First, ask the user for or obtain:

• The HTML structure in the browser developer tools
• The computed styles of the relevant elements
• The CSS properties of the parent container (especially position, overflow, display)
• A screenshot (if available)

2. Common Issues Checklist

Absolutely positioned content being clipped

问题：position: absolute 的元素被父容器裁剪
检查：
- [ ] 父容器是否有 overflow: hidden 或 overflow: auto
- [ ] 祖先容器是否有 overflow: hidden
- [ ] 父容器是否设置了 position: relative
- [ ] 元素的 top/left/right/bottom 值是否超出父容器

解决方案：
1. 将 overflow: hidden 改为 overflow: visible
2. 或将绝对定位元素移到更外层的容器
3. 或使用 fixed 定位（相对于视口）

Element position offset

问题：元素位置与预期不符
检查：
- [ ] positionX/positionY 或 left/top 值是否正确
- [ ] 最近的 position: relative 祖先是哪个
- [ ] 是否有 margin/padding 影响
- [ ] transform 是否影响定位上下文

解决方案：
1. 确认定位参考点是正确的祖先元素
2. 检查 CSS 单位（px vs % vs rem）
3. 使用浏览器检查器的"元素选择"功能定位问题

Content not displaying

问题：React 组件渲染但内容不可见
检查：
- [ ] 元素是否有 width/height（可能为 0）
- [ ] opacity 是否为 0
- [ ] visibility 是否为 hidden
- [ ] display 是否为 none
- [ ] z-index 是否被其他元素遮挡
- [ ] color 是否与背景色相同

解决方案：
1. 在开发者工具中检查 Computed 面板
2. 临时添加边框或背景色调试：border: 1px solid red
3. 检查条件渲染逻辑

Tailwind classes not taking effect

问题：Tailwind CSS 类没有应用
检查：
- [ ] 类名拼写是否正确
- [ ] 是否被更高优先级的样式覆盖
- [ ] 动态类名是否正确生成（字符串拼接问题）
- [ ] tailwind.config.js 中 content 配置是否包含该文件

解决方案：
1. 使用 !important 临时测试：!overflow-visible
2. 检查 className 是否正确传递
3. 使用内联 style 作为备选方案

3. Browser Debugging Commands

Run in the browser console:

// 高亮所有绝对定位元素
document.querySelectorAll('[style*="position: absolute"]').forEach(el => {
  el.style.outline = '2px solid red';
  console.log(el, getComputedStyle(el));
});

// 查找 overflow: hidden 的容器
document.querySelectorAll('*').forEach(el => {
  const style = getComputedStyle(el);
  if (style.overflow === 'hidden' || style.overflowX === 'hidden' || style.overflowY === 'hidden') {
    el.style.outline = '2px dashed blue';
    console.log('overflow-hidden:', el);
  }
});

// 检查元素的完整 computed 样式
const el = document.querySelector('.your-selector');
console.table({
  position: getComputedStyle(el).position,
  overflow: getComputedStyle(el).overflow,
  display: getComputedStyle(el).display,
  width: getComputedStyle(el).width,
  height: getComputedStyle(el).height,
  top: getComputedStyle(el).top,
  left: getComputedStyle(el).left,
});

// 查找定位祖先
function findPositionedAncestor(el) {
  let current = el.parentElement;
  while (current) {
    const position = getComputedStyle(current).position;
    if (position !== 'static') {
      console.log('Positioned ancestor:', current, 'position:', position);
      return current;
    }
    current = current.parentElement;
  }
  console.log('No positioned ancestor found, using viewport');
  return null;
}
findPositionedAncestor(document.querySelector('.your-selector'));

4. React DevTools Inspection

1. Open React DevTools
2. Select the problematic component
3. Check:
   • Whether props are passed correctly
   • Whether state contains the expected data
   • Whether the conditions for conditional rendering are met

5. Common Fix Patterns

Fix absolute positioning being clipped

// 问题代码
<div className="relative overflow-hidden">
  <div style={{ position: 'absolute', top: 200, left: 100 }}>
    被裁剪的内容
  </div>
</div>

// 解决方案 1: 移除 overflow-hidden
<div className="relative overflow-visible">
  ...
</div>

// 解决方案 2: 条件性 overflow
const hasAbsoluteContent = blocks.some(b => b.props?.positionX !== undefined);
<div className={`relative ${hasAbsoluteContent ? '' : 'overflow-hidden'}`}>
  ...
</div>

// 解决方案 3: 分离容器
<div className="relative">
  <div className="overflow-hidden">
    {/* 需要裁剪的内容 */}
  </div>
  <div className="absolute-content-wrapper">
    {/* 绝对定位内容 */}
  </div>
</div>

Output Format

After the analysis is complete, provide:

1. Problem Diagnosis: Clearly state what caused the problem
2. Cause Analysis: Explain the CSS mechanism and why this happens
3. Solution: Provide specific code modification suggestions
4. Verification Steps: Tell the user how to verify whether the fix is effective

Example Conversation

User: My absolutely positioned element is being clipped

Claude：

1. Please run the following command in the browser to find containers with overflow:hidden:

   document.querySelectorAll('*').forEach(el => {
     const style = getComputedStyle(el);
     if (style.overflow === 'hidden') {
       el.style.outline = '2px dashed blue';
       console.log('overflow-hidden:', el);
     }
   });
   

2. Please tell me which containers were marked
3. Also, please check whether the parent container of the absolutely positioned element has position: relative