{"id":22850050,"url":"https://github.com/gah-code/gatsby-theme-ui-template","last_synced_at":"2026-05-06T03:33:44.900Z","repository":{"id":263719093,"uuid":"891277901","full_name":"gah-code/gatsby-theme-ui-template","owner":"gah-code","description":"My Gatsby template configured with Theme UI showcasing multi-mode color themes, MDX integration, and scalable component architecture.","archived":false,"fork":false,"pushed_at":"2025-02-26T08:04:13.000Z","size":1507,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-05T13:37:05.464Z","etag":null,"topics":["gatsby","mdx","theme-development","theme-switcher","ui","usecontext"],"latest_commit_sha":null,"homepage":"https://gatsby-ui-theme.netlify.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gah-code.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":"2024-11-20T03:32:16.000Z","updated_at":"2025-02-26T08:04:17.000Z","dependencies_parsed_at":"2024-12-19T14:21:14.779Z","dependency_job_id":"ee8b6a84-3bf7-4df9-a481-73ed2f336ec9","html_url":"https://github.com/gah-code/gatsby-theme-ui-template","commit_stats":null,"previous_names":["gah-code/gatsby-theme-ui-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gah-code/gatsby-theme-ui-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fgatsby-theme-ui-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fgatsby-theme-ui-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fgatsby-theme-ui-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fgatsby-theme-ui-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gah-code","download_url":"https://codeload.github.com/gah-code/gatsby-theme-ui-template/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gah-code%2Fgatsby-theme-ui-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32677928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T02:33:58.958Z","status":"ssl_error","status_checked_at":"2026-05-06T02:33:39.611Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["gatsby","mdx","theme-development","theme-switcher","ui","usecontext"],"created_at":"2024-12-13T05:06:14.894Z","updated_at":"2026-05-06T03:33:44.878Z","avatar_url":"https://github.com/gah-code.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Below is a more polished and cohesive `README.md` that incorporates your existing content, highlights the purpose of the project, and emphasizes mid-senior-level best practices. Feel free to tweak it further based on your specific needs or preferences.\n\n---\n\n# Gatsby Theme UI Template Starter 2025 Project\n\n[![Netlify Status](https://api.netlify.com/api/v1/badges/9ae06a33-c307-45b0-87ff-c6753251fc5b/deploy-status)](https://app.netlify.com/sites/gatsby-ui-theme/deploys)\n\n![Lighthouse Score](./src/images/lighthouse-score.png)\n\n## Overview\n\nThis project serves as a comprehensive **design system interface** built with **Gatsby**, **Theme UI**, and **MDX**. It is designed to streamline the creation of scalable, modern, and visually appealing web interfaces—particularly useful for mid-senior-level developers seeking insights into best practices and advanced implementation strategies.\n\nBy leveraging **Theme UI**’s robust API, we enable customizable and responsive UI components while ensuring seamless integration through Gatsby’s plugin ecosystem. This approach yields:\n\n- **High performance** via Gatsby's optimizations\n- **Visual consistency** through modular Theme UI configurations\n- **Maintainable architecture** that scales for larger teams and projects\n\nUltimately, this template provides a foundation for building design systems that are both **efficient** and **stylish**, aligning with current best practices in modern web development.\n\n---\n\n## Features\n\n- **Multi-Mode Color Themes**  \n  Supports Light, Dark, Purple, and Forest modes. Toggle between modes through a handy dropdown menu.\n\n- **Theme UI Integration**  \n  A modular theme structure with dedicated files for colors, typography, spacing, variants, and more—making future updates and expansions effortless.\n\n- **Syntax Highlighting**  \n  Powered by **Theme UI** and **@theme-ui/prism**. Easily customize syntax highlighting or use ready-made presets like Night Owl or Dracula.\n\n- **Component-Driven Architecture**  \n  Includes reusable components (e.g., `Layout`, `ColorModeToggle`) to ensure consistency and scalability in your projects.\n\n- **Showcase Page**  \n  Demonstrates usage of typography, buttons, forms, tables, and color variants—all defined in the theme.\n\n- **Testing Suite**  \n  Integrated with **Jest** and **Testing Library** to safeguard component integrity and functionality.\n\n---\n\n## Folder Structure\n\nBelow is a high-level look at the project’s folder organization:\n\n```plaintext\ngatsby-theme-ui-template/\n├── gatsby-config.js               # Configuration for Gatsby plugins\n├── gatsby-node.js                 # Handles dynamic page creation\n├── src/\n│   ├── pages/                     # Site pages\n│   │   ├── index.jsx              # Homepage\n│   │   ├── posts.jsx              # Post listing page\n│   │   ├── about.jsx              # About page\n│   │   ├── showcase.jsx           # Theme showcase page\n│   │   ├── 404.js                 # Custom 404 page\n│   │   ├── GridVariantsPage.jsx   # Grid layout examples\n│   │   ├── TypographyDemoPage.jsx # Typography showcase\n│   │   └── posts/                 # MDX blog posts\n│   │       ├── my-first-post.mdx\n│   │       ├── mdx-with-theme-ui.mdx\n│   │       ├── dynamic-heading-components.mdx\n│   │       ├── welcome-to-colorful-posts.mdx\n│   │       └── enhancing-dynamic-pages-with-seo-metadata-in-gatsby.mdx\n│\n│   ├── templates/                 # Page templates\n│   │   ├── using-dsg.js           # Deferred Static Generation example\n│   │   ├── post.jsx               # Single post template\n│   │   └── posts-page.jsx         # Post listing template\n│\n│   ├── components/                # Reusable components\n│   │   ├── header.jsx             # Main header component\n│   │   ├── ColorModeToggle.jsx    # Theme color mode toggle\n│   │   ├── variants.jsx           # Variant examples\n│   │   ├── ResponsiveTwoColumnGrid.jsx # Responsive grid layout\n│   │   ├── BreakpointShowcase.jsx # Debug breakpoints visually\n│   │   ├── seo.jsx                # SEO metadata component\n│   │   ├── demos/                 # Demo components\n│   │   │   └── demoOne.jsx\n│   │   ├── __tests__/             # Jest tests\n│   │   │   └── Layout.test.js\n│   │   ├── layout/                # Layout components\n│   │   │   ├── Layout.jsx\n│   │   │   ├── FlexLayout.jsx\n│   │   │   └── GlobalStyles.jsx\n│   │   ├── util/                  # Utility components\n│   │   │   ├── CodeBlock.jsx\n│   │   │   ├── Message.jsx\n│   │   │   ├── Paragraph.jsx\n│   │   │   ├── SectionBlock.jsx\n│   │   │   ├── Heading.js\n│   │   │   └── Section.jsx\n│   │   ├── ui/                    # UI-specific components\n│   │   │   ├── Header.jsx\n│   │   │   ├── Footer.jsx\n│   │   │   ├── Main.jsx\n│   │   │   ├── Navigation.jsx\n│   │   │   └── hero/\n│   │   │       └── InvertedBanner.js\n│\n│   ├── gatsby-plugin-theme-ui/    # Theme UI configuration\n│   │   ├── radii.js               # Border radii\n│   │   ├── typography.js          # Typography settings\n│   │   ├── colors.js              # Color palette\n│   │   ├── space.js               # Spacing scale\n│   │   ├── forms.js               # Form styles\n│   │   ├── syntax.js              # Syntax highlighting\n│   │   ├── styles.js              # Global styles\n│   │   ├── messages.js            # Message styles\n│   │   ├── text.js                # Text variants\n│   │   ├── buttons.js             # Button variants\n│   │   ├── variants.js            # Component variants\n│   │   └── index.js               # Main theme export\n│\n│   ├── styles/                    # Global CSS styles\n│   │   ├── global.css\n│   │   └── utils.css\n│\n│   ├── images/                    # Image assets\n│   │   ├── lighthouse-score.png\n│   │   ├── gatsby-icon.png\n│   │   └── example.png\n│\n│   ├── utils/                     # Utility scripts\n│   │   └── colorMode.js\n│\n│   ├── hooks/                     # Custom React hooks\n│   │   └── use-site-metadata.jsx\n├── ...\n```\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- **[Node.js](https://nodejs.org/)** (\u003e= 14.x)  \n- **[Gatsby CLI](https://www.gatsbyjs.com/docs/reference/gatsby-cli/)** (optional)\n\n### Installation\n\n1. **Clone the Repository**  \n\n   ```bash\n   git clone https://github.com/your-username/gatsby-theme-ui-starter.git\n   cd gatsby-theme-ui-starter\n   ```\n\n2. **Install Dependencies**  \n\n   ```bash\n   npm install\n   ```\n\n3. **Run the Development Server**  \n\n   ```bash\n   gatsby develop\n   ```\n\n4. **Open the Project**  \n   Navigate to **[http://localhost:8000](http://localhost:8000)** to see your site in action.\n\n---\n\n## Modular Theme Structure\n\nOur theme is broken down into independent files, each focusing on a specific aspect:\n\n1. **`colors.js`** – Defines color palettes and modes (Light, Dark, Purple, etc.).  \n2. **`typography.js`** – Configures fonts, sizes, weights, line heights.  \n3. **`space.js`** – Defines spacing scales for margins and paddings.  \n4. **`radii.js`** – Sets border radius styles (e.g., `default`, `circle`).  \n5. **`buttons.js`** – Defines button styles and variants (e.g., `primary`, `secondary`).  \n6. **`forms.js`** – Styles inputs, selects, and textareas.  \n7. **`text.js`** – Text variants for headings and displays.  \n8. **`variants.js`** – Generic component variants (e.g., `cards`, `badges`).  \n9. **`styles.js`** – Global styles for roots, headings, links, and more.  \n10. **`index.js`** – Combines everything into a single exportable theme object.\n\n---\n\n### Adding New Variants\n\nTo create a new button variant:\n\n1. Open **`src/gatsby-plugin-theme-ui/buttons.js`**.  \n2. Define your variant, for example:\n\n   ```js\n   const buttons = {\n     primary: { /* ... */ },\n     secondary: { /* ... */ },\n     tertiary: {\n       fontWeight: \"medium\",\n       color: \"text\",\n       bg: \"muted\",\n       \"\u0026:hover\": {\n         bg: \"highlight\",\n       },\n     },\n   };\n\n   export default buttons;\n   ```\n\n3. Use the variant in your JSX:\n\n   ```jsx\n   \u003cbutton sx={{ variant: \"buttons.tertiary\" }}\u003e\n     Tertiary Button\n   \u003c/button\u003e\n   ```\n\n---\n\n## Showcase Page\n\nExplore the **Showcase Page** at **[http://localhost:8000/showcase](http://localhost:8000/showcase)** to view live examples of:\n\n- Typography  \n- Buttons  \n- Forms  \n- Colors  \n- Tables  \n\n---\n\n## Testing\n\nThis project integrates **Jest** and **Testing Library** to verify the reliability of components. To run tests:\n\n```bash\nnpm test\n```\n\nYou can find an example test file in:\n\n```\nsrc/components/__tests__/Layout.test.js\n```\n\n---\n\n## Example Usage\n\nBelow are a few key files you might customize:\n\n- **`src/pages/posts.jsx`** – Main blog listing page  \n- **`src/templates/post.jsx`** – Single post template  \n- **`src/posts/mdx-with-theme-ui.mdx`** – Example MDX file demonstrating how to use Theme UI in posts\n\n### Customization\n\n- **`Layout.js`**  \n  Wraps all pages with consistent header, footer, and global styling.\n\n- **`ColorModeToggle.js`**  \n  A dropdown for switching between Light, Dark, Purple, and Forest modes.\n\n- **Global Styles**  \n  Located in `src/styles/global.css`, including resets and custom fonts.\n\n- **Utility Classes**  \n  Found in `src/styles/utils.css` for quick margin, padding, and text alignment helpers.\n\n---\n\n## Contributing\n\n1. **Fork** the repository  \n2. **Create** a new branch: `git checkout -b feature/new-feature`  \n3. **Commit** your changes: `git commit -m 'Add new feature'`  \n4. **Push** to the branch: `git push origin feature/new-feature`  \n5. **Open** a pull request\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).  \n**Created by Gilberto Alejandro Haro**\n\n---\n\n## Acknowledgments\n\n- [Gatsby](https://www.gatsbyjs.com/)  \n- [Theme UI](https://theme-ui.com/)  \n- [Testing Library](https://testing-library.com/)\n\n---\n\n## NEXT STEPS\n\n# 📖 Storybook Setup Guide\n\n## 🚀 Introduction\n\nThis guide outlines how to integrate **Storybook** into your **Gatsby + Theme UI** project, providing a structured approach to documenting and showcasing UI components, design tokens, and styling principles.\n\n## 📁 Recommended Folder Structure\n\n```\nmy-gatsby-theme-ui-project/\n├── .storybook/\n│   ├── main.js         # Storybook entry configuration\n│   ├── preview.js      # Global decorators, parameters, theming\n│   └── manager.js      # (optional) Custom Storybook UI\n│\n├── src/\n│   ├── components/\n│   │   ├── Button/\n│   │   │   ├── Button.jsx\n│   │   │   └── Button.stories.jsx\n│   │   ├── ColorModeToggle/\n│   │   │   ├── ColorModeToggle.jsx\n│   │   │   └── ColorModeToggle.stories.jsx\n│   │   ├── layout/\n│   │   │   └── FlexLayout.jsx\n│   │   ├── ui/\n│   │   │   └── InvertedBanner.js\n│   │   └── ...\n│   │\n│   └── stories/\n│       ├── Intro.stories.mdx         # Project introduction\n│       ├── Colors.stories.mdx        # Showcases brand colors \u0026 modes\n│       ├── Typography.stories.mdx    # Demonstrates text styles\n│       └── Tokens.stories.mdx        # Displays spacing, radii, etc.\n│\n├── src/gatsby-plugin-theme-ui/\n│   ├── index.js         # Main theme export\n│   ├── colors.js\n│   ├── typography.js\n│   ├── variants.js\n│   └── ...\n│\n├── package.json\n└── ...\n```\n\n## 🔧 Step-by-Step Setup\n\n### 1️⃣ Install and Initialize Storybook\n\n```sh\nnpx sb init\n# Or with Yarn:\nyarn dlx sb init\n```\n\n### 2️⃣ Configure `.storybook/main.js`\n\n```js\nmodule.exports = {\n  stories: [\n    \"../src/stories/**/*.stories.@(js|jsx|ts|tsx|mdx)\",\n    \"../src/components/**/*.stories.@(js|jsx|ts|tsx|mdx)\"\n  ],\n  addons: [\n    \"@storybook/addon-links\",\n    \"@storybook/addon-essentials\",\n  ],\n}\n```\n\n### 3️⃣ Configure `.storybook/preview.js`\n\n```js\nimport React from \"react\"\nimport { ThemeUIProvider } from \"theme-ui\"\nimport theme from \"../src/gatsby-plugin-theme-ui\"\n\nexport const decorators = [\n  (Story) =\u003e (\n    \u003cThemeUIProvider theme={theme}\u003e\n      \u003cStory /\u003e\n    \u003c/ThemeUIProvider\u003e\n  ),\n]\n\nexport const parameters = {\n  actions: { argTypesRegex: \"^on[A-Z].*\" },\n  controls: { expanded: true },\n}\n```\n\n### 4️⃣ Add Foundational Stories\n\n#### 🟣 `Colors.stories.mdx`\n\n```mdx\n# 🎨 Colors \u0026 Modes\n\n```jsx\nimport { Box, Text, useColorMode } from 'theme-ui';\n\nexport const ColorSwatches = () =\u003e {\n  const [colorMode, setColorMode] = useColorMode();\n\n  return (\n    \u003cBox\u003e\n      \u003cbutton onClick={() =\u003e setColorMode(colorMode === 'light' ? 'dark' : 'light')}\u003eToggle Mode\u003c/button\u003e\n      \u003cBox sx={{ display: 'grid', gridGap: 3 }}\u003e\n        {Object.entries(theme.colors).map(([name, value]) =\u003e (\n          typeof value === 'string' \u0026\u0026 (\n            \u003cBox key={name} sx={{ bg: value, p: 3 }}\u003e\n              \u003cText sx={{ color: 'background' }}\u003e{name}\u003c/Text\u003e\n            \u003c/Box\u003e\n          )\n        ))}\n      \u003c/Box\u003e\n    \u003c/Box\u003e\n  );\n};\n```\n\n#### 🔤 `Typography.stories.mdx`\n\n```mdx\n# 🔡 Typography\n\n```jsx\nimport { Box, Text } from 'theme-ui';\n\nexport const TypographyShowcase = () =\u003e (\n  \u003cBox\u003e\n    \u003ch1\u003eHeading H1\u003c/h1\u003e\n    \u003ch2\u003eHeading H2\u003c/h2\u003e\n    \u003cText sx={{ variant: 'paragraph' }}\u003eThis is a paragraph.\u003c/Text\u003e\n  \u003c/Box\u003e\n);\n```\n\n#### 🎛️ `Tokens.stories.mdx`\n\n```mdx\n# 🏗️ Design Tokens\n\n```jsx\nimport { Box, Text } from 'theme-ui';\n\nexport const Spacing = () =\u003e (\n  \u003cBox\u003e\n    {theme.space.map((val, i) =\u003e (\n      \u003cBox key={i}\u003e\n        \u003cText\u003eSpace {i}: {val}px\u003c/Text\u003e\n        \u003cBox sx={{ height: val, bg: 'muted' }} /\u003e\n      \u003c/Box\u003e\n    ))}\n  \u003c/Box\u003e\n);\n```\n\n### 5️⃣ Add Component Stories\n\n#### 🛑 `Button.stories.jsx`\n\n```js\nimport Button from \"./Button\"\n\nexport default {\n  title: \"Components/Button\",\n  component: Button,\n}\n\nconst Template = (args) =\u003e \u003cButton {...args} /\u003e\n\nexport const Primary = Template.bind({})\nPrimary.args = {\n  variant: \"primary\",\n  children: \"Primary Button\",\n}\n```\n\n### 6️⃣ Run Storybook\n\n```sh\nnpm run storybook\n# or\nyarn storybook\n```\n\nOpen [http://localhost:6006](http://localhost:6006) to view your Storybook.\n\n## 📌 Additional Enhancements\n\n- **MDX vs. JSX:** Use `.mdx` for documentation-like stories, `.stories.jsx` for prop-driven demos.\n- **Add-Ons:** Consider `storybook-addon-performance` for optimization.\n- **Theming:** Customize `.storybook/manager.js` for brand alignment.\n- **Deployment:** Run `npm run build-storybook` to generate a static build for Netlify/GitHub Pages.\n\n---\n\n### 🎉 Recap\n\n✅ Initialize Storybook with `sb init`  \n✅ Configure `.storybook` settings for Gatsby + Theme UI  \n✅ Create foundational stories (`Colors`, `Typography`, `Tokens`)  \n✅ Add component-specific stories (`Button`, `Toggle`, etc.)  \n✅ Run `npm run storybook` and enjoy your UI documentation!\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgah-code%2Fgatsby-theme-ui-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgah-code%2Fgatsby-theme-ui-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgah-code%2Fgatsby-theme-ui-template/lists"}