Design System is the complex organizational entity, allowing for multiple proven benefits but coming with several caveats.
There are a couple of things that require consideration from development perspective - architecture and growth pace, both interconnected. It is very important to start small, and it's also very important to outline a future Design System early, preventing scalability impediments and spontaneous growth drawbacks.
Design System Starter (DSS for short) Template allows for better technology shaping from the start. There are some foundational modules, however it's not necessary to maintain all of them from the get go. Since you already know where the product is headed, you just need to plan and execute accordingly - start with required parts and add more when needed.
Design System Template consists of number of packages, configs and apps, having various purposes.
All packages and apps have their dedicated README.md file containing more information about organization, scripts etc.
Primary framework for the template is React.
It is not opinionated nor forced recommendation, it's for demo purpose only.
Another staple of the DS Template is Typescript.
- ⭐️ Separate packages for UI, Icons, Design Tokens and more
- ⭐️ Automated icons generation from SVG
- ⭐️ Automated CSS generation from JS values
- 🚀 Example app to see everything in action
- 🚀 Storybook development and interactive documentation
- 🚀 Documentation website, auto-documenting components
- 🛠️ Visual Regression Testing for UI library
- 🛠️ Changelog generation and automated release process
- 🛠️ Packages versions synchronization
- 🛠️ Quick and reasonable linting and formatting
- React
- Typescript
- Storybook (ver 8)
- Turborepo
- Syncpack
- Vite
- Astro (ver 4)
- Vitest
- React Testing Library
- Playwright
- Biome
Now let's dig deeper and explore the modules in detail.
UI Library - dss-ui
Primary module. It is hard to imagine a modern Design System without UI module.
Template UI is based on the headless react-aria library.
Design Tokens - dss-tokens
Design Tokens in a separate module provide more flexibility for the clients not using the UI Library. It provides styling capabilities and consistency at the same time. It is easy to notice how quickly tokens become an essential dependency to nearly all packages and apps.
Icons - dss-icons
Secondary module, that is not usually separated from the very beginning. However it makes sense further to maintain a dedicated package. Icons offer a simple and efficient process of adding an Icon to the Design System setup.
Fonts - dss-fonts
Another secondary module, that is exactly what it's named after. Fonts distribution can be done very differently and it's just one of the ways to support it. Find more details in the documentation.
Typescript Config - tsconfig
There are 2 essential configurations - lib-js and lib-react.
Easy to notice that the latter should be used when framework is utilized.
Storybook - storybook
Primary app. Storybook is an essential tool for development, debugging and of course documenting UI.
Apart from consolidating all stories from the packages it also offers VRT capabilities together with Playwright.
Documentation Website - docs
Dedicated documentation website gives your Design System a nice touch of customization and signifies a certain maturity stage.
Apart from components presentation it also holds articles on patterns, typography, color system and everything else that is essential for your Design System.
Example with Vite and Typescript - example-vite
Example app is a great way to give your Design System a spin, collect insights and discover certain issues at the early stages. If you have multiple modules, it is also an idea for creating a demonstration of how they implement and collaborate together.
First things first, the monorepo is created with pnpm and turbo. Both technologies work in synergy for maximum efficiency and developer experience.
At this point it's worth mentioning that nearly all technologies can be substituted in one way or another with matching analogues according to your preferences or project requirements. Nothing extraordinary is used in any package or app, in the end it's all HTML, JS and CSS, however there is a certain bias towards certain technologies.
The whole documentation website is running on Astro.
UI library is tested in 2 ways - component testing and visual testing.
Note that component testing is part of ui package, whereas VRT is the part of Storybook app.
State management is not essential, more of an effective and easy enhancement for the project.
Explore docs and example app to learn more.
SVG processing is required for producing icons package.
Biome takes care of both linting and formatting at blazing speeds.
Main configuration is located at the project root and extended on the package level.
The most effective way to scaffold a new Design System component is via generator.
Here we rely on turbo generation functionality. Configuration files are located in the dedicated folder.
Run generator:
pnpm gen:componentWhen all operations succeed you should see changes in packages/dss-ui and apps/docs.
In UI you would find a scaffolding for the new component (note, for demo purposes components are based on react-aria, naturally your approach may vary significantly), including styling with vanilla-extract (similarly here, you styling approach can be very different) and Storybook stories.
In the Docs you would find new files that are sufficient for adding a component to the docs website.
All you need to do now is to fill the new files with content!
Scripts can be ran either from a project/app or the root path.
Note that root scripts mostly are global by design and would target all packages and apps.
There are a couple of exceptions. For example, to run Storybook in dev mode:
pnpm devBuild scripts are separated due to assumed different release process.
Packages build:
pnpm build:pckApps build:
pnpm build:appThere are different kinds of tests involved, some require building first.
Run component and visual tests:
pnpm testBoth linting and formatting commands follow Biome CLI without any customizations.
Lint everything:
pnpm lintFormat everything:
pnpm formatSyncpack provides granular control over dependencies, which can get out of control quite soon in a big monorepo setup. Configuration can be located in .syncpackrc.cjs.
Fix mismatches:
pnpm syncpackList mismatches for inspection:
pnpm syncpack:listChangelog automation can be implemented in a number of ways, here we rely on Changesets. Configuration can be found in the dedicated folder. Examples of the changelog generation are in the CHANGELOG.md files. Note that real-world logs will also contain commit data and links.
Generate changesets (changeset files can be committed if needed):
pnpm change:genBump the version(s):
pnpm change:versionPublish modules:
pnpm releaseProject uses Github actions and workflows for standard operations, such as post-merge checks, deployment of apps and release of the packages.
Workflows use the following secrets set up in the repo:
NPM_TOKEN- NPM authorization token, used for packages publishingVERCEL_ORG_ID- Vercel organization ID, used for deployment of appsVERCEL_PROJECT_STORYBOOK_ID- Vercel Project ID for Storybook application, used for deploymentVERCEL_PROJECT_DOCS_ID- Vercel Project ID for Docs application, used for deploymentVERCEL_PROJECT_EXAMPLE_VITE_ID- Vercel Project ID for Example Vite application, used for deploymentVERCEL_TOKEN- Vercel authorization token, used for all Vercel operations
This project is licensed under the MIT License