Token Consistency Checking

Token consistency checking verifies that design tokens maintain integrity across the system, identifying discrepancies before they cause problems. Consistency checking catches issues like duplicate values, broken references, naming convention violations, and misalignment between sources. Regular consistency checking maintains the reliability that makes design tokens valuable.

What Is Token Consistency Checking

Token consistency checking is the process of validating that tokens meet defined quality criteria and maintain expected relationships. This includes verifying that token values are valid, references resolve correctly, naming follows conventions, and tokens align with their authoritative sources.

Consistency checking operates at multiple levels: individual token validation, relationship verification between tokens, and alignment checking between different system locations.

How Token Consistency Checking Works

Consistency checking applies various validation rules to token data.

Value validation verifies that token values are appropriate for their types:

function validateColorValue(token) {
  const hexPattern = /^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{8})$/;
  const rgbPattern = /^rgb\(\d{1,3},\s*\d{1,3},\s*\d{1,3}\)$/;

  if (!hexPattern.test(token.value) && !rgbPattern.test(token.value)) {
    return { valid: false, error: `Invalid color value: ${token.value}` };
  }
  return { valid: true };
}

Reference validation ensures all token references resolve:

function validateReferences(tokens) {
  const errors = [];
  const tokenNames = new Set(tokens.map(t => t.name));

  tokens.forEach(token => {
    if (token.value.startsWith('{') && token.value.endsWith('}')) {
      const refName = token.value.slice(1, -1);
      if (!tokenNames.has(refName)) {
        errors.push(`Broken reference: ${token.name} -> ${refName}`);
      }
    }
  });

  return errors;
}

Naming validation checks adherence to conventions:

function validateNaming(token, conventions) {
  const segments = token.name.split('.');

  if (segments.length < conventions.minDepth) {
    return { valid: false, error: `Token name too shallow: ${token.name}` };
  }

  if (!conventions.validCategories.includes(segments[0])) {
    return { valid: false, error: `Invalid category: ${segments[0]}` };
  }

  return { valid: true };
}

Cross-location validation compares tokens across different sources (design tool exports, code repositories, documentation) to identify divergence.

Key Considerations

• Checking should run automatically in CI/CD pipelines
• Validation rules should be configurable per organization
• Error messages should be actionable and specific
• Warnings versus errors should have clear distinction
• Historical consistency (changes over time) may warrant tracking
• Performance matters for large token sets
• False positives erode trust in the checking system
• New validation rules should be introduced carefully

Common Questions

What should be checked automatically versus manually?

Automated checking suits objective, rule-based validation. Manual review handles subjective judgments and context-dependent decisions.

Automated checking should cover:

• Syntax validity (proper JSON, valid values)
• Reference integrity (all references resolve)
• Naming convention compliance (pattern matching)
• Duplicate detection (identical values or names)
• Type validation (colors are colors, numbers are numbers)
• Scale conformance (values on defined scales)

Manual review should cover:

• Semantic appropriateness (does this color fit its purpose?)
• Design coherence (do new tokens fit the system?)
• Deprecation decisions (should this token be retired?)
• Exception approvals (when rules should be bent)

The boundary between automated and manual shifts as systems mature. Patterns that initially require judgment can become automated rules once the judgment is codified.

How should checking integrate with development workflow?

Checking should be embedded in the development workflow at multiple points.

Pre-commit hooks run basic validation before code is committed locally. Fast checks catch obvious issues immediately:

#!/bin/bash
npm run validate-tokens || exit 1

Pull request validation runs comprehensive checks when changes are proposed:

# GitHub Actions
on: pull_request
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm ci
      - run: npm run validate-tokens
      - run: npm run check-consistency

Scheduled checks run broader validation periodically, catching issues that might not appear in individual change validation:

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

Blocking versus warning behavior should match issue severity. Broken references should block merges. Minor naming variations might warn without blocking.

How should consistency issues be reported?

Reporting should make issues visible and actionable.

Build output provides immediate feedback during development:

Token Consistency Check Results
================================
Errors: 3
  - color.brand.primary: Broken reference to color.blue.500
  - spacing.xxl: Value 72px not on spacing scale
  - typography.display: Missing required property 'lineHeight'

Warnings: 2
  - color.accent: Similar value to color.primary (consider alias)
  - spacing.xs: Unused token (no references found)

Dashboard visualization aggregates consistency status across the system over time. Trend lines show whether consistency is improving or degrading.

Notification channels alert appropriate people when issues are detected. Slack or email notifications for critical issues ensure timely response.

Issue tracking creates tickets for issues requiring follow-up. Automated issue creation from consistency failures ensures problems are tracked to resolution.

Summary

Token consistency checking validates that tokens maintain integrity through value validation, reference verification, naming convention enforcement, and cross-location alignment. Automated checking in CI/CD pipelines catches objective issues, while manual review handles subjective judgments. Clear reporting through build output, dashboards, and notifications ensures issues are visible and actionable. Regular consistency checking maintains the reliability that makes token systems valuable.