Suzi

A responsive, Sass and Grunt UI Framework by Matt Stow

v2.1.0 (2014-10-26)

Suzi is the starting point for all of our web projects and a culmination of 6+ years' experience in maintaining a front-end framework.

Features

• Built in a mobile-first, responsive philosophy (but can easily be used for fixed sites as well)
• Mixins for lots of CSS3 features including gradients with SVG & CSS3PIE support, rems with pixel fallbacks, correctly-prefixed transitioned transforms and CSS triangles
• Starter content styles, including clean typography, lists, tables, etc
• Starter form element styles: stacked on small-screen to 2-column at the breakpoint of your choice
• Simple form validation
• Responsive, lazy-loaded, touch-friendly carousels with optional navigation & pagination, analytics tracking & cookie-based remembering of last visible slide
• Simple, accessible JavaScript tabs with cookie-based remembering of the open pane
• Simple, accessible JavaScript accordions which transition to and from height: auto, and support multiple open panes
• Simple, but powerful HTML templating using grunt-includereplace-more
• Concatenation and minification of CSS and JS files with grunt-contrib-concat and grunt-contrib-uglify (unless running grunt dev)
• BrowserSync for automatic live-reloading of changes & synchronised browser testing
• Cache busting of CSS and JS assets with a unique timestamp querystring
• Optimising of images and SVGs with grunt-contrib-imagemin
• HTML validation
• OOCSS naming convention: .component_name--modifier & .function_or_feature_name-variant
• Tabs instead of spaces :)

---

Installation

1. Install Ruby (and add it to your Path Environment Variable on Windows)
2. Install Sass
3. Install node.js (and add it to your Path Environment Variable on Windows)
4. Open a shell window and install the Grunt CLI with npm install -g grunt-cli
5. Download or clone Suzi
6. Open a shell window in the Suzi root directory
7. Run npm install to install Suzi's Grunt dependencies

---

Usage

• Use grunt in a shell window to run Suzi in production mode
• Use grunt dev to run in dev mode (un-minified CSS and JS)
• Use grunt bust to manually bust the cache on CSS and JS files
• Use grunt validate to validate all of the HTML builds in /public/builds/
• Use grunt build to build the project for release

Set up

• Ensure you point your web server to run from the /public/ directory
• Customise includereplacemore.options.globals.siteTitle in Gruntfile.js to set the site name as the page <title> suffix

HTML Builds

• Create templates in /builds/
• Create and customise template includes in /builds/includes/
• Set the $title variable to customise the page's <title>
• Set the $currentPath variable to the template's file name to allow for .current navigation states
• You'll find common markup patterns in /builds/markup
• Access a quick list of all builds by browsing to /builds/index.html

Sass/CSS

• Set up variables for colors, fonts, sizes, breakpoints, etc in /css/custom/_config.scss
• Add @font-face declarations to /css/custom/_fonts.scss
• Make simple customisations to links, headings, lists & tables in /css/custom/_simple.scss
• Make simple customisations to form elements in /css/custom/_forms.scss
• Modify the carousels in /css/custom/_carousel.scss
• Create and add site specific partials in /css/custom and import them from /css/custom/_site.scss
• Add any LT IE9 overrides to /css/custom/_ltie9.scss
• Add any print overrides to /css/custom/_print.scss

JavaScripts

• Use /js/all.js for all custom methods
• Customise concat.all.src in Gruntfile.js to add or remove scripts which are to be loaded at all times
• Put any un-minified JavaScript plugins/libraries in /js/vendor
• Lazy-load additional scripts using window.suzi.jsVendorPath + 'plugin.name.js'

Images

• Put CSS images, favicon and SVGs in /images/
• Put content images which the site doesn't "rely" on in /images/content
• Use url('{{ imgPath }}image-name.ext') when referencing images in CSS
• Use {{ imgContentPath }}image-name.ext when referencing images in HTML

Fonts

• Put all web and icon fonts in /fonts/

---

Sass Mixins and Functions

Helper functions

• strip-units($number)

  Strips units from the number specified

• em($pixels, $context: 16, $unitless: false)

  Converts a pixel value to ems, with an optional parameter to make it unitless (which is useful for line-heights)

  • $pixels: target size in pixels
  • $context: context size in pixels (default: 16)
  • $unitless: whether to omit the em unit (default: false)

• percent($pixels, $context: $site-width)

  Converts a pixel value to a percentage

  • $pixels: target size in pixels
  • $context: context size in pixels (default: $site-width)

Functional mixins

• calc($property, $expression, $fallback: false)

  Outputs the calc() CSS function and an optional fallback

  • $property: The CSS property to be used
  • $expression: A mathematical expression, the result of which is used as the value
  • fallback: A fallback value for browsers that don't support calc()

• gradient($nodes: (#f6f8f9, 0%, #e5ebee, 50%, #d7dee3, 50%, #f2f5f7, 100%), $direction: 'to bottom', repeating: false)

  Outputs the complete CSS3 gradient syntax for Chrome, Safari, Firefox, Opera, IE10, other capable browsers and SVG for IE9

  • $nodes takes a list of comma-separated #color, position% pairs. If only a single color is passed in, a plain background or background-color will be created depending on $use-background-property
  • $direction takes either the legacy syntax or the unprefixed W3C syntax, including angles. The following angles are supported for SVGs: 0, 10, 45, 90, 135, 170, 180, 190, 225, 270, 315, 350
  • $repeating: whether to create repeating linear gradients (default: false)
  • Uses the background property (and background-image for IE9) unless the global $use-background-property is false
  • Outputs a fallback background of the last color in the list unless the global $use-background-fallback is false
  • Outputs base 64 SVG syntax for IE9 unless $repeating is true
  • Outputs CSS3PIE syntax for LT IE9 unless the global $use-pie-background is false or $repeating is true

• grid($breakpoints: (480, 600, 768, 960), $percentages: (10, 20, 25, 30, 33.3333, 40, 50, 60, 66.6666, 70, 75, 80, 90, 100), $float-classes: false)

  Outputs relevant media queries and helper classes for Suzi's flexible, customisable and responsive grid system

  • $breakpoints: A list of the breakpoints (in pixels) that media queries and classes should be generated for (default: 480, 600, 768, 960))
  • $percentages: A list of the class name percentages to be output for each breakpoint and as simple default overrides (default: 10, 20, 25, 30, 33.3333, 40, 50, 60, 66.6666, 70, 75, 80, 90, 100)
  • $float-classes: Whether to output classes to float .grid_items to alter source order appearance (default: false)

• grid-override($name, $gutter, $media-query: false)

  Outputs $name_-prefixed .grid_container and .grid_item classes to override standard grid styles.

  • $name: The prefix to use for .grid_container and .grid_item classes. For instance, $name: small produces .small_grid_container and .small_grid_item
  • $gutter: The new gutter value for the relevant margin and padding properties for these grid override classes
  • $gutter can also be a list to allow different horizontal and vertical gutters. The 1st parameter is horizontal, and the 2nd vertical, eg: (30px, 10px) for 30px horizontal and 10px vertical
  • $media-query: Whether to only override the gutter at a particular media query

• hover($pseudo: false)

  Outputs :hover & :focus rules for the current element

  • $pseudo: the name of a single pseudo-element (after, before) or a list of multiple to create :hover & :focus rules for

• nth-child($an: 2n, $sibling: '*', $count: 15)

  Allows nth-child functionality for .ltie9 (if you can't/don't want to use Selectivzr) by outputting crazy sibling selectors

  • $an: the counting method, eg: 2n, 3n, odd (default: 2n)
  • $an can also be a list, with the 2nd parameter being the modifier, eg: 2 for ($an+2) or -3 for ($an-3)
  • $sibling: the sibling element selector, eg: 'li', 'div' (default: '*')
  • $count how many sibling selectors to support, eg: 10, 20 (default: 15)

• triangle($direction: right, $width: 5px, $height: 10px, $color: $std-link-color, $layout: true, $border-style: true, $webkit-rotate: true, $important: false)

  Outputs a CSS triangle for use in :before/:after pseudo-elements. It duplicates the rule, using rgba for transparency to prevent 'black fringes'

  • direction: up, down, left, right (default: right)
  • $width: width in pixels (default: 5px)
  • $height: height in pixels (default: 10px)
  • $color: triangle's hex color (default: $std-link-color)
  • $layout: whether to output CSS content, display, height & width properties (default: true)
  • $border-style: whether to output the CSS border-style property (default: true)
  • $webkit-rotate: whether to rotate the triangle by 360deg in WebKit for smoother appearance (default: true)
  • $important: whether to also output !important on border-color and border-width properties (defa