tokens-lint

v0.1.0

Published

a month ago

Standalone linting framework for W3C DTCG design token files

0High
0Medium
0Low

design-tokens-manager

@design-tokens-manager/linter

Standalone linting framework for W3C DTCG design token files.

It is tool-agnostic (no ESLint dependency), ships a small built-in rule pack, and supports custom rules via a plugin-style API.

What You Get

Pure linting core (runtime + types)
5 built-in MVP rules
CLI with stylish, JSON, and SARIF output
Shareable config packages (recommended and strict)
Programmatic API for custom rules/plugins

Packages

@design-tokens-manager/linter-core: traversal, references, runtime, shared types
@design-tokens-manager/linter-rules: built-in rule pack (MVP)
@design-tokens-manager/linter-cli: CLI + config loading + formatters
@design-tokens-manager/linter-config-recommended: baseline shared config
@design-tokens-manager/linter-config-strict: stricter shared config

See package-level docs:

Quick Start

Prerequisite: pnpm

pnpm install
pnpm build
pnpm test:rules

Use It Programmatically

import { createLinter } from '@design-tokens-manager/linter-core';
import { allRules } from '@design-tokens-manager/linter-rules';

const linter = createLinter(allRules);

const result = linter.lint(tokens, {
  rules: {
    'core/valid-dtcg': 'error',
    'core/required-type': 'error',
    'naming/convention': ['warn', { case: 'kebab-case' }],
  },
});

console.log(result.errorCount, result.warningCount);

Use It From The CLI

Example config:

// tokens.lint.config.js
export default {
  rules: {
    'core/valid-dtcg': 'error',
    'core/no-unresolved-refs': 'error',
    'core/no-circular-refs': 'error',
    'naming/convention': ['warn', { case: 'kebab-case' }],
  },
};

Run:

pnpm lint:tokens "tokens/**/*.json"

Common options:

pnpm lint:tokens -f json "tokens/**/*.json"
pnpm lint:tokens -f sarif "tokens/**/*.json"
pnpm lint:tokens -c ./tokens.lint.config.js "tokens/**/*.json"
pnpm lint:tokens --output ./lint-report.txt "tokens/**/*.json"

When using --output, the report is written to that file and a confirmation is printed.

Built-in Rules (MVP)

Core:

core/valid-dtcg
core/required-type
core/no-unresolved-refs
core/no-circular-refs

Naming:

naming/convention

Rule details and examples: RULES.md

Config Presets

Recommended:

import recommended from '@design-tokens-manager/linter-config-recommended';

export default {
  rules: {
    ...recommended.rules,
  },
};

Strict:

import recommended from '@design-tokens-manager/linter-config-recommended';
import strict from '@design-tokens-manager/linter-config-strict';

export default {
  rules: {
    ...recommended.rules,
    ...strict.rules,
  },
};

Why manual merging? shareable-config extends is not auto-resolved by the CLI yet.

Runnable examples: examples/README.md

Plugin Architecture

You can add custom rules using the core API. For a working example, see examples/plugin-example.mjs.

Testing

pnpm test
pnpm test:rules
pnpm test -- --grep "naming"

CLI Output And Exit Codes

Output formats:

stylish
json
sarif

Exit codes:

0: no errors
1: lint completed with at least one error
2: invalid invocation, unsupported format, or no files matched

Project Status

Active and stable for the MVP rule set.

The shared config type currently includes fields such as extends, plugins, ignorePatterns, and overrides, but runtime merge/resolve behavior for those fields is not fully implemented yet. rules is the primary active configuration input today.

Roadmap for additional rules: WHATS-NEXT.md

Contributing

See:

License

MIT. See LICENSE.