Architecture Overview
This overview targets contributors and advanced users who want to understand how design-lint works under the hood.
Table of contents
Processing flow
Files pass through a series of stages:
Scan sources → Create documents → Parse → Run rules → Format resultsEach stage is extensible through plugins or custom environments.
Environment model
The Environment abstraction hides platform concerns. The default Node environment bundles a file-based DocumentSource, module resolution, disk caching, and token loading. Other environments can provide equivalents for editors, build tools, or cloud services.
Core modules
DocumentSource
Supplies raw text to the linter. The Node adapter FileSource reads from disk.
Parser adapters
Convert documents into ASTs. CSS uses PostCSS, JavaScript and TypeScript rely on the TypeScript compiler, and Vue/Svelte files compile before analysis. See src/core/framework-parsers.
File type mapping
File extensions and default file search patterns live in file-types.ts. The exported FILE_TYPE_MAP tells the linter which parser to apply, while defaultPatterns lists the globs used to discover files. To support a new extension, add it to FILE_TYPE_MAP (and defaultPatterns if needed) and implement or reference the appropriate parser.
Rule engine
Registers rules and coordinates execution. See src/core/linter.ts and src/core/rule-registry.ts.
Formatter pipeline
Transforms collected results into human- or machine-readable output. Implementations live under src/formatters.
Plugin loader
Resolves configuration packages, rules, and formatters. The Node implementation is src/adapters/node/plugin-loader.ts.
Plugin manager
Coordinates plugin loading and registers rules. It validates rule shape, prevents name collisions, and exposes the final set of plugins to the linter. See src/core/plugin-manager.ts.
Cache provider
Stores persistent cache entries across runs. src/adapters/node/node-cache-provider.ts caches to disk.
Token provider
Supplies design tokens to rules. In v8 the only public token provider is DsrTokenProvider, which fetches the live token graph from a running DSR kernel process via the DSQL protocol. The dsr field on CreateNodeEnvironmentOptions is required — the kernel is the sole authoritative token source. ConfigTokenProvider is an internal class used only by the kernel daemon to seed itself on startup; it is not part of the public API.
Token tracker
Keeps track of token usage across linted files and reports unused values for the design-system/no-unused-tokens rule. Implementation: src/core/token-tracker.ts.
Policy enforcement
A designlint.policy.json file placed next to your config adds static guardrails on top of the rule set. Policies can require specific rules to be enabled, set a minimum severity floor, enforce token coverage thresholds, and activate ratchet mode (preventing new violations from being introduced). Policy files support extends for shared presets. See src/config/policy-loader.ts and src/config/policy-enforcer.ts.
Performance and caching
design-lint processes files concurrently across CPU cores. File-level lint results are cached between runs in .designlintcache to reduce repeated work.
Contributing to core
To work on design-lint itself, read CONTRIBUTING.md. It covers the testing and build process, commit guidelines, and release workflow.