Surface is a custom Drupal theme which is compatible with Drupal 9 and 10. Surface is the default front-end theme for UCLA Health Sciences School of Medicine.
Surface is built using Storybook (HTML edition), and Vite (Vanilla JS edition), with the help of many NodeJS packages to improve automation and make use of the latest Front-End tooling. See package.json for specifics about packages being used.
There are several custom npm commands that allows developers to build and run different
tasks during and after development. These commands can be found in package.json.
The most common ones to use include:
npm run build: This is the command that builds all your local assets and builds your project. This should be the first command to be executed if you are building your project for the first time.
* `npm run watch`: This will run both `npm run vite:watch` and `npm run storybook:dev`. This is the most common command to run while working with Surface during development. Among the tasks the watch command runs, are: - Cleaning out the `dist` folder and compiling a fresh copy of all production code. - Linting (CSS and JS) files to ensure code standards are met. - Watching for changes to CSS, JS and Images and compiling them if needed. - Recrusively globbing through all CSS and JS files within the source directory.
>**NOTE**: Most tasks included in the watch command can be found in `vite.config.js`
* `npm run storybook:build`: This command will build a local/static instance of Storybook for production in your theme's `/storybook` directory. The `npm run build` command should be executed prior to the `storybook:build` command to ensure all required assets are available prior to building storybook.
Surface uses Storybook as its design system and that's where all components on the sites are originally built and maintained. Storybook can be accessed on its own by running npm run watch and navigating to http://localhost:6006.
Although Surface adheres to the Atomic Design methodology, it does not use the same naming conventions for naming its patterns. Our naming convention for the top level categories are:
- Elements - equivalent to Atoms
- Components - equivalent to Molecules
- Collections - equivalent to Organisms
- Layouts - equivalent to templates
- Pages - same
Surface is built using the latest development practices for CSS, JS, and Twig. Within Surface's Storybook, all components are built using BEM methodology for selector classes and ES6 for Javascript.
For a simple demonstration of how to build components in Storybook and integrate them with Drupal, we are sharing a couple of components we use on our projects. These components are:
- Breadcrum, Button, Date, Date badge, Eyebrow, Images, Readtime, Title
- Callout, Card, Featured card, Quote
Static Surface theme built with Storybook
For demo purposes, we have included Drupal template suggestions inside templates/, which also include examples of how a particular Drupal entity (i.e. content type) is integrated with a Storybook component.
For more information, see Drupal.org theming guide.
Surface was built with 🩵 by the good folks at UCLA Health.
For a walkthrough on how this project was built, along with other related goodies, take a look a the blog series by Mario Hernandez.