Building with Emulsify Drupal part 1: Storybook

Once you’ve successfully installed Emulsify and run the start command (yarn develop or npm run develop), one of the first things you’ll want to do is set up your style guide basics (colors, fonts, typography, layout, and variables). In this article, we’ll walk through each of these to establish a foundation for the components we’ll be building.

Color

One of the first things you see in Storybook is a nicely displayed color palette. Emulsify ships with a powerful color usage experience, including support for OS dark mode. To use this, first open components/00-base/01-colors/_00-colors-vars.scss and add/edit your color values. Once your color values are in place, add them into color usage variables in components/00-base/01-colors/_01-colors-used.scss, including dark mode values if your project will support that. If you add new color usage variables to this file, be sure to add them also to components/00-base/01-colors/colors.yml. Now, you will see your color palette in Storybook. To use these color usage variables, we have created a minimal color function that works like this:

body {
  background-color: clr(background);
  color: clr(text);
}

By using the color usage variables, there are a couple of benefits worth noting. The first is that your color palette will be kept separate from your usage. So, if your color palette changes, you only have to add/change the color value to components/00-base/01-colors/_00-colors-vars.scss and then set it to a usage value in components/00-base/01-colors/_01-colors-used.scss. Your application will then automatically use that color across all components. The second benefit is that Emulsify uses CSS custom properties (with a Sass fallback for older browsers), which makes supporting OS dark mode easy. You’ll notice the variables are already covered by the darkColors mixin in components/00-base/01-colors/_01-colors-used.scss. To use it anywhere else, simply use the following media query to add dark mode-specific styles:

@media (prefers-color-scheme: dark) {
  // your styles
}

Fonts

The next thing I like to do is set up fonts. In this example, we’ll be using a Typekit account but you can use anything you’d like. Assuming you’ve created a Typekit “kit,” you’ll need to do a couple of things: Add the CSS reference and your new font family stack. The CSS reference will need to be added in a couple of places. For Storybook, you can create .storybook/preview-head.html for any tags you would like to add to the HTML head (in fact, their README page covers adding Typekit) as follows:

<link rel="stylesheet" href="https://use.typekit.net/#######.css">

For Drupal, you can load the libraries as usual via the theme’s THEMENAME.libraries.yml file. If you are using the font(s) on all pages, you can just add it to the global library like in bold below:

global:
  css:
    theme:
      dist/style.css: {}
      //use.typekit.net/########.css: { external: true, minified: true }

As for the font stacks, some have already been defined in Emulsify in the default variables file (components/00-base/00-defaults/_01-variables.scss). Simply replace your $font-body and $font-heading variables with your new font values and you will see your new fonts in Storybook!

Customizing Storybook

One of the things I often like to do at this point is to quickly customize the Storybook instance for the project. You can do a number of things, but here’s a couple of quick changes to give it a nice project-specific feel. Storybook has built-in support for theming, and we apply our own theme that you can edit by default in Emulsify. Open up .storybook/emulsifyTheme.js and you will automatically see a place to load a custom logo, title, and brand URL to brand your Storybook experience. There are also a number of other variables available you can customize and tweak. 

Typography

For the site’s typography, you will find most of the files you will need for headings and text in the components/01-atoms/text directory. From there, you can go to headings/_headings.scss to set up both the mixins for all headings and the implementation for all headings inside wysiwyg areas. And inside text/_text.scss, you will find the same kind of mixins and implementation for your body copy as well as many other base-level text elements. By now, you have likely noticed we separate mixins into components whenever we can, but there is also a global mixins file (components/00-base/00-defaults/_03-mixins.scss) for those that need to be used across multiple components.

Layouts

Finally, we include a base-level layout structure (a simple grid system) that can be used inside components/03-organisms/grid. We’ve found that with modern CSS (flexbox, CSS grid) and component-driven development, the need for a third-party grid system has waned. That said, if you prefer to use one, you can of course use it within Emulsify. But for purposes of describing what Emulsify contains out of the box, let’s look at the default grid.

Inside the directory above, you’ll find a very flexible Flexbox grid component. Most of the magic happens in the grid item file (components/03-organisms/grid/_grid-item.scss). This is the simple code for creating a grid where the last item stretches to fill the width. Because Emulsify is a starter kit, these are meant to be tweaked to your project needs. We highly recommend creating a grid like this and reusing it where possible. For examples of this grid component being used, see components/03-organisms/grid/_grid-examples.twig. Although we will get into building higher-level components later, you can at least see in those components (and particularly their scss files) that we are just including our grid component and scss mixins—reusability at its best!

Coming up next

Now we’re getting to the good stuff: building our components! In upcoming posts, we’ll be covering editing and building some components and leveraging the ones we’ve covered here. Stay tuned!

Read more of the Building with Emulsify series:

• Building with Emulsify part 1: Storybook
• Building with Emulsify part 2: Callout component
• Building with Emulsify part 3: Component complexity
• Building with Emulsify part 4: Component grid