├── docs ├── appendix │ ├── glossary.md │ └── library.md ├── img │ ├── favicon.ico │ └── astrogoat.png ├── getting-started │ ├── system-requirements.md │ ├── commands.md │ └── quickstart.md ├── approach │ ├── js.md │ ├── twig.md │ ├── styles.md │ └── assets.md ├── faq │ ├── troubleshooting.md │ ├── how-to-contribute.md │ └── general.md ├── dev │ ├── coding.md │ ├── linting.md │ ├── task-running.md │ ├── testing.md │ └── bundling.md ├── apps │ ├── general.md │ ├── grav.md │ ├── pl.md │ └── drupal.md ├── architecture │ ├── config.md │ ├── components.md │ └── folders.md └── index.md ├── .gitignore ├── SUMMARY.md ├── README.md └── mkdocs.yml /docs/appendix/glossary.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | .idea 3 | build 4 | site -------------------------------------------------------------------------------- /SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Table of contents 2 | 3 | * [Initial page](README.md) 4 | 5 | -------------------------------------------------------------------------------- /docs/img/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/phase2/frontend-docs/master/docs/img/favicon.ico -------------------------------------------------------------------------------- /docs/img/astrogoat.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/phase2/frontend-docs/master/docs/img/astrogoat.png -------------------------------------------------------------------------------- /docs/getting-started/system-requirements.md: -------------------------------------------------------------------------------- 1 | ## Prerequisites 2 | 3 | - [Node `^8.0.0`](https://nodejs.org) 4 | - [PHP `5.6`, `^7.0.0`](https://php.net) 5 | - [Composer `^1.0.0`](https://getcomposer.org) -------------------------------------------------------------------------------- /docs/approach/js.md: -------------------------------------------------------------------------------- 1 | All javascript should be written in ES6 (ES2015) according to the [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript). Webpack will use Babel to transpile all javascript back to ES5 in emitted bundles. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Phase2's Front End Tooling Documentation (Particle & Friends) 2 | 3 | ## live docs available [here](https://phase2.github.io/frontend-docs/) 4 | 5 | ## to work on & edit locally: 6 | 7 | pip install mkdocs 8 | mkdocs serve 9 | 10 | # published with: 11 | 12 | mkdocs gh-deploy 13 | -------------------------------------------------------------------------------- /docs/faq/troubleshooting.md: -------------------------------------------------------------------------------- 1 | it's usually npm rebuild node-sass or a misplaced comma during a twig compile. 2 | 3 | sometimes it's linting rules, which can be disabled as needed. we recommend not doing that too often, though. they're enabled to help you! 4 | 5 | will fill this out more as more errors/pain points are found :( 6 | -------------------------------------------------------------------------------- /docs/dev/coding.md: -------------------------------------------------------------------------------- 1 | ### IDE/Text Editor Setup 2 | 3 | Install an [EditorConfig](http://editorconfig.org/) plugin for Particle coding conventions. 4 | 5 | - [VSCode](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) 6 | - [JetBrains (*Storm)](https://plugins.jetbrains.com/plugin/7294-editorconfig) 7 | - [Atom](https://github.com/sindresorhus/atom-editorconfig) 8 | - [Sublime Text](https://github.com/sindresorhus/editorconfig-sublime) -------------------------------------------------------------------------------- /docs/faq/how-to-contribute.md: -------------------------------------------------------------------------------- 1 | # Particle 2 | 3 | Pull Requests, bug reports, and the like on the [Particle repo](https://github.com/phase2/particle) are welcomed and encouraged. 4 | 5 | Please install an [EditorConfig plugin](/dev/coding/#idetext-editor-setup) to match coding conventions before opening PRs. 6 | 7 | # These docs 8 | 9 | Pull requests to the [Front End docs repo](https://github.com/phase2/frontend-docs) are welcomed and encouraged. If you are employed by Phase2, you can edit the files directly in github. Thanks! -------------------------------------------------------------------------------- /docs/faq/general.md: -------------------------------------------------------------------------------- 1 | # Why doesn't Particle support _? 2 | Particle is designed to be application-agnostic. If your application can use javascript and/or css, a Particle-built design system can be compiled for it. 3 | 4 | If you want Particle to include a specific app by default, pull requests welcome and encouraged! 5 | 6 | # I don't need _ app, how do I remove it? 7 | A couple files need to be adjusted. See [here](/apps/general/#adding-or-removing-apps) for the breakdown. 8 | 9 | # What's with the goat? 10 | It's cute right? 11 | -------------------------------------------------------------------------------- /docs/appendix/library.md: -------------------------------------------------------------------------------- 1 | # Technologies included 2 | + [Webpack](https://webpack.js.org/) 3 | + [Gulp](https://gulpjs.com/) 4 | + [Babel](https://babeljs.io/) 5 | + [Jest](https://facebook.github.io/jest/) 6 | + [Twig](https://twig.symfony.com/) 7 | + [Sass](https://sass-lang.com/) 8 | + [yo](https://github.com/yeoman/yo) 9 | + [Bootstrap](https://getbootstrap.com/) 10 | + [ESLint](https://eslint.org/) 11 | + [Stylelint](https://stylelint.io/) 12 | 13 | # Further Reading 14 | + [Pattern Lab](http://patternlab.io/) 15 | + [Atomic Design](http://bradfrost.com/blog/post/atomic-web-design/) -------------------------------------------------------------------------------- /docs/dev/linting.md: -------------------------------------------------------------------------------- 1 | "It's going to hurt your feelings." 2 | 3 | _Both linters can be disabled per-line/per-section/per-file if need be, check their respective docs for info._ 4 | 5 | # Javascript Linting 6 | Javascript linting generally follows the AirBnB standards, with some extras to help out Webpack and Jest. 7 | To make changes to the default rules, edit `.eslintrc.js` 8 | 9 | [eslint docs](http://eslint.org/docs/rules/) 10 | 11 | 12 | # Style Linting 13 | Sass linting defaults to Phase2's blend of sane house rules, but can be edited to whatever your project requires. 14 | To make changes to the default rules, edit `.stylelintrc` 15 | 16 | [stylelint docs](http://stylelint.io/user-guide/) 17 | -------------------------------------------------------------------------------- /docs/apps/general.md: -------------------------------------------------------------------------------- 1 | Particle features "apps" which simply consume the design system in `source/` and then present it according to their needs. 2 | 3 | ### Adding or Removing Apps 4 | 5 | Particle makes adding or removing apps a snap! By default Particle has a Pattern Lab installation, a Drupal theme, and a Grav theme included. But these can be added to, removed, or changed easily. If you'd like to make changes, see these pieces: 6 | 7 | * `module.exports` in `config.js` 8 | * Path imports in `gulpfile.js` 9 | * If the app is twig-based, `twigNamespaces` task in `gulpfile.js` 10 | * `dev` and `build` scripts in `package.json` 11 | * Add or delete App folder under `/apps` 12 | * Special: to remove Grav, delete `particle.yaml` 13 | -------------------------------------------------------------------------------- /docs/apps/grav.md: -------------------------------------------------------------------------------- 1 | 2 | `apps/grav/` 3 | 4 | Grav is a flat file CMS that uses Twig as a template engine. Learn more [here](https://learn.getgrav.org/). 5 | 6 | #### Grav integration of design system Twig files 7 | 8 | With the inclusion of the Grav plugin, [twig-namespaces](https://github.com/phase2/grav-pl-starter/tree/master/app/user/plugins/twig-namespaces), Grav Twig templates in `templates/` can `{% include %}`, `{% extends %}`, and `{% embed %}` the Twig patterns within `source/_patterns/`. Similar to Drupal above, including these patterns is done as follows: 9 | 10 | ```twig 11 | {% include "@organisms/path/to/file.twig" with { 12 | title: label, 13 | imageUrl: field_name.raw.path, 14 | largeCTA: true, 15 | } %} 16 | ``` 17 | 18 | Configuration for Grav and additional docs can found at `apps/grav/README.md`. 19 | -------------------------------------------------------------------------------- /docs/dev/task-running.md: -------------------------------------------------------------------------------- 1 | ### Gulp 2 | 3 | Gulp 4 is used to run a small set of tasks that can't be accomplished by Webpack alone. Examine `gulpfile.js` for all tasks available. Feel free to edit and add tasks to this file. 4 | 5 | Gulp 4 is used and the `npm run` commands above basically trigger gulp without having to install a global dependency. If you want to run specific gulp tasks, run `npm run gulp -- TASKNAME`. The `--` passes whatever comes after to the `gulp` command. Run `npm run gulp -- --tasks` to see the whole list, here's some examples of what you can do: 6 | 7 | - `npm run gulp -- --help` - See the help menu 8 | - `npm run gulp -- compile` - Compile Pattern Lab 9 | 10 | For more info on Gulp: 11 | 12 | - [Gulp 4 Docs](https://github.com/gulpjs/gulp/tree/4.0/docs) 13 | - [Gulp 4 Readme](https://github.com/gulpjs/gulp/blob/4.0/README.md) -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Particle Docs 2 | theme: readthedocs 3 | pages: 4 | - Home: 'index.md' 5 | - Getting Started: 6 | - System Requirements: 'getting-started/system-requirements.md' 7 | - Quickstart: 'getting-started/quickstart.md' 8 | - Commands: 'getting-started/commands.md' 9 | - Architecture: 10 | - Folder Structure: 'architecture/folders.md' 11 | - Component Structure: 'architecture/components.md' 12 | - Config Structure: 'architecture/config.md' 13 | - Development: 14 | - Coding: 'dev/coding.md' 15 | - Bundling: 'dev/bundling.md' 16 | - Task Running: 'dev/task-running.md' 17 | - Linting: 'dev/linting.md' 18 | - Testing: 'dev/testing.md' 19 | - Apps: 20 | - General: 'apps/general.md' 21 | - Drupal: 'apps/drupal.md' 22 | - Pattern Lab: 'apps/pl.md' 23 | - Grav: 'apps/grav.md' 24 | - Approach: 25 | - Sass/CSS: 'approach/styles.md' 26 | - Javascript: 'approach/js.md' 27 | - Twig: 'approach/twig.md' 28 | - Assets: 'approach/assets.md' 29 | - FAQ: 30 | - General: 'faq/general.md' 31 | - Troubleshooting: 'faq/troubleshooting.md' 32 | - How to contribute: 'faq/how-to-contribute.md' 33 | - Appendix: 34 | - Glossary: 'appendix/glossary.md' 35 | - Library: 'appendix/library.md' -------------------------------------------------------------------------------- /docs/approach/twig.md: -------------------------------------------------------------------------------- 1 | Most of the Design System lives in the source folders from `00-protons` to `03-organisms`. The next two folders in source are also part of the design system, but tend to get structured slightly differently than the rest here at Phase2. 2 | 3 | # Templates 4 | Templates are meant to be leaner. They may or may not be used explicitly by templates in Drupal and elsewhere, but they provide guidance for where classes need to be applied, and a reliable mock for Pattern Lab. 5 | 6 | # Pages 7 | Pages are treated purely as _demo_ patterns. They are used _solely_ by Pattern Lab to mock up working designs prior/in parallel to Drupal entities being constructed. They _use_ the template patterns for structure, and import their own demo images that are not included in the overall design system's dependency chain. You'll notice by default, there are no individual page "components", everything lives comfortably inside a /demo/ folder. 8 | 9 | This is one reason that the static PL bundle is so much larger than other production app bundles-- it explicitly includes the full demoPages item, as part of the demo glob inside of `apps/pl/index.js`. 10 | 11 | This split is the reason there are no demo folders inside of individual template components. Pages is a conglomeration of all template demos. 12 | -------------------------------------------------------------------------------- /docs/architecture/config.md: -------------------------------------------------------------------------------- 1 | ## Configuration 2 | 3 | A small `config.js` file at the root of the project provides basic path settings. Developers are encouraged to edit the Gulp and Webpack files directly to suit their needs. 4 | 5 | ## Webpack 6 | 7 | [Webpack](https://webpack.js.org/) does the heavy lifting of assets compilation and transformation. Webpack allows importing of Sass, images, fonts, and other assets into javascript files, bundling output files like CSS and javascript. Note the two webpack files at the root of the project: 8 | 9 | - `webpack.particle.dev.js`: Development settings shared amongst all consuming apps. 10 | - `webpack.particle.prod.js`: Production settings shared amongst all the consuming app. 11 | 12 | Each app features three webpack files. Take for example, the `pl` app: 13 | 14 | - `webpack.pl.shared.js`: Config shared by prod and dev 15 | - `webpack.pl.prod.js`: Production-only config merged over the top of `webpack.pl.shared.js` and `webpack.particle.prod.js` (from root) 16 | - `webpack.pl.dev.js`: Development-only config merged over the top of `webpack.pl.shared.js` and `webpack.particle.dev.js` (from root) 17 | 18 | You are encouraged to read through all three files to understand how assets are parsed and prepared. 19 | 20 | ## Drupal theme config 21 | 22 | The Drupal theme config is located at `apps/drupal`. Look for the usual `.info.yml`, `.libraries.yml`, and `.theme` files. 23 | 24 | ## Pattern Lab config 25 | 26 | The Pattern Lab config file is located at `apps/pl/pattern-lab/config/config.yml`. 27 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # What is Particle? 2 | [Particle](https://github.com/phase2/particle/) is an opinionated toolkit for building application-agnostic design systems built with love by [Phase2](https://www.phase2technology.com/). 3 | 4 | ![Particle Logo Astrogoat](img/astrogoat.png) 5 | 6 | Particle is an opinionated set of tools and examples to: 7 | 8 | 1. Build an application-agnostic **design system** of asset files like Twig, Sass, javascript, and images 9 | 1. Apply that design system to a locally-served **Pattern Lab** for rapid prototyping 10 | 1. Apply that design system to a **Drupal or Grav theme** 11 | 12 | ## Provides 13 | 14 | - Drupal theme, Grav theme, and Pattern Lab app 15 | - Strict [Atomic Design](http://atomicdesign.bradfrost.com/) component structure 16 | - Webpack bundling of all CSS, javascript, font, and static image assets for multiple targets (Drupal theme, Grav theme, Pattern Lab) 17 | - [Webpack Dev Server](https://github.com/webpack/webpack-dev-server) for local hosting and hot reloading of assets into Pattern Lab 18 | - [Twig namespaced paths](https://symfony.com/doc/current/templating/namespaced_paths.html) 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. 19 | - Iconfont auto-generation 20 | - Bootstrap 4 integration, used for all starting example components 21 | - Auto-linting against the [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript) and sane Sass standards 22 | - All Webpack and Gulp files are fully configurable 23 | -------------------------------------------------------------------------------- /docs/getting-started/commands.md: -------------------------------------------------------------------------------- 1 | Start up watches and a local server for Pattern Lab in dev mode. All assets will be served very fast from memory: 2 | 3 | ```bash 4 | npm start # An alias for npm run dev:pl 5 | ``` 6 | 7 | Start up watches and compile assets to disk for Drupal on changes (see above for enabling Drupal cache clears as part of this): 8 | 9 | ```bash 10 | npm run dev:drupal 11 | ``` 12 | 13 | Compile production assets for Pattern Lab (e.g. for a static file host): 14 | 15 | ```bash 16 | npm run build:pl 17 | ``` 18 | 19 | Compile production assets for Drupal 20 | 21 | ```bash 22 | npm run build:drupal 23 | ``` 24 | 25 | Compile production assets for Grav 26 | 27 | ```bash 28 | npm run build:grav 29 | ``` 30 | 31 | Reinstall and setup Pattern Lab 32 | 33 | ```bash 34 | npm run setup 35 | ``` 36 | 37 | Run all linters: 38 | 39 | ```bash 40 | npm run lint 41 | ``` 42 | 43 | Run only Javascript linters: 44 | 45 | ```bash 46 | npm run lint:js 47 | ``` 48 | 49 | Run only Sass linters: 50 | 51 | ```bash 52 | npm run lint:scss 53 | ``` 54 | 55 | Run all tests: 56 | 57 | ```bash 58 | npm test 59 | ``` 60 | 61 | Run only unit test: 62 | 63 | ```bash 64 | npm run test:unit 65 | ``` 66 | 67 | Run only pa11y accessibility tests: 68 | 69 | ```bash 70 | npm run test:pa11y 71 | ``` 72 | 73 | Run Yeoman generator to make new component: 74 | 75 | ```bash 76 | npm run new 77 | ``` 78 | 79 | Run any Gulp task: 80 | 81 | ```bash 82 | # See gulpfile.js for gulp tasks 83 | npm run gulp -- gulpTaskName 84 | # For instance, running a full Pattern Lab compile 85 | npm run gulp -- compile 86 | ``` -------------------------------------------------------------------------------- /docs/apps/pl.md: -------------------------------------------------------------------------------- 1 | `apps/pl/` 2 | 3 | Refer to the [Pattern Lab Documentation](http://patternlab.io/docs) for extensive info on how to use it. Particle is a custom Pattern Lab 2 *Edition* that is heavily influenced by the [Drupal Edition of Pattern Lab](https://github.com/pattern-lab/edition-php-drupal-standard) and uses the Twig engine to bring it inline with Drupal 8's use of Twig. 4 | 5 | The `app/pl` folder simply imports the design system from `source/` and provides its own custom Sass for UI and json generation. Any Twig files that change in `source/` cause a full Pattern Lab rebuild. The Pattern Lab engine and config lives within `apps/pl/pattern-lab`. 6 | 7 | #### `Faker` data in Pattern Lab 8 | 9 | [`Faker`](https://github.com/fzaninotto/Faker) generates fake data and the [Faker plugin for Pattern Lab](https://github.com/pattern-lab/plugin-php-faker) is used here. This generates *different* fake content for each compile, and allows [translated content](https://github.com/pattern-lab/plugin-php-faker#locales) as well. 10 | 11 | **Faker only works in the global data files** found in `source/_data/` currently until [this bug](https://github.com/pattern-lab/plugin-php-faker/issues/2) is fixed. 12 | 13 | Use it like this in `source/_data/data.json`: 14 | 15 | ```json 16 | { 17 | "description": "Faker.paragraph", 18 | "text": "Faker.words(3, true)", 19 | "byline": "Faker.sentence", 20 | "intro": "Faker.sentences(2, true)" 21 | } 22 | ``` 23 | 24 | The formatters (things like `.paragraph`, `.words`, etc) can accept options, when you see `Faker.words(3, true)` that means give me 3 random words and I'd like them as a string and not an array of strings. All the [formatters and their options are documented here](https://github.com/fzaninotto/Faker#formatters) - there's tons: numbers, address, names, dates, and more. 25 | -------------------------------------------------------------------------------- /docs/apps/drupal.md: -------------------------------------------------------------------------------- 1 | 2 | `apps/drupal/` 3 | 4 | (REVAMP) - templates/ - Drupal twig templates. These often will `include`, `embed`, or `extend` the Twig templates found in Pattern Lab like this: `{% include "@molecules/branding/branding.twig" with { url: path('') } %}`. We keep the components in Pattern Lab "pure" and ignorant of Drupal's data model and use these templates to map the data between the two. Think of these as the Presenter templates in the [Model View Presenter](https://en.wikipedia.org/wiki/Model–view–presenter) approach. Also, Drupal Twig templates that have nothing to do with Pattern Lab go here. 5 | 6 | ## Drupal integration of design system Twig files 7 | 8 | Drupal Twig templates in `templates/` can `{% include %}`, `{% extends %}`, and `{% embed %}` the Twig patterns within `source/_patterns/`. See the [Atomic Design and Namespaces](#atomic-design-and-namespaces) section above for details, but implementing, say, an organism is pretty straightforward: 9 | 10 | ```twig 11 | {% include "@organisms/path/to/file.twig" with { 12 | title: label, 13 | imageUrl: field_name.raw.path, 14 | largeCTA: true, 15 | } %} 16 | ``` 17 | 18 | (Note: update this) For a demonstration in a sample codebase of how exactly to integrate templates, see the [`drupal-lab`](https://github.com/phase2/drupal-lab) repo; in particular note how both a [node teaser template](https://github.com/phase2/drupal-lab/blob/master/web/themes/dashing/templates/content/node--article--teaser.html.twig) and a [views field template](https://github.com/phase2/drupal-lab/blob/master/web/themes/dashing/templates/views/views-view-fields--newspage--page.html.twig) in the Drupal `templates/` folder can embed the [card template](https://github.com/phase2/drupal-lab/blob/master/web/themes/dashing/pattern-lab/source/_patterns/02-molecules/cards/card.twig) from Pattern Lab while formatting the data. 19 | -------------------------------------------------------------------------------- /docs/approach/styles.md: -------------------------------------------------------------------------------- 1 | ## Sass 2 | 3 | Particle makes a very clear distinction between *printing* and *non-printing* Sass in components. 4 | 5 | > Printing Sass generates actual, rendered CSS output. 6 | 7 | This results in rendered CSS: 8 | 9 | ```scss 10 | .thing { 11 | background: blue; 12 | } 13 | ``` 14 | 15 | > Non-printing Sass results in no CSS 16 | 17 | This won't output any CSS: 18 | 19 | ```scss 20 | $rando-var: 33px; 21 | @mixin doThing() { 22 | background: blue; 23 | } 24 | ``` 25 | 26 | There is a distinct role for each in the component system of Particle. In the `button` component featured above in [Anatomy of a Component](/architecture/components/#anatomy-of-a-component), note this import: 27 | 28 | ```javascript 29 | // source/_patterns/01-atoms/button/_index.js 30 | ... 31 | import './_button.scss'; 32 | ... 33 | 34 | ``` 35 | 36 | Looking into `source/_patterns/01-atoms/button/_button.scss` reveals: 37 | 38 | ```scss 39 | @import '../../00-protons/config'; // DOES NOT OUTPUT CSS! 40 | 41 | $btn-border-radius: 0.25rem; 42 | @import "~bootstrap/scss/buttons"; // OUTPUTS CSS! 43 | 44 | .custom-class { 45 | color: red; // OUTPUTS CSS! 46 | } 47 | ``` 48 | 49 | This approach to component styes allows sharing non-printing Sass **configuration**, while also ensuring our component prints its custom CSS exactly once. We can now safely `@import 'atoms/button;` anywhere in our other javascript components as many times as needed and there will be no duplicate CSS output for buttons! 50 | 51 | 52 | 53 | # BEM 54 | This is not enforced, because it would be hellish to lint for... but we strongly encourage the use of [BEM syntax](http://getbem.com/introduction/) for your markup and stylesheets. 55 | 56 | # Style Rules 57 | Our in-house code style rules are designed for readability and avoiding [specificity wars](http://www.standardista.com/css3/css-specificity/) as much as possible. -------------------------------------------------------------------------------- /docs/approach/assets.md: -------------------------------------------------------------------------------- 1 | ### Font Icons 2 | 3 | Useful for small, frequently used icons that are a single color which is changeable via CSS. 4 | 5 | 1. Place `filename.svg` in `source/_patterns/01-atoms/icon/svg/` 6 | 1. Start up active server with `npm start` or compile via `npm run compile:pl|drupal` 7 | 1. View new font icon demo page in Pattern Lab at [Atoms > Icon > Icons](http://localhost:8080/pl/?p=atoms-icons) 8 | 1. Use either way: 9 | - HTML class: `icon--filename` 10 | - Sass Mixin: `@include icon(filename)` 11 | 12 | > IMPORTANT: Font icons are only compiled at the start of a webpack build. The webpack dev server will have to be restarted to see new icons appear in the font. 13 | 14 | #### Inline SVG 15 | 16 | Useful for larger, less frequently used vector images that potentially could be multi-color or able to animate. 17 | 18 | 1. Place `file.svg` within a namespaced folder, like `source/_patterns/01-atoms/icon/svg/`. 19 | 1. Use the special `_svg.twig` pattern to inline it completely. For instance, using the path in step 1, include it like so: 20 | ```twig 21 | {% include '@atoms/image/_svg.twig' with { 22 | svgpath: '@atoms/icon/svg/file.svg', 23 | } %} 24 | ``` 25 | 1. OR just use the [`source`](https://twig.symfony.com/doc/2.x/functions/source.html) function provided by Twig: `{{ source('@atoms/icon/svg/file.svg') }}` 26 | 27 | ### Static images 28 | 29 | If your component uses a static image and you need it to be available for the final bundled output, you **must** import it in the dependency chain. In your component's `index.js`, remember to `@import 'path/to/static-image.png';`! A component should import _every_ asset that it uses. This ensures that webpack bundles all necessary production assets into the correct location in the dist folder, and correctly lines up the filepaths. 30 | 31 | 32 | This is also how demo patterns consumed by Pattern Lab get any local static images. Importing images in `a-component/demo/index.js` will ensure that they are available for Pattern Lab's demo without junking up the overall production bundle. See `source/_patterns/01-atoms/image/demo/index.js` for an example. 33 | -------------------------------------------------------------------------------- /docs/dev/testing.md: -------------------------------------------------------------------------------- 1 | Particle provides the starting point for various types of testing. Tests are located under the tools directory: 2 | 3 | # ./particle/ 4 | . 5 | ├── tools/ 6 | │ ├── tasks/ 7 | │ └── tests/ 8 | │ │ └── accessibility/ 9 | │ │ └── unit/ 10 | │ │ └── vrt/ 11 | │ └── ... 12 | └── ... 13 | 14 | 15 | 16 | ### Unit Testing 17 | 18 | Particle provides unit testing using [Jest](https://facebook.github.io/jest/docs/en/tutorial-jquery.html). 19 | 20 | Simply run the following to run Jest tests against the design system: 21 | 22 | ```js 23 | npm run test:unit 24 | ``` 25 | 26 | Note the `__tests__` folders within components for examples. 27 | 28 | When using the new component generator (`npm run new`), a basic test will be generated for you. This initial test checks that it is correctly registered in the design system. 29 | 30 | ### Accessibility Testing 31 | 32 | To run [pa11y](http://pa11y.org/) accessibility testing on Pattern Lab rendered output, first you'll need to install the pa11y npm package: 33 | 34 | ```bash 35 | npm install pa11y 36 | ``` 37 | 38 | To save these devDependencies to your project *permanently*, run the following instead: 39 | 40 | ```bash 41 | npm install pa11y --save-dev 42 | ``` 43 | 44 | Then whenever you want to run your tests, simply start the local Pattern Lab dev server in one session: 45 | 46 | ```bash 47 | npm run start 48 | ``` 49 | 50 | And the kick off the pa11y tests in another session: 51 | 52 | ```bash 53 | npm run test:pa11y 54 | ``` 55 | 56 | See `./tools/pa11y.js` for configuration [options](https://github.com/pa11y/pa11y/tree/5.x#configuration). Note the ignore options are for example only, add your needed updates to the options object. Add additional pages to the test via the `testPaths` array. 57 | 58 | ```js 59 | const options = { 60 | standard: 'WCAG2AAA', 61 | ignore: [ 62 | 'WCAG2AAA.Principle3.Guideline3_1.3_1_1.H57.2', 63 | ], 64 | log: { 65 | debug: console.log, 66 | error: console.error, 67 | info: console.log, 68 | }, 69 | }; 70 | ``` 71 | 72 | ### Visual Regression Testing 73 | 74 | Particle does not include VRT out of the box, but there are plenty of great options out there depending on your needs. 75 | Here are some of our favorites, in alphabetical order: 76 | 77 | + [BackstopJS](https://github.com/garris/BackstopJS) 78 | + [PhantomJS](https://github.com/ariya/phantomjs) 79 | + [Puppeteer](https://github.com/GoogleChrome/puppeteer) 80 | + [SlimerJS](https://github.com/laurentj/slimerjs) 81 | + [WebdriverIO](http://webdriver.io/) 82 | -------------------------------------------------------------------------------- /docs/architecture/components.md: -------------------------------------------------------------------------------- 1 | ## Generating a Component 2 | 3 | Components have a specific file structure. Instead of making a developer create all required files by hand, we use a [Yeoman](http://yeoman.io/) generator to easily create new component folders. Simply run: 4 | 5 | ```bash 6 | npm run new 7 | ``` 8 | 9 | Follow the onscreen prompts for the location, included files, and name of the new component. **Then make sure you edit `source/design-system.js` and add your new component.** 10 | 11 | ## Anatomy of a Component 12 | 13 | All components require a set of files: 14 | 15 | # ./source/_patterns/01-atoms/button/ 16 | . 17 | ├── __tests__ # Jest unit tests. Read automatically during `npm run test:unit` 18 | │ └── button.test.js # Unit test JS functions. Limited DOM manipulation 19 | ├── demo # Demo implementations, can be removed on deploy to prod 20 | │ ├── index.js # Pulls in twig, yaml, md inside demo/ so webpack is aware 21 | │ ├── buttons.md # Markdown with extra notes, visible in PL UI 22 | │ ├── buttons.twig # Demonstrate with a plural name, visible to PL since no underscore 23 | │ └── buttons.yml # Data provided to the demo pattern 24 | ├── _button.scss # Most components require styles, underscore required 25 | ├── _button.twig # The pure component template, "_" required to hide from PL UI 26 | └── index.js # Component entry point 27 | 28 | With the power of [Webpack](https://webpack.js.org/), all static assets a component needs are `import`ed right into the `index.js` **entry point** alongside the javascript methods: 29 | 30 | ```javascript 31 | // source/_patterns/01-atoms/button/index.js 32 | 33 | // Import *EVERY* NPM dependency. 34 | import $ from 'jquery'; 35 | // Import specific plugins this component may need 36 | import 'bootstrap/js/src/button'; 37 | 38 | // source/_patterns/01-atoms/00-protons/index.js 39 | import 'protons'; 40 | 41 | // Module template. Changes to this file trigger a PL rebuild 42 | import './_button.twig'; 43 | 44 | // Import local Sass (which in turn imports Bootstrap Sass) 45 | import './_button.scss'; 46 | 47 | // Requirement 1 of a component: name 48 | export const name = 'button'; 49 | 50 | // Requirement 2 of a component: disable function 51 | export function disable() {} 52 | 53 | // Requirement 3 of a component: enable function. `$context` is `$(document)` in PL, and `context` in Drupal 54 | export function enable($context) { 55 | 56 | // `.button()` is only available because of `import 'bootstrap/js/src/button';` above 57 | $('#blah', $context).button('toggle'); 58 | } 59 | 60 | // Req. 4 of a component: default export is the enable function 61 | export default enable; 62 | ``` 63 | -------------------------------------------------------------------------------- /docs/getting-started/quickstart.md: -------------------------------------------------------------------------------- 1 | Particle builds design systems in dev mode for local hosting, or production mode for optimized asset generation. 2 | 3 | ## Quickstart anywhere 4 | 5 | 1. [Download the latest release](https://github.com/phase2/particle/releases) 6 | 1. Extract anywhere (i.e. the readme should be at `any/where/particle/README.md`) 7 | 1. Within the extracted folder run: 8 | 9 | ```bash 10 | npm install 11 | npm run setup 12 | npm start 13 | ``` 14 | 15 | Simply wait until the webpack bundle output appears then visit [http://0.0.0.0:8080/pl](http://0.0.0.0:8080/pl) (or [http://localhost:8080/pl](http://localhost:8080/pl)) and start working. 16 | 17 | ## Quickstart with Drupal 8 18 | 19 | Particle provides a Drupal 8 theme, the starting steps are slightly different: 20 | 21 | 1. [Download the latest release](https://github.com/phase2/particle/releases) 22 | 1. Extract to `themes/` at the root of your Drupal 8 install. (i.e. this readme should be at `{drupal-root}/themes/particle/README.md`) 23 | 1. Download and install the [Component Libraries module](https://www.drupal.org/project/components): 24 | 25 | ``` 26 | drush dl components 27 | drush en components -y 28 | ``` 29 | 30 | or 31 | 32 | ``` 33 | drupal module:install components 34 | ``` 35 | 36 | 1. Within `{drupal-root}/themes/particle/` run: 37 | 38 | ```bash 39 | npm install 40 | npm run setup 41 | npm run build:drupal 42 | ``` 43 | 44 | This will compile all assets and provide all namespaced Twig paths to the Drupal theme. Make sure to choose this theme in Drupal Appearance settings and `drush cr ` or `drupal cr all` to clear cache. 45 | 46 | For rapid, development-mode recompile and Drupal cache clear, edit `webpack.drupal.dev.js`, find the `onBuildEnd` plugin and edit it from: 47 | 48 | ```js 49 | // ORIGINAL 50 | plugins: [ 51 | new WebpackShellPlugin({ 52 | onBuildEnd: [ 53 | // CHANGE THE FOLLOWING LINE 54 | 'echo \nWebpack drupal dev build complete! Edit apps/drupal/webpack.drupal.dev.js to replace this line with `drupal cr all` now.', 55 | ], 56 | dev: false, // Runs on EVERY rebuild 57 | }), 58 | ], 59 | ``` 60 | 61 | to: 62 | 63 | ```js 64 | // UPDATED 65 | plugins: [ 66 | new WebpackShellPlugin({ 67 | onBuildEnd: [ 68 | 'drupal cr all', 69 | ], 70 | dev: false, // Runs on EVERY rebuild 71 | }), 72 | ], 73 | ``` 74 | 75 | Now you have active Drupal development-mode compilation and cache clearing by just running: 76 | 77 | ```bash 78 | npm run dev:drupal 79 | ``` 80 | 81 | You can still work in Pattern Lab while also working in Drupal by also running in another terminal: 82 | 83 | ```bash 84 | npm start 85 | ``` 86 | 87 | Just like in the regular Quickstart, when Webpack output appears, visit [http://0.0.0.0/pl](http://0.0.0.0/pl) (or [http://localhost/pl](http://localhost/pl)) to immediately start building and previewing your design system in Pattern Lab. 88 | -------------------------------------------------------------------------------- /docs/dev/bundling.md: -------------------------------------------------------------------------------- 1 | ## Assets 2 | 3 | Assets are "static" files that make up all clientside applications. Examples of static assets are: 4 | 5 | - CSS 6 | - Javascript bundles 7 | - .map files for debugging CSS and Javascript 8 | - Font files 9 | - JPEG, PNG, GIF, and SVG images 10 | - favicons 11 | 12 | > Assets are compiled to the dist/ folder if they are `@import`'d in some file within the dependency chain of your app. Only files within dist/ are available to be served to your apps. 13 | 14 | We include .twig files on the dependency chain to assist webpack's file watching. 15 | 16 | ### "Dependency Chain" 17 | 18 | Particle takes a modern approach to asset management through Webpack. Instead of files spread around a project that have to be referenced individually on the client side, apps now have entry point javascript files that `@import` dependencies that `@import` dependencies that `@import` dependencies and so on. 19 | 20 | Using Webpack to **[bundle](https://webpack.js.org/guides/getting-started/#creating-a-bundle)** this dependency chain up into as few output files as possible to the `dist/` directory means we have a `source/` (and `apps/`) folder that is structured the way we want to work, with a consistent output. 21 | 22 | Consider this dependency chain for the `apps/pl` app: 23 | 24 | <- @protons 25 | <- jquery 26 | <- bootstrap/src/js/buttons 27 | <- @atoms/button <- _button.scss 28 | <- @protons 29 | <- jquery 30 | <- bootstrap/src/js/cards 31 | apps/pl <- source/design-system <- @molecules/card <- _card.scss 32 | <- @protons 33 | <- bootstrap/src/js/jumbotron 34 | <- @organisms/header <- _header.scss 35 | 36 | 37 | 38 | Even though `@protons` and `jquery` are included multiple times, webpack removes this duplication as it treeshakes for the compiled bundle. The amount of common chunks and vendor-only bundles generated can be configured in the root `webpack.particle.*.js` configs. 39 | 40 | ### Webpack dev server 41 | 42 | Running `npm start` compiles Pattern Lab, then starts a *hot reloading* webpack dev server, then injects assets into the Pattern Lab. All static html files generated by Pattern Lab will be served at [http://0.0.0.0/pl](http://0.0.0.0/pl) and all modifications to assets on the dependency chain will be automatically injected into the browser. This means that you can work on Sass and javascript, the bundle will recompile, and the browser will reload rapidly. 43 | 44 | Dev server config can be found inside of `particle/apps/pl/webpack.pl.dev.js` 45 | -------------------------------------------------------------------------------- /docs/architecture/folders.md: -------------------------------------------------------------------------------- 1 | # Structure 2 | 3 | The following are significant items at the root level: 4 | 5 | # ./ 6 | . 7 | ├── apps # Things that use the compiled design system. Drupal theme & PL 8 | ├── dist # Bundled output: CSS, js, images, app artifacts (like PL html) 9 | ├── source # The design system. All assets compiled to dist/ 10 | ├── tools # Gulp plugins and node tools 11 | ├── gulpfile.js # Defines the few tasks required in the workflow 12 | ├── webpack.particle.dev.js # Shared bundle configuration for all dev entry points 13 | ├── webpack.particle.prod.js # Shared bundle configuration for all prod entry points 14 | └── ... # Mostly just config 15 | 16 | # Source structure 17 | `source/` holds all assets for the design system and looks like this: 18 | 19 | # ./source/ 20 | . 21 | ├── _patterns # All assets live within an Atomic "pattern" 22 | │ ├── 01-atoms # Twig namespace: @atoms, JS/Sass namespace: atoms 23 | │ │ ├── button # For instance, the button atom 24 | │ │ │ ├── __tests__ # Jest javascript unit tests 25 | │ │ │ ├── demo # Patterns feature a demo folder to show implementation 26 | │ │ │ │ ├── index.js # Pulls in twig, yaml, md inside demo/ so webpack is aware 27 | │ │ │ │ ├── buttons.twig # Demonstrate with a plural name, visible to PL since no underscore 28 | │ │ │ │ └── buttons.yml # Data provided to the demo pattern 29 | │ │ │ ├── _button.scss # Most components require styles, underscore required 30 | │ │ │ ├── _button.twig # The pure component template, underscore required 31 | │ │ │ └── index.js # Component entry point (See "Anatomy of a Component below) 32 | │ │ └── ... # Other @atoms 33 | │ └── ... # @protons, @atoms, @molecules, @organisms, @templates, @pages 34 | └── design-system.js # The ultimate importer/exporter of the design system pieces 35 | 36 | >The design system is *consumed by* "apps". The three apps included are a Drupal theme, Grav theme, and a Pattern Lab installation. 37 | 38 | # App structure 39 | `apps/pl/` holds the *entry point* for all Pattern Lab assets, as well as the PHP engine: 40 | 41 | # ./app/pl/ 42 | . 43 | ├── pattern-lab/ # Holds the Pattern Lab installation 44 | │ ├── ... # composer.json, config, console php, ... 45 | ├── scss # PL-only Sass; styles that shoudln't junk up the design system 46 | │ ├── _scss2json.scss # Output certain Sass variables into json for demo in PL 47 | │ └── _styleguide.scss # Custom PL UI styles 48 | ├── demo # Holds things related to just "demos" for the design system 49 | │ └── demos.glob # Special file used by webpack to "glob" all demos within source/ 50 | ├── webpack.pl.shared.js # Webpack config shared between PL dev and PL prod 51 | ├── webpack.pl.dev.js # Webpack config unique to dev, or that overrides shared 52 | ├── webpack.pl.prod.js # Webpack config unique to prod, or that overrides shared 53 | └── index.js # Imports and applies the design system to a bundle for PL 54 | 55 | `apps/drupal/` holds the *entry point* for all Drupal 8 theme assets, as well as templates, yml, etc: 56 | 57 | # ./app/drupal/ 58 | . 59 | ├── scss/ # Theme-only Sass, tweaks to Drupalisms that need not be in the DS 60 | │ └── _drupal-styles.scss # Add more drupal styles here, like _views.scss, _field.scss etc 61 | ├── templates # Templates integrate Drupal data with design system patterns 62 | │ ├── block.html.twig # Example Drupal template integrating, say @molecules/_card.twig 63 | │ └── ... # There wil be many Drupal templates 64 | ├── index.js # Imports and applies the design system to a bundle for Drupal 65 | ├── particle.info.yml # Theme information. DS namespaces are auto-injected! 66 | ├── particle.libraries.yml # The output js and css bundles are included here 67 | ├── particle.theme # Drupal preprocess functions 68 | ├── webpack.drupal.shared.js # Webpack config shared between drupal dev and drupal prod 69 | ├── webpack.drupal.dev.js # Webpack config unique to dev, or that overrides shared 70 | ├── webpack.drupal.prod.js # Webpack config unique to prod, or that overrides shared 71 | └── index.js # Imports and applies the design system to a bundle for Drupal 72 | 73 | 74 | ## Atomic Design and Namespaces 75 | 76 | "Namespaces" are simply aliases to paths on a file system. The design system within `source/` adheres strongly to [Atomic Design](http://atomicdesign.bradfrost.com/), with `@protons` added on. 77 | 78 | | Path | Twig | Javascript | Sass | 79 | | -------------------------------- | ------------ | ----------- | ---- | 80 | | `source/_patterns/00-protons/` | `@protons` | `protons` | TBD 81 | | `source/_patterns/01-atoms/` | `@atoms` | `atoms` | TBD 82 | | `source/_patterns/02-molecules/` | `@molecules` | `molcules` | TBD 83 | | `source/_patterns/03-organisms/` | `@organisms` | `organisms` | TBD 84 | | `source/_patterns/04-templates/` | `@templates` | `templates` | TBD 85 | | `source/_patterns/05-pages/` | `@pages` | `pages` | TBD 86 | 87 | > Note: Namespaces within Sass are a work in progress! 88 | 89 | Our reasoning for categorization of components within each is pretty close to pure Atomic Design principals, but here's a quick explanation. 90 | 91 | - **Protons** features Sass systems and non-consumable pattern markup. No Twig file will `@include` anything from `@protons`, but javascript and Sass will. This is a uniquely Particle convention. 92 | 93 | - **Atoms** upward **will** be included in other Twig files. 94 | 95 | > "Atoms of our interfaces serve as the foundational building blocks that comprise all our user interfaces. These atoms include basic HTML elements like form labels, inputs, buttons, and others that can’t be broken down any further without ceasing to be functional. [Source.](http://atomicdesign.bradfrost.com/chapter-2/#atoms) 96 | 97 | - **Molecules** are more complex widgets that must at least include an atom and sometimes other molecules. 98 | 99 | > "In interfaces, molecules are relatively simple groups of UI elements functioning together as a unit. For example, a form label, search input, and button can join together to create a search form molecule." [Source.](http://atomicdesign.bradfrost.com/chapter-2/#molecules) 100 | 101 | - **Organisms** feature atoms, molecules, and even other organisms (sparingly). Think headers, footers, blog rolls. 102 | 103 | > "Organisms are relatively complex UI components composed of groups of molecules and/or atoms and/or other organisms." [Source.](http://atomicdesign.bradfrost.com/chapter-2/#organisms) 104 | 105 | - **Templates** are page layouts, giving us a view into how content can possibly be laid out. 106 | 107 | > "Templates are page-level objects that place components into a layout and articulate the design’s underlying content structure." [Source.](http://atomicdesign.bradfrost.com/chapter-2/#templates) 108 | 109 | - **Pages** can be considered full "prototypes" of a design systgem, with real content, images, etc. 110 | 111 | > "Pages are specific instances of templates that show what a UI looks like with real representative content in place." [Source.](http://atomicdesign.bradfrost.com/chapter-2/#pages) 112 | --------------------------------------------------------------------------------