vLint

AST linter for vDsl prop surface. Token scale validation, className/style bypass guards, as-prop consistency. CLI + ESLint plugin.

Why

A design system holds only while every component uses it. The first hand-typed className="mt-[13px]", style={{padding: 7}}, or bg-[#3a3a3a] is a hole. Nothing stops it — types pass, build is green, the screen renders. The erosion is invisible until it is irreversible: months later half the app tracks the tokens and half is frozen ad-hoc pixels and hardcoded hex, theme changes propagate to one half, dark mode breaks in scattered places, the 8px grid is full of 7px and 13px gaps.

vLint is the watchdog against that drift. Each escape from the vDsl surface is caught at lint time — on the pull request that introduced it — not discovered as rot a year later. Without vLint you have a design system everyone bypasses; with it, bypassing the system fails the build.

Install

npm install @booga/vlint

CLI

vlint src/**/*.tsx
vlint src/components/Button.tsx --config vlint.config.json

Exit codes: 0 clean, 1 error-severity violations, 2 internal failure.

Programmatic

import { lint, lintGlob, rules } from "@booga/vlint";

const result = lint("src/Button.tsx");
result.diagnostics; // { file, line, column, ruleId, message, severity }[]

const results = await lintGlob("src/**/*.tsx", {
  ignore: ["**/dist/**"],
  rules: { "valid-token-values": "error" },
  tokenScale: [0, 1, 2, 3, 4, 6, 8, 12, 16],
});

ESLint plugin

// .eslintrc.js
module.exports = {
  plugins: ["vlint"],
  extends: ["plugin:vlint/recommended"],
};

Config

import { LintConfigSchema } from "@booga/vlint";

// All fields optional — schema shows defaults
LintConfigSchema.parse({
  rules: { "valid-token-values": "error" },
  ignore: ["**/node_modules/**", "**/dist/**"],
  tokenScale: [0, 1, 2, 3, 4, 6, 8, 12, 16, 20, 24],
  tokenProps: ["p", "px", "py", "m", "mx", "my", "gap", "w", "h"],
});

Rules

| Rule | Default | What it flags | Drift it prevents | |---|---|---|---| | no-raw-classname | error | className on any lowercase HTML element | margins/padding that never track theme or spacing changes | | no-raw-style | error | style prop on any JSX element | inline pixel values off the 8px grid, frozen and unthemeable | | valid-token-values | warn | Token prop values not in the declared scale | off-grid spacing that breaks rhythm across screens | | no-arbitrary-class | error | Tailwind arbitrary values like bg-[#fff] | hardcoded hex that breaks dark mode and palette changes | | consistent-as-prop | warn | as="div" polymorphism with raw HTML tags on vDsl components | polymorphic components downgraded to raw tags, losing semantic + styling guarantees |

Contributing

Code of conduct: Contributor Covenant 2.1

License

MIT © 2026 bvasilenko