{"id":19373411,"url":"https://github.com/xop/awsm-docs","last_synced_at":"2026-05-16T04:07:19.951Z","repository":{"id":209141729,"uuid":"717030827","full_name":"XOP/awsm-docs","owner":"XOP","description":"Design System Documentation Website Slingshot ","archived":false,"fork":false,"pushed_at":"2024-02-26T21:19:12.000Z","size":1030,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-07T01:51:36.593Z","etag":null,"topics":["astro","design-system","design-tokens","headless-components","scaffolding","ui-components","ui-library"],"latest_commit_sha":null,"homepage":"https://awsm-docs.vercel.app/","language":"TypeScript","has_issues":false,"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-10T11:58:37.000Z","updated_at":"2024-07-10T19:06:03.000Z","dependencies_parsed_at":"2023-12-29T22:31:37.085Z","dependency_job_id":"84c16b18-9194-4aee-a867-52a7b03854d4","html_url":"https://github.com/XOP/awsm-docs","commit_stats":null,"previous_names":["xop/awsm-docs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fawsm-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fawsm-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fawsm-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XOP%2Fawsm-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XOP","download_url":"https://codeload.github.com/XOP/awsm-docs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240500609,"owners_count":19811559,"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","headless-components","scaffolding","ui-components","ui-library"],"created_at":"2024-11-10T08:28:05.962Z","updated_at":"2026-05-16T04:07:14.921Z","avatar_url":"https://github.com/XOP.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWSM Design System Documentation Website Slingshot \n\n\u003e See it in [Action](https://awsm-docs.vercel.app/)\n\n## About\n\nAWSM Docs is practically a template for a quick scaffolding of Design System (or UI library) documentation.  \nIt is built with [Astro](https://astro.build/) and relies on [MDX](https://docs.astro.build/en/guides/markdown-content/) for documentation, which is non-developer friendly. However the most interesting part is using [Storybook](https://storybook.js.org/) stories format both for development and examples in the docs website.\n\n## Contents\n\nRepo is organized with [nx](https://nx.dev/) and split into apps and packages.  \n\n### Apps\n\nApps contain **docs**, which is the documentation project itself.\n\nAnother app is **storybook**, which is used for UI development.  \nNote, that it is set up to consume stories from the relative path,  \ncompared to the classic in-project location.\n\nBoth apps consume and expose stories from the UI package.\n\n### Packages\n\nThere are core and support packages.  \nCore packages consist of design tokens (`awsm-tokens`) and UI library (`awsm-ui`).  \nSupport packages are basically configuration - `eslint-config-awsm` and `awsm-tsconfig`.\n\n\n## Technologies\n\n### UI library\n\nUI library is represented by several classic elements from 2 categories - `Button`, `Switch` and `Disclosure`.  \nEach component is using a different headless UI library for demo purposes.   \nStorybook can be adjusted respectively, but in this case there's no need.\n\nNote that I use React, however there should be no problem with using Vue, Solid etc.\n\nHeadless libraries used:\n\n- [React Aria components](https://react-spectrum.adobe.com/react-aria/index.html)\n- [Radix UI primitives](https://www.radix-ui.com/primitives)\n- [Headless UI components](https://headlessui.com/)\n\n### Styling \n\nThere are 2 styling approaches in this project for demonstration purposes.  \nFirst is scoped CSS in Astro, along with CSS modules. Both rely on CSS variables as design tokens.   \nSecond is using [vanilla-extract](https://vanilla-extract.style/) as a styling engine,  \nto showcase CSS-in-JS application and JS tokens as well. \n\nThere should be no issues with using alternative styling engines,  \nhowever you would need to adjust settings in `.storybook` and `astro.config.mjs`.\n\n\n## Usage\n\nInstall project dependencies:\n```sh\npnpm i\n```\n\nRun Storybook:\n```sh\nnx run storybook:dev\n```\n\nRun Docs locally:\n```sh\nnx run docs:dev\n```\n\nSimilarly, build Docs:\n```sh\nnx run docs:build\n```\n\n\n## Customization\n\nDocs app is made with customization and scaling in mind.\n\nThe structure of the website is pretty much traditional for the Design System websites,  \nwhich gives a solid kickstart, yet there are many things that can be improved further.  \n\nComponents in docs are intentionally under-styled, just to give a sense of presentation.  \nSame for functionality, pages, structure - everything can be tweaked or removed for your benefit.  \n\n\n## Extras\n\nTo learn more about the project in less technical terms welcome to check out the article on your favorite platform:\n\n- [Medium](https://medium.com/@genedesign/how-to-build-awsm-docs-07375167a6b2)\n- [dev.to](https://dev.to/genedesign/how-to-build-awsm-docs-with-storybook-and-astro-4ego)\n- [Hasnode](https://designtokens.hashnode.dev/awsm-docs-with-storybook-and-astro)\n- [Substack](https://genedesign.substack.com/p/how-to-build-awsm-docs)\n\n\n## [LICENSE](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxop%2Fawsm-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxop%2Fawsm-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxop%2Fawsm-docs/lists"}