---
name: radii-spacing
description: Audit CSS and component files for 8pt grid compliance — consistency score, file-by-file violations, sed fix commands, and design debt score
version: 3.0.0
author: radii.cloud
---

# Radii Spacing

Audit the provided code for spacing consistency and 8pt grid compliance. Map every spacing value to Radii's `--spacing-*` token system, report a per-file consistency score, compute a design debt score, and output executable `sed` commands for the most common violations.

## The 8pt grid

Every spacing value should be a multiple of 4px. Radii token scale:

```
--spacing-0:  0px    zero
--spacing-1:  4px    micro gaps, icon padding
--spacing-2:  8px    tight padding, small gaps
--spacing-3:  12px   compact padding
--spacing-4:  16px   standard padding, comfortable gap
--spacing-5:  20px   medium padding
--spacing-6:  24px   section gap, card padding
--spacing-8:  32px   large gap, generous padding
--spacing-10: 40px   section spacing
--spacing-12: 48px   large section
--spacing-16: 64px   hero sections
--spacing-20: 80px   page sections
--spacing-24: 96px   major layout gaps
```

Violations: 5, 7, 9, 11, 13, 14, 15, 17, 18, 19, 21–23, 25–31, etc.

## What to scan

- `padding`, `padding-top/right/bottom/left`
- `margin`, `margin-top/right/bottom/left`
- `gap`, `column-gap`, `row-gap`
- `inset`, `top`, `right`, `bottom`, `left` (spacing use, not positioning)
- Tailwind arbitrary values: `p-[13px]`, `mt-[22px]`, `gap-[18px]`
- CSS custom property values in spacing context

Skip: `border-width`, `border-radius`, `font-size`, `line-height`, `1px` borders, `0`.

## Output format

```
**Spacing audit — [on-grid]/[total] values on-grid**
Design debt score: [off-grid-count / total-count * 100]% off-grid ([off-grid] values need fixing)

Top violations (by frequency):
  [value]px — [count]× → replace with [token] ([px])
  Fix: sed -i 's/[value]px/var(--spacing-[n])/g' [filename].jsx
  Locations: [file]:[line], [file]:[line]

File scores:
  [filename]: [X]% on-grid ([on]/[total]) — [priority: Fix first / Good / Clean]

Most common pattern: [e.g., "13px — off by 1px from --spacing-3 (12px) — used 7 times"]

⚡ Quick fix commands (run in order — highest frequency first):
  1. [count] fixes: sed -i 's/padding: [val]px/padding: var(--spacing-[n])/g' src/**/*.jsx
  2. [count] fixes: sed -i 's/gap: [val]px/gap: var(--spacing-[n])/g' src/**/*.jsx
  3. [count] fixes: sed -i 's/margin: [val]px/margin: var(--spacing-[n])/g' src/**/*.jsx
```

## Tailwind v4 projects

For Tailwind v4, show both approaches:
1. Token reference: `p-[var(--spacing-4)]`
2. After adding to @theme: native class `p-4` works once `--spacing-4: 16px` is in the @theme block

For Tailwind arbitrary values, show:
```bash
# Replace arbitrary Tailwind spacing with token references
sed -i 's/p-\[13px\]/p-\[var(--spacing-3)\]/g' src/**/*.jsx
```

## Design debt scoring

```
0–10% off-grid: ✅ Excellent — minimal cleanup needed
11–25% off-grid: ⚠️ Fair — focused cleanup session recommended
26–50% off-grid: ❌ Poor — spacing system not being used
51–100% off-grid: 🚨 Critical — no spacing system in use
```

## Learn more

https://radii.cloud/terms/spacing-system
https://radii.cloud/terms/padding
https://radii.cloud/terms/whitespace
https://radii.cloud/terms/negative-space