{"id":28604019,"url":"https://github.com/uber/base-design-docs","last_synced_at":"2025-06-11T17:40:18.705Z","repository":{"id":42793507,"uuid":"272778004","full_name":"uber/base-design-docs","owner":"uber","description":"A documentation site for the Base design system.","archived":false,"fork":false,"pushed_at":"2024-01-09T23:10:23.000Z","size":5569,"stargazers_count":27,"open_issues_count":11,"forks_count":9,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-09T07:59:56.847Z","etag":null,"topics":["design-system","documentation"],"latest_commit_sha":null,"homepage":"https://base-design-docs.vercel.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/uber.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}},"created_at":"2020-06-16T18:02:32.000Z","updated_at":"2024-01-03T00:41:25.000Z","dependencies_parsed_at":"2024-01-10T00:27:35.481Z","dependency_job_id":"c8ca8a51-4795-4ed0-abcf-d0962c421a4a","html_url":"https://github.com/uber/base-design-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/uber/base-design-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fbase-design-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fbase-design-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fbase-design-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fbase-design-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uber","download_url":"https://codeload.github.com/uber/base-design-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uber%2Fbase-design-docs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259308163,"owners_count":22837974,"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","documentation"],"created_at":"2025-06-11T17:40:10.688Z","updated_at":"2025-06-11T17:40:18.692Z","avatar_url":"https://github.com/uber.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Development\n\nFirst, clone and install dependencies:\n\n```bash\n$ git clone https://github.com/uber/base-design-docs.git\n$ cd base-design-docs\n$ yarn\n```\n\nThen, create a `.env.local` file like so:\n\n```bash\n# The base figma file for the org\nFIGMA_FILE_KEY=XYZ\n\n# The figma project to build pages from\nFIGMA_PROJECT_ID=XYZ\n\n# A figma API auth token with access to the above file\nFIGMA_AUTH_TOKEN=XYZ\n```\n\nYou can find the first two variables by looking at the URL for a project:\n\n```\nhttps://www.figma.com/files/FIGMA_FILE_KEY/project/FIGMA_PROJECT_ID/Some-Cool-Project\n```\n\nYou can create an auth token on your Figma user settings page. Note, this auth token needs viewing access to the project and each file in it.\n\nOnce you have your environment set up, run the development server:\n\n```bash\n$ yarn dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) with your browser to see the result.\n\nPages auto-update as you edit files.\n\n## How this works\n\nThis project is built with Next.js and Vercel.\n\nWe use `getStaticPaths` and `getStaticProps` to render a webpage for each top-level Frame in each file in our Figma Project. So, what is a top-level Frame?\n\nFirst, recall that every Figma File has the following structure:\n\n```\nProject \u003e File[] \u003e Page[] \u003e Frame[]\n```\n\nEvery Project can have multuple Files, which can have multiple Pages, which in turn can have multiple Frames. **Top-level Frames are the direct child Frames of a Page**. We render a webpage for every one of these top-level Frames.\n\nTake the following Figma file structure:\n\n```\n- Docs\n  - Setup\n    - Getting started\n    - Living styleguides\n  - Color\n    - Light tokens\n    - Dark tokens\n  - Typography\n    - Uber Move\n    - Uber Move Mono\n  - Grid\n    - Columns\n    - Rows\n```\n\nThis results in the following webpages being rendered:\n\n```\n- Getting started\n- Living styleguides\n- Light tokens\n- Dark tokens\n- Uber Move\n- Uber Move Mono\n- Columns\n- Rows\n```\n\nIn our navigation, these pages will be grouped by their parent Pages. Something like this:\n\n```\nSetup\n  - Getting started\n  - Living styleguides\n...\n```\n\nWe apply this to each file in the Figma project. Note, the file structure itself only impacts the rendered website by influencing the order of pages. We have a step that essentially \"joins\" each page into one list before processing top-level frames.\n\nThere are a couple more conventions to keep in mind:\n\n- We only use Pages that start with a capital letter.\n- We only use Frames that start with a captial letter and are visible.\n\nSo, given any arbitrary Project, provided at build-time as `FIGMA_PROJECT_ID`, so long as the files in the project follow the above conventions, we can build a website.\n\n### Building the site\n\nAt build time, we ask Figma for all of the files in our project (`FIGMA_PROJECT_KEY`). This is saved in `data/project.json`. With that information, we can query each file in the project. We ask for the first two levels of each file's node tree. This will give us the Pages/Top-level Frames for the file. With the pages/frames for each file we can build a site map, which gets saved in `data/siteMap.json`.\n\nThis first part of the build is initiated by `getStaticPaths`, which Next.js calls to build a static collection of pages. The second part of the build is calling `getStaticProps` for each of the pages we've returned in `getStaticPaths`.\n\nDuring the `getStaticProps` call we ask the Figma API for a PNG of the relevant Frame. We receive a link to the generated image from the API, download it to the `public` directory and then embed the image on the page with `next/image`.\n\n### Prior art\n\nWe've done [some prototyping](https://v9-80-0.baseweb.design/guidelines) where we render the Frame as HTML \u0026 CSS (through React). The main benefit is that the pages are indexable— which is useful for SEO and cross-page search. It would also be interesting if the webpages could be made responsive.\n\nThere have been a lot of issues with the HTML \u0026 CSS approach though. To start, it isn't clear if you can do responsive pages without an excessive amount of convention in your Figma File. We want our designers to focus on presenting useful documentation, not fussing over the rules for adding it. Furthermore, for a large File, the API can take quite a long time to query all of the JSON necessary to render the Frame accurately.\n\nAt a certain point a CMS is probably better suited for delivering structured data that can be rendered nicely across multiple mediums.\n\nSo, with all of this considered, for now we use images (pngs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber%2Fbase-design-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuber%2Fbase-design-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuber%2Fbase-design-docs/lists"}