@breadstone-infrastructure/token-linter

A configurable, extensible linter for Style Dictionary token JSON files. Validates structure, consistency, naming, and values across themes.

Features

• 14 built-in rules covering structural, quality, and formatting concerns
• Config-file driven — place a tokenlinter.config.mjs in your project
• Rule severity overrides — set rules to error, warning, info, or off
• Auto-fix support — fixable rules (alphabetical sort, missing includes) can write corrections
• Multiple reporters — console (colored), JSON (CI), summary (compact)
• Extensible — register custom rules via the public IRule interface
• Standalone — usable as a library, CLI, or via Nx executor

Usage

Config file (tokenlinter.config.mjs)

import { defineConfig } from '@breadstone-infrastructure/token-linter';

export default defineConfig({
  themes: ['joy', 'memphis', 'cosmopolitan'],
  tokensDir: 'tokens/themes',
  mixinsDir: 'tokens/mixins',
  reporter: 'console',
  rules: {
    'forbidden-value': 'warning',
    'empty-json': 'off',
  },
  ruleOptions: {
    'forbidden-key': { keys: ['transition', 'shadow'], themes: ['memphis'] },
    'nested-depth': { maxDepth: 3 },
  },
});

Nx Executor

{
  "token-lint": {
    "executor": "@breadstone-infrastructure/nx-tasks:token-linter",
    "options": {
      "configFile": "tokenlinter.config.mjs"
    }
  }
}

Built-in Rules

| Rule | Default Severity | Fixable | Description | |---|---|---|---| | component-presence | error | — | All themes contain the same component files | | key-consistency | error | — | Same keys per component across themes | | includes-consistency | warning | — | $includes arrays match across themes | | missing-includes | warning | ✓ | All files have a $includes field | | empty-json | warning | — | No empty token files | | forbidden-value | warning | — | No forbidden values (unset, 0px, all) | | forbidden-key | warning | — | No forbidden keys (configurable) | | naming-convention | warning | — | camelCase token keys | | value-schema | info | — | Values match CSS patterns | | value-consistency | info | — | var() vs hardcoded drift detection | | duplicate-value | info | — | Duplicate values that could be shared | | nested-depth | warning | — | Max nesting depth enforcement | | mixin-reference | error | — | $includes refs point to real mixins | | alphabetical-sort | warning | ✓ | Keys sorted alphabetically |

License

MIT