Known Limitations

Inherent limitations of the static analysis approach used by design-token-lint.

design-token-lint uses regex-based static analysis to extract class names from source files. This approach is fast and requires no build step, but it cannot evaluate code at runtime. As a result, some dynamic patterns are not correctly analyzed.

The set of attribute names and utility functions scanned is configurable via classAttributes and classFunctions in your config file. By default, className, class, cn, clsx, classNames, and twMerge are scanned.

These are not bugs — they are inherent to static analysis.

Supported: Multiline className

Multiline className values are supported:

<div
  className="
    p-4
    bg-gray-500
  "
>

Classes spread across multiple lines are extracted correctly.

Supported: Object Keys in class

Astro’s class:list object syntax is supported — class names in quoted keys are extracted:

<div class:list={[{ "p-4": true, "m-8": isActive }]}>

Both p-4 and m-8 are extracted and linted.

Limitation: Conditional Expressions

Ternary expressions inside className are not extracted:

// Not linted — classes inside ternaries are silently skipped
<div className={isActive ? "p-4" : "m-8"}>

The extractor looks for string literals directly assigned to className or class. The ternary syntax is not matched, so no classes are extracted — and no violations are reported.

This means the linter will silently miss prohibited classes inside ternaries rather than producing false positives. There is no workaround for making the linter check inside ternaries. If you need to ensure these classes are linted, extract them into static variables:

// These static strings are linted
const activeClass = "p-hgap-sm";
const inactiveClass = "m-vgap-md";
<div className={isActive ? activeClass : inactiveClass}>

Limitation: Template Interpolation

Template literals with dynamic expressions produce garbled class names that never match any linting rules:

// Not linted — `p-${size}` is extracted as a literal string, matches no rules
<div className={`p-${size} bg-${color}-500`}>

The extractor captures the raw template content including ${...} expressions. The resulting strings (p-${size}, bg-${color}-500) don’t match any pattern, so violations inside them are never reported.

Workaround: Add an ignore comment or refactor to use static class names:

// Use ignore comment to acknowledge this is intentional
{/* design-token-lint-ignore */}
<div className={`p-${size}`}>

Limitation: Escaped Quotes

Class attributes containing escaped quotes may extract incorrectly:

// May extract incorrectly
<div className="p-4 \"m-8\"">

The regex parser does not handle escaped quote sequences inside string literals.

Workaround: Avoid escaped quotes inside class attributes. Use JSX expression syntax instead:

<div className={'p-4 m-8'}>

Summary