{"id":15286244,"url":"https://github.com/xop/design-system-starter","last_synced_at":"2025-04-13T03:08:09.131Z","repository":{"id":254679844,"uuid":"724541988","full_name":"XOP/design-system-starter","owner":"XOP","description":"Design System Starter Template","archived":false,"fork":false,"pushed_at":"2024-09-13T15:46:59.000Z","size":3439,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T03:08:02.052Z","etag":null,"topics":["astro","design-system","design-tokens","documentation-tool","monorepo","storybook","template-project","turborepo","ui-components","ui-library"],"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/XOP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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-11-28T09:43:47.000Z","updated_at":"2025-03-13T10:15:02.000Z","dependencies_parsed_at":"2024-08-25T10:24:32.121Z","dependency_job_id":"175ccb51-53f4-4815-b6b6-37708ae30b3e","html_url":"https://github.com/XOP/design-system-starter","commit_stats":null,"previous_names":["xop/design-system-starter"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fdesign-system-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fdesign-system-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fdesign-system-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fdesign-system-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XOP","download_url":"https://codeload.github.com/XOP/design-system-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248657918,"owners_count":21140846,"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":["astro","design-system","design-tokens","documentation-tool","monorepo","storybook","template-project","turborepo","ui-components","ui-library"],"created_at":"2024-09-30T15:11:17.832Z","updated_at":"2025-04-13T03:08:09.105Z","avatar_url":"https://github.com/XOP.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Design System Starter Template\n\n## About\n\nDesign System is the complex organizational entity, allowing for [multiple proven benefits but coming with several caveats](https://medium.com/@genedesign/design-systems-beyond-basics-unveiling-nuances-and-oversights-6c85807b1c26).  \nThere 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.\n\n**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.\n\n## Overview\n\nDesign System Template consists of number of packages, configs and apps, having various purposes.  \nAll packages and apps have their dedicated README.md file containing more information about organization, scripts etc.\n\nPrimary framework for the template is [React](https://react.dev/).  \nIt is not opinionated nor forced recommendation, it's for demo purpose only.  \nAnother staple of the DS Template is [Typescript](https://www.typescriptlang.org/).\n\n### Features at a glance:\n\n- ⭐️ Separate packages for UI, Icons, Design Tokens and more\n- ⭐️ Automated icons generation from SVG\n- ⭐️ Automated CSS generation from JS values\n- 🚀 Example app to see everything in action\n- 🚀 Storybook development and interactive documentation\n- 🚀 Documentation website, auto-documenting components\n- 🛠️ Visual Regression Testing for UI library\n- 🛠️ Changelog generation and automated release process\n- 🛠️ Packages versions synchronization\n- 🛠️ Quick and reasonable linting and formatting\n\n### Brief technologies overview:\n\n- [React](https://react.dev/)\n- [Typescript](https://www.typescriptlang.org/)\n- [Storybook](https://storybook.js.org/) (ver 8)\n- [Turborepo](https://turbo.build/repo)\n- [Syncpack](https://jamiemason.github.io/syncpack/guide/getting-started/)\n- [Vite](https://vitejs.dev/)\n- [Astro](https://astro.build/) (ver 4)\n- [Vitest](https://vitest.dev/)\n- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)\n- [Playwright](https://playwright.dev/)\n- [Biome](https://biomejs.dev/)\n\nNow let's dig deeper and explore the modules in detail.\n\n---\n\n## Packages\n\n### UI Library - [dss-ui](/packages/dss-ui/README.md)\n\nPrimary module. It is hard to imagine a modern Design System without UI module.  \nTemplate UI is based on the headless [react-aria](https://react-spectrum.adobe.com/react-aria/) library.\n\n### Design Tokens - [dss-tokens](/packages/dss-tokens/README.md)\n\nDesign 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.\n\n### Icons - [dss-icons](/packages/dss-icons/README.md)\n\nSecondary 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.\n\n### Fonts - [dss-fonts](/packages/dss-fonts/README.md)\n\nAnother 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](/packages/dss-fonts/README.md).\n\n## Configs \n\n### Typescript Config - [tsconfig](/tsconfig/package.json)\n\nThere are 2 essential configurations - `lib-js` and `lib-react`.  \nEasy to notice that the latter should be used when framework is utilized.\n\n## Apps\n\n### Storybook - [storybook](/apps/storybook/README.md)\n\n\u003e [Deployed Demonstration](https://ds-starter-storybook.vercel.app/)\n\nPrimary app. [Storybook](https://storybook.js.org/) is an essential tool for development, debugging and of course documenting UI.  \nApart from consolidating all stories from the packages it also offers VRT capabilities together with [Playwright](https://playwright.dev/).\n\n### Documentation Website - [docs](/apps/docs/README.md)\n\n\u003e [Deployed Demonstration](https://ds-starter-docs.vercel.app/)\n\nDedicated documentation website gives your Design System a nice touch of customization and signifies a certain maturity stage.  \nApart from components presentation it also holds articles on patterns, typography, color system and everything else that is essential for your Design System.\n\n### Example with Vite and Typescript - [example-vite](/apps/example-vite/README.md)\n\n\u003e [Deployed Demonstration](https://ds-starter-app-vite.vercel.app/)\n\nExample 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. \n\n---\n\n## Technology\n\nFirst things first, the monorepo is created with [pnpm](https://pnpm.io/) and [turbo](https://turbo.build/repo). Both technologies work in synergy for maximum efficiency and developer experience.\n\nAt 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.\n\n### Development\n\n- [Storybook](https://storybook.js.org/)\n\n### Libraries\n\n- [react-aria](https://react-spectrum.adobe.com/react-aria/)\n\n### CSS\n\n- [vanilla-extract](https://vanilla-extract.style/)\n- [CSS modules](https://github.com/css-modules/css-modules)\n- [clsx](https://www.npmjs.com/package/clsx)\n- [normalize.css](https://www.npmjs.com/package/@csstools/normalize.css)\n\n### Building\n\n- [Vite](https://vitejs.dev/)\n- [tsup](https://tsup.egoist.dev/)\n\n### Documentation\n\nThe whole [documentation](/apps/docs/README.md) website is running on Astro.\n\n- [Astro](https://astro.build/)\n\n### Testing\n\nUI library is tested in 2 ways - component testing and visual testing.  \nNote that component testing is part of [ui package](/packages/dss-ui/tests/setup.ts), whereas VRT is the part of [Storybook app](/apps/storybook/playwright.config.ts).\n\n- [Vitest](https://vitest.dev/)\n- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)\n- [Playwright](https://playwright.dev/)\n\n### State management\n\nState management is not essential, more of an effective and easy enhancement for the project.  \nExplore [docs](/apps/docs/src/store/store.ts) and [example app](/apps/example-vite/src/components/Space/Space.tsx) to learn more.\n\n- [nanostores](https://github.com/nanostores)\n- [jotai](https://jotai.org/)\n- [store2](https://www.npmjs.com/package/store2)\n\n### SVG processing\n\nSVG processing is required for producing [icons package](/packages/dss-icons/scripts/generateIcons.cts).\n\n- [SVGR](https://react-svgr.com/)\n\n### Linting and formatting\n\nBiome takes care of both linting and formatting at blazing speeds.  \nMain configuration is located at the [project root](/biome.json) and extended on the package level.\n\n- [Biome](https://biomejs.dev/)\n\n### Cool stuff\n\n- [tsParticles](https://particles.js.org/)\n\n### Color and Tokens\n\n- [Unicornix Color Themes](https://www.npmjs.com/package/unicornix)\n- [Design Tokens Generator](https://www.design-tokens.dev/)\n\n## Adding Components\n\nThe most effective way to scaffold a new Design System component is via generator.  \nHere we rely on [turbo generation](https://turbo.build/repo/docs/core-concepts/monorepos/code-generation#custom-generators) functionality. Configuration files are located in the [dedicated folder](/turbo/generators/config.ts).\n\nRun generator:\n```sh\npnpm gen:component\n```\n\nWhen all operations succeed you should see changes in `packages/dss-ui` and `apps/docs`.  \nIn [UI](/packages/dss-ui/src/components/) you would find a scaffolding for the new component (note, for demo purposes components are based on [react-aria](https://react-spectrum.adobe.com/react-aria/), naturally your approach may vary significantly), including styling with [vanilla-extract](https://vanilla-extract.style/) (similarly here, you styling approach can be very different) and [Storybook](https://storybook.js.org/) stories.  \n\nIn the [Docs](/apps/docs/src/content/components/) you would find new files that are sufficient for adding a component to the docs website.  \n\nAll you need to do now is to fill the new files with content!\n\n## Scripts\n\nScripts can be ran either from a project/app or the root path.  \nNote that root scripts mostly are global by design and would target all packages and apps.\n\nThere are a couple of exceptions. For example, to run Storybook in dev mode: \n```sh\npnpm dev\n```\n\n### Build\n\nBuild scripts are separated due to assumed different release process.\n\nPackages build:\n```sh\npnpm build:pck\n```\n\nApps build:\n```sh\npnpm build:app\n```\n\n### Test\n\nThere are different kinds of tests involved, some require building first.\n\nRun component and visual tests:\n```sh\npnpm test\n```\n\n### Linting and Formatting\n\nBoth linting and formatting commands follow [Biome CLI](https://biomejs.dev/reference/cli/) without any customizations.\n\nLint everything:\n```sh\npnpm lint\n```\n\nFormat everything:\n```sh\npnpm format\n```\n\n### Dependencies sync\n\n[Syncpack](https://jamiemason.github.io/syncpack/) 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](/.syncpackrc.cjs).\n\nFix mismatches:\n```sh\npnpm syncpack\n```\n\nList mismatches for inspection:\n```sh\npnpm syncpack:list\n```\n\n### Changelog and Release\n\nChangelog automation can be implemented in a number of ways, here we rely on [Changesets](https://github.com/changesets/changesets/tree/main). Configuration can be found in the [dedicated folder](/.changeset/config.json). Examples of the changelog generation are in the CHANGELOG.md files. Note that real-world logs will also contain commit data and links.\n\nGenerate changesets (changeset files can be committed if needed):\n```sh\npnpm change:gen\n```\n\nBump the version(s):\n```sh\npnpm change:version\n```\n\nPublish modules:\n```sh\npnpm release\n```\n\n### Automation\n\nProject uses Github [actions](/.github/actions/) and [workflows](/.github/workflows/) for standard operations, such as post-merge checks, deployment of apps and release of the packages. \n\nWorkflows use the following secrets set up in the repo:\n\n- `NPM_TOKEN` - NPM authorization token, used for packages publishing\n- `VERCEL_ORG_ID` - Vercel organization ID, used for deployment of apps\n- `VERCEL_PROJECT_STORYBOOK_ID` - Vercel Project ID for Storybook application, used for deployment\n- `VERCEL_PROJECT_DOCS_ID` - Vercel Project ID for Docs application, used for deployment\n- `VERCEL_PROJECT_EXAMPLE_VITE_ID` - Vercel Project ID for Example Vite application, used for deployment\n- `VERCEL_TOKEN` - Vercel authorization token, used for all Vercel operations\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxop%2Fdesign-system-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxop%2Fdesign-system-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxop%2Fdesign-system-starter/lists"}