npm package: @paths.design/w3c-tokens-validator
Description: W3C Design Tokens Community Group (DTCG) 1.0 schema and validator
Author: Darian Rosebrook
Latest version: 1.0.0

# W3C Design Tokens Schema & Validator

A generic, reusable schema and validator for [W3C Design Tokens Community Group (DTCG) 1.0](https://tr.designtokens.org/format/) specification. This package can be used in any project without repository-specific dependencies.

## Schema Variants

This package includes **two schema variants**:

- **`schemas/w3c-schema-strict.json`** (default) - Strict DTCG 1.0 compliance, structured values only
- **`schemas/w3c-schema-permissive.json`** - Extended schema with custom types and string value support

See [schemas/README.md](./schemas/README.md) for detailed comparison and usage.

## Features

- ✅ **W3C DTCG 1.0 Compliant**: Full support for all standard token types
- ✅ **Dual Schema Support**: Choose strict (default) or permissive validation
- ✅ **Type-Safe**: TypeScript definitions included
- ✅ **Comprehensive Validation**: Schema validation + custom rules (circular references, type checking)
- ✅ **Accessibility Validation**: Optional WCAG 2.1 contrast ratio validation
- ✅ **Framework Agnostic**: Works with any JavaScript/TypeScript project
- ✅ **CLI Support**: Command-line interface for easy integration
- ✅ **Zero Dependencies** (except Ajv for validation)

## Installation

```bash
npm install @paths.design/w3c-tokens-validator ajv ajv-formats
# or
yarn add @paths.design/w3c-tokens-validator ajv ajv-formats
# or
pnpm add @paths.design/w3c-tokens-validator ajv ajv-formats
```

**Note:** `ajv` and `ajv-formats` are peer dependencies and must be installed separately.

## Usage

### TypeScript/JavaScript Module

```typescript
import { validateDesignTokens, setDefaultSchema } from '@paths.design/w3c-tokens-validator';
import schema from '@paths.design/w3c-tokens-validator/schema-strict'; // or '/schema-permissive'

// Set the schema (required before first use)
setDefaultSchema(schema);

const tokens = {
  color: {
    primary: {
      $type: 'color',
      $value: {
        colorSpace: 'srgb',
        components: [1, 0, 0],
      },
    },
  },
  spacing: {
    small: {
      $type: 'dimension',
      $value: {
        value: 8,
        unit: 'px',
      },
    },
  },
};

const result = validateDesignTokens(tokens);

if (!result.isValid) {
  console.error('Validation errors:', result.errors);
  result.errors.forEach((error) => {
    console.error(`  ${error.path}: ${error.message}`);
  });
}

if (result.warnings.length > 0) {
  console.warn('Warnings:', result.warnings);
}
```

**Note:** You can also provide the schema directly in options:

```typescript
import { validateDesignTokens } from '@paths.design/w3c-tokens-validator';
import schema from '@paths.design/w3c-tokens-validator/schema-strict';

const result = validateDesignTokens(tokens, {
  customSchema: schema,
});
```

### Command Line Interface

```bash
# After building (npm run build)
node dist/cli.js tokens.json

# Validate all JSON files in a directory
node dist/cli.js ./tokens/

# Or use the npm script
npm run validate tokens.json
```

### Validate from File

```typescript
import { validateDesignTokensFromFile } from '@paths.design/w3c-tokens-validator';

const result = await validateDesignTokensFromFile('./tokens.json');

if (result.isValid) {
  console.log('✅ Tokens are valid!');
} else {
  console.error('❌ Validation failed:', result.errors);
}
```

### Format Results

```typescript
import { validateDesignTokens, formatValidationResult } from '@paths.design/w3c-tokens-validator';

const result = validateDesignTokens(tokens);
console.log(formatValidationResult(result));
```

## Supported Token Types

The validator supports all DTCG 1.0 standard token types:

- `color` - Color values with color space support
- `dimension` - Size and spacing values (px, rem)
- `fontFamily` - Font family names or stacks
- `fontWeight` - Font weight (numeric or named)
- `duration` - Time durations in milliseconds
- `cubicBezier` - Easing functions
- `number` - Numeric values
- `border` - Border composite values
- `transition` - Transition composite values
- `shadow` - Box shadow values
- `gradient` - Gradient values
- `typography` - Typography composite values
- `strokeStyle` - Stroke/border style values

## Validation Features

### Schema Validation

Validates tokens against the W3C DTCG 1.0 JSON Schema, checking:

- Required properties (`$type`, `$value`)
- Value structure matches token type
- Valid color spaces and components
- Valid dimension units
- Proper token reference format

### Custom Validations

Beyond schema validation, the validator also checks:

- **Circular References**: Detects circular token dependencies
- **Self-References**: Prevents tokens from referencing themselves
- **Type Consistency**: Warns about potential type mismatches
- **Format Warnings**: Suggests improvements for color/dimension formats

## TypeScript Types

```typescript
import type {
  DesignTokens,
  Token,
  TokenType,
  ColorValue,
  DimensionValue,
  TokenReference,
} from './w3c-types';

const tokens: DesignTokens = {
  color: {
    primary: {
      $type: 'color',
      $value: {
        colorSpace: 'srgb',
        components: [1, 0, 0],
      },
    },
  },
};
```

## Examples

### Basic Color Token

```json
{
  "color": {
    "primary": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [0.2, 0.4, 0.8]
      },
      "$description": "Primary brand color"
    }
  }
}
```

### Dimension Token with Reference

```json
{
  "spacing": {
    "base": {
      "$type": "dimension",
      "$value": {
        "value": 16,
        "unit": "px"
      }
    },
    "large": {
      "$type": "dimension",
      "$value": "{spacing.base}"
    }
  }
}
```

### Typography Composite Token

```json
{
  "typography": {
    "heading": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Inter, sans-serif",
        "fontSize": {
          "value": 24,
          "unit": "px"
        },
        "fontWeight": "bold",
        "lineHeight": 1.5
      }
    }
  }
}
```

### Shadow Token

```json
{
  "shadow": {
    "elevation": {
      "$type": "shadow",
      "$value": {
        "offsetX": {
          "value": 0,
          "unit": "px"
        },
        "offsetY": {
          "value": 4,
          "unit": "px"
        },
        "blur": {
          "value": 8,
          "unit": "px"
        },
        "spread": {
          "value": 0,
          "unit": "px"
        },
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0],
          "alpha": 0.1
        }
      }
    }
  }
}
```

## Validation Options

```typescript
import { validateDesignTokens } from './w3c-validator';

const result = validateDesignTokens(tokens, {
  // Disable custom validations (only schema validation)
  customValidations: false,

  // Use a custom schema instead of default
  customSchema: myCustomSchema,

  // Allow additional properties (default: true)
  allowAdditionalProperties: true,
});
```

## Integration Examples

### CI/CD Pipeline

```yaml
# GitHub Actions example
- name: Validate Design Tokens
  run: |
    npm install @paths.design/w3c-tokens-validator ajv ajv-formats
    npm run build --prefix node_modules/@paths.design/w3c-tokens-validator
    node node_modules/@paths.design/w3c-tokens-validator/dist/cli.js ./tokens/
```

### Pre-commit Hook

```bash
#!/bin/sh
# .git/hooks/pre-commit

npm run validate --prefix node_modules/@paths.design/w3c-tokens-validator -- ./tokens/
if [ $? -ne 0 ]; then
  echo "Design token validation failed!"
  exit 1
fi
```

### npm Scripts

```json
{
  "scripts": {
    "validate:tokens": "w3c-validate ./tokens/",
    "validate:tokens:watch": "chokidar 'tokens/**/*.json' -c 'npm run validate:tokens'"
  }
}
```

## API Reference

### `validateDesignTokens(tokens, options?)`

Validates design tokens against the W3C schema.

**Parameters:**

- `tokens` (unknown): The design tokens object to validate
- `options` (ValidationOptions, optional): Validation options

**Returns:** `ValidationResult`

### `validateDesignTokensFromFile(filePath, options?)`

Validates design tokens from a JSON file.

**Parameters:**

- `filePath` (string): Path to the JSON file
- `options` (ValidationOptions, optional): Validation options

**Returns:** `Promise<ValidationResult>`

### `formatValidationResult(result)`

Formats validation results for console output.

**Parameters:**

- `result` (ValidationResult): Validation result to format

**Returns:** `string`

## Contributing

This is a generic, reusable package. To use it in your project:

1. Copy the files to your project
2. Install dependencies (`ajv`, `ajv-formats`)
3. Import and use as needed

## License

MIT

## Author

**Darian Rosebrook**  
GitHub: [@darianrosebrook](https://github.com/darianrosebrook)

This schema and validator are based on the W3C Design Tokens Community Group specification and can be used freely in any project.

## Contrast Validation (Optional)

The validator includes optional WCAG 2.1 contrast ratio validation for accessibility:

```typescript
import { validateDesignTokensWithContrast } from '@paths.design/w3c-tokens-validator/with-contrast';
import schema from '@paths.design/w3c-tokens-validator/schema-strict';
import { setDefaultSchema } from '@paths.design/w3c-tokens-validator';

setDefaultSchema(schema);

const result = validateDesignTokensWithContrast(tokens, {
  contrastValidation: {
    level: 'AA_NORMAL', // WCAG AA for normal text
    colorPairs: [
      {
        foreground: '#000000',
        background: '#ffffff',
        context: 'Primary text on background',
        level: 'AA_NORMAL',
      },
    ],
  },
});

if (result.contrast) {
  console.log(
    `Contrast validation: ${result.contrast.validPairs}/${result.contrast.totalPairs} pairs passing`
  );
}
```

### WCAG Levels

- `AA_NORMAL`: 4.5:1 (normal text, 14pt and smaller)
- `AA_LARGE`: 3.0:1 (large text, 18pt+ or 14pt+ bold)
- `AAA_NORMAL`: 7.0:1 (enhanced accessibility, normal text)
- `AAA_LARGE`: 4.5:1 (enhanced accessibility, large text)

## References

- [W3C Design Tokens Format Module](https://tr.designtokens.org/format/)
- [Design Tokens Community Group](https://www.w3.org/community/design-tokens/)
- [JSON Schema Specification](https://json-schema.org/)
- [WCAG 2.1 Contrast Requirements](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)