A mature, feature-rich, responsive Sass and Grunt UI framework
CSS JavaScript HTML Ruby
Clone or download
Pull request Compare This branch is 79 commits ahead, 1 commit behind stowball:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A responsive, Sass and Grunt UI Framework by Matt Stow

v3.0.0 (2015-09-07)

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


  • Built in a mobile-first, responsive philosophy (but can easily be used for fixed sites as well)
  • HTML templating using grunt-twigger
  • Automatically generated vendor prefixes for CSS using Autoprefixer PostCSS - grunt-postcss
  • BrowserSync for automatic live-reloading of changes & synchronised browser testing
  • BEM naming methodology with single underscores instead of single hyphens for delimiting long class names: .block_name--modifier, .block_name__element & .function_or_feature_name-variant
  • 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
  • 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
  • Gradients with SVG & CSS3PIE support, rems with pixel fallbacks and CSS triangles
  • Responsive, lazy-loaded, touch-friendly carousels with optional navigation & pagination, analytics tracking & cookie-based remembering of last visible slide
  • Concatenation and minification of CSS and JS files with grunt-contrib-concat and grunt-contrib-uglify (unless running grunt dev)
  • Cache busting of CSS and JS assets with a unique timestamp querystring
  • Optimising of images and SVGs with grunt-contrib-imagemin
  • HTML validation
  • Tabs instead of spaces :)


  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


  • 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 twigger.options.data.siteName in Gruntfile.js to set the site name as the page <title> suffix

HTML Builds

  • Create templates in /html/_builds/
  • Create and customise template includes in /html/_includes/
  • Set the title variable to customise the page's <title>
  • Build your navigation hierarchy by modifying /content/hierarchy.js
  • You'll find common markup patterns in /html/_markup
  • Access a quick list of all builds by browsing to http://localhost:3000/builds/index.html


  • 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


  • Create modules in /js/modules/module-name.js
  • Use /js/app.js for module initialization
  • Try to pass reference to module dependencies in the init() method attached to your module, rather than relying on it being available in the global scope
  • Customise concat.all.src in Gruntfile.js to add or remove scripts which are to be loaded at all times; this includes vendor scripts and modules
  • Put any un-minified JavaScript plugins/libraries in /js/vendor
  • Lazy-load additional scripts using window.suzi.jsVendorPath + 'plugin.name.js'

Use the following template for modules:

var moduleName = (function() {
	// Internal module properties and methods.
	// ...

	return {
		init: function() {
			// ...

		// Exposed module properties and methods.
		// ...


  • 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


  • 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 a CSS gradient with SVG fallback for IE9 and CSS3PIE syntax for LT 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 .grid and .grid__item modifier classes to override standard grid styles with.

    • $name: The suffix to use for .grid and .grid__item classes. For instance, $name: small produces .grid--small and .grid__item--small
    • $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 (default: false)
  • placeholder($color: $form-placeholder-color, $text-transform: $form-placeholder-text-transform)

    Outputs cross-browser placeholder styles using

    • $color: Sets the color of the placeholder text (default: $form-placeholder-color)
    • $text-transform: Sets the text-transform property of the placeholder text (default: $form-placeholder-text-transform)
  • rem($property, $values, $use-px-fallback: $rem-with-px-fallback)

    Converts a pixel value to rems, while also outputting the pixel fallback (optional)

    • $property: valid CSS property
    • $values: valid CSS value in pixels
    • $use-px-fallback: whether to output a pixel fallback as well (default: $rem-with-px-fallback [true])

Class mixins

  • classquery($class-name, $output-ltie9-rule)

    Generates .classquery-$class-name & (optional) .ltie9 [data-classquery*=".classquery-$class-name"] selectors to be used with class.query.js to manage responsive content

    • $class-name: the class name to use (default: default)
    • $output-ltie9-rule: whether to output the .ltie9 rule. Set to false if the class is used for a max-width media query (default: true)
  • clearfix

    Float clearing without hacks for IE7+ and every other browser

  • hidden($hide: true)

    Accessibly hide (and un-hide) an element off-screen

    • $hide: whether to hide or unhide the (default: true)
  • hide-text($display: false, $width: false, $height: false)

    Hide an element's text content

    • $display: sets the display property to a value of your choice (default: false)
    • $width: sets the width of the element (default: false)
    • $height: sets the heightof the element (default: false)
  • horizontal($vertical-align: top, $width: 100%)

    Sets the UL specified and its immediate LIs to use display: table to create an evenly spaced, horizontal list for modern browsers and uses floats for .ltie8. Used in the .horizontal and .horizontal_auto classes

    • $vertical-align: the vertical-align value to give to the child LIs (default: top)
    • $width: the width value to give to the UL (default: 100%)
  • icomoon

    Generates [class^="icon-"], [class*=" icon-"] selector for easy overriding of base icomoon icon font styles

  • icon($name)

    Generates .icon-$name selector for easy overriding of individual icomoon icon font styles

CSS Property mixins

  • background($color, $duplicate-as-pie: false)

    Outputs a background rule with the $color specified. If $duplicate-as-pie is true, it will also output a -pie-background property (useful for overriding a gradient on hover, for example)

  • font-size-line-height($font-size, $line-height: false, $important: false)

    Outputs a rem (and pixel fallback) font-size and an optional unitless line-height from the values provided

    • $font-size: target font-size to achieve in pixels
    • $line-height: target line-height size to achieve in pixels if not false (default: false)
    • $important: whether to also output an !important declaration on both properties (default: false)
  • line-height($target, $context: 16, $important: false)

    Outputs a unitless line-height from the target and context sizes provided

    • $target: target line-height size to achieve in pixels
    • $context: the font-size in pixels of the current element (default: 16)
    • $important: whether to also output an !important declaration (default: false)
  • pie($position: relative, $path: false)

    Outputs a position property and CSS3PIE behavior property with path to PIE.htc

    • $position: position property to use or false for none (default: relative)
    • $path: path to PIE.htc if specified, otherwise uses $default-pie-path variable when false (default: false [$default-pie-path: '/css/PIE.htc'])
  • rgba($property, $value: '', $color: #000, $opacity: 0.5, $use-fallback: true)

    Converts any property's color and opacity to rgba, with the option to output a default fallback color or a composite fallback color of your choice

    • $property: the CSS property to use, for example border
    • $value: an optional value prefix to use, such as 1px solid (default '')
    • $color: color to be converted - either a single value or a list
    • if $color is a list, the second parameter is used as the fallback colour - useful for composite fallbacks
    • $opacity: alpha opacity of the color (default: 0.5)
    • $use-fallback: whether to output the fallback color (default: true)
  • rgba-background($color, $opacity: 0.5, $use-fallback: true, $use-background-color: false)

    Converts a background color and opacity to rgba, with the option to output a default fallback color or a composite fallback color of your choice

    • $color: color to be converted - either a single value or a list
    • if $color is a list, the second parameter is used as the fallback colour - useful for composite fallbacks
    • $opacity: alpha opacity of the color (default: 0.5)
    • $use-fallback: whether to output the fallback color (default: true)
    • $use-background-color: whether to use background-color property instead of background (default: false)

31 transition-timing-function variables are defined in src/partials/_easing-functions.scss

  • viewport($width: device-width)

    Outputs, -moz, -ms, -o, -webkit and unprefixed @viewport with the value passed in (default: device-width)

Media Query mixins

Four variables are provided for media query operators: $min, $max, $min-h & $max-h for min-width, max-width, min-height and max-height, respectively

  • media-query($value, $ltie9: $use-ltie9-mq-fallbacks, $operator: $min, $px: false)

    Outputs a standard media query using ems and an optional .ltie9 fallback

    • $value: pixel value for the breakpoint
    • $ltie9: whether to output .ltie9 fallback (default: $use-ltie9-mq-fallbacks [true])
    • $operator: operator for the breakpoint, e.g. min-width, max-width, min-height, max-height (default: $min [min-width])
    • $px: use px instead of ems
  • media-query-and($mqs, $first-operator: $min, $second-operator: $max, $px: false)

    Outputs a media query with an 'and' condition and an optional .ltie9 fallback (unless max-width is less than $site-width)

    • $mqs: A list (or list of lists) of two pixel values for the first and second breakpoints. If the second value is omitted in a nested list, then it uses the standard media-query() mixin
    • $ltie9: whether to output .ltie9 fallback (default: $use-ltie9-mq-fallbacks [true])
    • $first-operator: operator for the first breakpoint, e.g. min-width, max-width, min-height, max-height (default: $min [min-width])
    • $second-operator: operator for the second breakpoint
    • $px: use px instead of ems
  • media-query-retina

    Outputs a media query for Hi-DPI devices

Forked from Matt Stow's Suzi.

Copyright (c) 2014 Matt Stow
Licensed under the MIT license (see LICENSE for details)