{"id":18534776,"url":"https://github.com/atomicojs/design-tokens","last_synced_at":"2025-05-14T23:35:05.207Z","repository":{"id":113779323,"uuid":"477881903","full_name":"atomicojs/design-tokens","owner":"atomicojs","description":null,"archived":false,"fork":false,"pushed_at":"2022-04-24T04:56:08.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-09T08:22:09.341Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/atomicojs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-04-04T21:37:23.000Z","updated_at":"2022-04-04T21:39:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"0d303159-82d5-4a4f-91dc-2218d0a58e5b","html_url":"https://github.com/atomicojs/design-tokens","commit_stats":{"total_commits":30,"total_committers":1,"mean_commits":30.0,"dds":0.0,"last_synced_commit":"5603f41adb12a19300812eeeeb6a87dc515e1be0"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicojs%2Fdesign-tokens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicojs%2Fdesign-tokens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicojs%2Fdesign-tokens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/atomicojs%2Fdesign-tokens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/atomicojs","download_url":"https://codeload.github.com/atomicojs/design-tokens/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253492529,"owners_count":21916959,"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":[],"created_at":"2024-11-06T19:16:55.591Z","updated_at":"2025-05-14T23:35:05.110Z","avatar_url":"https://github.com/atomicojs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @atomico/design-tokens\r\n\r\n[![doc](https://raw.githubusercontent.com/atomicojs/atomico/brand/link-to-doc.svg)](https://atomico.gitbook.io/doc/atomico/atomico-design-tokens) [![Discord](https://raw.githubusercontent.com/atomicojs/atomico/brand/link-to-discord.svg)](https://discord.gg/7z3rNhmkNE)\r\n\r\n`@atomico/design-tokens` makes it easy to use design tokens for webcomponents, thanks to `@atomico/design-tokens` you can maintain scalable and highly modifiable component systems.\r\n\r\nWith `@atomico/design-tokens` you can:\r\n\r\n1. [Resolve scalability and maintenance issues with your design tokens](#resolve-scalability-and-maintenance-issues-with-your-design-tokens).\r\n2. [Create utility classes from design tokens](#create-utility-classes-to-be-used-internally-by-your-component-system).\r\n\r\n## Resolve scalability and maintenance issues with your design tokens.\r\n\r\nDesign systems are complex to develop, due to the number of configurations that are shared between all our components, with `@atomico/design-tokens` we will solve:\r\n\r\n1. Naming problems of the custom properties of your design tokens.\r\n2. Legibility of your CSS.\r\n\r\n### How does @atomico/design-tokens solve the scalability of your design tokens?\r\n\r\nFor this example we will use Atomico, by the way you can use `@atomico/design-tokens` with any library.\r\n\r\n```tsx\r\nimport { css } from \"atomico\";\r\nimport { compose, tokens } from \"@atomico/design-tokens\";\r\n\r\nconst designTokens = compose(\r\n  tokens(\r\n    {\r\n      size: {\r\n        xl: \"40px\",\r\n        l: \"32px\",\r\n        m: \"28px\",\r\n        s: \"20px\",\r\n      },\r\n    },\r\n    \"ds\"\r\n  )\r\n);\r\n\r\nexport const tokens = designTokens(css``);\r\n```\r\n\r\nThe result of the CSS will be the following:\r\n\r\n```css\r\n:host {\r\n  --size-xl: var(--ds--size-xl);\r\n  --size-l: var(--ds--size-l);\r\n  --size-m: var(--ds--size-m);\r\n  --size-s: var(--ds--size-s);\r\n}\r\n```\r\n\r\nThis is a technique that I have created to improve the scalability of design tokens, with it you can:\r\n\r\n1. edit token globally using custom properties:\r\n\r\n```css\r\n:root {\r\n  --my-ds--size-xl: 50px;\r\n}\r\n```\r\n\r\n\u003e This is also applicable within a selector.\r\n\r\n2. Simplify maintenance, since your components will use the custom properties without a prefix:\r\n\r\n```tsx\r\nimport { c, css } from \"atomico\";\r\nimport tokens from \"./tokens\";\r\nfunction button() {\r\n  return (\r\n    \u003chost shadowDom\u003e\r\n      \u003cslot /\u003e\r\n    \u003c/host\u003e\r\n  );\r\n}\r\n\r\nbutton.styles = [\r\n  tokens,\r\n  css`\r\n    :host {\r\n      height: var(--size-xl);\r\n      background: var(--color-primary-60);\r\n      padding: var(--size-xxs) var(--size-xs);\r\n    }\r\n  `,\r\n];\r\n```\r\n\r\n## Create utility classes to be used internally by your component system.\r\n\r\nI am personally a fan of custom properties, but their use would become repetitive, to avoid this and improve maintenance @atomico/design-tokens introduces `classes`, a generator of utility classes based on the proposed design tokens, example:\r\n\r\n```tsx\r\nimport { css } from \"atomico\";\r\nimport { compose, tokens, classes } from \"@atomico/design-tokens\";\r\n\r\nconst designTokens = compose(\r\n  classes({\r\n    size: {\r\n      xl: \"40px\",\r\n      l: \"32px\",\r\n      m: \"28px\",\r\n      s: \"20px\",\r\n    },\r\n  })\r\n);\r\n\r\nexport const tokensSize = designTokens(\r\n  css`\r\n    .gap.--size {\r\n      gap: var(--size);\r\n    }\r\n  `\r\n);\r\n```\r\n\r\nThe `classes` middleware will parse the CSSStyleSheet to relate the custom propeprtiy `--size` as a class of `.gap`, internally the `css` will be as follows:\r\n\r\n```css\r\n.gap\\.xl {\r\n  gap: var(--size-xl);\r\n}\r\n\r\n.gap\\.l {\r\n  gap: var(--size-l);\r\n}\r\n\r\n.gap\\.m {\r\n  gap: var(--size-m);\r\n}\r\n\r\n.gap\\.s {\r\n  gap: var(--size-s);\r\n}\r\n```\r\n\r\nThis makes it really simple to reuse the tokens, example:\r\n\r\n```tsx\r\nimport { c } from \"atomico\";\r\nimport { tokensSize } from \"./tokens\";\r\n\r\nfunction button() {\r\n  return (\r\n    \u003chost shadowDom\u003e\r\n      \u003cbutton class=\"gap.xl\"\u003e\r\n        \u003cslot /\u003e\r\n      \u003c/button\u003e\r\n    \u003c/host\u003e\r\n  );\r\n}\r\n\r\nbutton.styles = tokensSize;\r\n\r\ncustomElements.define(\"my-button\", c(button));\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomicojs%2Fdesign-tokens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fatomicojs%2Fdesign-tokens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fatomicojs%2Fdesign-tokens/lists"}