{"id":29607501,"url":"https://github.com/projectwallace/css-design-tokens","last_synced_at":"2025-10-14T01:15:46.580Z","repository":{"id":301632044,"uuid":"1009839407","full_name":"projectwallace/css-design-tokens","owner":"projectwallace","description":"Create Design Tokens by going through CSS to find colors, font-sizes, gradients etcetera and turn them into a Design Tokens spec-compliant token format.","archived":false,"fork":false,"pushed_at":"2025-09-22T10:03:45.000Z","size":184,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-06T00:34:50.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.projectwallace.com/design-tokens","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/projectwallace.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","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,"zenodo":null}},"created_at":"2025-06-27T20:02:01.000Z","updated_at":"2025-10-01T15:07:36.000Z","dependencies_parsed_at":"2025-06-27T22:31:46.555Z","dependency_job_id":"a26cb0fa-8017-4e31-ac3b-aa5738038e9d","html_url":"https://github.com/projectwallace/css-design-tokens","commit_stats":null,"previous_names":["projectwallace/css-design-tokens"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/projectwallace/css-design-tokens","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectwallace%2Fcss-design-tokens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectwallace%2Fcss-design-tokens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectwallace%2Fcss-design-tokens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectwallace%2Fcss-design-tokens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/projectwallace","download_url":"https://codeload.github.com/projectwallace/css-design-tokens/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/projectwallace%2Fcss-design-tokens/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279012523,"owners_count":26085135,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-07-20T18:33:36.127Z","updated_at":"2025-10-14T01:15:46.573Z","avatar_url":"https://github.com/projectwallace.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# css-design-tokens\n\nCreate Design Tokens by going through CSS to find colors, font-sizes, gradients etcetera and turn them into a [Design Tokens spec](https://tr.designtokens.org/)-compliant token format.\n\n## Table of contents\n\n- [Installation](#installation)\n- [Usage](#usage)\n- [Token types](#token-types)\n  - [Color](#color)\n  - [Font-size](#font-size)\n  - [Font-family](#font-family)\n  - [Line-height](#line-height)\n  - [Gradient](#gradient)\n  - [Box-shadow](#box-shadow)\n  - [Radius](#radius)\n  - [Duration](#duration)\n  - [Easing](#easing)\n- [Extensions](#extensions)\n- [Acknowledgements](#acknowledgements)\n\n## Installation\n\n```sh\nnpm install @projectwallace/css-design-tokens\n```\n\n## Usage\n\n```js\nimport { css_to_tokens } from '@projectwallace/css-design-tokens'\n\nlet {\n  color,\n  font_size,\n  font_family,\n  line_height,\n  gradient,\n  box_shadow,\n  radius,\n  duration,\n  easing,\n} = css_to_tokens(`.my-design-system { color: green; }`)\n\n// Or if you already have done CSS analysis with @projectwallace/css-analyzer\nimport { analyze } from '@projectwallace/css-analyzer'\nimport { analysis_to_tokens } from '@projectwallace/css-design-tokens'\n\nlet analysis = analyze(`.my-design-system { color: green; }`, {\n  useLocations: true // may be `true` or `false`, it works either way\n})\nlet tokens = analysis_to_tokens(analysis)\n```\n\n### Stable unique token ID's\n\nAll tokens have a stabe unique ID using a very simple hashing algorithm. This is helpful when you run analysis multiple times over your project and lets you identify removed or added tokens easily.\n\n```ts\nlet { color } = css_to_tokens(\n  `.my-design-system {\n    color: green;\n    color: rgb(100 100 100 / 20%);\n  }`\n)\n\n// {\n//   'green-5e0cf03': {\n//     $type: 'color',\n//     ...\n//   },\n//   'grey-8139d9b': {\n//     $type: 'color',\n//     ...\n//   }\n// }\n```\n\n## Token types\n\n### Color\n\n['Color' Design Token format](https://www.designtokens.org/tr/third-editors-draft/color/#format)\n\nOnly fully compliant colors are listed. Colors that can't be parsed by [colorjs.io](https://colorjs.io/) are ignored, like `rgb(var(--red) var(--green) var(--blue))` or CSS system colors like `ButtonText`.\n\n- The optional `alpha` property is _always_ present.\n- The optional `hex` fallback property is _never_ present.\n- In addition to other tokens all colors have a `com.projectwallace.css-properties` extension that contains all the CSS properties that a specific color was used for.\n\n```js\nlet { color } = css_to_tokens(`.my-design-system { color: green; }`)\n\nlet color = {\n  'green-5e0cf03': {\n    $type: 'color',\n    $value: {\n      colorSpace: 'srgb',\n      components: [0, 0.5019607843137255, 0],\n      alpha: 1,\n    },\n    $extensions: {\n      'com.projectwallace.css-authored-as': 'green',\n      'com.projectwallace.usage-count': 2,\n      'com.projectwallace.css-properties': ['color', 'border-color'],\n    }\n  }\n}\n```\n\n### Font-size\n\n['Dimension' Design Token format](https://www.designtokens.org/tr/third-editors-draft/format/#dimension)\n\nFont-sizes are listed as `$type: 'dimension'` types if the font-size is declared with either `px` or `rem` or as plain type-less tokens otherwise.\n\n```js\nlet { font_size } = css_to_tokens(`.my-design-system {\n  .my-design-system {\n    font-size: 16px;\n    font-size: 1rem;\n    font-size: 20vmin;\n  }\n}`)\n\nlet font_size = {\n  'fontSize-171eed': {\n    $type: 'dimension',\n    $value: {\n      value: 16,\n      unit: 'px'\n    },\n    $extensions: {\n      'com.projectwallace.css-authored-as': '16px',\n      'com.projectwallace.usage-count': 1,\n    }\n  },\n  'fontSize-582e015a': {\n    $value: '20vmin',\n    $extensions: {\n      'com.projectwallace.css-authored-as': '20vmin',\n      'com.projectwallace.usage-count': 1,\n    }\n  },\n}\n```\n\n### Font-family\n\n['fontFamily' Design Token format](https://www.designtokens.org/tr/third-editors-draft/format/#font-family)\n\nFont-families are _always_ listed as `$type: 'fontFamily'`.\n\n```js\nlet { font_family } = css_to_tokens(`.my-design-system {\n  .my-design-system {\n    font-family: 'Inter';\n    font-family: Arial Black, sans-serif;\n  }\n}`)\n\nlet font_family = {\n  'fontFamily-3375cf09': {\n    $type: 'fontFamily',\n    $value: ['\\'Inter\\''],\n    $extensions: {\n      'com.projectwallace.css-authored-as': '\\'Inter\\'',\n      'com.projectwallace.usage-count': 1,\n    }\n  },\n  'fontFamily-582e015a': {\n    $type: 'fontFamily',\n    $value: ['Arial Black', 'sans-serif'],\n    $extensions: {\n      'com.projectwallace.css-authored-as': 'Arial Black, sans-serif',\n      'com.projectwallace.usage-count': 1,\n    }\n  },\n}\n```\n\n### Line-height\n\nLine heights can either be `dimension` or `number` types, or a plain type-less token. This depends on how well the value can be mapped to a valid token.\n\n```ts\nlet { line_height } = css_to_tokens(`\n  .my-design-system {\n    line-height: 1.5rem; /* rem -\u003e type=dimension */\n    line-height: 1.5; /* no unit -\u003e type=number */\n    line-height: 20vmin; /* can not be mapped to valid token type */\n  }\n`)\n\nlet line_height = {\n  'lineHeight-563f7fe2': {\n    $type: 'dimension',\n    $value: {\n      value: 1.5,\n      unit: 'rem'\n    },\n    $extensions: {\n      'com.projectwallace.css-authored-as': '1.5rem',\n      'com.projectwallace.usage-count': 1,\n    }\n  },\n  'lineHeight-bdb8': {\n    $type: 'number',\n    $value: 1.5,\n    $extensions: {\n      'com.projectwallace.css-authored-as': '1.5',\n      'com.projectwallace.usage-count': 1,\n    }\n  },\n  'lineHeight-582e015a': {\n    $value: '20vmin',\n    $extensions: {\n      'com.projectwallace.css-authored-as': '20vmin',\n      'com.projectwallace.usage-count': 1,\n    }\n  }\n}\n```\n\n### Gradient\n\nGradients are passed as-is, no mapping is done. This is because the spec is currently too limited in expressing a CSS gradient.\n\n```ts\nlet { gradient } = css_to_tokens(`\n  .my-design-system {\n    background: linear-gradient(to right, red, blue);\n  }\n`)\n\nlet gradient = {\n  'gradient-2aec04e5': {\n    $value: 'linear-gradient(to right, red, blue)',\n    $extensions: {\n      'com.projectwallace.css-authored-as': 'linear-gradient(to right, red, blue)',\n      'com.projectwallace.usage-count': 1,\n    }\n  }\n}\n```\n\n### Box-shadow\n\n['Shadow' Design Token type](https://www.designtokens.org/tr/third-editors-draft/format/#shadow)\n\n- Multiple shadows can be mapped, so beware that `$value` van either be a single object or an array.\n- Only if a box-shadow has a valid `color` type it will be mapped as a `box-shadow` type\n\n```ts\nlet { box_shadow } = css_to_tokens(`\n  .my-design-system {\n    box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.5);\n    box-shadow: 0 0 10px 0 rgba(0, 0, 0, 0.5), 0 0 10px 0 rgba(0, 0, 0, 0.5);\n    box-shadow: 0 0 0 0 var(--red);\n  }\n`)\n\nlet box_shadow = {\n  'boxShadow-6f90da6b': {\n    $type: 'shadow',\n    $value: {\n      offsetX: {\n        value: 0,\n        unit: 'px'\n      },\n      offsetY: {\n        value: 0,\n        unit: 'px'\n      },\n      blur: {\n        value: 10,\n        unit: 'px'\n      },\n      spread: {\n        value: 0,\n        unit: 'px'\n      },\n      inset: false,\n      color: {\n        colorSpace: 'srgb',\n        components: [0, 0, 0],\n        alpha: 0.5,\n      },\n    },\n    $extensions: {\n      'com.projectwallace.css-authored-as': '0 0 10px 0 rgba(0, 0, 0, 0.5)',\n      'com.projectwwallace.usage-count': 1,\n    }\n  },\n  'boxShadow-be2751ac': {\n    $type: 'shadow',\n    $value: [\n      {\n        offsetX: {\n          value: 0,\n          unit: 'px'\n        },\n        offsetY: {\n          value: 0,\n          unit: 'px'\n        },\n        blur: {\n          value: 10,\n          unit: 'px'\n        },\n        spread: {\n          value: 0,\n          unit: 'px'\n        },\n        inset: false,\n        color: {\n          colorSpace: 'srgb',\n          components: [0, 0, 0],\n          alpha: 0.5,\n        },\n      },\n      {\n        offsetX: {\n          value: 0,\n          unit: 'px'\n        },\n        offsetY: {\n          value: 0,\n          unit: 'px'\n        },\n        blur: {\n          value: 10,\n          unit: 'px'\n        },\n        spread: {\n          value: 0,\n          unit: 'px'\n        },\n        inset: false,\n        color: {\n          colorSpace: 'srgb',\n          components: [0, 0, 0],\n          alpha: 0.5,\n        },\n      }\n    ],\n    $extensions: {\n      'com.projectwwallace.css-authored-as': '0 0 10px 0 rgba(0, 0, 0, 0.5), 0 0 10px 0 rgba(0, 0, 0, 0.5)',\n      'com.projectwwallace.usage-count': 1,\n    }\n  },\n  'boxShadow-j4h5gas5h': {\n    $value: '0 0 0 0 var(--red)',\n    $extensions: {\n      'com.projectwwallace.css-authored-as': '0 0 0 0 var(--red)',\n      'com.projectwwallace.usage-count': 1,\n    }\n  }\n}\n```\n\n### Radius\n\nRadii are passed as-is, no mapping is done.\n\n```ts\nlet { radius } = css_to_tokens(`\n  .my-design-system {\n    border-radius: 10px;\n  }\n`)\n\nlet radius = {\n  'radius-170867': {\n    $value: '10px',\n    $extensions: {\n      'com.projectwwallace.css-authored-as': '10px',\n      'com.projectwwallace.usage-count': 1,\n    }\n  }\n}\n```\n\n### Duration\n\n['Duration' Design Token type](https://www.designtokens.org/tr/third-editors-draft/format/#duration)\n\nDurations can either be animation- or transition-durations or -delays. Even though `s` is a valid unit we _always_ map to `ms`.\n\n```ts\nlet { duration } = css_to_tokens(`\n  .my-design-system {\n    animation-duration: 1s;\n  }\n`)\n\nlet duration = {\n  'duration-17005f': {\n    $type: 'duration',\n    $value: {\n      value: 1000,\n      unit: 'ms'\n    },\n    $extensions: {\n      'com.projectwwallace.css-authored-as': '1s',\n      'com.projectwwallace.usage-count': 1,\n    }\n  }\n}\n```\n\n### Easing\n\n['Cubic Bézier' Design Token type](https://www.designtokens.org/tr/third-editors-draft/format/#cubic-bezier)\n\nEasings are mapped to cubic béziers when possible or represented as plain type-less tokens otherwise. [CSS Easing keywords](https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function) are also converted to cubic béziers.\n\n```ts\nlet actual = css_to_tokens(`\n  .my-design-system {\n    animation-timing-function: ease-in-out;\n    animation-timing-function: cubic-bezier(0, 0, 0.5, .8);\n    animation-timing-function: var(--test);\n  }\n`)\n\nlet easing = {\n  'easing-ea6c7565': {\n    $type: 'cubicBezier',\n    $value: [\n      0.42,\n      0,\n      0.58,\n      1\n    ],\n    $extensions: {\n      'com.projectwwallace.css-authored-as': 'ease-in-out',\n      'com.projectwwallace.usage-count': 1,\n    }\n  },\n  'easing-90111eba': {\n    $type: 'cubicBezier',\n    $value: [\n      0,\n      0,\n      0.5,\n      0.8\n    ],\n    $extensions: {\n      'com.projectwwallace.css-authored-as': 'cubic-bezier(0, 0, 0.5, .8)',\n      'com.projectwwallace.usage-count': 1,\n    }\n  },\n  'easing-12bb7f36': {\n    $value: 'var(--test)',\n    $extensions: {\n      'com.projectwwallace.css-authored-as': 'var(--test)',\n      'com.projectwwallace.usage-count': 1,\n    }\n  }\n}\n```\n\n## Extensions\n\nThis library adds a couple of potentially extensions to the design token values via the `com.projectwallace` namespace on the `$extensions` property of all generated design tokens.\n\n### Authored CSS values\n\nThis package parses CSS into Design Tokens but also provides a way to get the authored CSS via the `$extensions['com.projectwallace.css-authored-as']` property on any of the tokens:\n\n```ts\nlet { color } = css_to_tokens(`.my-design-system { color: green; }`)\n\n// {\n//   'green-5e0cf03': {\n//     ...\n//     $extensions: {\n//       'com.projectwallace.css-authored-as': 'green'\n//     }\n//   },\n// }\n\nlet authored_green = color['green-5e0cf03']['$extensions']['com.projectwallace.css-authored-as']\n\n// 'green'\n```\n\n### Usage count\n\nIf you need to know how often a particalur design token was found in the CSS you can use the `$extensions['com.projectwallace.usage-count']` property on any of the tokens:\n\n```ts\nlet { color } = css_to_tokens(`.my-design-system { color: green; }`)\n\n// {\n//   'green-5e0cf03': {\n//     ...\n//     $extensions: {\n//       'com.projectwallace.usage-count': 1\n//     }\n//   },\n// }\n\nlet green_count = color['green-5e0cf03']['$extensions']['com.projectwallace.usage-count']\n\n// 1\n```\n\n### CSS property usage\n\n__For color tokens only__\n\nYou can read the `$extensions['com.projectwallace.css-properties']` property to see for which CSS properties a color was used:\n\n```ts\nlet { color } = css_to_tokens(`.my-design-system { color: green; }`)\n\n// {\n//   'green-5e0cf03': {\n//     ...\n//     $extensions: {\n//       'com.projectwallace.css-properties': ['color']\n//     }\n//   },\n// }\n\nlet properties = color['green-5e0cf03']['$extensions']['com.projectwallace.css-properties']\n\n// ['color']\n```\n\n## Acknowledgements\n\n- [CSSTree](https://github.com/csstree/csstree) does all the heavy lifting of parsing CSS\n- [ColorJS.io](https://colorjs.io/) powers all color conversions necessary for grouping and sorting and converting into Color tokens\n\n## Related projects\n\n- [Design Tokens analyzer](https://www.projectwallace.com/design-tokens) - Online CSS to Design Tokens convernter, uses this package\n- [CSS Analyzer](https://github.com/projectwallace/css-analyzer) - The best CSS analyzer that powers all analysis on [projectwallace.com](https://www.projectwallace.com?utm_source=github\u0026utm_medium=wallace_css_design_tokens_related_projects)\n- [Color Sorter](https://github.com/projectwallace/color-sorter) - Sort CSS colors\n  by hue, saturation, lightness and opacity\n- [CSS Time Sort](https://github.com/projectwallace/css-time-sort) - Sort an array of `\u003ctime\u003e` values\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectwallace%2Fcss-design-tokens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprojectwallace%2Fcss-design-tokens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprojectwallace%2Fcss-design-tokens/lists"}