{"id":17749973,"url":"https://github.com/nclsndr/design-tokens-format-module","last_synced_at":"2025-04-01T13:33:44.815Z","repository":{"id":61714753,"uuid":"547577945","full_name":"nclsndr/design-tokens-format-module","owner":"nclsndr","description":"A Typescript implementation of the Design Tokens Format Module specification","archived":false,"fork":false,"pushed_at":"2023-05-30T22:23:10.000Z","size":102,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-14T12:50:27.956Z","etag":null,"topics":["design-system","design-tokens"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nclsndr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-07T23:28:49.000Z","updated_at":"2024-07-08T10:48:30.529Z","dependencies_parsed_at":"2024-07-08T10:48:25.476Z","dependency_job_id":"be24865c-a549-4504-8b64-c9176f1eb0e8","html_url":"https://github.com/nclsndr/design-tokens-format-module","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclsndr%2Fdesign-tokens-format-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclsndr%2Fdesign-tokens-format-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclsndr%2Fdesign-tokens-format-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nclsndr%2Fdesign-tokens-format-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nclsndr","download_url":"https://codeload.github.com/nclsndr/design-tokens-format-module/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246604610,"owners_count":20804099,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["design-system","design-tokens"],"created_at":"2024-10-26T11:41:59.766Z","updated_at":"2025-04-01T13:33:44.807Z","avatar_url":"https://github.com/nclsndr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Design Tokens Format Module\n\n*— A TypeScript implementation of the [Design Tokens Format Module](https://tr.designtokens.org/format/) specification along with some utility functions*\n\n## Abstract\n\nThis packages aims to provide the most agnostic JavaScript/TypeScript definitions from the [Design Tokens Format Module](https://tr.designtokens.org/format/) specification, for library developers and tooling creators.\n\nJoin the conversation on the [W3C Design Tokens Community Group](https://github.com/design-tokens/community-group) repository.\n\n\u003e ⚠️ Please note, the DTCG specification is NOT stable yet, breaking changes might occur in the future.\n\n## Installation\n\n### Using npm\n\n```bash\nnpm install design-tokens-format-module\n```\n\n### Using yarn\n\n```bash\nyarn add design-tokens-format-module\n```\n\n### Using pnpm\n\n```bash\npnpm add design-tokens-format-module\n```\n\n## Usage\n\nThis module provides all the type definitions and the most basic helpers required to work with a JSON design token tree.\n\n### Token tree\n\nConstrain a JSON object that represents a design token tree.\n\n```typescript\nimport { JSONTokenTree } from 'design-tokens-format-module';\n\nconst tokenTree = {\n  color: {\n    primary: {\n      $type: 'color',\n      $value: '#000000',\n    },\n  },\n  spacing: {\n    small: {\n      $type: 'dimension',\n      $value: {\n        value: 8,\n        unit: 'px',\n      },\n    },\n  },\n} satisfies JSONTokenTree;\n```\n\n### Design Token\n\nEach design token type is available as a TypeScript namespace.\n\n```typescript\nimport {\n  Color // Dimension, FontFamily... \n} from 'design-tokens-format-module';\n\ndeclare function parseColorToken(token: unknown): Color.Token;\ndeclare function parseColorValue(tokens: unknown): Color.Value;\ndeclare function matchIsColorTokenTypeName(\n  name: string,\n): name is Color.TypeName;\n```\n\n#### Design token type names\n\nAll token type names are available as a constant.\n\n```typescript\nimport { tokenTypeNames } from 'design-tokens-format-module';\n\nfor(const tokenTypeName of tokenTypeNames) {\n  // color, dimension...\n}\n```\n\n### All token types\n\nAll token type signatures are available within a type union.\n\n```typescript\nimport { DesignToken } from 'design-tokens-format-module';\n\ndeclare function parseDesignToken(token: unknown): DesignToken;\n```\n\n### Matchers\n\nJSON values can be evaluated against the token signature\n\n```typescript\nimport { matchIsToken, matchIsTokenTypeName, matchIsAliasValue } from 'design-tokens-format-module';\n\nfunction validateToken(token: unknown) {\n  if (matchIsToken(token)) {\n    const isValidType = matchIsTokenTypeName(token.$type ?? '');\n    if(matchIsAliasValue(token.$value)) {\n      // ...\n    }\n  }\n  // ...\n}\n```\n\n### Alias utils\n\nAlias values can be validated and parsed.\n\n```ts\nimport { captureAliasPath } from 'design-tokens-format-module';\n\nconst result = captureAliasPath('{path.to.token}');\n\nif(result.status === 'ok') {\n  result.value // string[]\n} else {\n  switch (result.error.tag) {\n    case 'TYPE_ERROR': {\n      result.error.message // Expected a string value. Got [x].\n      break;\n    }\n    case 'FORMAT_ERROR': {\n      result.error.message // Expected an alias value. Got [x].\n      break;\n    }\n  }\n}\n```\n\n### Enum-like constants\n\nSome token types have a fixed set of values. These are available as constants.\n\n```typescript\nimport { fontWeightValues, strokeStyleStringValues, strokeStyleLineCapValues } from 'design-tokens-format-module';\n```\n\n## Previous versions\n\nThe packages goal has shifted from being a generic parser — which requires way more feedback — to a reliable source of truth for the DTCG implementations in the JavaScript land.\n\n\u003e The features and APIs available before version 0.9.0 has been relocated to a [new location](https://github.com/nclsndr/design-tokens-tools/tree/main/packages/w3c-design-tokens-parser) where they get revamped and improved.\n\n## Contributing\n\nIf you find any typos, errors, or additional improvements, feel free to contribute to the project.\n\n### Development\n\nInstall dependencies.\n\n```bash\nnpm install\n```\n\nRun test in watch mode.\n\n```bash\nnpm run test\n```\n\nPlease add tests to cover the new functionality or bug fix you are working upon.\n\n### Before opening a PR\n\nWe expect the tests and the build to pass for a PR to be reviewed and merged.\n\n```bash\nnpm run test --run\n```\n\n```bash\nnpm run build\n```\n\n## API\n\n### `AliasValue` (type)\n\n```ts\ntype AliasValue = `{${string}}`;\n```\n\n### `Json` (namespace)\n\n```ts\nnamespace Json {\n  export type Value = JSONValue;\n  export type Object = JSONObject;\n  export type Array = JSONArray;\n  export type Primitive = string | number | boolean | null;\n}\n```\n### JSONTokenTree (type)\n\n```ts\ntype JSONTokenTree = {\n  [key: string]: DesignToken | JSONTokenTree | GroupProperties;\n} \u0026 GroupProperties;\n```\n\n### `Color`,`Dimension`, ... (namespace)\n\n```ts\nnamespace TokenTypeName {\n  export type TypeName = TypeName;\n  export type Value = Value;\n  export type Token = Token;\n}\n```\n\n### `DesignToken` (type)\n\n```ts\ntype DesignToken =\n  | ColorToken\n  | DimensionToken\n  // | ...\n```\n\n### `TokenTypeName` (type)\n\n```ts\ntype TokenTypeName = \n  | 'color'\n  | 'dimension'\n  // | ... \n```\n\n\n### `captureAliasPath` (function)\n\n```ts\nconst CAPTURE_ALIAS_PATH_ERRORS = {\n  TYPE_ERROR: 'Expected a string value.',\n  // ...\n} as const;\n\ntype ValidationError = {\n  [k in keyof Writable\u003ctypeof CAPTURE_ALIAS_PATH_ERRORS\u003e]?: {\n    message: string;\n  };\n};\n\ntype Result\u003cT, E\u003e =\n  | {\n  status: 'ok';\n  value: T;\n  error?: undefined;\n}\n  | {\n  status: 'error';\n  error: E;\n  value?: undefined;\n};\n\ndeclare function captureAliasPath(\n  value: unknown,\n): Result\u003cArray\u003cstring\u003e, ValidationError\u003e;\ndeclare function captureAliasPath\u003cAsString extends boolean | undefined\u003e(\n  value: unknown,\n  asString: AsString,\n): Result\u003cAsString extends true ? string : Array\u003cstring\u003e, ValidationError\u003e;\n```\n\nUsage\n\n```ts\nconst result = captureAliasPath('{path.to.token}');\n\nif(result.status === 'ok') {\n  result.value // string[]\n} else {\n  switch (result.error.tag) {\n    case 'TYPE_ERROR': {\n      result.error.message // Expected a string value. Got [x].\n      break;\n    }\n    case 'FORMAT_ERROR': {\n      result.error.message // Expected an alias value. Got [x].\n      break;\n    }\n  }\n}\n```\n\n\n### `matchIsAliasValue` (function)\n\n```ts\ndeclare function matchIsAliasValue(candidate: unknown): candidate is AliasValue;\n```\n\n### `matchIsGroup` (function)\n\n```ts\ndeclare function matchIsGroup(candidate: unknown): candidate is JSONTokenTree;\n```\n\n### `matchIsToken` (function)\n\n```ts\ndeclare function matchIsToken(candidate: unknown): candidate is DesignToken;\n```\n\n### `matchIsTokenTypeName` (function)\n\n```ts\ndeclare function matchIsTokenTypeName(candidate: unknown): candidate is TokenTypeName;\n```\n\n\n### `ALIAS_PATH_SEPARATOR` (constant)\n\n```ts\nconst ALIAS_PATH_SEPARATOR = '.';\n```\n\n### `tokenTypeNames` (constant)\n\n```ts\nconst tokenTypeNames = [\n  'color',\n  'dimension',\n  // ...\n] as const;\n```\n\n### `fontWeightValues` (constant)\n\n```ts\nconst fontWeightValues = [\n  100,\n  'thin',\n  'hairline',\n  // ...\n] as const;\n```\n\n### `strokeStyleStringValues` (constant)\n\n```ts\nconst strokeStyleStringValues = [\n  'solid',\n  'dashed',\n  // ...\n] as const;\n```\n\n### `strokeStyleLineCapValues` (constant)\n\n```ts\nconst strokeStyleLineCapValues = [\n  'round',\n  'butt',\n  // ...\n] as const;\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnclsndr%2Fdesign-tokens-format-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnclsndr%2Fdesign-tokens-format-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnclsndr%2Fdesign-tokens-format-module/lists"}