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