{"id":19651356,"url":"https://github.com/mimshins/react-design-tokens","last_synced_at":"2025-04-28T16:31:27.292Z","repository":{"id":139153053,"uuid":"611987604","full_name":"mimshins/react-design-tokens","owner":"mimshins","description":"An optimized and creative theming solution that generates CSS variables based on the tokens provided.","archived":false,"fork":false,"pushed_at":"2024-06-23T20:34:15.000Z","size":312,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T09:51:05.508Z","etag":null,"topics":["design","design-system","react","theme","theme-provider","tokens"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mimshins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2023-03-10T00:36:30.000Z","updated_at":"2025-03-30T00:04:33.000Z","dependencies_parsed_at":"2024-06-23T21:51:37.352Z","dependency_job_id":null,"html_url":"https://github.com/mimshins/react-design-tokens","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimshins%2Freact-design-tokens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimshins%2Freact-design-tokens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimshins%2Freact-design-tokens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mimshins%2Freact-design-tokens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mimshins","download_url":"https://codeload.github.com/mimshins/react-design-tokens/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251345933,"owners_count":21574807,"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","design-system","react","theme","theme-provider","tokens"],"created_at":"2024-11-11T15:06:19.607Z","updated_at":"2025-04-28T16:31:26.764Z","avatar_url":"https://github.com/mimshins.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React Design Tokens\n\nAn optimized and creative theming solution that generates CSS variables based on the tokens provided.\n\n\u003chr /\u003e\n\n## Installation\n\n\u003e Please note that [react](https://www.npmjs.com/package/react) \u003e= 17 and [react-dom](https://www.npmjs.com/package/react-dom) \u003e= 17 are peer dependencies.\n\nRun the following script to install and save in your `package.json` dependencies:\n\n```bash\n# with npm\nnpm install react-design-tokens\n\n# or with yarn\nyarn add react-design-tokens\n\n# or with pnpm\npnpm add react-design-tokens\n```\n\n\u003chr /\u003e\n\n## API Documentation\n\nThe library exposes two APIs, `create` and `defaultCSSVariableGenerator`:\n\n### 1. `create`\n\n```ts\ndeclare const create: (tokens, config?) =\u003e {\n  VariantSelector,\n  useTokens,\n  generateCSSVariablesAsInlineStyle,\n}\n```\n\nThis is the main API exposed by the library. It will take your tokens and an optional config options to create your theming client.\n\nThe `tokens` param expects to have `variants` and `common` tokens provided.\n\n```ts\nconst tokens = {\n  variants: {/* The variant tokens map */},\n  common: {/* Tokens that are common and non-variant */}\n}\n```\n\n\u003e Please note that we shallow-merge tokens of a selected variant with common tokens to generate the result tokens. (Merging order: `{ ...variantTokens, ...commonTokens }`)\u003cbr /\u003eCommon tokens can therefore potentially override variant tokens. Make sure they don't have any intersected keys.\n\nThe `config` options are:\n\n| Property Name | Type | Default | Description |\n|---------------|------|---------|-------------|\n| cssVariableGenerator | `context =\u003e ({ variableName: string; variableValue: string; } \\| null)` | `defaultCSSVariableGenerator` | The function which is being used to generate CSS variables based on the provided variants map. |\n\nThe theming client consists of:\n\n#### `\u003cVariantSelector\u003e`:\n\nA wrapper component which will activate a variant for the tree it's wrapping. The properties are:\n\n| Property Name | Type | Default | Description |\n|---------------|------|---------|-------------|\n| children? | `React.ReactNode` | - | The content of the component. |\n| disableCSSVariableGeneration? | `boolean` | `false` | If `true`, CSS variable generation will be disabled.\u003cbr /\u003eUseful when you are manually controlling or populating CSS variables using `generateCSSVariablesAsInlineStyle`. |\n| variant | `string` | - | The variant to be activated. It has to be a valid variant key that exists in the provided variants map. |\n\n#### `useTokens()`:\n\nA React hook to use in a component that is descendant of `\u003cVariantSelector\u003e` wrapper. It returns the tokens of the selected variant.\n\n#### `generateCSSVariablesAsInlineStyle(variant, options?)`:\n\nA helper function to generate CSS variables in valid CSS syntax (`--variable=value`). It is helpful when you want to manually control the population of the CSS variables (e.g. Put initial tokens on html tag with `\u003chtml style={generateCSSVariablesAsInlineStyle('dark')} /\u003e`)\n\nThe `options` are:\n\n| Property Name | Type | Default | Description |\n|---------------|------|---------|-------------|\n| disableCommonTokensGeneration | `boolean` | `false` | If `true`, Common tokens CSS variable generation will be disabled. |\n\n### 2. `defaultCSSVariableGenerator`\n\n```ts\ndeclare const defaultCSSVariableGenerator: (context: {\n    tokenFamilyKey: string;\n    tokenKey: string;\n    tokenPath: string;\n    tokenValue: unknown;\n  }) =\u003e {\n    variableName: string;\n    variableValue: string;\n} | null;\n```\n\nThe default CSS variable generate function. The generated variables obey the following rules:\n- Values that are not of type `string` or `number` will be omitted (returns `null`).\n- Values of type `number` will be converted into `{tokenValue}px`.\n- The generated variable format: `{ variableName: 'PATH-TO-TOKEN', variableValue: 'tokenValue' }`\n\n#### `context.tokenFamilyKey`:\n\nThe key of a root token family.\n\nFor example, The `colors` key is a `tokenFamilyKey` in the following variants map:\n\n```ts\n{\n  dark: {\n    colors: {\n      primary: {},\n      secondary: {},\n      // ...\n    }\n  },\n  light: {\n    colors: {\n      primary: {},\n      secondary: {},\n      // ...\n    }\n  },\n}\n```\n\n#### `context.tokenKey`:\n\nThe key (name) of the token.\n\n#### `context.tokenValue`:\n\nThe value of the token.\n\n#### `context.tokenPath`:\n\nThe dot-separated path to the token from which the root key has been omitted.\n\n\u003chr /\u003e\n\n## Basic Usage\n\nTo getting started, all you need to do is:\n\n1. Create your own variants map:\n\n```ts\n// theming.ts\n\nconst tokens = {\n  variants: {\n    dark: {\n      colors: {\n        primary: {\n          base: \"d1\",\n          hover: \"d2\",\n          active: \"d3\",\n          disabled: \"d4\",\n        },\n        secondary: {\n          base: \"d5\",\n          hover: \"d6\",\n          active: \"d7\",\n          disabled: \"d8\",\n        },\n        neutral: {\n          text: {\n            base: \"d9\",\n            secondary: \"d10\",\n            tertiary: \"d11\",\n          },\n          background: {\n            base: \"d12\",\n            container: \"d13\",\n            elevated: \"d14\",\n          },\n        },\n      },\n    },\n    light: {\n      colors: {\n        primary: {\n          base: \"l1\",\n          hover: \"l2\",\n          active: \"l3\",\n          disabled: \"l4\",\n        },\n        secondary: {\n          base: \"l5\",\n          hover: \"l6\",\n          active: \"l7\",\n          disabled: \"l8\",\n        },\n        neutral: {\n          text: {\n            base: \"l9\",\n            secondary: \"l10\",\n            tertiary: \"l11\",\n          },\n          background: {\n            base: \"l12\",\n            container: \"l13\",\n            elevated: \"l14\",\n          },\n        },\n      },\n    },\n  },\n  common: {\n    typefaces: {\n      monospace: \"c1\",\n      rtl: \"c2\",\n      ltr: \"c3\",\n      decorative: \"c4\",\n    },\n    space: \"c5\",\n  }\n};\n```\n\n2. Create a theming client:\n\n```ts\n// theming.ts\n\nimport { create } from \"react-design-tokens\";\n\nconst tokens = {\n  variants: {\n    dark: {\n      colors: {\n        primary: {\n          base: \"d1\",\n          hover: \"d2\",\n          active: \"d3\",\n          disabled: \"d4\",\n        },\n        secondary: {\n          base: \"d5\",\n          hover: \"d6\",\n          active: \"d7\",\n          disabled: \"d8\",\n        },\n        neutral: {\n          text: {\n            base: \"d9\",\n            secondary: \"d10\",\n            tertiary: \"d11\",\n          },\n          background: {\n            base: \"d12\",\n            container: \"d13\",\n            elevated: \"d14\",\n          },\n        },\n      },\n    },\n    light: {\n      colors: {\n        primary: {\n          base: \"l1\",\n          hover: \"l2\",\n          active: \"l3\",\n          disabled: \"l4\",\n        },\n        secondary: {\n          base: \"l5\",\n          hover: \"l6\",\n          active: \"l7\",\n          disabled: \"l8\",\n        },\n        neutral: {\n          text: {\n            base: \"l9\",\n            secondary: \"l10\",\n            tertiary: \"l11\",\n          },\n          background: {\n            base: \"l12\",\n            container: \"l13\",\n            elevated: \"l14\",\n          },\n        },\n      },\n    },\n  },\n  common: {\n    typefaces: {\n      monospace: \"c1\",\n      rtl: \"c2\",\n      ltr: \"c3\",\n      decorative: \"c4\",\n    },\n    space: \"c5\",\n  }\n};\n\nexport const { useTokens, VariantSelector, generateCSSVariablesAsInlineStyle } = create(tokens);\n```\n\n3. Use the theme variants:\n\n```tsx\n// App.tsx\n\nimport { VariantSelector } from \"./theming\";\n\nconst App = () =\u003e {\n  return (\n    \u003cVariantSelector variant=\"dark\"\u003e\n      \u003cLayoutComponent\u003e\n        {/* Components with dark variant tokens */}\n      \u003c/LayoutComponent\u003e\n      \u003cLayoutComponent\u003e\n        \u003cVariantSelector variant=\"light\"\u003e\n          {/* Components with light variant tokens */}\n        \u003c/VariantSelector\u003e\n      \u003c/LayoutComponent\u003e\n    \u003c/VariantSelector\u003e\n  );\n}\n\nexport default App;\n```\n\n4. You can now access the tokens down the tree using `useTokens` hook. Also you have access to the generated CSS variables in your CSS.\n\nThe CSS variables generated for this variants map with default configuration set and the `dark` variant being selected is:\n\n```\n--colors-primary-base: d1;\n--colors-primary-hover: d2;\n--colors-primary-active: d3;\n--colors-primary-disabled: d4;\n--colors-secondary-base: d5;\n--colors-secondary-hover: d6;\n--colors-secondary-active: d7;\n--colors-secondary-disabled: d8;\n--colors-neutral-text-base: d9;\n--colors-neutral-text-secondary: d10;\n--colors-neutral-text-tertiary: d11;\n--colors-neutral-background-base: d12;\n--colors-neutral-background-container: d13;\n--colors-neutral-background-elevated: d14;\n--typefaces-monospace: c1;\n--typefaces-rtl: c2;\n--typefaces-ltr: c3;\n--typefaces-decorative: c4;\n--space: c5;\n```\n\n## Contributing\n\nRead the [contributing guide](https://github.com/mimshins/react-design-tokens/blob/main/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.\n\nContributing to `react-design-tokens` is about more than just issues and pull requests! There are many other ways to support the project beyond contributing to the code base.\n\n\n## License\n\nThis project is licensed under the terms of the [MIT license](https://github.com/mimshins/react-design-tokens/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmimshins%2Freact-design-tokens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmimshins%2Freact-design-tokens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmimshins%2Freact-design-tokens/lists"}