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 metadata and parsed documents across runs. src/adapters/node/node-cache-provider.ts caches to disk.
Token provider
Supplies design tokens to rules. src/adapters/node/token-provider.ts normalises tokens from configuration.
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.
Performance and caching
design-lint processes files concurrently across CPU cores. Parsed documents and rule results are cached between runs in .designlintcache to reduce 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.