A highly scalable, performance focused design system boilerplate setup with configurable tokens, smart theming, strong types and auto-generated css variables.
You can server render themes with zero runtime concerns. This website is server rendered with light theme. Try reloading the page after disabling JavaScript and you'll see the server rendered theme in action.
- Themes are statically compiled (no runtime theming).
- Components are styled using Emotion.
- Tokens are based on System UI Theme Specification.
- Components are built with Styled System component API for rapid UI development.
- Strong types with full token autocomplete support in component APIs
The design system is built with a set of constraints that allows us to statically compile theme definitions and build flexibile APIs.
-
Predefine all your themes. i.e no runtime theme creation. This allows us to statically define themes using css variables and create strongly typed theme tokens. Strong types help with full autocomplete support in component APIs. Eg.
- Box component
backgroundColorprop autocompletes with available color tokens -primary,secondary, etc. - Box component
paddingprop autocompletes with available spacing tokens -small,large, etc.
- Box component
-
Token groups are identified and based on System UI Theme Specification. Eg.
colors,space,fontSizes, etc. -
Keep your token groups flat. Don't nest your tokens within token groups. Eg.
colors.primaryis allowed.colors.primary.successis not allowed. -
All themes should have the same set of tokens. Eg. dark theme cannot have a token that's not available in light theme.
-
Theming is setup with CSS custom properties (css variables). This makes it easy to switch or server render themes without runtime concerns. Eg.
token.colors.primaryhas the same css variable across themes and makes it easy to statically define styles instead of defining the styles during runtime based on theme.background: ${tokens.colors.primary}instead ofbackground: ${(prop) => prop.theme.colors.primary}.
- Theme definitions are automatically converted to css variables using the
createThemeutility. - The generated css variables are theme-name scoped in
ThemeProvider.
This is how the generated css variables are inserted into the global stylesheet —
body[data-theme='light'] {
--theme-colors-primary: blue;
--theme-colors-secondary: lightblue;
}
body[data-theme='dark'] {
--theme-colors-primary: green;
--theme-colors-secondary: lightgreen;
}So when you use a token in your component —
const Example = () => {
return (
<div css={{ backgroundColor: tokens.colors.primary }}>Hello World</div>
);
};This is what is used as token value —
const Example = () => {
return (
<div css={{ backgroundColor: 'var(--theme-colors-primary)' }}>
Hello World
</div>
);
};And the css variable --theme-colors-primary value is scoped based on the data attribute in body element — <body data-theme="light">
Theming is completely css driven. All themes are statically defined using tokens which are then converted to css variables. Current theme is decided based on a html attribute on body element. Eg. <body data-theme="light">. So server rendering themes is just a matter of rendering the right theme name as body attribute.
All themes use the same css variable names as token values. So you can define the styles statically without needing runtime theme prop.
import { tokens } from '@unpublished/design-system';
const Example = () => {
return (
<div css={{ backgroundColor: tokens.colors.primary }}>Hello World</div>
);
};Getting current theme is as simple as querying the DOM attribute. You don't need Context or fancy hooks to provide you the value.
const themeName = document.body.getAttribute('data-theme');Note: You can use a context based hook if you need — useTheme().
Switching theme is as simple as setting the theme name on body element. Since themes are completely css driven, themes can be changed without re-rendering the whole tree.
document.body.setAttribute('data-theme', 'dark');Note: You can also re-render the whole tree on theme change using useTheme() hook if you have to.
MIT © Dinesh Pandiyan