CssVarsDesignToken simplifies theme management in React applications by leveraging CSS variables and providing hooks for theme selection. By following the provided guidelines, you can easily integrate design tokens and themes into your components for consistent styling.
Define dark and light themes however you like.
const themes= {
light: {
color: { bg: '#fff', fg: '#333' },
layout: { margin: 10 }
},
dark: {
color: { bg: '#333', fg: '#fff' },
layout: { margin: 20 }
}
}Wrap your app in a CssVarsDesignTokenProvider
import {
CssVarsDesignTokenProvider,
useCssVarsDesignTokenContext
} from 'css-vars-design-token';
const App = () =>
<CssVarsDesignTokenProvider themes={themes}>
<Components />
</CssVarsDesignTokenProvider>
function Components() {
const { theme, toggle } = useCssVarsDesignTokenContext();
return (
<div>
Current Theme: <strong>{theme}</strong>
<button onClick={toggle}>Toggle Theme</button>
</div>
);
}And use CSS Variables wherever you like. The object keys are flattened and converted to CSS variables.
h1 {
color: var(--color-fg);
background-color: var(--color-bg);
margin: var(--layout-margin);
}<div style={{ margin: "var(--layout-margin)" }}>
Hello World
</div>npm install --save css-vars-design-tokenTo use CssVarsDesignToken in your project, you need to have installed the following peer dependencies:
reactAny recent version will do.
Ensure that you have these dependencies included in your project.
-
CssVarsDesignTokenProvider
- The
CssVarsDesignTokenProvidercomponent is used to provide themes and design tokens to the components within its subtree. - It accepts the following props:
themes: An object containing theme configurations, where each key represents a theme name and the value is a DesignToken object.style(optional): Additional CSS styles to apply to the root element.
- The
-
useCssVarsDesignToken
- Custom hook to access design tokens from the context and to manage themes and toggle between them.
- Should be used within a component wrapped by
CssVarsDesignTokenProvider.
-
toCssVarsDesignToken
- Utility function to convert DesignToken objects into CSS variable format.
Here is a simple example demonstrating the usage of CssVarsDesignToken with basic theming:
<html>
<head>
<style>
* {
background-color: var(--primary);
color: var(--secondary);
}
</style>
</head>
<body>
<div id="root"></div>
<script type="text/babel">
function App() {
const { toggle } = useCssTheme();
return (
<div>
<button onClick={toggle}>Toggle Theme</button>
</div>
);
}
ReactDOM.createRoot(document.getElementById('root')).render(
<CssVarsDesignTokenProvider
themes={{
light: { primary: '#333', secondary: '#666' },
dark: { primary: '#fff', secondary: '#ccc' }
}}
>
<App />
</CssVarsDesignTokenProvider>
);
</script>
</body>
</html>Here is an example using the deeply-structured nature of the Design Token for more complex theming:
<html>
<head>
<style>
body {
margin: var(--layout-margin);
background-color: var(--color-bg);
color: var(--color-fg);
}
</style>
</head>
<body>
<div id="root"></div>
<script type="text/babel">
function StructuredThemeComponent() {
const { theme, toggle } = useCssTheme();
return (
<div>
<p>Current Theme: {theme}</p>
<button onClick={toggle}>Toggle Theme</button>
</div>
);
}
ReactDOM.createRoot(document.getElementById('root')).render(
<CssVarsDesignTokenProvider
themes={{
light: {
color: { bg: '#fff', fg: '#333' },
layout: { margin: 10 }
},
dark: {
color: { bg: '#333', fg: '#fff' },
layout: { margin: 20 }
}
}}
>
<StructuredThemeComponent />
</CssVarsDesignTokenProvider>
);
</script>
</body>
</html>
> [email protected] test:coverage
> jest --coverage
PASS ./test.tsx
Function toCssVars
✓ toCssVars returns the expected flat list of css vars (1 ms)
React integrations
✓ Computed style matches the expectation from the token (13 ms)
✓ Computed style matches the other theme upon toggling (8 ms)
---------------------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------------------|---------|----------|---------|---------|-------------------
All files | 92.85 | 65 | 100 | 92.59 |
css-vars-design-token.tsx | 92.85 | 65 | 100 | 92.59 | 23,30
---------------------------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests: 3 passed, 3 total
Snapshots: 0 total
Time: 1.635 s
Ran all test suites.
There are additional dependencies for development:
typescriptfor auto-completion and type checking.jestfor testing.webpackfor bundling the project.eslintandprettierfor linting and formatting.http-serverfor running the demo locally.org-modefor generating documentation.
The following npm scripts are available for development:
npm test: Run Jest for testing.npm run build: Build the project using Webpack in production mode.npm run clean: Remove thedistandcoveragedirectories.npm run demo: Start a local server to view the demo at http://localhost:8080/demo.html.npm run lint: Lint the project using ESLint.npm run format: Format the TypeScript and JSX files using Prettier.npm run test:watch: Watch mode for running Jest tests.npm run test:coverage: Run Jest with test coverage reporting.
If you want to contribute to this project, please follow these guidelines:
- Fork the repository on GitHub.
- Clone your forked repository locally.
- Make your changes in a feature branch.
- Write tests for your changes if applicable.
- Update the documentation as needed.
- Submit a pull request to the
mainbranch. - Provide a clear description of the changes you made in your pull request.
Thank you for contributing to this project!