/joe-style-guide

AMA Journal of Ethics Style Guide

Primary LanguageSCSS

Latest Release

Living Style Guide for Journal of Ethics

This will be the new and improved living style guide for the Journal of Ethics. It is the canonical source for the Digital Technology Team's Drupal 8 work on Journal of Ethics, as well as 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 this Style Guide on a project:

Style Guide Developers - To begin working:

Environment setup (mac)

  • Have homebrew installed
  • brew update
  • brew install nvm
  • nvm install v9.9.0
  • nvm use 9.9.0
  • nvm alias default v9.9.0

Just the first time:

  • cd styleguide
  • composer install
  • npm install
  • 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.

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 original style guide documentation before writing new JS.
  • This package uses npm shrinkwrap to maintain consistent packages across machines. When installing a new npm package, be sure to run npm shrinkwrap --dev and commit the resulting file.
    • If you have trouble running npm shrinkwrap, try npm prune or rm -rf node_modules/ && npm install

Project Branches

This project will maintain a number of branches:

  • develop - the (uncompiled) working branch
  • gh-pages - the compiled, publicly accessible “testing” artifact
  • dev-assets - 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*
sudo npm cache clean -f
sudo npm install -g n
sudo n stable

* Node versions higher than v7.10.0 are not yet supported, so please exercise caution when using these instructions.

  • 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 placed 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?

When adding new SVG icon assets:

Inline CSS is bad because can affect other SVG files. Example: the .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 optimizing .svg icons is SVGO. It's lightweight and fast.

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