{"_id":"@designesy/tokens","_rev":"4-7881dc8367f2e4118d9bd6712141ed79","name":"@designesy/tokens","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@designesy/tokens","version":"0.1.0","keywords":["design-tokens","dtcg","w3c","design-tokens-community-group","token-validation","design-system","ci","lint","designesy"],"author":{"name":"Designesy","email":"hello@designesy.org"},"license":"MIT","_id":"@designesy/tokens@0.1.0","maintainers":[{"name":"designesy","email":"le@designesy.org"}],"homepage":"https://www.designesy.org/contracts/tokens","bugs":{"url":"https://github.com/LE-VAI/designesy-org/issues"},"bin":{"designesy-tokens":"dist/cli.js"},"dist":{"shasum":"bd603463adfff013d9f883ee65500be9e3cdc462","tarball":"https://registry.npmjs.org/@designesy/tokens/-/tokens-0.1.0.tgz","fileCount":6,"integrity":"sha512-y2PQfUHK50tUB5uop4Tyk78yDWSKm8DfglX5HqtQZ0kWrcAq2uxQk4yFbcHFa8PgyA/c5H8zc+iy9POv5E4Ymg==","signatures":[{"sig":"MEYCIQCFalJ6vHduhOOt+jCxW7P9Zfknqa3Bt2T13brHCtKlogIhAIuoF/I0A/2feB4rSumIgxcH0gCDY/C89DdOeTthM4GU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33140},"main":"./dist/validator.js","type":"module","types":"./dist/validator.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/validator.d.ts","import":"./dist/validator.js"}},"gitHead":"2235f29b739f7f208ac23f60645bbe61ccefa30c","scripts":{"build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"designesy","email":"le@designesy.org"},"repository":{"url":"git+https://github.com/LE-VAI/designesy-org.git","type":"git","directory":"packages/tokens"},"_npmVersion":"11.12.1","description":"Standalone DTCG 2025.10 design token validator — 10 conformance checks, zero dependencies, works offline.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^26.2.0"},"_npmOperationalInternal":{"tmp":"tmp/tokens_0.1.0_1786768162919_0.0029461887446533552","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@designesy/tokens","version":"0.2.0","keywords":["design-tokens","dtcg","w3c","design-tokens-community-group","token-validation","design-system","ci","lint","designesy"],"author":{"name":"Designesy","email":"hello@designesy.org"},"license":"MIT","_id":"@designesy/tokens@0.2.0","maintainers":[{"name":"designesy","email":"le@designesy.org"}],"homepage":"https://www.designesy.org/tokens","bugs":{"url":"https://github.com/LE-VAI/designesy-org/issues"},"bin":{"designesy-tokens":"dist/cli.js"},"dist":{"shasum":"b59a57549788bf367f6afabd289efc3398829d7a","tarball":"https://registry.npmjs.org/@designesy/tokens/-/tokens-0.2.0.tgz","fileCount":6,"integrity":"sha512-69qJDC++p54dts9NH2U8POkR1W1a0iDCSZyZ9DJhp3NPZtA0K3Ky0xcfNOldsg5Fe+84r27BxXTJ6xdTw1VVvg==","signatures":[{"sig":"MEUCIQCZPJmIZxyZrudT8eOsl85k7VgeTUBlYBhqVHPhPLcPcwIgdB5HYXP4LYVAuPCCDEo6/Bwyy6DfTUBmBNCsn+L11l4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":60616},"main":"./dist/validator.js","type":"module","types":"./dist/validator.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/validator.d.ts","import":"./dist/validator.js"}},"gitHead":"9520c30e8779b13acfb22b2438018388b41af808","scripts":{"test":"node --test test/test.js","build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"designesy","email":"le@designesy.org"},"repository":{"url":"git+https://github.com/LE-VAI/designesy-org.git","type":"git","directory":"packages/tokens"},"_npmVersion":"11.12.1","description":"Standalone DTCG 2025.10 design token validator — 20 conformance checks, zero dependencies, works offline.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^26.2.0"},"_npmOperationalInternal":{"tmp":"tmp/tokens_0.2.0_1786780968759_0.15883930422885606","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@designesy/tokens","version":"0.2.1","keywords":["design-tokens","dtcg","w3c","design-tokens-community-group","token-validation","design-system","ci","lint","designesy"],"author":{"name":"Designesy","email":"hello@designesy.org"},"license":"MIT","_id":"@designesy/tokens@0.2.1","maintainers":[{"name":"designesy","email":"le@designesy.org"}],"homepage":"https://www.designesy.org/contracts/tokens","bugs":{"url":"https://github.com/LE-VAI/designesy-org/issues"},"bin":{"designesy-tokens":"dist/cli.js"},"dist":{"shasum":"f4e19b54729b71df6a345af9702dbfe969068c88","tarball":"https://registry.npmjs.org/@designesy/tokens/-/tokens-0.2.1.tgz","fileCount":8,"integrity":"sha512-bsfFoyPeOIl0y5j7hfHYq1hsLu6YGfV7jBTHCqL9jY4dgC0YR65Uz84XU3cMm05QvNt6ghaGgMEKxV7fdp33uw==","signatures":[{"sig":"MEYCIQDTodZlTH/mUZEEhStvDZwSQ45biisehdGCtHjBaquLkQIhAPGSt4PKL0+riyAKjdAsJwVtwQZJS7MloyG/0hxYsxCH","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":65950},"main":"./dist/validator.js","type":"module","types":"./dist/validator.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/validator.d.ts","import":"./dist/validator.js"}},"gitHead":"3d3a39ae6688318a020eeb4cf58fc72bc9d5a32e","scripts":{"test":"node --test test/test.js","build":"tsc -p tsconfig.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"designesy","email":"le@designesy.org"},"repository":{"url":"git+https://github.com/LE-VAI/designesy-org.git","type":"git","directory":"packages/tokens"},"_npmVersion":"11.12.1","description":"Standalone DTCG 2025.10 design token validator — 20 conformance checks, zero dependencies, works offline.","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^26.2.0"},"_npmOperationalInternal":{"tmp":"tmp/tokens_0.2.1_1786809609244_0.6080748822746156","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@designesy/tokens","version":"0.2.2","description":"Standalone DTCG 2025.10 design token validator — 20 conformance checks, zero dependencies, works offline.","license":"MIT","author":{"name":"Designesy","email":"hello@designesy.org"},"maintainers":[{"name":"designesy","email":"le@designesy.org"}],"homepage":"https://www.designesy.org/contracts/tokens","repository":{"type":"git","url":"git+https://github.com/LE-VAI/designesy-org.git","directory":"packages/tokens"},"bugs":{"url":"https://github.com/LE-VAI/designesy-org/issues"},"keywords":["design-tokens","dtcg","w3c","design-tokens-community-group","token-validation","design-system","ci","lint","designesy"],"type":"module","exports":{".":{"import":"./dist/validator.js","types":"./dist/validator.d.ts"}},"main":"./dist/validator.js","types":"./dist/validator.d.ts","bin":{"designesy-tokens":"dist/cli.js"},"engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^26.2.0","typescript":"^5.7.0"},"scripts":{"build":"tsc -p tsconfig.json","test":"node --test test/test.js","pretest":"npm run build","prepublishOnly":"npm run build"},"_id":"@designesy/tokens@0.2.2","gitHead":"4a6b9b8512a85fa8bd21d37a056b6e3786a49ee0","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-xmoadlXnwQ2MeGDEntnVgZtHc0778YjYW7ZLSxFYcKFNdAnad7kXcA1Zdey4FcgyR/iSN2aWuIQKlARmCVyahw==","shasum":"87c3052017921649748710ba60055a8d78824dcc","tarball":"https://registry.npmjs.org/@designesy/tokens/-/tokens-0.2.2.tgz","fileCount":8,"unpackedSize":65899,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@designesy%2ftokens@0.2.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCLTE+tWtsGisUdb8/Jf5WwwJMdB9Vn843Id85G2gBW8AIhAKbqcfPWO9cG68+7Gq5WVPVrjtuSnA866QVhEuX8UORS"}]},"_npmUser":{"name":"designesy","email":"le@designesy.org"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tokens_0.2.2_1786847093285_0.14773576223133844"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-15T04:29:22.822Z","modified":"2026-08-16T02:24:53.718Z","0.1.0":"2026-08-15T04:29:23.053Z","0.2.0":"2026-08-15T08:02:48.901Z","0.2.1":"2026-08-15T16:00:09.398Z","0.2.2":"2026-08-16T02:24:53.414Z"},"bugs":{"url":"https://github.com/LE-VAI/designesy-org/issues"},"author":{"name":"Designesy","email":"hello@designesy.org"},"license":"MIT","homepage":"https://www.designesy.org/contracts/tokens","keywords":["design-tokens","dtcg","w3c","design-tokens-community-group","token-validation","design-system","ci","lint","designesy"],"repository":{"type":"git","url":"git+https://github.com/LE-VAI/designesy-org.git","directory":"packages/tokens"},"description":"Standalone DTCG 2025.10 design token validator — 20 conformance checks, zero dependencies, works offline.","maintainers":[{"name":"designesy","email":"le@designesy.org"}],"readme":"# @designesy/tokens\n\n[![npm version](https://img.shields.io/npm/v/@designesy/tokens?color=blue&label=npm)](https://www.npmjs.com/package/@designesy/tokens)\n[![npm downloads](https://img.shields.io/npm/dw/@designesy/tokens)](https://www.npmjs.com/package/@designesy/tokens)\n[![license](https://img.shields.io/npm/l/@designesy/tokens?color=green)](./LICENSE)\n[![CI](https://github.com/LE-VAI/designesy-org/actions/workflows/ci.yml/badge.svg)](https://github.com/LE-VAI/designesy-org/actions/workflows/ci.yml)\n[![dependencies](https://img.shields.io/badge/dependencies-0-blue)](./package.json)\n[![DTCG](https://img.shields.io/badge/DTCG-2025.10-blue)](https://www.designtokens.org/)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-green)](./package.json)\n\nStandalone DTCG 2025.10 design token validator. 20 conformance checks. Zero dependencies. Works offline.\n\n## Why\n\nThe W3C Design Tokens Format Module reached its first stable version (2025.10) on October 28, 2025, backed by 24+ organizations including Adobe, Google, Meta, and Figma. Token adoption is at 84% of teams.\n\nBut no standalone DTCG validator CLI exists on npm. Terrazzo has `co check`, but it's bundled inside a full token compiler. This package is the first focused, standalone DTCG validator — the `npm audit` of design tokens.\n\n## Install\n\n```bash\n# One-off (no install needed)\nnpx @designesy/tokens tokens.json\n\n# Or install locally\nnpm install --save-dev @designesy/tokens\n```\n\n## Usage\n\n### Validate a local file\n\n```bash\nnpx @designesy/tokens tokens.json\n```\n\nOutput:\n```\nDesignesy Tokens Validator — DTCG 2025.10\nSource: tokens.json\nTokens: 47\n\nScore: 90/100  Grade: A  —  18 pass, 2 warn, 0 fail\n\n  ✓ t01  PASS  Every token has $type (direct or inherited)\n  ✓ t02  PASS  Every token has $value\n  ✓ t03  PASS  Semantic tokens have $description\n  ~ t04  WARN  Color tokens use OKLCH or Display-P3\n         3 primitive color(s) using legacy hex (valid DTCG, should migrate to OKLCH)\n  ✓ t05  PASS  Custom types namespaced under $extensions\n  ✓ t06  PASS  Aliases resolve to valid typed tokens\n  ~ t07  WARN  $schema property present\n  ✓ t08  PASS  DTCG 2025.10 structural validation\n  ✓ t09  PASS  No type drift between themes\n  ✓ t10  PASS  Dimension units are px or rem only\n  ✓ t11  PASS  $type is one of 15 valid spec types\n  ✓ t12  PASS  Token names don't start with $ (except $root)\n  ✓ t13  PASS  Token names don't contain {, }, or .\n  ✓ t14  PASS  $value matches $type structure (primitives)\n  ✓ t15  PASS  Color value well-formedness\n  ✓ t16  PASS  Composite type structure\n  ✓ t17  PASS  Canonical $value:\"{ref}\" alias syntax\n  ✓ t18  PASS  Alias type compatibility\n  ✓ t19  PASS  Circular reference detection\n  ✓ t20  PASS  $deprecated value valid\n\nResult: PASS with 2 warning(s)\n```\n\n### Validate a remote URL\n\n```bash\nnpx @designesy/tokens https://www.designesy.org/export/dtcg\n```\n\n### CI gate — fail if score below threshold\n\n```bash\nnpx @designesy/tokens tokens.json --min-score 80\n# Exit code 0 if score ≥ 80, exit code 1 if below\n```\n\n### JSON output for piping\n\n```bash\nnpx @designesy/tokens tokens.json --json\n```\n\n### Quiet mode (only output on failure)\n\n```bash\nnpx @designesy/tokens tokens.json --quiet\n```\n\n## The 20 Checks\n\n| ID | Check | PASS | WARN | FAIL |\n|----|-------|------|------|------|\n| t01 | Every token has `$type` (direct or inherited) | All typed | — | Any missing |\n| t02 | Every token has `$value` | All valued | — | Any missing |\n| t03 | Semantic tokens have `$description` | All described | Primitive missing | Semantic missing |\n| t04 | Color tokens use OKLCH or Display-P3 | All structured | Legacy hex primitives | Semantic uses bare hex |\n| t05 | Custom types namespaced under `$extensions` | Namespaced | — | Bare custom type |\n| t06 | Aliases resolve to valid typed tokens | All resolve | — | Dangling reference |\n| t07 | `$schema` property present | Present | Missing (no editor validation) | — |\n| t08 | DTCG 2025.10 structural validation | Passes | — | Schema violation |\n| t09 | No type drift between themes | Consistent | — | Drift detected |\n| t10 | Dimension units are px or rem only | Valid units | — | Invalid unit |\n| t11 | `$type` is one of 15 valid spec types | All valid | — | Invalid type name |\n| t12 | Token names don't start with `$` (except `$root`) | All valid | — | Name starts with `$` |\n| t13 | Token names don't contain `{`, `}`, or `.` | All valid | — | Forbidden character |\n| t14 | `$value` matches `$type` structure (primitives) | All conform | — | Value/type mismatch |\n| t15 | Color value well-formedness | All well-formed | — | Malformed color |\n| t16 | Composite type structure | All valid | — | Missing required child |\n| t17 | Canonical `$value:\"{ref}\"` alias syntax | All valid | — | Invalid alias syntax |\n| t18 | Alias type compatibility | All compatible | — | Type mismatch |\n| t19 | Circular reference detection | No cycles | — | Circular chain detected |\n| t20 | `$deprecated` value valid | All valid | — | Invalid value type |\n\n## Scoring\n\n20 checks. PASS = 1 point, WARN = 0.5 points, FAIL = 0 points.\n\nScore = (points / 20) × 100\n\n| Grade | Score |\n|-------|-------|\n| A | ≥ 90 |\n| B | ≥ 80 |\n| C | ≥ 70 |\n| D | ≥ 60 |\n| F | < 60 |\n\n## Programmatic API\n\n```typescript\nimport { validateTokens, validateTokenString } from '@designesy/tokens';\n\n// From a parsed object\nconst result = validateTokens(tokenJsonObject, 'tokens.json');\nconsole.log(result.score);  // 90\nconsole.log(result.grade);  // 'A'\nconsole.log(result.valid);  // true (no FAILs)\n\n// From a JSON string\nconst result2 = validateTokenString(jsonString, 'tokens.json');\nif ('error' in result2) {\n  console.error(result2.error);\n}\n```\n\n## GitHub Actions\n\nUse this package as a CI gate to validate your design tokens on every PR.\nThe example below uses SHA-pinned actions — the 2026 supply-chain security\nbest practice. Dependabot bumps the SHAs when new versions land.\n\n```yaml\nname: Validate design tokens\non: [pull_request]\npermissions:\n  contents: read\njobs:\n  tokens:\n    runs-on: ubuntu-latest\n    steps:\n      # SHA-pinned (replace with current SHAs from the action repos)\n      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af573 # v4.2.2\n      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0\n        with:\n          node-version: '22'\n      - run: npx @designesy/tokens@0.2.1 tokens.json --min-score 80\n```\n\nOr use the composite action (no Node setup needed):\n\n```yaml\n- uses: LE-VAI/designesy-org/.github/actions/tokens-validate@main\n  with:\n    url: https://example.com/tokens.json\n    min-score: 80\n```\n\n## Spec Reference\n\n- [W3C Design Tokens Format Module 2025.10](https://www.designtokens.org/)\n- [DTCG JSON Schema](https://www.designtokens.org/schemas/2025.10/format.json)\n- [Designesy Tokens Contract](https://www.designesy.org/contracts/tokens)\n\n## License\n\nMIT © [Designesy](https://www.designesy.org)","readmeFilename":"README.md"}