Quartz, a Drupal Starterkit based theme using Single Directory Components, Storybook, and PostCSS

This theme is for Drupal Single Directory Components which is now in Drupal 10.1 core. It also uses these contrib modules and other libraries. Most of front-end heavy lifting happens in the theme using a CL Server patch so that Storybook and CL server work entirely within the theme.

Specs

• Drupal 10.2.2
• Storybook v7.6.10
• Laravel Mix 6.0.49
• Node JS v18
• Docker 4.23.0 (120376) with VirtioFS and Kubernetes enabled
• Lando 3.20.8
• PHP 8.2
• MariaDB 10.3.27-MariaDB
• Composer 2.6.6

Key points

1. SDC templates are entity agnostic, so it's "bring your own content" from Drupal and map it to a an SDC template. So whether you are using custom blocks, Paragraphs, ECK, Nodes as Micro-content, or some other custom entity type the same SDC template will work for any of these.
2. Vanilla CSS with PostCSS for missing features via Laravel Mix, a wrapper for Webpack running inside Lando.
3. Storybook server for theming and component presentation independent of Drupal, also runs inside Lando.

Overview

1. quartz, a custom Starterkit theme which houses the components
2. Storybook, which makes theming a component easier as you do not need to connect it to data in Drupal
3. A Drupal / Storybook bridge via its NPM working inside Lando, "@lullabot/storybook-drupal-addon
4. Laravel Mix working inside Lando to compile CSS using PostCSS. web/themes/custom/quartz/webpack.mix.js This is more secure, more up to date, and faster than Gulp.

Get Started

1. Add this theme to a Drupal 10 Lando / composer based project
2. Read about the example files to get up and running with the correct Lando configs or use them as a guide for an existing project.
3. Once you are set with Lando and all other settings as per the above, from the root of the project, run lando start.
4. Use your existing site database or inititalize a new drupal site using the Lando command
5. Run lando drush uli - Make sure you can login as admin
6. Now map your own content to the Single Directory components. For examples of this, you can look at these templates, block--inline-block--accordion.html.twig and block--inline-block--accordion.html.twig. These map Drupal content to the SDC entity agnostic templates,accordion.twigand accordion-item.twig respectively.
7. Run lando storybook- This will start storybook in the theme and you can access it at http://localhost:9210/
8. Run lando watch - This will start Laravel Mix watching for CSS changes and stylelint the CSS at http://localhost:3000/

Debugging

It would be ideal to get up and running with Xdebug whether you are using PHPStorm or VS Code. You can also use {{ drupal_breakpoint() }} to use Xdebug inside twig templates which comes in handy when debugging components.

If you need more info on how to get up and running with Xdebug, see Lando's documentation for PHPStorm and VS Code.

Key contrib modules

1. Single Directory Components | Drupal.org Note, this is now in Drupal 10.1 core so no need to install this on its own anymore
2. Component Libraries: Theme Server - Lets you use component libraries, like Storybook, in your Drupal project, without Twig.js!
3. No Markup - Presents a custom field formatter to remove field markup which is crucial to keep component markup intact. This module us highly recommended for SDC work
4. Twig Tweak - Provides a Twig extension with some useful functions and filters that can improve development experience as well as allowing Xdebug to be used in Twig templates

NPMs

See web/themes/custom/quartz/package.json for a list of NPMs used on this project. Of note is Lullabot/storybook-drupal-addon: Storybook addon to facilitate integrating Storybook with Drupal projects. which connects Storybook to Drupal.

Issues of note

• CL server unable to render the stories when storybook not installed at root of Drupal Installation There is an MR open for this and composer has been updated to pull in the changes. This issue is still in progress so expect there to be changes. "drupal/cl_server": "dev-3369045-cl-server-unable",

Videos

• Single Directory Components in Core: Pittsburgh 2023 - YouTube
• Drupal: Converting a component to Single Directory Components (SDC) - YouTube
• Ignite Our Approach to Design Systems and Faster Site Building: Pittsburgh 2023 - YouTube
• Components as Site Building Tools

@TODO

• Update to using the Storybook module and get rid of CL Server
• Get storybook working in Lando.
• Get Laravel Mix working in Lando. This will replace gulp.
• Watch for Twig changes
• add a JS watch in webpack.mix.js.
• Create a theme composer.json file so it can be pulled in to other projects via Composer
• Create a theme config so that blocks are placed appropriately upon theme activation
• Create more components!
  • Button link modifiers and states
  • Card with modifiers
  • CTA modifiers
  • Hero (in process)