Component Patterns

HTML

Usage: Action link – for blocky hyperlinking. This pattern is used heavily in user interface elements (essential for .project), but can also be used as a standalone element in content.

Specification: High contrast color (typically red) differentiated from body text and other UI. Also commonly in dark shades on index pages. Left-aligned when on its own. Use lower case except for proper names.

HTML

Usage: Links to related resources to the page. An aside like .ancillary but only used at the end of a page.

Specification: Similar to .footnotes: light grayblue-50 background and slightly right-aligned. Although based on the style of .ancillary, they diverge on larger screen sizes.

HTML

Usage: Links and credits to people to thank for help or inspiration. An aside like .ancillary but only used at the end of a page. Include in front matter as thanks, passed through as Markdownified HTML.

Restrictions: End of document by default.

Specification: Similar to .ancillary--endnotes but with an opposing color background (oppositely) left-aligned.

Content flows after or around the <aside> block. The .ancillary block should be used for content that is related to the main body but not necessarily as important – supporting the main story without being directly a part of it. This paragraph represents the layout and style of main body content.

Use with a captured ancillary value and insert with {% include block/ancillary.html %}.

HTML

Usage: For content that is related to the main body but not necessarily as important – supporting the main story without being directly a part of it.

Specification: Lower contrast light background that connects seamlessly with the body background, pushed slightly or significantly to the right of body text on larger layouts.

  1. Using lorem ipsum filler text encourages people reviewing the design not to read the text, which makes it difficult to judge legibility of body text until too late in the design process. Nathan Ford wrote some good words on this topic. Nathan Ford suggests reading tweets instead of ipsum, but I prefer a different approach. If I am constrained in my ability to design content-first, my current practice is to use unread content from my Instapaper queue, so my eyes will focus on trying to read in the working design or prototype.

  2. I wrote more about my preference of minimal tools like Jekyll instead of tools like WordPress in an essay on future-friendliness and robustness.

HTML

Usage: Only used at the end of a page for related references. Used with [^1]/[^1]: pattern in Markdown.

Specification: Similar to .ancillary--endnotes: light grayblue-50 background and slightly right-aligned. Generated by Jekyll after every element in the page layout.

An example image. Never forget alt text.
An example image. Never forget alt text.
HTML

Usage: A grid containing two or more images (or other elements).

Specification: Based on .grid. Similar outer layout to .image–wide, with overflowing margins on larger screens. Flexes to include multiple items, with 1em margins. Typically contains at least one <figure> with an image inside <img>. Figcaption is optional.

An example image. Never forget alt text.
An example image. Never forget alt text.
HTML

Usage: A grid containing two or more images (or other elements).

Specification: Unlike .grid–wide, with margins constrained to the typical width of other content. Flexes to include multiple items, with 1em margins. Typically contains at least one <figure> with an image inside <img>. Figcaption is optional.

<h1>Code block</h1>
<!-- A comment block in HTML -->
<p>This is an HTML code block processed with Rouge and Jekyll.</p>
// An SCSS code snippet
$white: hsl(204, 10%, 95%);

.highlight {
  color: $white;
  margin-top: 1em;
  padding: 1em;
}

// Use {% capture %} tags in Liquid to markdownify blocks of code or captions.

This is a markdownified code caption contained within a parent .code block.

This is a code block with no language specified.
Markdown
HTML

Usage: Code blocks for page layouts. Markdown style is GitHub Flavored Markdown for fenced code blocks.

Specification: High contrast background. Full bleed within page. Only the text color of comments has contrast against the text color of code. No syntax highlighting. <figcaption>s work similarly to photo captions. Parent <figure> should be called .code.

An example image. Never forget alt text.

This is the narrowest possible image pattern.

HTML

Usage: Images that need to take up the full width of the body but not much more. Vertically oriented images are a good use case for this style. Contrast with .image

Specification: Typically 50% width (wider on smaller screens), but this is somewhat layout-dependent. Contains an <img>. Figcaption is optional.

An example image. Never forget alt text.

This is the widest possible image pattern. The figcaption for this style is optional, right-aligned and capped at 50% width on larger screens.

HTML

Usage: Images that need to take up more than the full width of the body for maximum visual impact. Contrast with .image.

Restrictions: Avoid using on images taller than 4:3 ratio. Ideally used for 3:2 or wider.

Specification: Typically greater than 100% width, with overflowing margins on larger screens. Contains an <img>. Figcaption is optional, right-aligned and capped at 50% width on larger screens.

An example image. Never forget alt text.

This is the second-widest possible image pattern.

HTML

Usage: Images that need to take up the full width of the body but not much more, especially at larger screen sizes. Square or vertically photos are a good use case for this style. Contrast with .image--wide and .image--half.

Specification: Typically 100% width, but this is somewhat layout-dependent (bleeds edge-to-edge on small screens). Contains an <img>. Figcaption is optional.

HTML

Usage: Block of text and images for a project summary for including inline in pages. Hand-picked rather than automatically generated for projects.

Restrictions: On any content page.

Specification: Fewer metadata items than a .project. Large navigation action directing to the project page on the site (instead of source or live page for the project). Generated automatically on project pages with Liquid. Image uses background-image (scaled roughly 3:2) from an image from the project. No license information – only original publishing date and updated date.

HTML

Usage: Block of text and images for a project summary with actions for source and links where available.

Restrictions: Only on project pages.

Specification: Different color from body text, with block links to a project source, link, or download. When no link is available, no links are included. Generated automatically on project pages with Liquid. Image uses background-image (scaled roughly 3:2) from an image from the project. Optionally includes license information.