A full featured toolkit for compiling js, sass and styleguide

Features
Requirements
Quick Start
Compiling
JavaScript
Styleguide
Sass
Node

• Gulp
• Webpack
• Fabricator
• Image minification
• Browser Sync

• Node 6+
• npm 5+

To create standalone directory named toolkit inside your current folder

git clone [email protected]:agencychief/toolkit.git yourtoolkit
cd yourtoolkit
npm install

To add toolkit files to current folder (theme install)

git init
git remote add origin [email protected]:agencychief/toolkit.git
git pull origin master
npm install
rm -rf .git
rm .gitignore

Development: Starts a watch of the toolkit files and initializes Browser Sync

npm run dev

Standalone: Starts a watch of the toolkit files and launches a local server to work on the styleguide directly

npm run standalone

Production: Compiles and minifies files for packaging

npm run prod

Files location: src/js

The toolkit, by default, utilizes Webpack for JavaScript management. Read this to learn how to disable webpack processing. Webpack allows us to create a modular JavaScript project.

All js files that are added to the main js folder will be output as a standalone file in the output folder. All js files in subdirectories will not be output as standalone files.

script.js is a standalone js file and is an example which includes component JS files from a subdirectory includes. Require functions can be removed or commented out safely if you are not using these components functionality.

1. Follow steps outlined in Node section below.
2. Add a new JavaScript file to src/js/includes, declare your node_module dependency, and add any custom code.
3. Add your new file as a dependency in script.js:

   require('./includes/my_new_file')
   

1. Add a new JavaScript file to src/js/includes, and add any custom code.
2. Add your new file as a dependency in script.js:

   require('./includes/my_new_file')
   

1. Add new file to src/js. This will be output into the dist/js folder when compiled.

If you want to add additional folders to output standalone JavaScript files you can modify the config.src.scripts settings in the gulpfile.js using this pattern

'output_directory_name' : 'path_to_the_file',

The toolkit uses webpack by default to process the js files in the src/js directory, however this processing can be disabled by appending :nopack to the compiling command.

# Examples
npm run dev:nopack  
npm run prod:nopack  
npm run standalone:nopack

The toolkit will use jQuery from an external source loaded from a WordPress or Drupal install, or CDN.

Files location: src/styleguide

New components/elements/pages/structures will be added to the styleguide on compile.

This directory contains documentation in Markdown format.
Edit existing files or create a new ones related to your unique build.
Each document will add a section and print the content on the docs page in your styleguide.

This directory contains core functionality to generate the styleguide.
Reasons you would need to edit these files:

1. Add/Change styleguide menu sections
   To update styleguide menu, edit styleguide/templates/includes/f-menu.html.
2. Add/Change default wrapper markup for 'Pages'
   To update 'Pages' wrapper markup, edit styleguide/templates/pages-layout.html.
3. Add/Change links to resources
   To update reference to resource, edit styleguide/templates/default.html.

Fabricator uses handlebars syntax in its HTML files. Read the full documentation of Fabricator.

This directory contains the component files used to build out the styleguide.
This is the location where most if not all work in the styleguide is done

Materials are organized using Atomic Design methodology and correspond with sass organization.

1. Add HTML file to the material subdirectory.

1. Create a new directory within one of the material subdirectories.
2. Add HTML files into your new directory.
   All HTML files will be grouped together in a styleguide section labeled with the name of the directory. See styleguide/materials/elements/button for an example.

'Pages' are used to prototype pages using a collection of components, elements, and structures.
New pages should be added in styleguide/materials/pages directory.

1. Add HTML you'd like, and include existing components/elements/structures using handlebars syntax.

See styleguide/materials/pages/home.html for an example.

Files location: src/sass

Sass files are organized using Atomic Design methodology

Atomic Design outlines 5 stages:

• Atoms: UI elements that can’t be broken down any further and serve as the elemental building blocks of an interface
• Molecules: Collections of atoms that form relatively simple UI components
• Organisms: Complex components that form discrete sections of an interface
• Templates: Components within a layout and demonstrate the design’s underlying content structure
• Pages: Articulate variations to demonstrate the final UI and test the resilience of the design system.

The toolkit sass structure aligns with these stages to a certain extent:

• base one level removed: primarily variables and mixins which can be used in building components, elements, etc
• elements to atoms
• components to molecules
• structures to organisms

We've also included an animations directory which will house reusable microinteraction css animations.

We encourage mobile-first best practices for media queries, but include some other beneficial breakpoints declarations.

The toolkit includes breakpoint-sass to handle the writing of media queries. Call it using the breakpoint mixin:

@include breakpoint($variable){
  // Your styles here
}

The toolkit has 9 breakpoint variables defined out of the box:
$min-width
$mobile
$lg-mobile
$tablet
$tablet-only
$all-devices
$desktop
$desktop-only
$lg-desktop

Check src/sass/base/_variables.scss for values

1. Follow steps outlined in Node section below.
2. Open gulpfile.js, find includePaths, and add the path to the library's stylesheet directory to this array.

   'node_modules/name_of_library/path/to/stylesheets'
   

3. Open styles.scss and import the library at the top of the file.

   // Add third party library
   @import name_of_library
   

When developing please keep accessibility in mind. Elements should be keyboard accessible and have focus states. Additionally, remember to check the color contrast when using a background color.

Saves the files into the node_modules folder and adds them to the package.json file as a dev dependency

npm install module_name --save-dev

or from github

npm install git://github.com/USERNAME/PROJECT.git --save-dev

Removes the files from the node_modules folder and also removes the dev dependency from the package.json file

npm uninstall module_name --save-dev

Use this shrinkwrap when development is done to lock specific versions of modules for maintenance

npm shrinkwrap --dev