README

Drupal 8 Theme to use with Whirlwind Distribution

Global Prerequisites

You will need the following installed globally (in the following order):

• NodeJS

Download installer for your system and follow installer's prompts.

• gulp

  npm install --global gulp-cli
  

• Browsersync

  npm install -g browser-sync
  

Sass/Gulp dependencies

• Libsass - CSS on steroids
• Sass Breakpoint - Simpler media queries
• Mappy Breakpoints - Media queries helper
• Susy 2 - Grid system by Miriam Suzanne
• Sass MQ - Alternative media queries helper
• Typi - Responsive typography
• Modular Scale - Harmony in design

Installation

Run npm install to install all the dependencies.

Workflow configuration

Mappy Breakpoint

Use Mappy Breakpoint for simpler media queries. Nest media queries inside the declarations not the other way around. To use mappy-bp define your breakpoints inside 010-global/layout/_breakpoints.scss.

.test {
    width: 100%;

    @include mappy-bp(med){
      width: 250px;
    }

    @include mappy-bp(desk){
      width: 150px;
    }
}

Susy 2

For flexible grid system use Susy. Configure susy in /010-global/layout/_config.scss e.g.:

//Setting Susy map
$susy: (
  flow: ltr, // ltr | rtl
  output: float, // float | isolate
  math: fluid, // fluid | static (requires column-width)
  column-width: false, // false | value
  container: auto, // length or % | auto
  container-position: center, // left | center | right | <length> [*2] (grid padding)
  last-flow: to,
  columns: 12,
  gutters: 1/2,
  gutter-position: before, // before | after | split | inside | inside-static (requires column-width)
  global-box-sizing: border-box, // content-box | border-box (affects inside/inside-static)
  debug:
    (
      image: hide, //show | hide | show-columns | show-baseline
      color: rgba(blue, .2),
      output: background, // background | overlay
      toggle: bottom right, //	right | left and top | bottom
    ),
);


//Setting Box sizing for the site
@include border-box-sizing;

//Set Susy container
body {
  @include container(1200px);
}

Modular Scale

Define modular scale map inside 010-global/type/_typi.scss. Modular scale ratios

$modularscale: (
  base: 16px,
  ratio: 1.067
);

Typi

Responsive typography is defined inside 010-global/type/_typi.scss as well. You can define behaviors for global and specific elements like headings e.g.:

$typi: (
  base: (
    null: (15px, 1.4),
    med: (16px),
    large: (17px)
  ),

  h1: (
    null:  (ms(7), 1.3),
    land:  (ms(8)),
    med:   (ms(9), 1.2),
    large: (ms(10)),
    wide:  (ms(11), 1.2)
  ),
);

use vr() units for styling:

.test{
    padding: vr(.5); // 1/2 of base = 8px
}

Naming conventions

Follow BEM as much as possible e.g.:

Icons

icon__search.svg

icon__arrow-left--normal.svg
icon__arrow-left--active.svg
icon__arrow-left--hover.svg

Colours

$color__text--dark:              #111111;
$color__text--medium:            #424242;
$color__text--light:             #4D4D4D;
$color__text--white:             #FFFFFF;
$color__text--description:       #4D4D4D;

Scss

article--teaser.scss
article--full.scss
article--search-index.scss

search__header.scss
search__content.scss
search__filters.scss
search__pager.scss

Classes

<div class="callout">
    <h2 class="callout__title"></h2>
    <div class="callout__content">
        <div class="callout__image"></div>
        <div class="callout__body"></div>
    </div>
</div>

Gulp

After installation run gulp in root directory. Gulp will open localhost:3000 in your default browser and parse Acquia Dev Desktop local site url. If it fails or you are not using Acquia Dev Desktop add the url in the gulp-custom-vars.js file. Optionally, the Drupal Browsersync module can be installed which will enable automatic style refreshing on any local URL (not just http://localhost:3000). Enable the module then go to Appearance > Default theme > Settings and check Enable Browsersync inside Browsersync Settings at the bottom of the page. As gulp runs, it watches sass and injects changes into the browser as you work.

Gulp will watch for changes to Twig templates, automatically clear the cache and refresh the page using Browsersync. For this to work the command line environment needs to be set up correctly so Drush can be run. If you're using Acquia Dev Desktop you will need to set the PATH environment variable before running gulp. The export string can be copied from the terminal window that is opened by clicking the Open Drush console button in Dev Desktop. Paste it into the terminal that gulp will be run from. The string will look similar to this:

### Common issues

1. Receiving an error during `clearDrupalCache`:
   ```[10:51:15] Starting 'clearDrupalCache'...
   [10:51:15] ERROR: Could not clear Drupal cache.```

   Set the environment variables as outlined in the Gulp section above.