Design tokens are code and deserve the same linting rigor as CSS or JavaScript. This post makes the case for design token linting and breaks down what to lint across three tiers: critical rules (broken references, circular references, type-value mismatches, incomplete structure), quality rules (naming conventions, duplicate values, colour contrast compliance, dark mode completeness, reference depth limits), and nice-to-have rules (documentation, semantic naming, unused tokens, scale consistency). Each rule category maps to a severity level — errors that block, warnings that surface issues, and informational suggestions — with guidance on building up a ruleset from minimum viable to comprehensive.
Table of contents
The Case for Linting Design TokensWhy It Matters Across the TeamWhat Should You Lint?Critical RulesQuality RulesNice-to-Have RulesHow Severity Levels WorkConfiguring Rules by NeedYour Tokens Are CodeSort: