CSS in Kickoff

Philosophy

Kickoff comes with a robust CSS framework; it provides many sensible defaults so that you can get your project up and running in the shortest possible time.

We make use of the excellent Sass CSS preprocessor which allows us to use many extra features beyond the capabilities of vanilla CSS.

This section will take you through how Kickoff uses CSS and Sass, and how easy it is to manipulate the code when developing your own projects.

Notice: v8 breaking changes

Version 8.0.0 of Kickoff changed how various parts of the Sass framework is actually used. In an effort to make the framework more maintainable, certain elements have actually been extracted and made into standalone npm modules. These can then be @import-ed in our main kickoff.scss file.

Kickoff’s external Sass modules

- Kickoff’s Sass utility functions and mixins
- our Sass grid framework
- Simple fluid-width videos using only CSS

3rd party Sass modules

is used for improved media queries, see below for more about this
- Normalize.css is now imported using a Sass port of the library

Other changes

Kickoff’s forms now have basic theme support. Included in the framework is the old ‘standard’ theme and the new ‘Material design’ theme. Switching themes is as easy as changing the import declaration from within assets/src/scss/components/forms/forms.scss. The markup is different between the two themes so make sure you read the docs from within each theme file.
We added support for linting with and use as our rules (with some overrides). Settings for this can be found in the package.json file. It is recommended that you install a stylelint plugin for your IDE.
All mixin and functions included in kickoff-utils.scss have been renamed to include the ko- prefix. It is a form of namespacing so there are fewer conflicts with 3rd party libraries. For example @include font-size(base) is now @include ko-font-size(base)

Sass

Kickoff is made with at its core. It makes developing systems-based CSS faster, easier, and more fun.

Sass has two syntaxes. The most commonly used syntax is known as “SCSS” (for “Sassy CSS”), and is a superset of CSS3’s syntax. This means that every valid CSS3 stylesheet is valid SCSS as well. SCSS files use the extension .scss; we use this version for Kickoff.

scss folder structure

Kickoff structures it’s Sass files in quite a specific way. The scss directory contains the following files and directories:

scss
├── README.md
├── _color-palette.scss
├── _global.scss
├── _helper-classes.scss
├── _reset.scss
├── _typography.scss
├── _variables.scss
├── changelog.md
├── components
│   ├── _buttons.scss
│   ├── _code.scss
│   ├── _embedded-content.scss
│   ├── _icons.scss
│   ├── _links.scss
│   ├── _lists.scss
│   ├── _media-object.scss
│   ├── _scrollbars.scss
│   ├── _skip-navigation.scss
│   ├── _tables.scss
│   └── forms
│       ├── README.md
│       ├── _forms.scss
│       ├── _form-helpers.scss
│       ├── _form-theme-material.scss
│       ├── _form-theme-standard.scss
│       ├── _forms-custom-file.scss
│       ├── _forms-custom-radioscheckboxes.scss
│       └── _forms-custom-select.scss
├── kickoff.scss
├── partials
│   ├── _browser-upgrade.scss
│   ├── _footer.scss
│   └── _masthead.scss
├── styleguide
│   └── _swatch.scss
├── styleguide.scss
└── views
    ├── _home.scss
    └── _print.scss

Elements, components, partials & views

We use a similar philosophy to Atomic Design but instead of atoms, molecules, organisms & templates we use elements, components, partials & views; below is out distinction.

Elements

Elements are single elements.

Components

Components are small, self-contained files that concern one type of thing, that crucially, are reusable. For example, lists, forms etc. We have included quite a few in the directory: & for example, but you should add your components there too. Please the included components to see what Kickoff offers, or see some of them in action in our demo area.

Partials

Partials are partial parts of a page, like a masthead, sidebar or footer. They typically have multiple ‘components’ inside them and can also be reusable. The directory should contain style partials, like _footer.scss or _masthead.scss.

Views

Used for entire views (or pages). Usually these files consist of small tweaks that only concern a particular view. The directory should contain view-specific styles that don’t fit into their own module, think _home.scss or _recipe-page.scss for example. N.b. We recommend that it is better to make reusable components rather than styling based on a view. Therefore, the styles in this folder should be minimal.

Sass utility functions and mixins

Kickoff’s Sass mixins are hosted in a separate git repo, see the documentation for what’s provided at .

Important Sass files

It’s important to become familiar with all of these files so you can make full use of the framework.

All roads lead to here. This is the base SCSS file and is the hook by which Grunt compiles the projects CSS. kickoff.scss is compiled to /assets/dist/css/kickoff.css and is used on Internet Explorer 9+, Chrome, Safari, Firefox and Opera.

This file contains all styles that do not obviously fit within any other scss partial. For example, we include our body’s background styles and the main .l-container styles. Try not to fill this up with all your styles though. Your Sass should be written in a modular way, and so the majority of your Sass should be organised within the components, partials or views directories.

This file contains a bunch of helper styles, like .clearfix (for clearing floats), .ir for using background image replacement, .is-hidden etc.

Sass Variables

We take full advantage of Sass’ variables and there are two key files that should be edited at the start of development on any new Kickoff project. These are scss/_variables.scss and scss/_color-palette.scss.

This is where you define your global Sass variables. Here you can define your:

Global typographic styles — including font choices and typographic scale.
Responsive breakpoints — we try not to target specific devices or device types with these variables. Instead they should be set with the design in mind. The $breakpoints sass map, contains our default breakpoints, these are used by the grid and can be referenced by using the bp(mid) sass function. See how to use the breakpoints when using our mixins, below.

Text colour, link colours, background colour, form fields and various component colours can all be set in this file.

Useful CSS classes & styles

.l-container: found in /assets/src/scss/_global.scss, this class controls the main content ‘column’ on your site.
.btn: found in /assets/src/scss/components/_buttons.scss for buttons. See the possible modifiers on the components demo page
Anchor links (a) are styled in /assets/src/scss/components/_links.scss
.l-mb0 or .l-mt0: for zeroing any margin-bottom/top values. See also the other helper classes in /assets/src/scss/_helper-classes.scss
.clearfix: for clearing floats. See also the other helper classes in /assets/src/scss/_helper-classes.scss
.h1, .h2, .h3, .h4: font-sizing helper classes for headings

Responsive

Kickoff does not enforce a mobile first approach to CSS, but it is encouraged and it takes a fairly unique approach to responsive sites.

Media queries

#### Media queries v8.0.0 and above Kickoff v8.0.0 introduced a new mixin library to handle media-queries. This library, allows for a more simple syntax and better control of media-queries. There is just one mixin call that takes a few different options:

Example

// The keywords below are from the $breakpoints map in _variables.scss

// Equivalent to min-width query
@include media(">mid") {
	width: 50%;
}

// Equivalent to min-width and max-width query
@include media(">narrow", "<=wide") {
	width: 50%;
}

// Equivalent to min-width
@include media(">200px") {
	width: 50%;
}

There are more features to the library so please . Both Kickoff and the Kickoff grid make use of this library.

Media queries v7.0.0 and below

Media queries in Kickoff are typically handled with a . These are used so that we can define separate media-query content for < IE9 and browsers with support for media queries. These are directly related to the global $fix-mqs var defined in kickoff-old-ie.scss. kickoff-old-ie.scss ignores any content in media-queries with values less than the $fix-mqs var value.

respond-min for min-width media queries
respond-max for max-width media queries
respond-min-max for min-width & max-width media queries

It is worth noting that these mixins still work in version 8+, but along with v8’s naming conventions, they include a namespace as well, e.g. ko-respond-min.

Example

/**
 * This Sass mixin:
 * The value for the width should be unitless and we suggest
 * using your predefined breakpoint variables as the argument
 */
@include respond-min(800) {
	a {
		color: darkgoldenrod;
	}
}
/* Is the same as: */
@media screen and (min-width: 800px) {
	a {
		color: darkgoldenrod;
	}
}

/**
 * All the mixins:
 */
@include respond-min(wide) {
	a {
		color: darkgoldenrod;
	}
}
@include respond-max($bp-single-col) {
	a {
		color: green;
	}
}
@include respond-min-max(narrow, mid) {
	a {
		color: purple;
	}
}

Better media query example

Rather than having all of your media queries for different widths stored in separate scss files or placed at the bottom of each SCSS partial, we suggest making use of Sass’ nested media queries.

This means that all styles related to an element are together, for example:

a {
	padding: 1em;

	@include media('>800') {
		padding: 2em;
	}
}

CSS Naming scheme

Kickoff uses a bespoke naming scheme for classnames, inspired loosely by the .

This obviously isn’t compulsory to use in your own Kickoff projects, but is documented here as guidance, and is what we use across our Kickoff projects.

/* Descriptors use camel-casing if more than one word: e.g. twoWords */
.form {
	...
}

/* ========= */

/* Child elements use single hyphens: - */
.form-controlGroup {
	...
}

/* ========= */

/* Modifier element use a double hyphen: -- */
.form {
	...
}
.form--horizontal {
	...
}

/* ========= */

/* Element state: .is- or .has- */
.is-active {
	...
}

/* ========= */

/* Sass variables use dash-case */
a {
	color: $color-primary;
}

Module naming helper mixins

In v7, we included some mixins to help keep consistent CSS output. See below:

@include component('foo') {
	margin: auto;

	@include modifier('bar') {
		padding: 20px;
	}

	@include modifier('baz') {
		padding: 50px;

		@include respond-min(mid) {
			padding: 20px;
		}
	}

	@include state('active') {
		background-color: green;
	}
}

.foo {
  margin: auto;
}

.foo--bar {
  padding: 20px;
}

.foo--baz {
  padding: 50px;
}

@media screen and (min-width: 46.875em) {
  .foo--baz {
    padding: 20px;
  }
}

.foo.is-active {
  background-color: green;
}

Modernizr

Kickoff includes a version of Modernizr but it is not used by default. If you are using our new grid and are supporting IE8 or below, you will need it to detect flexbox support. To find out how to use it, see or see our Javascript documentation to find out where it is included.

Kickoff

CSS in Kickoff

Philosophy

Notice: v8 breaking changes

Kickoff’s external Sass modules

3rd party Sass modules

Other changes

Sass

scss folder structure

Elements, components, partials & views

Elements

Components

Partials

Views

Sass utility functions and mixins

Important Sass files

Sass Variables

Useful CSS classes & styles

Responsive

Media queries

Example

Media queries v7.0.0 and below

Example

Better media query example

CSS Naming scheme

Module naming helper mixins

Modernizr

Where next?

Kickoff's Javascript

Tooling

Kickoff