Style guide

I’ve redesigned my site for the umpteenth time now. One big phase has always been the work on the basic visual appearance. Up until now, I scavanged my archive for posts that have the elements that needed to be styled: code blocks, quotes, etc. This was a tedious process. Now, I use this document containing all basic forms of content my site uses. My personal style guide.

What I mean with “basic forms of content” can be summarized by listing the set of elements on a page that can be styled with plain CSS element selectors (i.e. without any classes). If you’re familar with Harry Roberts’ Inverted Triangle CSS methodology, the style guide deals only with the elements layer.

Contents

Inline Styles

The most common forms of emphasis are italics and bold text. Mostly seen in handwritten notes, another form is a mark. It tends to stick out of its context in a rather attention-grabbing fashion so be careful when to use this.

Rarely, you see abbreviations like MDN (Mozilla Developer Network) marked up with the abbr element. However, note that the title attribute is often not conveyed to assistive technology; therefore, it’s best to add the expansion as regular text on first usage of the abbreviation.

Edits made to a text can be repersented represented by marking up the parts that were deleted with <del> and inserted with <ins>.

One can mark up keyboard shortcuts such as Ctrl+D with <kbd> tags. Inline code is usually added in <code> tags.

Lists

  1. First list item

  2. Second list item

    with content spanning

    multiple paragraphs.

  3. Third list item

    1. More creativity

    2. Even more creativity

Quotes

Whenever accessibility is really hard, it’s usually just an over-complex component and should be dumped anyway.

Heydon Pickering

As my grandma used to say Remember, there is a proper HTML element for when one wants to quote inline.

Code

By default, code blocks work well but are rather limited compared to what we see in our text editors. It would be nice to have automatic line numbers. Maybe this can be done with CSS counters and by wrapping each line of code in its own code element.

pre {
  padding: 0.5em 1em;
  overflow-x: auto;
  background-color: var(--c-code-block-background);
  border-radius: 0.5em;
}

Headings

Heading Level 1

Heading Level 2

Heading Level 3

Heading Level 4

Heading Level 5
Heading Level 6

Images

Rain drops on a spiders’ web
via Flickr, shot with a Helios 44-2 1:2.0/58mm manual lens.

A figures’ caption should have a slightly smaller text size than regular text.