Style Guide

Introduction #

This is Oli Studholme’s personal style guide from oli.jp. We’re reusing it here to give us a head start, but it needs updating. The notes below may not match reality.

→ HTML5 Doctor CSS stylesheet

Assumptions & Setup #

add extra styling directly to head <style>, or add per block, targeted by id and in <style scoped> e.g <table> code like #testing-results .col1, #testing-results .col2 {width: 33%;}
UTF8 and attributes quoted so only these characters need to be entities: “&” & and “<” < (I do “>” > as well via snippets)
main content is inside <article>
the center column is 60%, with min-width = 400px (667px total), and max-width = 672px (1120px total)
the baseline grid is based on 24px, which = line-height (16px/1.5 default font size)
@font-face in effect for headings and code (hopefully won’t be too slow). Deliberately not using for body copy until WebKit fixes bug 25207

Class-based block styles #

Callouts #

These are highlighted (block-level) sections of content:

class="callout" — white box for long asides or content that’s not suitable for marginalia, but not important enough for callout highlight-block; use for diversions/backstory
class="callout highlight-block" — white box with gold border; use for vital content such as a main points summary or disambiguation guide, kind of like a block-level <strong>
class="callout note-block" — pinkish box with pink border and italics; use for author notes when drafting (remove before publishing) as a visual todo reminder
class="callout warning-block" — white box with red border; use for serious warnings
Note <blockquote>, <table> and <img> have similar styles by default (add .clean to container to turn off block <img> styling, and .cleaner to disable border and padding)

`class="callout"` #

In general, use callout highlight-block instead. This style can be used for an aside that’s more important than or too long for marginalia, but not something in need of emphasis.

one
two
three

`class="callout highlight-block"` #

Use this style to emphasise crucial blocks of content (ref: choosing between <article>, <section>, and <div>, Chapter 3)

Able
Miss Baker
Laika

`class="callout note-block"` #

Use this style for author notes — text is italicised by default

`class="callout warning-block"` #

Use this style to warn the reader about serious problems

An example table
Column header	Another header
Row header	Some data

<blockquote> #

Use <blockquote> for including long-form content from other sources. Highlight important text using <mark>. In addition to text in <p>, blockquotes can contain lists, tables etc. Add a citation using <footer><cite><a href="link">Citation source</a></cite></footer>

style guide

Code #

Use a 2 space-per-tab indent. Use <mark> to indicate relevant text (formatted as bold). This is what a standard code block looks like (<pre><code>)

<p>This is what a standard code block looks like (<pre><code>…</code></pre>)</p>

This is the same block with .callout applied

<p>This is what a standard code block with .callout looks like (<pre class="callout"><code>…</code></pre>)</p>

Aside — `sidenote` marginalia #

An <aside> in the right margin for minor content, notes, definitions, reminders or any other short piece of text that’s an addendum and not main content. For longer runs of text consider <aside class="callout">, which appears in the main column.

<aside class="sidenote"><p>…</p></aside>

I place it in the source before the thing I want to describe so it’s level once floated right

Browser support table (and vendor prefix code) #

Basically just a table (aping caniuse.com: check Mozilla Developer Network links for first added dates), but adding the class table.browser-support formats vendor prefixes. Use .warning on <td> to color version number red, then add table note numbers with <sup>1</sup> etc manually. Combine these with <ol class="key"> and make sure your <li> order matches the table notes ;-) These table notes should refer/link to further explanation. I’m using <abbr title=”not supported”>-</abbr> for the unsupported dash. Finally I’ve made <th> 30% wide (to stop <td> from wrapping for no reason), and <code> in <th> has no-wrap.

There’s also an aside style .vendor-prefix for a copy-paste code block to the right of the table (needed?).

-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;

Table 2: Browser support for `box-sizing`
IE	Mozilla	Safari	Chrome	Opera
8.0¹ `-ms-`	1.0 `-moz-` 4.0ß	3.0 `-webkit-`	5.0 `-webkit-`	7.0 `-o-`

IE 8 only supports discombobulation, not full transubstantiation. See Black magicks (relative link) for more info.

Example table for multi-column layout information:

Table 3: this table has the classes `.browser-support.wide`
Property	IE	Mozilla	Safari	Chrome	Opera
`column-width`	-	1.5 `-moz-`	3.0 `-webkit-`	5.0 `-webkit-`	-
`column-count`	-	1.5 `-moz-`	3.0 `-webkit-`	5.0 `-webkit-`	-
`columns`	-	-	3.0 `-webkit-`	5.0 `-webkit-`	-
`column-gap`	-	1.5 `-moz-`	3.0 `-webkit-`	5.0 `-webkit-`	-
`column-rule`	-	3.5 `-moz-`	3.0¹ `-webkit-`	5.0¹ `-webkit-`	-
`column-span`	-	-	-	-	-

WebKit browsers (Safari and Chrome) don’t display a column-rule that’s wider than column-gap (ref).

Columns #

If you’d like to do multicolumn text (I used it for a list of short terms); class="column" = 2 columns, class="columns" = 3 columns. They can also be used with .callout if you want.

one
two columns
three
four
five

one
two
three columns
four
five

one
two
three columns
four
five

Basic block positioning #

Combine these basic classes to add images or examples into text

.left — float: left
.right — float: right
.half — width: 45%
.right.half — automatically add a border on the left to separate
.aside.img — float: right and clear: both
.group — clearfix

Example — list plus image floated right inside `<div class="group">` * #

Visual example of the semantic element nesting in the following list

Page header (site name, logo, search…)
Main navigation
Main content (wrapper)
- Article (main column)
  - Article title
  - Article metadata
  - Article content…
  - Article footer
- Sidebar
  - Sidebar title
  - Sidebar content…
Page Footer

Default element styles #

Headings #

Default sizes are:

<h1> — 2em Quicksand
<h2> — 1.25em Quicksand
<h3> — 1.125em Quicksand
<h4> — 1.125em Helvetica Neue
<h5> — 1em Helvetica Neue bold
<h6> — 1em Helvetica Neue

`<h1>` level heading title (italic, bold)

text

`<h2>` level heading title (italic, bold)

text

`<h3>` level heading title (italic, bold)

text

`<h4>` level heading title (italic, bold)

text

`<h5>` level heading title (italic, bold)

text

`<h6>` level heading title (italic, bold)

text

Note that while I load Museo Sans and Museo Sans italic, I don’t use bold or bold italic fonts (to cut down page weight and because I don’t need them) — don’t use or they may be faked poorly by the browser.

Default table style #

Tables are centered and based on the width of the content by default. For forcing full column width, or for larger tables that also use the margins, you can use:

.wide — center column full width
.wider — center column plus right margin
.widest — center column plus both margins

Note that .wider and .widest kill .sidenote, and all three will break .callout boxes. Don’t forget <thead>! Bonus points for using scope="col|row" ;-)

Table with no width class applied
Pattern	Meaning	Described in section	CSS
*	any element	Universal selector	2

Table with no width class applied, but lots of content
Pattern	Meaning	Described in section	CSS
*	any element	Universal selector Some extra text to demonstrate how table width works when there’s more than one line of content in a table cell	2

Table with `.wide`
Pattern	Meaning	Described in section	CSS
*	any element	Universal selector	2

Table with `.wider`
Pattern	Meaning	Described in section	CSS
*	any element	Universal selector	2

Table with `.widest`
Pattern	Meaning	Described in section	CSS
*	any element	Universal selector	2

Using document or scoped styles you can also control column widths, eg #testing-results .col1, #testing-results .col2 {width: 33%;}

Default image style #

Hanami — cherry blossom viewing

block-level <img>

Hanami — cherry blossom viewing

<img class="clean"> (no box shadow)

Hanami — cherry blossom viewing

<img class="cleaner"> — .cleaner removes border and padding

Example image that’s wide enough to break the layout

<img class="cleaner wide"> — .wide removes max-width (to width: auto;) so images larger than the content column won’t be scaled down

Hanami — cherry blossom viewing inline image (inside <p>)

Default figure style #

Currently images are left-aligned by default, and images in figures are centered by default.

Definition lists #

Albert: A Rhesus monkey who, riding on a V2 rocket to over 63 km on June 11, 1948, became the first monkey astronaut
Albert II: Attained the altitude of 134 km on June 14, 1949, becoming USA’s first space monkey; The Kármán line of 100 km is considered the beginning of space

Phrasing styles & sundry items #

.amp or <abbr title="and">&</abbr> — @simplebits ampersand (&) (for headings; I use <abbr> ;-)
.semantic-list — this suppresses bullets/numbering (eg if you want a list without them)

Default phrasing styles #

First this is a link. Going alphabetically we have an abbreviation, then the <b> element, followed by a line break
next a cite element (browser default), then an inline code example (<code>) containing <mark>. Next ~~some deleted text~~, followed by a definition (no special styling). Emphasised text is semantically different from italicised text. Images inside <p> are automatically inline (outside they’re block). Some inserted text precedes text the user should enter (“enter the password kronos”) via the keyboard (<kbd>), and marked text (<mark>). We then have programming output using <output>, an inline quote using <q>, some legalese using <small>, and a <span> of text (obviously unstyled). For important content there’s <strong>. Subscript text (<sub>) like H₂O and superscript text (<sup>) such as M^me Baker won’t break the measure. Mathematic variables (<var>) like $monkey use the default style. Finally there’s the poorly-supported <wbr> element for indicating acceptable break points in long words. It’s most useful in code samples, for example:

Without <wbr>: <a href="http://www.whatwg.org/specs/webapps/currentwork/multipage/contentmodels.html#phrasingcontent0">
With <wbr>: <a href="http://www.whatwg.org/specs/webapps/currentwork/multipage/contentmodels.html#phrasingcontent0">

Other bits (just in case) #

Making the rollover section links #

<a class="permalink" href="#section-id">#</a> — I add this snippet to the ends of the heading of each section, to give a quick way to refer to the section (eg for feedback via email). I made a TextMate snippet to do this.

My example section #

<section id="example-section">
<h4>My example section <a class="permalink" href="#example-section">#</a></h4>
…
</section><!-- /#example-section -->

In-article table of contents #

This makes a 1/2 width box floated right, intended to contain in-article links (linking to the ids that I added for the .permalink effect). Use <nav class="in-page">, with <h2> for the title. It only has styles for two levels of nesting.

Metadata #

Similar to .sidenote, the class .meta moves things to the left margin. Currently I only use it for article metadata.

The meta style works differently to .sidenote — it’s absolutely positioned using the containing flow element (add .relative to give the containing element position:relative)

Changed blocks (`<ins>` & `<del>`) #

This isn’t an issue at the moment, but there are also styles for inline and block-level inserted content, and inline deleted content.

An inserted block (.callout.changed-block) containing some inserted text (<ins>). I don’t use this style for now ~~but I could if I preferred green over gold for the highlighted blocks (<del>)~~.

HTML5 Doctor

Helping you implement HTML5 today

Style Guide

Introduction #

Assumptions & Setup #

Class-based block styles #

Callouts #

`class="callout"` #

`class="callout highlight-block"` #

`class="callout note-block"` #

`class="callout warning-block"` #

`<blockquote>` #

Code #

Aside — `sidenote` marginalia #

Browser support table (and vendor prefix code) #

Columns #

Basic block positioning #

Example — list plus image floated right inside `<div class="group">` * #

Default element styles #

Headings #

`<h1>` level heading title (italic, bold)

`<h2>` level heading title (italic, bold)

`<h3>` level heading title (italic, bold)

`<h4>` level heading title (italic, bold)

`<h5>` level heading title (italic, bold)

`<h6>` level heading title (italic, bold)

Default table style #

Default image style #

Default figure style #

Definition lists #

Phrasing styles & sundry items #

Default phrasing styles #

Other bits (just in case) #

Making the rollover section links #

My example section #

In-article table of contents #

Metadata #

Changed blocks (`<ins>` & `<del>`) #

Introduction #

Assumptions & Setup #

Class-based block styles #

Callouts #

class="callout" #

class="callout highlight-block" #

class="callout note-block" #

class="callout warning-block" #

<blockquote> #

Code #

Aside — sidenote marginalia #

Browser support table (and vendor prefix code) #

Columns #

Basic block positioning #

Example — list plus image floated right inside <div class="group"> * #

Default element styles #

Headings #

<h1> level heading title (italic, bold)

<h2> level heading title (italic, bold)

<h3> level heading title (italic, bold)

<h4> level heading title (italic, bold)

<h5> level heading title (italic, bold)

<h6> level heading title (italic, bold)

Default table style #

Default image style #

Default figure style #

Definition lists #

Phrasing styles & sundry items #

Default phrasing styles #

Other bits (just in case) #

Making the rollover section links #

My example section #

In-article table of contents #

Metadata #

Changed blocks (<ins> & <del>) #

`class="callout"` #

`class="callout highlight-block"` #

`class="callout note-block"` #

`class="callout warning-block"` #

`<blockquote>` #

Aside — `sidenote` marginalia #

Example — list plus image floated right inside `<div class="group">` * #

`<h1>` level heading title (italic, bold)

`<h2>` level heading title (italic, bold)

`<h3>` level heading title (italic, bold)

`<h4>` level heading title (italic, bold)

`<h5>` level heading title (italic, bold)

`<h6>` level heading title (italic, bold)

Changed blocks (`<ins>` & `<del>`) #