Tailwind Spacing Audit

Tailwind Spacing Audit & Refactor

Systematically detect and fix inconsistent spacing in Tailwind CSS v4+ layouts. The root cause of most spacing bugs is fragmented spacing authority — multiple competing mechanisms (gap, margin, padding, fixed widths) controlling the space between the same set of visual peers.

Use $ARGUMENTS as the target scope. If $ARGUMENTS is empty, ask the user which component or file to audit.

Philosophy

Good spacing has one property: a single source of truth per spacing relationship. Every pair of adjacent items should have exactly one class/mechanism determining the space between them. When gap-2 appears on a parent AND me-1 on a child AND ms-2 on a sibling, three competing authorities produce visual noise.

The goal is never "make all numbers the same" — it's to ensure each spacing decision is intentional, non-redundant, and traceable to one mechanism.

Workflow

Step 0: Detect Framework

Before auditing, detect the project's templating framework to determine which attribute name and file globs to use throughout the audit.

Scan the project for template files:

• *.tsx / *.jsx — React (className=)
• *.vue — Vue (class=, :class=)
• *.svelte — Svelte (class=)
• *.astro — Astro (class=)
• *.html — plain HTML (class=)
• *.erb — Rails ERB (class=)
• *.blade.php — Laravel Blade (class=)

Use the detected attribute name(s) and file globs for all subsequent search commands. If multiple frameworks are present, search across all of them.

For React projects, use className= in search patterns. For all other frameworks, use class=. When both React and non-React templates exist, use (class|className)= to match both.

Step 1: Structural Audit

Before touching any code, read references/heuristics.md for the full detection checklist. Scan the component and produce a spacing map — a brief annotation of every spacing mechanism acting on the group of elements the user is concerned about:

[LinkedIn] --gap-1--> [Wrench] --gap-1--> [Babylon.js] --me-1+flex--> [Theme(me-2)]
            ^ parent gap                   ^ margin leak    ^ separate container

This makes fragmentation visible. Call out:

• How many distinct spacing mechanisms are active between visual peers
• Which items live in different containers but appear to be in the same visual group
• Any fixed widths (w-*) on items whose siblings are content-sized

Step 2: Classify Anti-Patterns

Read references/patterns.md for the full catalog with before/after examples. The most common patterns, in order of frequency:

1. Container fragmentation — Visually related items split across sibling containers with different spacing strategies. The #1 cause of "it looks uneven."
2. Margin/gap mixing — A flex parent uses gap-* but children also carry m*-*.
3. Padding asymmetry — Peer interactive elements with different px-* values.
4. Fixed width on content-adaptive items — One item has w-24 while siblings size to content, creating uneven internal whitespace.
5. Wrapper nesting — Unnecessary <div> with flex alignment classes wrapping a single child, adding an extra layout level that obscures the true spacing. Uses className in React (<div className="flex items-center">) or class in other frameworks (<div class="flex items-center">).

Step 3: Refactor

Apply these principles in order of priority:

3a. Merge fragmented containers. If items belong to the same visual group, place them in the same flex container. One parent, one gap-* value. Remove outer margin classes (me-*, ms-*) that were compensating for the split.

3b. Choose one spacing authority per relationship. Between any two adjacent items, exactly one of these should be active — never more:

• gap-* on the parent (preferred for uniform spacing)
• Margin on a specific child (only for intentional exceptions)
• Padding inside the child (for internal spacing, not between-item spacing)

3c. Standardize interactive element envelopes. Buttons, links, and toggles that are visual peers should share:

• The same height class (e.g., all h-8 or all h-12)
• The same horizontal padding (e.g., all px-2)
• Content sizing (no w-* unless every peer also has the same fixed width)

3d. Flatten unnecessary wrappers. If a <div> wraps a single interactive child purely for alignment, check whether the child can receive the alignment classes directly. Common in navbars where each button got wrapped in a single-child alignment div during incremental development.

3e. Preserve intentional spacing breaks. Not every spacing difference is a bug. A visual separator (like a divider between nav groups) is intentional asymmetry. Ask before normalizing something that might be a deliberate design choice.

Step 4: Validate

After refactoring, re-draw the spacing map and confirm:

• Every pair of adjacent items has exactly one spacing authority
• All items in the same visual group share one parent container
• Interactive elements have consistent envelope classes
• No w-* on items that should be content-sized (unless all peers match)
• Hit targets (clickable area) are consistent across peer elements

Tailwind v4 Specifics

Tailwind v4 changed how spacing works in important ways:

• gap-* is the canonical way to space flex/grid children. Prefer it over margins.
• Arbitrary values use gap-[12px] syntax if the scale doesn't have what's needed, but prefer scale values (gap-1 = 4px, gap-2 = 8px, gap-3 = 12px, gap-4 = 16px).
• space-x-* and space-y-* still exist but are margin-based under the hood. Prefer gap-* for new code; flag space-* as a migration opportunity when found alongside gap-*.
• CSS logical properties: me-* (margin-inline-end) and ms-* (margin-inline-start) replace mr-*/ml-* in LTR/RTL-aware code. The anti-pattern is the same regardless of physical vs logical naming.

Output Format

When presenting findings:

1. Spacing map — The visual annotation showing current spacing mechanisms
2. Anti-patterns found — Numbered list with pattern name and specific elements involved
3. Proposed refactor — The actual code change, shown as a focused diff or before/after. Only change spacing-related classes; don't rewrite unrelated markup.
4. Validation checklist — The Step 4 checklist filled in for the refactored code

When the fix is straightforward, collapse steps 1-4 into a concise explanation + code. Don't over-formalize simple cases.

Reference Files

For detailed detection logic and worked examples, consult:

• references/heuristics.md — Seven detection heuristics (H1-H7) with Tailwind class patterns and search commands for codebase-wide scanning
• references/patterns.md — Anti-pattern catalog with before/after examples for each pattern, plus a quick decision tree for diagnosing spacing issues

What This Skill Does NOT Cover

• Color, typography, or non-spacing visual design
• Responsive breakpoint strategy (though spacing changes should preserve existing breakpoints)
• Component API design or prop architecture
• Tailwind config or theme customization
• Animation or transition timing

Portability notes

• $ARGUMENTS — the text the user passed when invoking this skill. If your host does not substitute it, read it as the user's request in the current turn, and ask when there is none.
• Bundled files — every relative path in this skill points at a file shipped inside this skill directory. Read them from here, not from the host's plugin tree.