react-design-tokens v1.2.1
React Design Tokens
An optimized and creative theming solution that generates CSS variables based on the tokens provided.
Installation
Please note that react >= 17 and react-dom >= 17 are peer dependencies.
Run the following script to install and save in your package.json
dependencies:
# with npm
npm install react-design-tokens
# or with yarn
yarn add react-design-tokens
# or with pnpm
pnpm add react-design-tokens
API
The exposed APIs:
createTheming(defaultTheme, config?) => { useTheme, getVariablesAsStyles, ThemeProvider }
\ The main exposed API which will return:\useTheme
: A React Hook to hook into the provided theme object.\ThemeProvider
: A React Context Provider to provide the theme object down the tree and also populate the generated CSS variables for it's children.getVariablesAsStyles
: A helper function that gets a theme object and returns its CSS variables as inlinestyle
DOM property. (Useful when you want to opt-ininitializeVariablesOnHTMLRoot
and you also want your variables to be attached to:root
during SSR)defaultTheme
\ The default theme which will be used asThemeContext
's default value.config
optional\ The theming configuration object.config.cssVariableGenerator
optional\ The function which is being used to generate CSS variables based on the provided theme object.config.initializeVariablesOnHTMLRoot
optional | default:false
\ If set totrue
, initial<ThemeProvider>
will attach CSS variables to the HTML element (Also known as:root
).
defaultCssVariableGenerator(tokenFamilyKey, tokenPath, tokenValue)
\ The default CSS variable generate function. The generated variables obey the following rules:\ 1- Values that are not of typestring
ornumber
will be omitted.\ 2-number
values will be converted into{tokenValue}px
.\ 3- Overall variable string:{path-to-token}: {tokenValue}
tokenFamilyKey
\ The key of a root token family.tokenPath
\ The dot-separated path to the token from which the root key has been omitted.tokenValue
\ The value of the token.
Basic Usage
To getting started, all you need to do is:
- Create your own theme:
// theming.ts
export const theme = {
colors: {
primary: {
base: "1",
hover: "2",
active: "3",
disabled: "4"
},
secondary: {
base: "5",
hover: "6",
active: "7",
disabled: "8"
},
neutral: {
text: {
base: "9",
secondary: "10",
tertiary: "11"
},
background: {
base: "12",
container: "13",
elevated: "14"
}
}
},
dark: 1
};
export type Theme = typeof theme;
- Create a theming client for your theme: \ (We recommend to create a theming for each theme object)
// theming.ts
import { createTheming } from "react-design-tokens";
export const theme = {
colors: {
primary: {
base: "1",
hover: "2",
active: "3",
disabled: "4"
},
secondary: {
base: "5",
hover: "6",
active: "7",
disabled: "8"
},
neutral: {
text: {
base: "9",
secondary: "10",
tertiary: "11"
},
background: {
base: "12",
container: "13",
elevated: "14"
}
}
},
dark: 1
};
export type Theme = typeof theme;
export const { ThemeProvider, useTheme } = createTheming(theme);
- Provide the theme:
// App.tsx
import { ThemeProvider, theme } from "./theming";
const App = () => {
return (
<ThemeProvider theme={theme}>
{/* Components */}
</ThemeProvider>
);
}
export default App;
- You can now access the
theme
object down the tree usinguseTheme
hook. Also you have access to the generated CSS variables in your CSS.
The CSS variables generated for this theme with default configuration are as follows:
--colors-primary-base: 1;
--colors-primary-hover: 2;
--colors-primary-active: 3;
--colors-primary-disabled: 4;
--colors-secondary-base: 5;
--colors-secondary-hover: 6;
--colors-secondary-active: 7;
--colors-secondary-disabled: 8;
--colors-neutral-text-base: 9;
--colors-neutral-text-secondary: 10;
--colors-neutral-text-tertiary: 11;
--colors-neutral-background-base: 12;
--colors-neutral-background-container: 13;
--colors-neutral-background-elevated: 14;
--dark: 1px;
Notes
You can only access the CSS variables in a sub-tree which is being wrapped with
ThemeProvider
. (In other words, each sub-tree has it's own CSS variables)Inner theme objects will be merged with outer theme objects. So to override an outer theme, just provide the tokens you want to change in the child-tree:
<ThemeProvider theme={theme}>
<ThemeProvider
theme={{ colors: { neutral: { text: { tertiary: "#000" } } } }}
>
</ThemeProvider>
</ThemeProvider>
Contributing
Read the contributing guide to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
Contributing 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.
License
This project is licensed under the terms of the MIT license.
24 days ago
26 days ago
26 days ago
1 month ago
2 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago