From design-system-ops
Validates design token files against DTCG 2025.10, Style Dictionary v3/v4, Tokens Studio, or custom schemas to catch structural errors before builds fail.
npx claudepluginhub murphytrueman/design-system-opsThis skill uses the workspace's default tool permissions.
A skill for validating that design token files conform to their expected format — DTCG 2025.10, Style Dictionary v3/v4, Tokens Studio, or a custom schema. Catches structural issues before they break build pipelines, cause silent failures, or produce incorrect output.
Audits design system token definitions for naming violations, missing semantic tiers, and structural debt in tiered architectures. Generates severity-rated findings and prioritized remediations.
Audits design token usage in code and design files for consistency, coverage, gaps, and hard-coded values. Generates reports with prioritized recommendations.
Detects design systems in code, identifies token drifts with paired evidence blocks showing definitions vs conflicting usages. Use for auditing UI consistency.
Share bugs, ideas, or general feedback.
A skill for validating that design token files conform to their expected format — DTCG 2025.10, Style Dictionary v3/v4, Tokens Studio, or a custom schema. Catches structural issues before they break build pipelines, cause silent failures, or produce incorrect output.
Token files are infrastructure. When a token file is malformed — a missing $type declaration, a $value that resolves to nothing, an alias that points to a deleted token — the failure mode is rarely loud. The build might still succeed. The wrong value might ship. The design intent might be silently lost.
Schema validation is the first line of defence. It answers a simple question: do these files meet the structural contract they claim to meet? A DTCG file must have $value on every token. A Style Dictionary file must have valid reference syntax. A Tokens Studio export must preserve group hierarchy.
This skill is not about naming conventions or architectural quality — those belong in token-audit. This skill is about structural integrity: can the file be parsed, transformed, and consumed by downstream tools without error?
This skill validates token file structure only. It does not assess naming quality (use naming-audit), token architecture health (use token-audit), or token usage in code (use token-compliance). If the token source format is not recognisable as DTCG, Style Dictionary, Tokens Studio, or a declared custom schema, ask the user to identify the format before proceeding. If no token files are provided or accessible, there is nothing to validate — stop and confirm the file location with the user.
Check for .ds-ops-config.yml in the project root. If present, load:
system.token_format — pre-selects the primary format to validate against (dtcg, style-dictionary-v3, style-dictionary-v4, tokens-studio, custom)integrations.style_dictionary — if enabled, use Style Dictionary's built-in validation as a cross-checkseverity.schema_* — overrides for finding severity (e.g. schema_missing_type: critical)Style Dictionary v4 (integrations.style_dictionary.enabled: true):
npx style-dictionary build --config [path] --dry-run to get Style Dictionary's own validation errorsIf no config exists, proceed with defaults.
Ask for or confirm:
value property)$value property)If the token files contain format indicators (e.g., $type fields suggest DTCG), auto-detect the format and confirm with the user.
For each file in the provided path:
Produce the file inventory:
| File | Format detected | Tokens | Parse status |
|---|---|---|---|
| colors.json | DTCG 2025.10 | 47 | ✓ Parsed |
| spacing.json | Style Dictionary v3 | 12 | ✓ Parsed |
| broken.json | Unknown | 0 | ✗ Parse error: unexpected token at line 23 |
For each successfully parsed file, run format-specific validation:
$value property$type (or inherit from a parent group's $type){group.token} syntax with curly braces$type, all children without their own $type inherit it$ prefix on non-spec properties — custom properties should not start with $ to avoid confusion with spec properties$extensions if presentvalue required — every leaf token must have a value property (not $value){group.token.value} with .value suffixvalue, original, name, comment, themeable, attributes are reservedAll DTCG checks above, plus:
$value and $type (not legacy value){size.base} * 2), validate syntax{group.token} without .value suffixIf files use multiple formats (common during migration):
Structure the report as:
# Token Schema Validation Report
## Summary
- Files scanned: X
- Files valid: Y
- Files with errors: Z
- Target format: [DTCG 2025.10 / Style Dictionary v3 / etc.]
- Strictness: [strict / lenient]
## File Inventory
[Table from Step 2]
## Validation Results
### ✓ Valid Files
[List each valid file with token count]
### ✗ Files with Errors
#### [filename.json]
| # | Check | Status | Detail | Fix |
|---|-------|--------|--------|-----|
| SV-01 | $type required | ❌ FAIL | 3 tokens missing $type: `color.brand.accent`, `spacing.page.gutter`, `font.body.size` | Add `$type: "color"`, `$type: "dimension"`, `$type: "fontFamily"` respectively |
| SV-02 | Alias resolution | ❌ FAIL | `{color.legacy.blue}` referenced by `color.semantic.info` does not exist | Either create `color.legacy.blue` or update the reference to `{color.primitive.blue.500}` |
### ⚠️ Warnings
[Non-critical issues: missing $description, custom $ properties, etc.]
## Format Compliance Score
- DTCG 2025.10: X% compliant (Y/Z checks pass)
- [If migrating] Legacy tokens remaining: N files, M tokens
## Recommendations
[Prioritised list of fixes, grouped by: parse errors first, then broken references, then missing declarations]
If the user requests it or if the output will feed into another tool:
{
"format": "dtcg-2025.10",
"files_scanned": 12,
"files_valid": 10,
"files_invalid": 2,
"findings": [
{
"id": "SV-01",
"file": "colors.json",
"token": "color.brand.accent",
"check": "$type_required",
"status": "FAIL",
"fix": "Add $type: \"color\""
}
]
}
Before delivering the report, verify:
$type: \"color\" to token color.brand.accentFor systems with fewer than 5 token files: run the same validation but present results as a single-page summary rather than a per-file breakdown. Include the specific fix for every single issue rather than grouping by pattern.