fourkitchens / emulsify-gatsby-theme-jam Goto Github PK

Components win. They’re the building blocks of UI. Everywhere you look, people are building component libraries and they’re using component based frameworks to build them. Working on a component library is hard work and ensuring an organization buys into your design system is even harder. Storybook has become the defacto "workshop" for components. However, it is not the appropriate tool for a organization's design system, which includes all sorts of other information and may only display a subset of the components in your library.

Emulsify is a customizable and themeable design system generator built with Gatsby. It reads your component library and builds a design system for you. Using MDX you can author custom documenation for each component and other helpful pages for your design system's audience.

Using a Gatsby Starter is the fastest way to get up-and-running.

• Twig Starter

• Create a directory for your design system.

mkdir my-design-system
cd my-design-system

• yarn init
• yarn add react react-dom gatsby gatsby-theme-emulsify
• Create a gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: "gatsby-theme-emulsify",
      options: {
        componentLibPath: 'components', // Where your component library lives
        docPagesPath: 'styleguide', // Where your custom styleguide pages live
        basePath: __dirname, // Needed to make above paths relative to your project
        designSystems: [
          {
            name: "Acme Corporation", // Other design system you may want to link to in a parent/child situation
            link: "https://acme-design-system.netlify.com"
          },
        ],
        // Site Metadata for style guide
        siteMetadata: {
          title: "B&E Security",
          description: "Your favorite security company",
          author: "B&E Security",
        }
      },
    },
  ],
}

• In your project root, create a components directory and add a directory for each component.
• Add your component and an adjacent .yml file that will be used to populate the data needed to render the component.
• In your project root, create a styleguide directory and inside it create a Components directory with an empty .md file in it. This is needed for placing links to each component in the sidebar.

---
title: "Components"
description: "This is the components section"
publishToStyleGuide: true
---

• You're now ready to start documenting your component library!

Create a Code.mdx file alongside one of your component.

Inside of Code.mdx, use the <Code />, <Component />, and/or <TableOfContents /> components in your MDX to fluidly author your docs and inline code snippets and rendered examples of your component.

---
title: "CTAs"
description: "Call To Action component for use on landing pages"
tab: "Code"
tabOrder: 1
publishToStyleGuide: true
---

<TableOfContents />

# This is a CTA

## Example

<Component />

## Source

<Code />

This file will be used to generate a "Code" tab on CTA component documentation. Create any number of tabs: "Style", "Usage", etc...

• <Code /> renders the source for you component with syntax highlighting
• <Component /> renders your component inline
• <TableOfContents /> renders a Table of Contents for the given page

In a styleguide directory in your component library root directory, you can create custom pages to be added to your design system.

Inside styleguide, create a directory called 1__Getting Started.

Inside 1__Getting Started create Welcome.md.

---
title: "Welcome"
description: "Welcome to the Acme Corporation design system"
publishToStyleGuide: true
---

# Welcome to the Acme Corporation design system!

This page will be automatically added to the menu bar in your design system.

The following design systems were build with Emulsify:

• https://my-design-system-emulsify.netlify.com/
• https://acme-design-system-emulsify.netlify.com/

• yarn inside yarn workspace root
• yarn workspace acme-design-system develop

• Theme UI integration
• Add React support
• Move Twig functionality to Gatsby plugin
• Clean up gatsby node to abstract language support
• Code tabs (tab per language loaded)
• Search