Emulsify Drupal

Emulsify is an open-source toolset for creating and implementing design systems on your website

Storybook, Emulsify Core 4, and a Vite-based build workflow for Drupal 11.3+

Emulsify Drupal is the official Drupal parent theme for Emulsify. It provides a Storybook component library, Emulsify Core 4 tooling, and a Vite-based build workflow for Drupal 11.3+ with Drupal 12 forward compatibility. Until Drupal 12 beta or stable recommended-project releases are available, Drupal core development branch coverage is experimental.

The current 7.x series no longer depends on stable9; Emulsify now ships its own complete template layer instead of inheriting one from a Drupal parent theme.

Documentation

docs.emulsify.info

Quick Links

1. Installation
2. Usage
3. Upgrade guide
4. Twig component includes
5. Template override map
6. Favicon generation lifecycle
7. Optional design-token integration
8. Release readiness checklist

Demo

1. Storybook

How To

Generate a child theme

Emulsify Tools is required by the Emulsify Drupal parent theme. Use its Drush helper command to generate a child theme:

drush emulsify my_theme

The helper module also exposes the fully qualified command name:

drush emulsify_tools:bake my_theme

The whisk directory is the generation-only starterkit source used by both generation methods. Do not enable whisk directly; generated child themes keep emulsify as their runtime parent theme.

You can also generate the same child theme with Drupal core's standard Starterkit command from the root of your Drupal site:

php web/core/scripts/drupal generate-theme my_theme --starterkit whisk --path themes/custom

These generation methods should be treated as equivalent:

1. They generate the theme into web/themes/custom/my_theme.
2. They use the whisk starterkit source.
3. They keep emulsify as the runtime parent theme for the generated theme.
4. They preserve project.emulsify.json so Emulsify Core can identify the generated Drupal project structure.

After generation:

1. Enable the theme:

drush theme:enable my_theme -y
drush config:set system.theme default my_theme -y
drush cr -y

2. Install the generated theme's frontend dependencies:

cd web/themes/custom/my_theme
npm install

3. Start the generated theme's local tooling:

npm run develop

Generated child themes use the Vite build workflow and Emulsify Core 4 scripts shipped by the whisk starterkit source.

Write Twig component includes

For new project Twig, prefer Drupal Single Directory Component names:

{% include "my_theme:list" with {
  items: items,
} only %}

The Twig function form is also supported:

{{ include("my_theme:list", {
  items: items,
}, with_context = false) }}

Replace my_theme with the generated theme machine name. Legacy namespace includes such as {% include "@components/button/button.twig" %} are still valid for existing projects and migrations, but they are not the recommended default for new project components. See docs/twig-component-includes.md for the component include guidance.

Verify your generated child theme

Run these commands from the generated child theme directory, not from whisk:

cd web/themes/custom/my_theme
node --version
npm install
npm run build
npm run storybook-build
npm run test

Generated child themes require Node.js 24 or newer. Use npm install for the first local install, or npm ci when the generated child theme already has a committed package-lock.json.

These checks verify the expected local workflow:

1. node --version confirms the Node.js runtime satisfies the generated theme requirement.
2. npm install installs Emulsify Core 4 and the generated theme tooling.
3. npm run build compiles Drupal-facing assets with the Vite build workflow.
4. npm run storybook-build verifies the static Storybook build.
5. npm run test verifies the generated Jest setup. It passes when no project tests exist yet.

Optional browser-based accessibility check:

npm run a11y

npm run a11y builds Storybook and runs the Emulsify Core accessibility check. Use it in local or CI environments that can run the required browser-based tooling.

Manage generated favicon packages

The generated favicon workflow is built around one portable SVG source stored in theme settings.

Emulsify Drupal owns the theme-facing parts of that workflow: the theme settings form, config defaults and schema, admin previews, frontend head tags, generated asset references in <theme>.settings, and sanitized SVG storage for config portability.

1. Configure the package in the theme settings form for emulsify or a generated child theme.
2. Save the theme settings form to generate or update the package during normal admin changes.
3. Review package and portable-source diagnostics in the theme settings UI.

Emulsify Tools owns deployment-oriented Drush operations for those same settings. After configuration import or deploy, use the Emulsify Tools favicon commands to generate, inspect, or reset environment-local package files before public traffic reaches the environment. See the Emulsify Tools README for the full command documentation.

Runtime page requests never generate favicon files. If the configured package is missing, Emulsify skips favicon head tags until the theme settings form or the Emulsify Tools generate command creates the package.

Generated favicon packages require the PHP gd extension and the Imagick extension for SVG rasterization. If either extension is unavailable, the uploaded SVG can still be stored in configuration, but PNG and ICO package generation will fail until those extensions are installed.

The theme settings UI surfaces the current portable-source and package status. Portable SVG copies larger than 256 KB are flagged because very large config payloads are awkward to review and deploy.

See docs/favicon-generation.md for generated files, package location, generator limits, and deployment expectations.

Contributing

Code of Conduct

The project maintainers have adopted a Code of Conduct that we expect project participants to adhere to. Please read the full text so that you can understand what actions will and will not be tolerated.

Contribution Guide

Please also follow the issue template and pull request templates provided. See below for the correct places to post issues:

1. Emulsify Drupal
2. Emulsify Tools Drupal Module
3. Emulsify Twig Extensions

Committing Changes

To facilitate automatic semantic release versioning, we utilize the Conventional Changelog standard through Commitizen. Follow these steps when committing your work to ensure semantic release can version correctly.

1. Stage your changes, ensuring they encompass exactly what you wish to change, no more.
2. Create a Conventional Commit message, either manually or with your preferred commit helper.
3. Your commit message will be used to create the changelog for the next version that includes that commit.

Release Readiness

Run the release guard before merging packaging, starterkit, favicon settings, or release metadata changes, and before preparing a 7.x release:

npm run release:check

Use Node.js 24.10 or newer for local release tooling.

Use npm run release:check -- --skip-smoke when you only want the static metadata, README, duplicate-script, and schema checks. The static checks verify that favicon settings stay aligned across FaviconSettings::DEFAULTS, config/install/emulsify.settings.yml, and config/schema/emulsify.schema.yml.

Author

Emulsify® is a product of Four Kitchens — We make BIG websites.

Contributors

Brian Lewis 💻 📖	Randy Oest 💻 📖	Callin Mullaney 💻 📖	Patrick Coffey 💻 📖	Luke Herrington 💻 📖	Aaron Couch 💻 📖
Marc Berger 💻 📖	James Todd 💻 📖	Kurt Trowbridge 💻 📖	Chris Martin 💻 📖	Adam Erickson 💻 📖	Chris Runo 💻 📖
Andy Carlberg 💻 📖	eatsmarter-benny 💻 📖	Brian Perry 💻 📖	Israel Shmueli 💻 📖	John Karahalis 💻 📖	Mihaic100 💻 📖
Paul Sebborn 💻 📖

This project follows the all-contributors specification. Contributions of any kind welcome!