Merge pull request #23 from phase2/Jwaxo-pl-additions

Add notes on PL Data structures and Demos

Author: tjheffner

Diff for: .gitignore

@@ -1,4 +1,5 @@
 node_modules
+.DS_Store
 .idea
 build
 site

Diff for: README.md

@@ -8,7 +8,7 @@ Particle is an opinionated set of tools and examples to:
 
 ## Particle Features
 
-* Drupal theme, Grav theme, Pattern Lab instance
+* Drupal theme, Grav theme, [Pattern Lab](https://patternlab.io/docs/) instance
 * Strict [Atomic Design](http://atomicdesign.bradfrost.com/) component structure
 * Robust Webpack bundling of all CSS, JavaScript, font, and static assets for multiple targets
 * [Webpack Dev Server](https://github.com/webpack/webpack-dev-server) for local hosting and hot reloading of assets into Pattern Lab
@@ -21,6 +21,7 @@ Particle is an opinionated set of tools and examples to:
 
 ## Documentation To-Do List
 
+* Go over basics of Pattern Lab, the specific way Particle has Pattern Lab set up by default, and suggested uses.
 * Folder & config structure need updated to current Webpack structure
 * Explain Particle.js and how the `Particle()` function smashes various Webpack configs together
 * Explain Webpack structure \(CSS modes, etc.\)

Diff for: particle/architecture/component-structure.md

@@ -10,10 +10,6 @@ npm run new
 
 Follow the onscreen prompts for the location, included files, and name of the new component.
 
-### For versions prior to v10.1.0:
-
-**Then make sure you edit** `source/design-system.js` **and add your new component.** Versions after this should update next time you build.
-
 ## Anatomy of a Component
 
 All components require a set of files:
@@ -41,6 +37,8 @@ Optionally, you can add a `__test__` folder to your components base directory \(
 ├── ...
 ```
 
+## Importing Assets
+
 With the power of Webpack, all static assets a component needs are `import`ed right into the `index.js` **entry point** alongside the JavaScript methods:
 
 ```javascript
@@ -77,3 +75,28 @@ export function enable($context) {
 export default enable;
 ```
 
+## Using Demos
+
+Every component has an optional demo folder, which is automatically pulled into Pattern Lab. These files are only built for Pattern Lab, so you should never do work on them that you expect to see on a production app, such as a Drupal theme.
+
+The Yeoman generator creates four files by default in this folder, which describe the general Phase2 way to demonstrate how to use a new component:
+
+### index.js
+Describes to Webpack the files to include when generating the Pattern Lab demos. This most likely will only need to be touched when you are creating multiple demo pages for a single component.
+
+### component.twig
+This should serve as an example twig file that shows an inclusion of the new pattern, placed with example variables and layouts so that it will appear like an intended component when viewed in the demos.
+
+The default .twig file places a standard Twig-style `include` of your new component, but you can (and should) modify this page to meet your design system better. Look at the default patterns for good examples of how to create a demo template.
+
+### component.md
+An additional readme that may describe how to use your demo, its implications, or others. By default the variables that a component requires are often documented here, in addition to in the component's _component.twig file.
+
+### component.yml
+An optional way to override the data in `/_data/data.yml`, to display something specific in your demo. These data structures are only included in their respective page's demos when rendering the demo's template, so they are safely separated from other pattern demos.
+
+Due to Particle including the [Faker plugin of Pattern Lab](https://github.com/pattern-lab/plugin-php-faker), you can use the [Node.JS Faker API](https://www.npmjs.com/package/faker) to generate random data to appear in your demos! See `/_data/data.yml` for examples.
+
+**Note:** If you would like to create demo data to be global between all patterns, add the variables to a Yaml file in the `/_data` folder, such as `/_data/data.yml`.
+
+For more information about how Pattern Lab expects variables to be added for use in patterns, see the [Pattern](https://patternlab.io/docs/data-overview.html) Lab docs.

Diff for: readme.md

@@ -1,12 +1,35 @@
-# Phase2's Front End Tooling Documentation (Particle & Friends)
+# Intro
 
-## live docs available [here](https://phase2.github.io/frontend-docs/)
+Particle is an opinionated set of tools and examples to:
 
-## to work on & edit locally:
+1. Build an application-agnostic **design system** made of assets like Twig, Sass, JavaScript, images, etc
+2. Apply that **design system** to a locally-served Pattern Lab for rapid prototyping
+3. Apply that **design system** to other consuming apps like, Drupal, Grav, or \(soon\) Wordpress
 
-    pip install mkdocs
-    mkdocs serve
+## Particle Features
 
-# published with:
+* Drupal theme, Grav theme, [Pattern Lab](https://patternlab.io/docs/) instance
+* Strict [Atomic Design](http://atomicdesign.bradfrost.com/) component structure
+* Robust Webpack bundling of all CSS, JavaScript, font, and static assets for multiple targets
+* [Webpack Dev Server](https://github.com/webpack/webpack-dev-server) for local hosting and hot reloading of assets into Pattern Lab
+* [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
+* Iconfont auto-generation
+* Bootstrap 4 integration, used for all starting example components
+* Auto-linting against the [AirBnB JavaScript Style Guide](https://github.com/airbnb/javascript) and sane Sass standards
+* All Webpack and Gulp files are fully configurable
+* [PostCSS](https://github.com/postcss/postcss/blob/master/README.md) automation and expansion, with [Autoprefixer](https://github.com/postcss/autoprefixer/blob/master/README.md).
+
+## Documentation To-Do List
+
+* Go over basics of Pattern Lab, the specific way Particle has Pattern Lab set up by default, and suggested uses.
+* Folder & config structure need updated to current Webpack structure
+* Explain Particle.js and how the `Particle()` function smashes various Webpack configs together
+* Explain Webpack structure \(CSS modes, etc.\)
+* Expand on technologies Particle automatically includes to make Sass/JS faster.
+* Troubleshooting cleanup \("nothing to see here", datetime error?, etc.\)
+* Testing notes \(Jest, Pa11y, Cypress?\)
+* Vue-related notes
+* Example workflows
+* Flesh out the "thinking" sections
+* Update the Drupal apps section \(what goes here vs. Drupal under Frontend?\)
 
-    mkdocs gh-deploy