Home

Awesome

 ______     ______   __  __     __         ______
/\  ___\   /\__  _\ /\ \_\ \   /\ \       /\  ___\
\ \___  \  \/_/\ \/ \ \____ \  \ \ \____  \ \  __\
 \/\_____\    \ \_\  \/\_____\  \ \_____\  \ \_____\
  \/_____/_   _\/_/_  \/_____/   \/_____/_  \/_____/
    /_____/\ /_____/\  /_____/\ /________/\/_____/\
    \:::_ \ \\:::_ \ \ \:::_ \ \\__.::.__\/\:::_ \ \
     \:(_) \ \\:(_) ) )_\:\ \ \ \  \::\ \   \:\ \ \ \
      \: ___\/ \: __ `\ \\:\ \ \ \  \::\ \   \:\ \ \ \
       \_\/_____\_\/_\_\/_\_____\/_  \__\/__  \_____\/
        /________/\/_/\/_/\ /_____/\ /_____/\ /_____/\
        \__.::.__\/\ \ \ \ \\:::_ \ \\::::_\/_\::::_\/_
           \::\ \   \:\_\ \ \\:(_) \ \\:\/___/\\:\/___/\
            \::\ \   \::::_\/ \: ___\/ \::___\/_\_::._\:\
             \::\ \    \::\ \  \ \ \    \:\____/\ /____\:\
              \__\/     \__\/   \_\/     \_____\/ \_____\/

NPM version

Design In Browser, Build In Browser, Sign Off In Browser

Designing in browser is a long wished for goal but always has seemed just slightly out of reach. From the technical knowledge needed to set everything up to actually do the coding to getting sign off from clients, it seems like a daunting task to begin to do it. Style Prototypes aims to make the whole process much easier and much more approachable for everyone from Designers who don't know what a Git is to full on Unicorns. Style Prototypes grew from the wonderful Style Guide built by Mason Wendell for his kick ass Survival Kit and now constitutes a whole system for building Style Tiles, Style Guides, Component Guides, and Color Guides straight in browser. By leveraging the power of Sass, Compass, Yeoman, Grunt, and Bower, we are able have at our fingertips the tools necessary to sit back and just design. If you're a designer new to all of this, I've written up a Designer's QuickStart Guide to get you started! Read it and enjoy it!

Style Prototypes are a unique tool because, not only are they responsive by default (meaning your client will be able to sign off on styles they've been able to see natively on all browsers and devices), they encourage Style and Color Guide driven Style Tile and Component Guide generation. This means that after you've built out your Style Tile, you'll be on your way to having finished your Style Guide, which you need to for Style Guide Driven Design (and coincidentally takes lots of design decisions off of the shoulders of Front End Developers). You'll also never need to have someone guess at what colors they can use with a fully built out Color Guide with both hex and Sass values.

Speaking of Sass values, the whole shebang is designed to be turned into a Compass Extension to easily distribute and reuse your finished Style Guide throughout your team in a way that doesn't require an additional website and inspectors flying all over the place. Truly drop in and use functionality. Yah, it's that awesome.

Come with me on this journey.

Table of Contents

  1. Requirements
  2. Creating a Style Prototype
  3. Anatomy of a Style Prototype
  4. Running Style Prototypes
  5. Working with Style Prototypes
  6. Components
  7. Your Style Guide
  8. Your Compass Extension
  9. License

Requirements

Style Prototypes are available as a Yeoman Generator that utilizes Sass+Compass. This makes it drop-dead easy to create a new Style Prototype. So, in order to use them, you first need to make sure you have the underlying dependencies installed.

After you have installed the underlying dependencies, you need to install the generator dependencies. From your Command Line, type in the following:

npm install -g yo grunt-cli bower generator-style-prototype weinre

gem install bundler

You may need to run these as an administrator. To do so, type sudo in front of both gem and npm. This command will install the Ruby gem Bundler for handling gem dependencies, Yeoman, Grunt, Bower, and the Style Prototype generator.

Please Note

While a Unix based system (Mac, Linux, etc…, basically not Windows) isn't required per se to run Style Prototypes, some of the advanced functionality available uses Unix commands.

Creating a Style Prototype

Once you have all of the dependencies installed, it's time to create a new Style Prototype. From the command line, type in the following:

yo style-prototype

This will start a wizard for you to set up your Style Prototype. There are four optional flags you can pass into this command:

After you have started the wizard, you will be presented with a series of prompts to set up your Style Prototype:

Once you've filled out the wizard, Yeoman will work its magic and generate your Style Prototype for you!

Anatomy of a Style Prototype

Upon install, a bunch of files and folders will be created for you. If you haven't run the dependency installation, please do so now. The files and folders are generally, divided into three categories: App, Design, and Development.

App Files and Folders

Files and folders listed below are all part of the underlying system that make up Style Prototypes and generally should only ever be edited by advanced users.

Design Files and Folders

Files and folders listed below make up the bread and butter of what you will be working with when using Style Prototypes. Everything listed below you should feel free to edit.

Development Files and Folders

Files and folders listed below make up development-related files that should only be edited by users who understand their contents as they will affect how your output behaves.

Running Style Prototypes

Style Prototypes runs atop of Grunt, making doing things like running a development server and compiling your files easy.

Development Server

You can run a development server to build on by running the following command:

grunt server

If you include --launch, it will also launch your site for you after the server is running. Your development server will be available at localhost:8000 by default. Running the server will also listen for changes in Sass, HTML, Images, JavaScript, and Configuration and will do all necessary recompiling and reloading of the page for you. It also runs your CSS and JavaScript through CSS Lint and JSHint for you automatically.

Exporting Final Site

Once you have your Style Prototype built, you can run the following command:

grunt build

This will build a static version of your assets for you. If you include --commit it will also automatically commit these files to your Git repository for you.

If you are planning on deploying your site to an external server, you can then run the following command:

grunt export

This will export your static assets to a folder (by default export). If you include the --to=/path/to/export, it will export to the folder of your choosing.

If you would like to deploy your final site to GitHub pages, you can run the following command after having built your site using grunt build:

grunt deploy

Changing Version Number

To properly change the version number of your Style Prototype, you should run one of the following commands:

Versioning is done in the style of SemVer. In your config.yml file, under the Versioning heading, there are options for controlling if you'd like to automatically commit and tag your repository when you bump your project

Creating a Compass Extension

One of the most useful features of Style Prototypes is being able to easily generate a Compass Extension from your developed Style Guide. This is made extremely easy with Grunt, simply run the following command:

grunt extension

This will build your Compass extension out of your Sass, Images, and JavaScript directory and include your Gemfile, bower.json, .editorconfig, .jshintrc, and .csslintrc files as well. If you include --install, it will install the Compass extension for you too.

Working with Style Prototypes

When working with Style Prototypes, there are two main preprocessing languages you're working with, Sass and Handlebars. Sass is used for CSS and Handlebars is used for HTML. In addition, there are a handful of Grunt commands to allow you to work with and build your Style Prototypes.

Handlebars

Handlebars is a JavaScript based HTML preprocessor. Anything you can do in Handlebars normally you can do in Style Prototypes. You can create custom helpers inside of helpers.js and, in addition to the standard helpers that come with Handlebars, the following are also available:

In addition to handlebars pages, you can write Markdown files and they will be converted into pages as well.

All pages that you create can contain at the top a JSON declaration to provide scoped variables to work with under the page variable (including Markdown files). These JSON declarations look like the following:

{
  "title": "Hello World",
  "examples": false
}
---

Sass+Compass

The bread and butter of your Style Prototype is your Style Guide. There are going to be two Sass files in your Sass directory, one called prototype.scss and a style guide partial named after your client. Do not rename these files unless you are an advanced user. These are the files and folders you'll find in your Sass folder:

The following Compass extensions are available to you out-of-the-box:

When creating Style Guide, it is a best practice to create partials in the components folder for discrete functionality, built as both a mixin and as an extendable selector, with a selector extending said extendable selector. This way, when going to use the Style Guide, you have both the mixin and the selector to choose from. When creating a new Style Prototype, you will be presented with some common components with example styling to guide you through the process.

Components

Components are the bread and butter of your style guide. They are reusable patterns comprised of HTML and CSS that can be used in multiple places throughout your site. Style Prototypes provides an easy interface for creating new components. In your config.yml file, under components, you can define a component (they must be in slug form, no capitals, no spaces). Each component will correspond to a component template inside of templates/components, so a button component will have a templates/components/button.html file. When adding a new component, this file, as well as the corresponding Sass files and a group partial, will be automatically generated for you. The templates for components do not have access to handlebars, but they do have access to variable replacements. The following replacements are available:

{{component}}: The name of the component (*i.e.* message)
{{type}}: The type of component (*i.e.* error)
{{property}}: Any custom property defined on the component

Each variable also has access to .slug for a slugified version of the name, and .cap for a capitalized version of the name.

Each component should have a corresponding group partial under partials/components with a folder for containing individual component instance's HTML under partials/components/{{component.slug}}. Each individual component instance's HTML should be named {{component}}--{{type}}.html.

This will allow the component and create-example-html helper function to bring in the correct HTML. In addition, each component should have a Sass file at sass/components/_{{component.slug}}.scss that contains it's theming, as well as a _mixins.scss and a _extends.scss file under sass/components/{{component.slug}}.

Styling for the general component inside of the main component Sass file should be wrapped in the following comments:

//////////////////////////////
// @{component.slug}
// Styling for component.cap Component

// {component.slug}@
//////////////////////////////

Styling for an individual component instance inside of the main component Sass file should be wrapped in the following comments:

//////////////////////////////
// @{component.slug--type.slug}
// type.cap styling for component.cap Component

// {component.slug--type.slug}@
//////////////////////////////

By wrapping your code in these special blocks, the create-example-sass helper function will be able to bring in the correct Sass that corresponds to the component.

For an in-depth look at dynamic components, take a look at the message and button components supplied. For an in-depth look at custom components, take a look at the supplied pager component.

Your Style Guide

Your Style Guide is the driving force behind your Style Prototype! Use the Elements, Typography, and Components pages to help you build out your Style Guide, using as least specific selectors as possible. Included is a global folder containing the basic base items for sharing across the Color Guide and Style Tile, as well as other files you'd use your Style Guide with.

Inside of global/variables/_colors.scss file are a handful of sample colors being generated by Color Schemer and utilizing Toolkit's Colour Stack functions to show how powerful those two tools are when used together to create color for your site. Inside of client-name-style-guide.scss you'll see active imports for Toolkit, Breakpoint, Singularity, Modular Scale, and Color Schemer. CSS Normalize is being brought in through a Compass extension, but you can use the hard Eric Meyer style reset if you'd like by replacing it with compass/reset.

Your Compass Extension

Generating your Compass Extension is easy! Simply follow the steps in Creating a Compass Extension, and you'll have your Compass Extension built!

Now comes the hard part, figuring out how to distribute your Style Guide. If you're OK with it being out in the open, make sure you've got a RubyGems account, then type gem push client-name-style-guide-1.0.0.gem (substituting name and version as appropriate). If you distribute this way, then installing and updating the style guide is the exact same as any other Compass Extension. A simple gem install client-name-style-guide will do. If you don't want it out in the open, you can email or self-serve the gem yourself, the only difference becomes gem update will no longer update the gem if you push an update. Users will then need to download the gem and, from the directory they've downloaded it to, run gem install client-name-style-guide-1.0.0.gem to install the extension.

In either case, it's easy to use. Simply add require 'client-name-style-guide' in your config.rb file and add @import "client-name-style-guide"; to your Sass file, and you're set (no trailing semicolon if you're using SASS syntax instead of SCSS syntax). It's important to note that you shouldn't use two style guides generated from this system in the same project, as their @import will conflict I believe. You can bring your images and JavaScript in as well. From the command line, run compass install client-name-style-guide. If you're creating a new project, you can do the whole thing in one go! Simply type compass create <my_project> -r client-name-style-guide to just require the style guide and do the @import yourself, or compass create <my_project> -r client-name-style-guide --using client-name-style-guide to create a new project with everything.

If you're using Bower components, you won't get them when using Compass's install/create commands, but it's easy to install them once you're finished. From your project's root folder, just run bower install and you should be all set! Also remember to run bundle install to install your Bundler dependencies!

That's It! Have Fun!

License

© Sam Richard, Mason Wendell

Original code licensed under GLPv3 Open Source projects used within this project retain their original licenses.