utcgilligan / particle

A starter kit for using the prototyping tool, Pattern Lab, in tandem with a Drupal theme. Utilizes Webpack for all asset management.

UTCWEB Particle: A design system integrating to Pattern Lab and a Drupal 8 theme

CheatSheet

Warning

1. the module and the submodule both have a master and develop branch.
2. if working on the git submodule don't update utccloud parent repo until you have commited changes. (data can be lost if you update utccloud while working on particle subtheme.
3. Only commit the changes on the parent git repo when you want utccloud to refer to the latest revision of the particle repo. In other words, it should be done once per PR to the main repo.

Setup

1. git submodule update --init --recursive -> the first time the submodule is added to your repo (on MacOS, linux handles this fine).
2. git submodule update --recursive -> after is beeing added once.
3. composer install and npm install -> if blt setup and sync have not been used.

Things to remember

1. gulp -> npm run dev:drupal
2. npm start -> starts the living stylesheet
3. ads run drush cr -> might be needed from time to time.

Particle: A design system integrating to Pattern Lab and a Drupal 8 theme

Particle is an opinionated set of tools and examples to:

1. Build an application-agnostic design system
2. Apply that design system to a locally-served Pattern Lab for rapid prototyping
3. Apply that design system to a Drupal theme

In depth documentation about frontend approach using this project at Phase2 Frontend Docs

Prerequisites

• Node ^8, ^10, ^12
• NPM ^5, ^6
• PHP ^7

Step-by-step instructions to install all dependencies for OSX can be found in this Gist.

Provides

• Drupal theme, Grav theme, and Pattern Lab app
• Strict Atomic Design component structure
• Webpack bundling of all CSS, javascript, font, and static image assets for multiple targets (Drupal theme, Grav theme, Pattern Lab)
• Webpack Dev Server for local hosting and hot reloading of assets into Pattern Lab
• Twig namespaced paths automatically added into Drupal theme and Pattern Lab config. Within any twig file, @atoms/thing.twig means the same thing to Drupal theme and Pattern Lab.
• Iconfont auto-generation
• Auto-linting against the AirBnB JavaScript Style Guide
• All Webpack files are fully configurable
• Simple Yeoman generator for Design System component creation

Quickstart

Particle builds design systems in dev mode for local hosting, or production mode for optimized asset generation.

Quickstart A

1. Simply run:

   npm create @phase2/particle particle

2. Then cd particle/ and run:

   npm start

Quickstart B

1. Download the latest release
2. Extract anywhere (i.e. this readme should be at any/where/particle/README.md)
3. Within the extracted folder run:

npm install
npm run setup
npm start

Simply wait until the webpack bundle output appears then visit http://0.0.0.0:8080/app-pl/pl/ (or http://localhost:8080/app-pl/pl/) and start working.

That's it. For much greater detail on the frontend approach using this project, check out the Phase2 Frontend Docs.

Design System Naming

The Design System Source folder is named default ./source/default. It's handy in multi-design setups to name this per design system and post-fix apps with that design system name. For example, apps/drupal-default/ contains the implementation of the default source directory. These are intended to be updated by the needs of your project. Test PR 2.0