{"id":16736267,"url":"https://github.com/flexdinesh/design-system-boilerplate","last_synced_at":"2025-03-21T21:31:41.574Z","repository":{"id":66288824,"uuid":"448435591","full_name":"flexdinesh/design-system-boilerplate","owner":"flexdinesh","description":"A design system boilerplate monorepo with opinionated principles, theming and token setup to build your own design system.","archived":false,"fork":false,"pushed_at":"2022-02-13T23:30:25.000Z","size":2499,"stargazers_count":50,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-18T05:34:21.447Z","etag":null,"topics":["design-system"],"latest_commit_sha":null,"homepage":"https://design-system-boilerplate.netlify.app/","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/flexdinesh.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":"2022-01-16T02:02:46.000Z","updated_at":"2024-12-18T03:25:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"3618f022-4e80-4496-b2de-d837bda5dcf7","html_url":"https://github.com/flexdinesh/design-system-boilerplate","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexdinesh%2Fdesign-system-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexdinesh%2Fdesign-system-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexdinesh%2Fdesign-system-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flexdinesh%2Fdesign-system-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flexdinesh","download_url":"https://codeload.github.com/flexdinesh/design-system-boilerplate/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244874324,"owners_count":20524577,"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":["design-system"],"created_at":"2024-10-13T00:08:51.636Z","updated_at":"2025-03-21T21:31:41.568Z","avatar_url":"https://github.com/flexdinesh.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Design System Boilerplate\n\nA highly scalable, performance focused design system boilerplate setup with **configurable tokens**, **smart theming**, **strong types** and auto-generated css variables.\n\n\u003e You can **server render themes** with zero runtime concerns. [This website](https://design-system-boilerplate.netlify.app) is server rendered with light theme. Try reloading the page after disabling JavaScript and you'll see the server rendered theme in action.\n\n## How does it work?\n\n- Themes are statically compiled (no runtime theming).\n- Components are styled using [Emotion](https://emotion.sh/docs/introduction).\n- Tokens are based on [System UI Theme Specification](https://system-ui.com/theme/).\n- Components are built with [Styled System](https://styled-system.com/) component API for rapid UI development.\n- Strong types with full token autocomplete support in component APIs\n\n## Principles\n\nThe design system is built with a set of constraints that allows us to statically compile theme definitions and build flexibile APIs.\n\n- 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.\n\n  - **Box** component `backgroundColor` prop autocompletes with available color tokens - `primary`, `secondary`, etc.\n  - **Box** component `padding` prop autocompletes with available spacing tokens - `small`, `large`, etc.\n\n- Token groups are identified and based on [System UI Theme Specification](https://system-ui.com/theme/). Eg. `colors`, `space`, `fontSizes`, etc.\n\n- Keep your token groups flat. Don't nest your tokens within token groups. Eg. `colors.primary` is allowed. `colors.primary.success` is not allowed.\n\n- All themes should have the same set of tokens. Eg. _dark_ theme cannot have a token that's not available in _light_ theme.\n\n- 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.primary` has 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 of `background: ${(prop) =\u003e prop.theme.colors.primary}`.\n\n## How does theming work?\n\n- Theme definitions are automatically converted to css variables using the `createTheme` utility.\n- The generated css variables are theme-name scoped in `ThemeProvider`.\n\nThis is how the generated css variables are inserted into the global stylesheet —\n\n```css\nbody[data-theme='light'] {\n  --theme-colors-primary: blue;\n  --theme-colors-secondary: lightblue;\n}\nbody[data-theme='dark'] {\n  --theme-colors-primary: green;\n  --theme-colors-secondary: lightgreen;\n}\n```\n\nSo when you use a token in your component —\n\n```jsx\nconst Example = () =\u003e {\n  return (\n    \u003cdiv css={{ backgroundColor: tokens.colors.primary }}\u003eHello World\u003c/div\u003e\n  );\n};\n```\n\nThis is what is used as token value —\n\n```jsx\nconst Example = () =\u003e {\n  return (\n    \u003cdiv css={{ backgroundColor: 'var(--theme-colors-primary)' }}\u003e\n      Hello World\n    \u003c/div\u003e\n  );\n};\n```\n\nAnd the css variable `--theme-colors-primary` value is scoped based on the data attribute in body element — `\u003cbody data-theme=\"light\"\u003e`\n\n## Server rendering themes\n\nTheming 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. `\u003cbody data-theme=\"light\"\u003e`. So server rendering themes is just a matter of rendering the right theme name as body attribute.\n\n## Example theme usage\n\n### Using tokens\n\nAll themes use the same css variable names as token values. So you can define the styles statically without needing runtime theme prop.\n\n```jsx\nimport { tokens } from '@unpublished/design-system';\n\nconst Example = () =\u003e {\n  return (\n    \u003cdiv css={{ backgroundColor: tokens.colors.primary }}\u003eHello World\u003c/div\u003e\n  );\n};\n```\n\n### Getting current theme name\n\nGetting current theme is as simple as querying the DOM attribute. You don't need Context or fancy hooks to provide you the value.\n\n```js\nconst themeName = document.body.getAttribute('data-theme');\n```\n\n_Note: You can use a context based hook if you need — `useTheme()`._\n\n### Switching theme\n\nSwitching 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.\n\n```js\ndocument.body.setAttribute('data-theme', 'dark');\n```\n\n_Note: You can also re-render the whole tree on theme change using `useTheme()` hook if you have to._\n\n## License\n\nMIT © [Dinesh Pandiyan](https://github.com/flexdinesh)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflexdinesh%2Fdesign-system-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflexdinesh%2Fdesign-system-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflexdinesh%2Fdesign-system-boilerplate/lists"}