Usage

How do I use this guide?

The guide breaks down the setup, configuration, and application of Live Wire. Use it as a reference for building your wireframes, creating a prototype, and then building upon your site or app’s design.

Setup

We’re using Gulp to do the following:

• Twig-based templating
• Sass compilation
• Javascript compilation
• Autoprefixer (automatically adds vendor prefixes to your CSS)
• LiveReload (auto-reloads your browser on each save. You’ll also need an appropriate browser extension)

To get started, you’ll need to:

Step 1

Install Node.js (we recommend installing through Homebrew).

Step 2

Download or clone Live Wires from the GitHub repository and save the contents in your project folder.

Step 3

Navigate to your project folder in Terminal and run npm install.

Step 4

Run bower install to install any third-party javascript libraries.

Step 5

Start the prepocessors by running gulp start in the Terminal.

To top

Project structure

One of the core philosophies behind Live Wires is stay out of the way as much as we can. We don’t want to impose any code standards or force you into a little box. Saying that, here are some guidelines that that will help you get started with Live Wires more easily.

Here’s how a Live Wires project is organized:

/source/templates/

This is where all working Twig templates live.

/source/templates/_includes/

Put your Twig template includes in here.

/source/templates/_layouts/

Put your Twig templates layouts in here.

/source/templates/example/

A set of example Live Wires prototype templates.

/app/guide/

The project style guide templates. This begins as a Live Wires reference, but becomes your project’s style guide as you begin writing CSS. Hint: Use the guide as a tool to design your elements and components.

/source/_scss/

This contains all of the pre-compiled Sass. This is where you will write your CSS.

/source/js/

This contains your pre-compiles javascript. This is where you will write your javascript.

/data/

You can put json or front matter content like dummy blog and data posts in here. It’s helpfull if you want to use real example content. Uses gulp-data.

/public/

Where your compiled project lives. What the browser reads. You can push this folder to any server as a static site.

/public/fonts/

Place any font files in here.

/public/img/

Place your images in here.

To top

Markup

We use standard HTML5 for markup. We try not to impose any markup styles or conventions, but do recommend BEM syntax to name your classes. This sets an easy standard for others to adopt and keeps the library tight, modular, and free of specificity issues.

Here’s the basic syntax:

.block {} /* A component or module */
.block__element {} /* A descendent of that module */
.block--modifier {} /* A modified or alternate version of the module */

Read more about BEM syntax.

‘Blanking out’ text

One of our favourite Live Wires features involves the ability to blank out text. This lets us design around actual content. However, if we want our team or client to focus on the layout or hierarchy of our wireframes and prototypes, we can hide the text so they won’t get distracted. To blank out paragraphs and list items, simply add a .content class to its parent element.

Note: /source/scss/settings/_livewires.scss must be included in the /source/scss/app.scss file for this to work.

    <div class="content">
  <p>This text would be blanked out.</p>
</div>

To top

CSS

All of the styles are written using Sass. All source files can be found in /source/scss/. We’ve set up a few basic starter styles to get you going, but encourage you to go through each file and customize it. Using this style guide as your own is a fine way to flesh out a UI system for every project.

SCSS file structure

/source/scss/

This file contains all of the SCSS styles in the project. The guide and your own templates both share the same CSS. What this means is that whenever you make changes to your styles, they will be reflected on your style guide and on your wireframe. This, here, guide becomes your own as you shape your templates. We normally use the guide to style each element, component, and module in our projects.

We’ve structured our SCSS folder based on Harry Robert’s ITCSS methodology.

app.scss

This generates your projects main CSS file. It has four includes:

_includes--base.scss

Imports the base scss variables and utilites that every SCSS file requires.

@import "1_settings/_includes--critical";

Pulls in the critical elements, components, and modules you want to include in your projects. We separate this from the following include so you can choose asyncronously load CSS that appears outside the viewport for quicker loading. More info on the technique at Filament Group.

@import "1_settings/_includes--secondary";

Pulls in the non-critical elements, components, and modules you want to include in your projects. We separate this from the above include so you can choose asyncronously load CSS that appears outside the viewport for quicker loading. More info on the technique at Filament Group.

@import "1_settings/_livewires";

Pulls in Live Wires styles which blank out the text inside of any element with a .content class in your HTML. Remove it to get rid of the blank text feature.

/source/scss/1_settings/

Contains the project variables, font includes and a few other things that set the stage.

_variables.scss

Set most global variables in here. You can set things like base typographic settings, default corner radius, breakpoint widths, and grid units.

_colors.scss

We keep our colour variables separate so we can easily experiement with multiple colour schemes.

_includes--base.scss

Imports the base scss variables and utilites that every SCSS file requires.

_includes.scss

Use this to include or exclude the sections you want in your project. We made everything modular, so you can use as much or as little as you like.

_font-faces.scss

Add any font or icon @font-face includes to this file.

/source/scss/2_tools/

Contains our handy logic-based SCSS tools like Mixins and Functions.

_mixins.scss & _functions.scss

These include powerful enhacements to help save time. Have a browse to see what’s available and how they work.

/source/scss/3_generic/

Contains third party styles like normalize as well as any plugin css that needs to be overridden.

/source/scss/4_elements/

Naked default HTML elements are styled here. Avoid styling with classes. e.g. paragraphs, headings, form fields

/source/scss/5_components/

The reusable pieces that consist of groups of elements. Start styling with classes here. e.g. callouts, pagination, code blocks

/source/scss/6_modules/

Major chunks that make up the main sections of a template. They often contain components and global elements, and are often used once per page. e.g. headers, footers, layout modules

/source/scss/7_theme/

This contains all colour-related styles. We’ve kept all the color assignments separate from structural styles to make theming easier, faster, and less prone to errors. Optional.

/source/scss/8_pages/

Page-specific styles. We recommend keeping larger files in this section out of the main stylesheet and only calling them on their respective pages.

/source/scss/9_overrides/

Anything that needs to sit at the bottom of the CSS. Put your important overrides in here.

_livewires.scss

Blanks out text inside of any element with a .content class in your HTML. Include this when presenting wireframes to clients or your team to focus their attention on layout and flow, rather than textual content. But hark the broken record: get your content in before you get into design.

To top

Helpers

We have some handy little helpers to make your life a little easer. Check out the /source/scss/9_overrides folder for more examples.

.hidden

Hide stuff from screenreaders and browsers.

.visuallyhidden

Hide stuff from browsers only.

.invisible

Hide but maintain layout.

.pull-right

Float object to the right.

.pull-left

Float object to the left.

.text-right

Right-aligned text.

.text-left

Left-aligned text.

.text-center

Centred text.

Use the SCSS @extend method on these, like:

@extend %group;

Add the clearfix hack to containing element (adding a class of clearfix or group to your HTML element also works but isn’t as cool).

Open type features(from Kenneth Ormandy’s Utility OpenType)

.liga

Common Ligatures

.dlig

Discretionary Ligatures

.smcp

Proper Small Caps

.c2sc

Caps to Small Caps

.caps

Small Caps and Caps to Small Caps

.case

Case Sensitive Forms

.titl

Titling alternates

.calt

Contextual alternates

.hist

Historical forms

.swsh

Swashes, 1–3

.salt

Stylistic Alternates, 1–3

.ss01

Stylistic Sets, 1–20

.frac

Diagonal Fractions

.afrc

Alternate Fractions

.ordn

Ordinals

.sups

Superscripts

.subs

Subscripts

.sinf

Scientific Inferiors

.lnum

Lining numbers

.onum

Oldstyle numbers

.pnum

Proportinal numbers

.tnum

Tabular numbers

.zero

Slashes Zero

To top

Javascript

Like our CSS and HTML, we try to keep our JavaScript modular so you can use only what you need. All javascript components are in /source/js and will compile automatically.

Third-party scripts

We use Bower to manage third-party scripts like jQuery plugins from the bower_components folder.

To top

Compatibility

We support all modern browsers including Internet Explorer 10 and up. If you need to support IE8 or anything earlier, you can solve most incompatilibilites by switching to jQuery 1.x and including the following polyfills:

• html5shiv
• Respond.js
• REM-unit-polyfill
• Selectivizr

We also use Auto-prefixer to write any necessary vendor prefixes for us. You’ll want to adjust the settings in mixture.json or Gruntfile.js for other browsers.

To top

Support

Submit your bug reports, pull requests, and questions to GitHub.

Other questions? Visit Live Wires for more info.

To top