DEPRECATED Living Style Guide for AMA

This style guide has been DEPRECATED. The AMA is now maintaining consistent design and hierarchy through the AMA Style Guide 2 which can be previewed on GitHub Pages

This is a deprecated living style guide for the American Medical Association. It is a platform-agnostic tool to empower employees and vendors to maintain consistent design and hierarchy throughout the AMA digital ecosystem.

This style guide is a compilation of atomic components that have been specifically tailored to the needs of AMA. By documenting and assembling this collection of patterns, we are able to build consistently, reuse code, and see all of our patterns in one place.

Style Guide Consumers - To use the Style Guide on a project:

• Grab the latest release
• Open the .zip into your project
• Link to the production files at assets/

Style Guide Developers - To begin working:

Environment setup (mac)

• Have homebrew installed
• brew install nvm
• nvm install v7.10.0 (or some relatively recent node version. Note 8.0.0 has a fatal bug with require-dir module)
• nvm use 7.10.0

Just the first time:

• cd styleguide
• composer install
• sudo npm install -g npm
• sudo npm install -g gulp
  • This will install gulp globally on your machine. If you don't have privileges, don't want to install globally, or need to manage multiple projects using gulp, you can invoke gulp via ./node_modules/.bin/gulp serve instead of directly.

Version Requirements

• Node.js - v7.10.1 ( always < v8.x as this has breaking conflicts)
• npm - >= v5.2

For ongoing development

• gulp serve to watch files and display the resulting page in your local browser.
• Occasionally things might stop refreshing well. If that happens, just kill (Control-C) gulp and re-run.
• gulp scss-lint will check your SCSS for code quality. Please ensure your code lints successfully. A few notes:
  • We're using autoprefixer to get all the latest and greatest vendor prefixes. You should not need to use vendor prefixes in your code.
  • If you do need a vendor prefix (for device-specific changes, like -webkit-appearance) you can disable linting for those lines.
• CSS sourcemaps are generated by gulp so you can see what files are generating the applicable css for each element. If you are seeing something like "style.css?123456789" when you inspect elements in your browser, check that you have "enabled CSS mapping" in your dev tools. Chrome's developer documentation shows how to check your settings.
• Javascript files in the style guide require special consideration. Please read the documentation before writing new JS.

Project Branches

The style guide project maintains a number of branches:

• develop - the (uncompiled) working branch
• gh-pages - the compiled, publicly accessible “production” artifact
• dev-assets - the compiled, Drupal-consumed artifact for testing
• master - the compiled production release that gets tagged.

For more detail on how to deploy to these branches, see Creating a Release

Troubleshooting:

Make sure your npm dependencies are up to date

If you run unto an unexpected error, you might just be missing a dependency

• Run npm install from the styleguide directory to grab any missing dependencies.

Make sure node and npm are up to date(-ish)

You might have to do any or all of these

• Update node using n instead of nvm If you have problems working with nvm, n is another package manager that will do the same thing.

sudo npm cache clean -f
sudo npm install -g n
sudo n 7.10.0

• Update npm

sudo npm install -g npm

• Rebuild npm to recompile any outdated packages.

npm rebuild

What's going on here?

Icons

Icons are being generated using Grunticon with the Gulpicon wrapper. This generates a three-tier system of fallbacks, which are controlled by a JS-based loader full desc.

New icons can be places in source/assets/icons/svg. When gulp icons is run, the process will minify the SVGs then run gulpicon using the config and template in the icons directory, finally outputting everything in public/assets/icons/. The loader and initialization code are in _00-head.twig.

Responsive implementation

We are using Breakpoint to handle media queries for responsive implementation.

The first time you run npm install the dependency will be installed, but if you run into an error, running npm install again should fix the issue.

How do I get rid of bloat and inline css in my SVG files?

Inline CSS is bad because can affect other SVG files. Example: .st0 class is included by Adobe Illustrator for some SVG icons. This can affect all the SVG files on the page that have a class called st0.

The tool of choice for this is SVGO. It's lightweight and fast.

• To install it cd into your working project directory npm install -g svgo
• After you install SVGO run svgo [point to your SVG assets directory path]