Skip to content

skillFrontendcss

CSS Layout Debugging

Diagnoses broken flexbox and grid layouts by inspecting the box model and computed styles, then fixes the root rule instead of piling on overrides.

npx workspacetemplates add css-layout-debugging --tool claude-code

Writes 1 file to .claude/skills/css-layout-debugging/

.claude/skills/css-layout-debugging/SKILL.md31 lines · 1.7 KBFile
---
name: css-layout-debugging
description: Diagnoses broken flexbox and grid layouts by inspecting the box model and computed styles, then fixes the root rule instead of piling on overrides.
---

# CSS layout debugging

Find the rule that causes the problem. Do not stack `!important` on top of it.

## Steps

1. Pin down the failure: the element, the viewport width, the expected layout versus the actual layout. If a dev server and browser tools exist, load the page at that width and take a screenshot.
2. Walk up from the broken element to the root. For each ancestor read the computed `display`, `position`, `width`, `height`, `min-*`, `max-*`, `overflow`, `margin`, `padding`, `box-sizing`, `flex`, `grid-template-*`, `gap` and `transform`. Use `getComputedStyle` through the browser console when you can.
3. Check the usual causes in order:
   - Flex items default to `min-width: auto`, so long text or images stop them shrinking; the fix is `min-width: 0` on the item.
   - Percentage heights need a parent with a definite height.
   - `overflow` other than visible on an ancestor breaks `position: sticky`.
   - Margins collapse between block siblings and parent and child.
   - `align-items: stretch` and `auto` margins fight each other.
   - A grid track sized with `1fr` has the same min-content trap; use `minmax(0, 1fr)`.
4. Change one property at a time, in the browser first, then in the source file that owns the rule.
5. Recheck at the failing width and at one narrower and one wider width.

## Rules

- Fix the owning rule; never patch with fixed pixel widths, magic margins or `!important`.
- Do not restructure the markup unless the cause is in it.

## Report

Cause in one sentence, the property and file changed, and the widths you rechecked.

What it does

Most layout bugs come from one wrong rule far from the symptom: a min-width that blocks shrinking, a margin that collapses, a percentage height with no parent height. This skill sends the agent to find that rule rather than add another override.

It reproduces the problem at the failing width, reads the computed values of the element and each ancestor, names the cause, and makes the smallest change that removes it.

Example

you › The sidebar pushes the main column off the screen under 900px

agent › Cause: .main is a flex child holding a pre block, and min-width: auto stopped it shrinking below the code width. Fix: min-width: 0 on .main in layout.css:42. Rechecked at 320, 600 and 1200px; the code block now scrolls inside its own box.

Questions

Does it need a browser?
It works better with one, since computed values settle arguments quickly. Without it, the agent reasons from the CSS and says what it could not confirm.
Will it rewrite my stylesheet?
No. It changes the one rule responsible and reports it, so the diff stays small.
  • Bundle Size Reduction

    Skilljavascript

    Free
  • Frontend i18n

    SkillFrontend

    Free