Emulsify Gatsby Theme is an open-source style guide generator that builds a customizable documentation site from an existing component library and MDX-authored documentation. It is a Gatsby theme built by Four Kitchens, the agency behind Emulsify, and is designed to help organizations scale their design systems while reducing cost, streamlining workflows, and improving accessibility.
What is Emulsify Gatsby Theme?
Emulsify Gatsby Theme is a fully themeable style guide generator built on Gatsby. It takes your component library and documentation written in MDX as input and produces a static style guide website as output. The theme is part of the Emulsify open-source design system toolset, developed and maintained by Four Kitchens.
Key Features
- Gatsby-powered static generation — The theme runs on Gatsby, producing a fast, static style guide site that can be deployed anywhere.
- MDX documentation authoring — Write component documentation and any additional pages using MDX, which combines Markdown with JSX for interactive examples.
- Theme UI theming — Style the generated site with Theme UI, allowing full customization of colors, typography, and layout to match your brand.
- Component library integration — The generator reads your existing component library and builds style guide pages from it automatically.
- Open-source license — Emulsify is open-source and the theme repository is publicly available on GitHub.
- Production example — Western University of Pennsylvania uses this theme for their identity style guide, demonstrating real-world applicability.
Who is it for?
- Design system teams — Use it to create a central, searchable style guide that documents reusable components and design guidelines.
- Development teams building with Gatsby — Developers who already know Gatsby and MDX can quickly set up a style guide with minimal configuration.
- Organizations scaling design — The tool helps reduce cost and streamline workflows by providing a clear canonical reference for components, while also improving accessibility through documented guidelines.
What can you do with it?
- Author documentation: Use MDX to write custom doc pages for each component, including live examples and usage notes.
- Create a branded style guide: Customize the theme via Theme UI to match your organization's visual identity, as shown in the Western University of Pennsylvania example.
- Generate a static site: The Gatsby build process outputs a static site that can be hosted on any static host or content delivery network.
How does it work?
Install the theme in your Gatsby workspace, add your component documentation as MDX files, and run the Gatsby build to generate the style guide. For development, cloning the workspace and running yarn develop starts a local server at the example site. The documentation on docs.emulsify.info covers installation, documenting pages, and documenting components.
FAQ
Is Emulsify Gatsby theme free?
Yes, Emulsify is open-source, and the Gatsby theme is publicly available under an open-source license. You can clone the workspace, install dependencies with yarn, and run it locally.
What technology does it use?
It is built with Gatsby, MDX, and Theme UI. Gatsby handles static site generation, MDX lets you write JSX-powered documentation, and Theme UI provides the theming system.
How do I get started?
Clone the workspace repository and run yarn from the root to install dependencies. Use yarn develop to run the example site, then refer to the documentation for installation, documenting pages, and documenting components.
