CSS code style guide for UCSF Library website - ucsf-ckm/ucsf-library-ux-and-web-documentation GitHub Wiki

Inspired by

• CSS Style Guides by Chris Coyier
• Code Style Guide: CSS from ThinkUp

Context

• Our custom CSS only reflects changes made to override or add to the styles generated by the chosen WordPress theme and Elementor Pro page builder plugin
• There are many best practices that only apply when you control all the code (e.g. splitting css into multiple files, global reset, BEM file naming, use a preprocessor, etc.,) so those will not be outlined here

Caveats

• Since we have only partial control, there may be rare instances where there’s just no other way except using !important but avoid as much as possible. Tends to cause more specificity problems than it solves.
• In general, we should be using classes and avoiding IDs, but there may be exceptions when styling existing HTML where we can’t add a class.

Comments

Comments and readable code are crucial for understanding and maintenance. CSS minification of the final version should eliminate performance concerns.

Begin with a defining comment like this, but suited to our site and styles

/*------------------------------------------------------------------
[Master Stylesheet]

Project:    Smashing Magazine
Version:    1.1
Last change:    05/02/08 [fixed Float bug, vf]
Assigned to:    Vitaly Friedman (vf), Sven Lennartz (sl)
Primary use:    Magazine 
-------------------------------------------------------------------*/

Only C style comments are valid for CSS code:

/* Comment goes here */

Do not use C++ style comments like

// Comment goes here

Comments that refer to selector blocks should be on a separate line immediately before the block to which they refer.

Short inline comments may be added after a property-value pair, preceded with a space.

/* Comment about this whole selector block. */

selector {
  property: value; /* Comment about this specific property-value pair. */
}

Sometimes a longer, explanatory comment is in order and can be formatted like this:

/**
 * 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.
 *
 * 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.
 */

Constants

Optional, but useful for quick reference as suggested by Rachel Andrew. Create some definitions at the top of your CSS file in comments, to define constants like color palette, typography, etc.

/*------------------------------------------------------------------
[Color codes]

Background: #ffffff (white)
Content:    #1e1e1e (light black)
Header h1:  #9caa3b (green)
Header h2:  #ee4117 (red)
Footer:     #b5cede (dark black)

a (standard):   #0040b6 (dark blue)
a (visited):    #5999de (light blue)
a (active): #cc0000 (pink)
-------------------------------------------------------------------*/

Structure

Structure the CSS file based on sections of the site, rather than grouping all colors together, all typography, etc.

TOC

For easier finding and editing, include a table of contents outlining each section, and use a + to prepend titles. A search for +Sidebar will only ever find the section with that name, whereas a search for just sidebar could find something like: .btn.sidebar

/*------------------------------------------------------------------
[Table of contents example]

+Body
+Header 
+Navigation 
+Content 
+Left column 
+Right column 
+Sidebar 
+RSS 
+Search 
+Boxes 
+Sideblog
+Advertisements
+Footer
-------------------------------------------------------------------*/

Highlight sections throughout the document clearly using this format:

/* ==========================================================================
   +Sidebar
   ========================================================================== */

If needed, also make sub-sections clear using this format:

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

Space

Leave five carriage returns between each TOC section. With that white space and the horizontal lines from headers, sections stand out easily when scanning the code.

Indentation

Use an indent of one tab (no spaces)

Names and Capitalization

Class names should be in lowercase, with words separated by hyphens.

.my-class-name {

HTML elements should be in lowercase.

body, div {

Avoid using ID names in CSS. Fine for JavaScript usage.

#my-id-name {

Selectors

• When working on a team, multi-line CSS is the way to go for scannability and for diff tools to be effective.
• Selectors should be on a single line, with a space after the last selector, followed by an opening brace.
• A selector block should end with a closing curly brace that is unindented and on a separate line.
• A blank line should be placed between each selector block.
• Selectors should never be indented.

selector {
}

selector {
}

Multiple selectors should each be on a single line, with no space after each comma.

selector1,
selector2,
selector3,
selector4 {
}

Selector Intent

Be a CSS sniper, not a CSS carpet bomber. Are you being specific enough? Are your selectors matching things for the right reasons, and are they future proof of you add another <ul> or <h2>? Are you using descriptive names when creating classes? Examples unpacked by Harry Roberts. Also, shorter selectors reduce location dependency and increase portability.

Property-Value Pairs

Property-value pairs should be listed starting on the line after the opening curly brace. Each pair should:

• be on its own line
• be indented one level
• have a single space after the colon that separates the property name from the property value
• end in a semicolon.

selector {
  name: value;
  name: value;
}

Multiple property-value pairs should be listed in alphabetical order by property. Easier than by importance which can be subjective and hard to keep consistent.

body {
  background: #fdfdfd;
  color: #333;
  font-size: 1em;
  line-height: 1.4;
  margin: 0;
  padding: 0;
}

For properties with multiple values, separate each value with a single space following the comma(s).

font-family: Helvetica, sans-serif;

If a single value contains any spaces, that value must be enclosed within double quotation marks.

font-family: "Lucida Grande", Helvetica, sans-serif;

Shorthand

Use shorthand properties whenever possible, but keeping each on a separate line, for example:

.box {
  border: 1px solid #000;
  font: italic bold .8em/1.2 Arial, sans-serif;
  padding: 10px 5px 10px 5px;
}

Colors

Use hex code for colors, or rgba() if opacity is needed. No uppercase, and shorten values when possible: #fff instead of #FFFFFF.

Dimensions

When denoting the dimensions – that is, the width or height – of an element or its margins, borders, or padding, specify the units in either em, px, or %. If the value of the width or height is 0, do not specify units.

  width: 12px;  /* Okay */
  width: 12%;   /* Okay */
  width: 12em;  /* Okay */
  width: 12rem; /* Okay */
  width: 0;     /* Okay */
  width: 12;    /* Not okay */
  width: 0px;   /* Not okay */