Styleguide
CSS standards & conventions
Elements
HTML basics
In order to normalize HTML elements cross-browser, I use my own flavor of Nicolas Gallagher's normalize.css
. It has a few tweaks here and there, but nothing major is changed. I keep that in a Sass directory named dependencies
, where I also store partials for fonts, functions, icons and variables. Element styles that pertain specifically to the designs I build are kept in an elements
directory. Element styles for this site are shown below.
Code
For syntax highlighting, I use Google's Prettify script. I'm aware of several popular alternatives, but in my experience Prettify is a great solution — it's fast, accurate and covers a ton of languages. I keep a _prettify.scss
partial in a Sass directory named plugins
, along with other partials that are specific to plugins and scripts. My _code.scss
partial is quite basic.
// --------------------------
// ---------- CODE ----------
// --------------------------
code {
display: inline-block;
padding-left: 0.25rem;
padding-right: 0.25rem;
background-color: lighten($off-white, 2%);
pre & {
display: inline;
padding-left: 0;
padding-right: 0;
background-color: transparent;
}
}
Forms
Headings
I keep heading styles fairly simple. I have a heading mixin that defines some basic styles that are used in heading classes. Those classes are then extended to the heading elements. This allows semantic use of headings, without design contraints, as shown in each paragraph element below.
Heading Level 1
Heading Level 2
Heading Level 3
Heading Level 4
Heading Level 5
Heading Level 6
Heading Level 1
Heading Level 2
Heading Level 3
Heading Level 4
Heading Level 5
Heading Level 6
Heading Level 1
Subheading for H1s
Heading Level 2
Subheading for H2s
Heading Level 3
Subheading for H3s
H3 as H1
Subheading for H1s
H2 as H3
Subheading for H3s
H1 as H2
Subheading for H2s
Lists
Unordered List
- List item
- List item
- List item
Ordered Lists
- List item
- List item
- List item
Horizontal List
- List item
- List item
- List item
Icon List
Number List
- List item
- List item
- List item
Tables
Standard Table
First Name | Last Name | Occupation |
---|---|---|
John | Doe | Designer |
Jane | Doe | Developer |
Jim | Doe | Administrator |
Bare Table
First Name | Last Name | Occupation |
---|---|---|
John | Doe | Designer |
Jane | Doe | Developer |
Jim | Doe | Administrator |
Fixed Table
First Name | Last Name | Occupation |
---|---|---|
John | Doe | Designer |
Jane | Doe | Developer |
Jim | Doe | Administrator |
Modules
Reusable chunks
I\'ve long been inspired by Nicole Sullivan\'s OOCSS, and in recent years, BEM. All CSS that I write is anchored by those methodologies, as well as a loose mixture of others like SMACCS and ACSS. Below are the modular chunks of CSS for this site, each of whose code lives in its own partial inside a Sass directory named modules
.
Callout
Message
Search
Utilities
Little helpers
Always is the case that you need small CSS rules to nudge a design one way or another. I call these micro rules that aid the pursuit of pixel perfection utilities. I keep a utilities
directory inside of which I have partials for color, layout, spacing and text. Below you can see these narrowly-scoped utility classes in action.
Color
Gray | Red | Orange | Green | Blue |
Dark Gray | Dark Red | Dark Orange | Dark Green | Dark Blue |
// ---------------------------
// ---------- Color ----------
// ---------------------------
// ------
// MIXINS
// ------
@mixin text-color($color) {
color: $color;
&--before {
&:before {
color: $color;
}
}
&--after {
&:after {
color: $color;
}
}
}
// ------
// STYLES
// ------
// Color
// -----
.gray {
@include text-color($gray);
}
.gray--dark {
@include text-color($gray--dark);
}
.red {
@include text-color($red);
}
.red--dark {
@include text-color($red--dark);
}
.orange {
@include text-color($orange);
}
.orange--dark {
@include text-color($orange--dark);
}
.green {
@include text-color($green);
}
.green--dark {
@include text-color($green--dark);
}
.blue {
@include text-color($blue);
}
.blue--dark {
@include text-color($blue--dark);
}
Layout
// ----------------------------
// ---------- LAYOUT ----------
// ----------------------------
// ------------
// PLACEHOLDERS
// ------------
// Layout placeholders are located in the structure/_layout.scss
// ------
// MIXINS
// ------
// Layout mixins are located in the structure/_layout.scss
// ------
// STYLES
// ------
// Floating
// --------
.clearfix {
@extend %clearfix;
}
// Visibility
// ----------
.visually-hide {
@extend %visually-hide;
}
.visually-show {
@extend %visually-show;
}
// Layout
// ------
.display--none {
display: none;
}
.display--block {
display: block;
}
Spacing
// -----------------------------
// ---------- SPACING ----------
// -----------------------------
.margin--none {
margin: 0;
}
.margin-top--none {
margin-top: 0;
}
.margin-bottom--none {
margin-bottom: 0;
}
.margin--xsmall {
margin: $space--xsmall 0;
}
.margin-top--xsmall {
margin-top: $space--xsmall;
}
.margin-bottom--xsmall {
margin-bottom: $space--xsmall;
}
.margin--small {
margin: $space--small 0;
}
.margin-top--small {
margin-top: $space--small;
}
.margin-bottom--small {
margin-bottom: $space--small;
}
.margin--medium {
margin: $space--medium 0;
}
.margin-top--medium {
margin-top: $space--medium;
}
.margin-bottom--medium {
margin-bottom: $space--medium;
}
.margin--large {
margin: $space--large 0;
}
.margin-top--large {
margin-top: $space--large;
}
.margin-bottom--large {
margin-bottom: $space--large;
}
.margin--paragraph {
margin: $space--paragraph 0;
}
.margin-top--paragraph {
margin-top: $space--paragraph;
}
.margin-bottom--paragraph {
margin-bottom: $space--paragraph;
}
.margin--block {
margin: $space--block 0;
}
.margin-top--block {
margin-top: $space--block;
}
.margin-bottom--block {
margin-bottom: $space--block;
}
.margin--section {
margin: $space--section 0;
}
.margin-top--section {
margin-top: $space--section;
}
.margin-bottom--section {
margin-bottom: $space--section;
}
.margin--hero {
margin: $space--hero 0;
}
.margin-top--hero {
margin-top: $space--hero;
}
.margin-bottom--hero {
margin-bottom: $space--hero;
}
Text
// --------------------------
// ---------- TEXT ----------
// --------------------------
// Alignment
// ---------
.text--left {
text-align: left;
}
.text--right {
text-align: right;
}
.text--center {
text-align: center;
}
// Presentation
// ------------
.text--nowrap {
white-space: nowrap;
}
.text--underline {
text-decoration: underline;
}
.text--strike {
text-decoration: line-through;
}
// Size
// ----
.text--small {
font-size: $font-size--small;
}
// Disclaimers
// -----------
.disclaimer {
color: $text-color--disclaimer;
}
Social
Styleguide Navigation