Element Library

Introduction

The Playpress Element Library is a set of rules and elemental building blocks that we use to build the Playpress website. It doubles as a test bed where we can see in one place the impact of changes we make.

Look and feel rules

We follow a set of look and feel rules to maintain consistency and create a coherent experience for customers.

We layer the look and feel on to the default styles of the browser.

Typography

We use:

• Sofia Pro in weights of 400 and 700
• a Minor Third scale (with a base of 1em) for text size
• line heights relative to the font size, in ratios of 1, 1.2 and 1.5

To ensure readable type, we:

• limit line lengths to 60 characters
• increase the size of text and space on a shared scale as the viewport grows

We only set the font size on childless nodes to avoid compounding.

Colours

We generate our colours on a perceptually uniform scale using the Lab colour space.

We then represent these colours using HSL notation as this is the most human readable format currently available in browsers.

Colour assignments

For each theme, we assign our colours to abstractions which we use in our elements.

To be accessible, we follow the standard convention that:

• unvisited links are blue
• visited links are purple
• focused elements are yellow
• errors are red

For consistency across dark and light themes, we use lighter colours for elevation.

• drop
• sunken
• background
• elevated
• inset
• input
• input-icon
• separator
• meta
• accent
• icon
• link
• visited
• active
• focus
• error

We use these colours in 5% increments of opaqueness.

Space

We size vertical space around text using the Minor Third scale, relative to the font size. Other space, we size (roughly) in powers of two, e.g. 2, 4, 8, 16 and so on.

Layout

We embrace the browser’s default of Flow Layout. We then responsibly enhance with layout modules like Grid, Flex and Multicol.

Elements

Elements are the building block of our websites.

Elements have a look, feel and behaviour that people expect, e.g. links are underlined and can be opened in a new tab, unlike buttons.

We use two types of elements:

• HTML
• Custom

HTML elements

There are over one hundred elements in HTML.

Content sectioning

We section content using the article, aside, footer, heading, header, nav, main, section, address and br elements.

Text content

We organise text content into blocks using the dl, ol, ul, li, dt, dd, p, div, hr, figure, figcaption, blockquote, q, cite and pre elements.

preformatted

Inline text semantics

We add semantics to inline text using the a, abbr, b, strong, code, data, dfn, em, i, kbd, mark, s, samp, small, span, sub, sup, time, u, var and wbr elements.

Image and Multimedia

We add images and multimedia using the audio, img, track and video elements.

Embedded Content

We embed other content using the embed, iframe, object, picture and source elements.

By combining the picture and source elements, we can offer:

• art direction
• alternative image formats, e.g. AVIF and WEBP

Scripting

We add dynamic content using scripting and the canvas, noscript and script elements.

Demarcating Edits

We demarcate edits using the del and ins elements.

Table Content

We construct tables using the table, caption, col, colgroup, tbody, td, tfoot, th, thead, and tr elements.

Forms

We build forms using the form, button, datalist, option, fieldset, input, label, legend, meter, select, optgroup, output, progress, and textarea elements.

We:

• only ask for information which is absolutely needed
• put required information first
• set the width to fit the information being requested
• add "(optional)" after labels of inputs that aren't required
• limit the number of fields on each page

We avoid:

• unnecessary words in labels like "Please" or "Enter"
• using button-like types on the input element: button, reset and submit
• using disabled states

When using a button, we:

• limit to one on each page
• use a verb, for example "Order"
• only use the accent colour

Interactive Elements

We add further interactivity using the details, summary and dialog elements.

Custom elements

There is a standard set of custom elements for interacting with websites that are understood by customers.

We build on top of these standards and conventions.

Navigation

We avoid using a back link element as this functionality is available in the browser.

We design the main navigation last as it's unlikely to be seen on smaller viewports.

Skip

We use this element so that keyboard customers can tab to the main content.

Breadcrumbs

We use this element so that customers can move back through pages and orientate themselves.

Pagination

We use this element so that customers can move side-ways through pages.

Signpost

We use this element so that customers can move forward through content.

Promo

We also use this element so that customers can move forward through content, but it's promoted in more detail than with the signpost element.

Content

Call out

We use this element to call out content to customers.

Hint

We use this element to provide input hints to customers.

Error

We use this element to inform customers of a per-field error.

Error summary

We use this element to summarise a collection errors for customers.