Configuration

Configure design-token-lint with .design-token-lint.json — prohibited patterns, allowed exceptions, ignored files, and scan patterns.

Create a .design-token-lint.json or design-token-lint.config.json file at your project root. The linter loads the first file it finds, falling back to built-in defaults if neither exists.

Full Example

{
  "prohibited": [
    "p-{n}",
    "px-{n}",
    "py-{n}",
    "m-{n}",
    "gap-{n}",
    "bg-{color}-{shade}",
    "text-{color}-{shade}",
    "border-{color}-{shade}"
  ],
  "allowed": ["p-0", "m-0", "gap-0", "p-1px"],
  "ignore": ["**/*.test.*", "**/*.stories.*"],
  "patterns": [
    "src/**/*.{tsx,jsx,astro}",
    "components/**/*.{tsx,jsx,astro}"
  ],
  "classAttributes": ["className", "class", "inputClassName", "wrapperClass"],
  "classFunctions": ["cn", "clsx", "classNames", "twMerge", "cva", "tv"]
}

Fields

All fields are optional and fall back to built-in defaults.

prohibited

An array of class name patterns to flag. Each pattern uses a placeholder syntax:

• {n} — matches numeric values like 4, 8, 0.5, 16. Used for spacing (padding, margin, gap, inset, top/left/right/bottom, etc.)
• {color} — matches standard Tailwind color names: slate, gray, zinc, neutral, stone, red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose
• {shade} — matches 2-3 digit shade values like 50, 100, 500, 950

Examples:

• p-{n} matches p-4, p-8, p-0.5
• bg-{color}-{shade} matches bg-red-500, bg-blue-300
• gap-x-{n} matches gap-x-2, gap-x-6

allowed

An exact-match allowlist. Any class in this array always passes, regardless of prohibited patterns. Useful for escape hatches like p-0, m-0, or p-1px.

ignore

File glob patterns to skip entirely. Common patterns:

{
  "ignore": [
    "**/*.test.*",
    "**/*.stories.*",
    "**/*.spec.*"
  ]
}

patterns

File glob patterns to scan when the CLI is called without explicit file arguments. If omitted, the CLI uses a default set (src/**, components/**, lib/**, app/**).

suggestionSuffix

A string appended to violation messages after the — separator, replacing the default suggestion text. Use this to point developers toward your project’s specific token naming convention.

Default messages (no suggestionSuffix):

• Spacing: Numeric spacing "p-4" — use a semantic spacing token or arbitrary value
• Color: Default Tailwind color "bg-gray-500" — use a design system color token

With suggestionSuffix:

{
  "suggestionSuffix": "use hgap-*/vgap-* or zd-* tokens"
}

• Spacing: Numeric spacing "p-4" — use hgap-*/vgap-* or zd-* tokens
• Color: Default Tailwind color "bg-gray-500" — use hgap-*/vgap-* or zd-* tokens

classAttributes

An array of attribute names the extractor scans for class names. Any JSX/HTML attribute in this list is treated as a class attribute and its string value is extracted and linted.

Default: ["className", "class"]

Use this when your project uses component libraries that accept class names through non-standard prop names:

{
  "classAttributes": ["className", "class", "inputClassName", "wrapperClass"]
}

This is useful for libraries like Headless UI, Radix UI, or custom component libraries that pass class names via multiple props.

Note: class:list (Astro’s directive syntax) is always scanned regardless of this setting.

classFunctions

An array of utility function names the extractor scans for class name arguments. Calls to these functions are extracted and their string arguments are linted.

Default: ["cn", "clsx", "classNames", "twMerge"]

Use this to add support for additional class-merging utilities in your project:

{
  "classFunctions": ["cn", "clsx", "classNames", "twMerge", "cva", "tv", "twJoin"]
}

This is useful when using libraries like class-variance-authority (cva), tailwind-variants (tv), or additional utilities from tailwind-merge such as twJoin.

Built-in Defaults

If no config file exists, the linter uses these defaults:

• Prohibited: all standard spacing utilities (p-*, m-*, gap-*, inset-*, scroll-*) with numeric values, plus all color utilities (bg-*, text-*, border-*, ring-*, etc.) with default Tailwind color-shade combinations
• Allowed: p-0, m-0, gap-0, p-1px
• Ignore: **/*.test.*, **/*.stories.*

See the package README for the full default list.

What Passes Automatically

These classes always pass without being in allowed:

• Semantic spacing tokens: p-hgap-sm, gap-vgap-xs, m-hgap-md (classes with hgap-* or vgap-* suffixes)
• Non-default colors: bg-surface, text-fg, bg-zd-black (any color name that isn’t one of the standard Tailwind palette names)
• Arbitrary values: w-[28px], bg-[#123], p-[10px]
• Non-spacing and non-color utilities: flex, grid, hidden, w-full, font-bold, etc.