Lint Rules Reference

Dispersa includes six built-in lint rules. Each rule is configurable with options.

require-description

Requires tokens to have a $description field. Descriptions improve token discoverability in design tools and documentation.

rules: {
  'dispersa/require-description': 'warn'
}

Options

Option	Type	Default	Description
minLength	number	1	Minimum description length
ignore	string[]	[]	Glob patterns to exclude

Example

rules: {
  'dispersa/require-description': ['warn', { minLength: 10 }]
}

---

case-check

Enforces consistent token case formatting. Checks each path segment individually, allowing tokens like color.brand.500 where numeric scales are common.

rules: {
  'dispersa/case-check': ['error', { format: 'kebab-case' }]
}

Options

Option	Type	Default	Description
format	'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case' | 'screaming-snake'	'kebab-case'	Naming format to enforce
ignore	string[]	[]	Glob patterns to exclude
pattern	string	—	Custom regex pattern (overrides format)
allowNumericSegments	boolean	true	Allow numeric segments (e.g., spacing.0)

Formats

Format	Example
kebab-case	color-brand-primary, red-500
camelCase	colorBrandPrimary
PascalCase	ColorBrandPrimary
snake_case	color_brand_primary
screaming-snake	COLOR_BRAND_PRIMARY

Custom pattern

rules: {
  'dispersa/case-check': ['error', { pattern: '^[a-z][a-z0-9-]*$' }]
}

---

no-deprecated-usage

Warns when tokens reference deprecated tokens (those with $deprecated). Helps migrate away from deprecated tokens in your design system.

rules: {
  'dispersa/no-deprecated-usage': 'warn'
}

Options

Option	Type	Default	Description
ignore	string[]	[]	Glob patterns to exclude

Example

{
  "color": {
    "old-primary": {
      "$type": "color",
      "$value": "#ff0000",
      "$deprecated": "Use color.brand.primary instead"
    }
  }
}

A token referencing {color.old-primary} will trigger a warning.

---

no-duplicate-values

Detects tokens with identical values. Consider using aliases instead of duplicate values to maintain a single source of truth.

rules: {
  'dispersa/no-duplicate-values': 'warn'
}

Options

Option	Type	Default	Description
ignore	string[]	[]	Glob patterns to exclude
types	string[]	[]	Only check specific token types

Example: Check only colors

rules: {
  'dispersa/no-duplicate-values': ['warn', { types: ['color'] }]
}

---

path-schema

Validates token path structure using segment definitions and path patterns. Most powerful for enforcing organizational conventions.

rules: {
  'dispersa/path-schema': ['warn', {
    segments: {
      category: { values: ['color', 'spacing'] },
      component: { values: ['button', 'input'] },
    },
    paths: ['{category}.{component}.*'],
  }]
}

Options

Option	Type	Default	Description
segments	Record<string, SegmentDefinition>	{}	Named segment definitions
paths	string[]	[]	Valid path patterns with {segment} placeholders
transitions	TransitionRule[]	[]	Context-aware segment transition rules
ignore	string[]	[]	Glob patterns to exclude

Segment Definition

{
  category: {
    values: ['color', 'spacing', 'typography'],  // or RegExp
  }
}

Path Patterns

{
  paths: [
    'color.base.{brand}',
    'color.semantic.{element}.{role}',
    'color.component.{component}.{state}',
  ]
}

Use {segment} for named segments, * for wildcard segments, {name?} for optional segments, and {a|b} for OR syntax (matches segment definitions a OR b).

Transition Rules

Alternative to patterns - define which segments can follow which:

{
  transitions: [
    { from: 'color', to: ['base', 'semantic', 'component'] },
    { from: 'semantic', to: ['text', 'bg', 'border'] },
    { from: 'semantic', to: 'component', allow: false }, // forbidden
  ]
}

Complete example

const lintRules = {
  'dispersa/path-schema': [
    'warn',
    {
      segments: {
        category: {
          values: ['color', 'spacing', 'typography', 'shadow'],
        },
        component: {
          values: ['button'],
        },
        variant: {
          values: ['primary', 'secondary', 'ghost', 'danger'],
        },
        property: {
          values: ['background', 'text', 'border', 'padding'],
        },
        state: {
          values: ['hover', 'active', 'focus', 'disabled'],
        },
      },
      paths: [
        '{category}.{component}.{property}',
        '{category}.{component}.{property}.{state?}',
        '{category}.{component}.{variant?}.{property}',
        '{category}.{component}.{variant?}.{property}.{state?}',
      ],
    },
  ],
}