How carbon-design-system/carbon-website works
Project Type & Purpose
• It’s a static site for the Carbon Design System documentation and demos.
• Built with GatsbyJS (a React-based SSG) and a custom theme (gatsby-theme-carbon).
• Publishes to a static hosting platform (e.g. Netlify/Vercel/CDN).
File Structure
• Root config: .babelrc, .eslintrc, gatsby-config.js, gatsby-node.js, gatsby-ssr.js, netlify.toml, nginx.conf.
• /src
– /components: React components (UI demos, charts, layout, etc.).
– /data: YAML/JSON source data for pages and GraphQL queries.
– /gatsby-theme-carbon: theme overrides & shared components.
– /pages: MDX/JSX page entrypoints.
– /styles: global & CSS modules.
– /plugins: custom Gatsby plugins for chart-index & component-index.
• CI/CD: .github/workflows (build, deploy, preview), netlify.toml, vercel.json.
Key Architecture Patterns
• “Data-as-Files”: src/data → Gatsby’s GraphQL layer → components/pages.
• Plugin-based extension: custom plugins under /plugins.
• Theme composition: custom theme in /gatsby-theme-carbon layered on top of Gatsby’s GraphQL & React.
• CI/CD-driven static build & deploy to CDN.
Main Components
a. Developer Workstation
– Git (GitHub repo)
– Node.js & Yarn
– Local Gatsby dev server (yarn dev)
b. Continuous Integration
– GitHub Actions workflows
– Netlify/Vercel build step (netlify.toml / vercel.json)
c. Gatsby Build Process
– Source files (components, pages, data, plugins, theme)
– GraphQL data layer (internal)
– Webpack bundler & SSG renderer
– Output: /public (static HTML, JS, CSS)
d. Hosting & Delivery
– Static web host (Netlify/Vercel/CDN)
– CDN edge nodes
– Client browser (React hydration & runtime navigation)
Relationships & Data Flows
• During Build: Source → GraphQL → HTML/JS/CSS → /public.
• At runtime: Browser requests static assets from CDN, hydrates React, loads data from inlined GraphQL JSON.
Technologies & Frameworks
• Build: Node.js, Yarn, GatsbyJS, Webpack, Babel
• Theming: gatsby-theme-carbon
• Data: MDX, YAML, JSON, GraphQL (internal)
• CI: GitHub Actions, Netlify/Vercel
• Hosting: Netlify/Vercel + CDN
• Dev tools: ESLint, Prettier, Husky pre-commit hooks