vGrid

8px-grid policy engine for utility-class projects. Scans .ts, .tsx, .js, .jsx, .html sources. Flags spacing utilities off the 8px grid, raw palette references, and repeated class patterns. Telemetry, preflight gate, programmatic API.

Install

npm install -D @booga/vgrid

Commands

| Command | Description | |---|---| | vgrid check [glob] | Scan files, print violations. Exit 0 = clean, 1 = violations, 2 = error. | | vgrid preflight | Strict mode: exits non-zero on any violation or repeat candidate. Wire as pre-publish gate. | | vgrid telemetry | Aggregate class usage to JSON. | | vgrid map | Print active policy (allowed classes, whitelisted 4px, palette tokens). |

Alias: vpx is identical to vgrid.

Config

vgrid.config.json at project root:

{
  "unit": 8,
  "fourPxAllowed": ["p-1"],
  "paletteAllowedTokens": ["bg-primary", "text-foreground"],
  "repeatThreshold": 5,
  "scan": ["src/**/*.{ts,tsx,js,jsx,html}"]
}

All fields except unit are optional. unit must be 8.

Policy

• 8px grid: spacing utilities with values that map to non-multiples of 8px are flagged (p-1 = 4px, p-3 = 12px, p-0.5 = 2px). Even values are clean (p-2 = 8px, p-4 = 16px).
• Raw palette: bg-red-500, text-blue-300, etc.; any utility with a numeric shade suffix. Use design tokens instead.
• Repeats: class names appearing more than repeatThreshold times surface as refactor candidates.

Programmatic API

import { GridPolicySchema, runCheck, scan } from "@booga/vgrid";

const policy = GridPolicySchema.parse({ unit: 8 });
const result = await scan(policy, process.cwd());

Code of conduct

Contributor Covenant 2.1

License

MIT © 2026 bvasilenko