A proposed style guide for while I was working at ao.com

001-styleguide.md

Goals

Make everything opt-in

Start with a plain base and make any styling changes optional extras that can be added.

• Ensure people can choose what they want.
• Never force changes unless you really mean to. Provide additional functionality via options.
• Expose API-like CSS.
• It’s easier to opt into something than it is to undo it.

Single Responsibility Principle

• One thing, one thing only, one thing well. Keeps things focused!
• Keeps thing small.
• Keeps things composable.
• Think Subway. 🥪

Separation of Concerns

• Let each piece of code solve its own problems.
• Keep things decoupled.

Make everything generic

A style guide should be thought of a design system of components and not set of pages. Having a naming convention that binds a component to its context of a page means its harder to share and scale.

Typography

Problems:

• When a sub heading can only be used for a sub heading (not scaleable)
• The naming convention mixes sizes ('Title large') with context ('Button')
• You can't increase / decrease the size names (Title xl-large, etc...)

... proposed solution 🥁

Naming convention

Split up typography types into headings and body styles.

Style names go up in size

Header styles	Body styles
Header One	Body One
Header Two	Body Two
Header Three	Body Three
Header Four	Body Four
Header Five	Body Five
Header Six	Body Six

CSS classes & mixins

CSS

  @include font-style('header', 'two'); // auto breakpoint
  @include font-style('header', 'two', 'mobile'); // no breakpoint

Mixins

.hero-banner {
  @include font-style('header', 'three', 'mobile');

  @media screen and (min-width: 900px) {
    @include font-style('header', 'one', 'desktop');
  }
}

Inline styles

Base class includes styling and also includes a breakpoint for mobile and desktop.

.u-header-one { @include font-style('header', 'one') }

Modifiers

.u-header-one--desktop {}
.u-header-one--mobile {}
.u-header-one--print {}

Colours

Problems

• Binding the names to context.
• No scope for other variations of colours e.g (brand--darker)
• Not scaleable
• Will neet aliasing to use the colours in correct context
• Hard to use across other sites (Boots, Next)

Proposed Solution

The ideal solution needs to be:

• Generic naming convention, so they're not tied to context
• White label Work across other sites
• Scalable (extra colours and shades)

---

Color-Name Dictionaries

http://chir.ag/projects/name-that-color/

CSS

Colour declarations (one for each theme)

$lima:        #6EB01B; // green
$crimson:     #C9112F; // red
$lipstick:    #CA0051; // pink
$sorbus:      #FD820A; // orange
$supernova:   #FEC30A; // yellow
$dodger-blue: #358DF6; // light blue
$denim:       #0A5DC1; // blue

Semantic variable names (default - ao)

/* Theme Colours Variables
   ========================================================================== */

   $primary:  $dodger-blue  !default; // blue 
   $accent:   $lima         !default; // green


/* Buttons
   ========================================================================== */

   $btn-bg--default:  $alto     !default; // grey
   $btn-bg--primary:  $primary  !default; // blue
   $btn-bg--success:  $lima     !default; // green
   $btn-bg--error:    $crimson  !default; // red

   $btn-color--default:    $white !default; // white
   $btn-color--disabled:   $gray  !default; // grey


/* Stars
   ========================================================================== */

   $star-bg:            $gray       !default; // grey
   $star-bg--filled-in: $supernova  !default; // yellow

CSS component

/* ==========================================================================
   #BUTTONS
   ========================================================================== */

.c-btn {
  color:  $btn-color--default;
}

/* Style variants
   ========================================================================== */

.c-btn--primary {
  background: $btn-bg--primary;
}

/* Colour Utitlies
   ========================================================================== */
.u-color--primary      { color: $primary      !important; }
.u-color--accent       { color: $accent       !important; }


.u-background--primary  { background: $primary  !important; }
.u-background--accent   { background: $accent    !important; }

CSS Methodologies

Atomic OOBEMITSCSS (joke-ish)

buttons-example.scss

/** 
 * ## Buttons 
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent porta placerat mollis. Nulla facilisi. Fusce vel porttitor augue. Mauris auctor tellus ac gravida elementum. Donec ultricies enim eget luctus sodales.
 */

/**
 * Default:
 * `.c-btn` - this is the default button with no stlyes. 
 *
 *     @example
 *     button.c-btn Default Button
 *
 */

 /**
 * Primary:
 * `.c-btn--primary` - this is the default button with no stlyes. 
 *
 *     @example
 *     button.c-btn.c-btn--primary Primary Button
 *
 */

/**
 * Disabled:
 * `.c-btn--disabled` - this is the default button with no stlyes. 
 *
 *     @example
 *     button.c-btn.c-btn--disabled Disabled Button
 *
 */

  /**
 * Expanded:
 * `.c-btn--expand` - this is the default button with no stlyes. 
 *
 *     @example
 *     button.c-btn.c-btn--primary.u-text--center.c-btn--expand Expanded Button
 *
 */

 /**
 * Ghost:
 * `.c-btn--ghost` - this is the default button with no stlyes. 
 *
 *     @example
 *     button.c-btn.c-btn--primary.c-btn--ghost Ghost Button
 *
 */


.c-btn {
  border: none;
  border-radius: $global-radius;
  padding: 16px;
  display: inline-block;
  margin: 0;
  cursor: pointer;
  padding: $spacing-unit-small;
  transition: $global-transition;
  border: none;
  font-family: $base-font-family;
  text-decoration: none;
  font-weight: 700;  
  border: 2px solid transparent;
}


/* Modifiers
   ========================================================================== */ 


.c-btn--primary {
  background-color: $btn-primary-bg;
  color: $btn-primary-color;

  &:hover {
    background-color: $btn-primary-bg-hover;
  }
}


.c-btn--disabled {
  background: $btn-disabled-bg;
  color: $btn-disabled-color;
}


.c-btn--ghost {  
  background-color: transparent;
  
  &.c-btn--primary {
    color: $btn-primary-bg;
    border-color: $btn-primary-bg;

    &:hover {
      color: $btn-primary-color;
      background: $btn-primary-bg;
    }
  }
}


.c-btn--expand {
  width: 100%;
}

buttons.md

Buttons

Default Button

.c-btn {
  padding: $btn-padding;
  border: 0;
  line-height: normal;
  background: none;
  color: inherit;
  overflow: visible;
  appearance: button;
  user-select: none;

}

Primary Button

.c-btn--primary {
    background-color: $btn-bg--primary;

    &:hover {
      background-color: $btn-bg-hover--primary;
    }
}

<a href="#" class="c-btn c-btn--primary u-text-center">Primary</a>

.c-btn--ghost {
border: 1px solid;
background: none;

&.c-btn--primary {
  border-color: $btn-bg--primary;

  &:hover {
    background-color: $btn-bg--primary;
    color: $btn-color--primary;
  }
}

<a href="#" class="c-btn c-btn--primary c-btn--ghost u-text-center">Ghost</a>

<a href="#" class="c-btn c-btn--primary u-text-center">
    <i class="c-icon c-icon--padlock u-padding-right--tiny"></i>
    Large size
</a>

.c-btn--plain {
  background-color: $btn-bg--primary;

  &.c-btn--primary {
    color: $btn-bg--primary;
  }

  &:hover {
    background-color: $btn-bg--primary;
      color: $btn-color--primary;
    }
  }
}

<a href="#" class="c-btn c-btn--primary c-btn--plain u-text-center">Plain</a>

styles.md

ITCSS 🍕

An ITCSS template for a scaleable css architecture. Methodology: OOBEMITSCSS...joke(ish)

To run styledown: styledown app.css config.md > index.html

View the generated style guide here: https://jezfx.github.io/styeguide/

Those layers are as follows:

• Settings – used with preprocessors and contain font, colour definitions, etc.
• Tools – globally used mixins and functions. It’s important not to output any CSS in the first 2 layers.
• Generic – reset and/or normalize styles, box-sizing definition, etc. This is the first layer which generates actual CSS.
• Elements – styling for bare HTML elements (like H1, A, etc.). These come with default styling from the browser so we can redefine them here.
• Objects – class-based selectors which define undecorated design patterns, for example media object known from OOCSS
• Components – specific UI components. This is where majority of our work takes place and our UI components are often composed of Objects and Components
• Utilities – utilities and helper classes with ability to override anything which goes before in the triangle, eg. hide helper class

Self documenting

1. For every new @include in app.scss write a description in the table of contents.
2. When updating a css file, document the changes in the styledown comments.
3. Refer to the ITCSS folder structure(above) when adding a new file.

Naming things:

Use a drill-down naming approach. Name things from ‘biggest to smallest’.

/* Incorrect. */  
.login-btn {}  
.delete-btn {}

.primary-nav {}  
.secondary-nav {}

/* Correct. */  
.btn-login {}  
.btn-delete {}

.nav-primary {}
.nav-secondary {}

.u-color-primary {}  
.u-color-background-primary {}  
.u-color-border-primary {}
.u-color-secondary {}  
.u-color-background-secondary {}  
.u-color-border-secondary {}

• Easy to locate all groups of styles.
• Narrow your intentions as you type.
• The more you type, the more you filter.
• Autocomplete can group related classes.

Commenting

/* ==========================================================================
   Section comment block
   ========================================================================== */

/* Sub-section comment block
   ========================================================================== */

/*
 * Short description using Doxygen-style comment format
 *
 * The first sentence of the long description starts here and continues on this
 * line for a while finally concluding here at the end of this paragraph.
 *
 * The long description is ideal for more detailed explanations and
 * documentation. It can include example HTML, URLs, or any other information
 * that is deemed necessary or useful.
 *
 * @tag This is a tag named 'tag'
 *
 * TODO: This is a todo statement that describes an atomic task to be completed
 *   at a later date. It wraps after 80 characters and following lines are
 *   indented by 2 spaces.
 */

/* Basic comment */