cpl.org Web Standards

Focusing on code (HTML, CSS, PHP, and JS) and content structure on cpl.org

Questions strictly on grammar and usage are not covered in this guide; they are covered in Cleveland Public Library Style Guide at XXXXX, see Laura A. Walter for details.

This guide is designed to:

  • provide consistency in design, quality, and structure of our code and content
  • ensure that best practices for content and code structure are being used where appropriate

Last updated 2018-11-23

Design principles:

Following the principles in our strategic plan, we:

“provide equal access to a vast range of information and
resources.”

– Structure code and design that so content can be usable and accessible to all.
– Accessibility is built into our code, not an afterthought. Our website strives to meet WCAG 2.0 Level AA Our Web Accessibility Policy offers further details.

“actively embrace new ways to adapt the Library to the
changing needs of the people we serve.”

– Don’t use new technology for the sake of using it but only if it helps to serve our patrons and that they want it.

“offer collections that are of interest to our users in ways
that are most convenient for them.”

– Ensuring patrons have access to content through means that are accessible to them.

“are passionate about providing library service to our
community.”

“conduct all interactions with respect and can be counted
on to do the right thing in a fair and equitable manner.”

Design:

Colors:

– Use our internal branding guide for color palette
– Ensure that you have enough contrast (4.5 or greater) between the color of text and the background
This tool from Eightshapes lets you compare foreground and background colors and their levels of contrast
– Exception: Text that is a part of a brand name or logo does not have any contrast requirement
– Do not use color as the only indication of a text’s importance or significance.

– For deciding which colors to use, review the CPL Identity and Brand Standards Manual.

Typeface:

– Use Proxima Nova

Content and Links:

– Ideally, use the proper elements. Mozilla’s MDN has a great comprehensive review of different elements.

– Use the headers tag to to structure your content .
– Do not use <strong> or <b> as headings or for creating sections or

– Use the <ol> tag for ordered lists and <ul> for unordered lists. Do not just write 1. 2. 3, in a list.

Do not use “Click Here” or other directional language for URLs.

For example:
Not: Click here for more details on the library's policy for room reservations .
Instead: Read the library's room reservation policy for additional details.

Do not include the verb as a part of the URL text; according to Penn State. The Nielsen Group also has more do’s and don’ts.
Gian Wild also has additional contexts and criticisms of WCAG

Avoid Using ‘Learn More’
– There are a couple different options: you could include retain the Learn More and add descriptive keywords (e.g. “Learn more about CPL’s partnerships with CMSD” )

Nielsen Norman Group’s Alternatives to Learn More links which has suggestions how to avoid ‘read more’ type links.

Alt Tags:

Appropriate alternative text depends heavily on the image’s context.
– ALT tags provides the content and the function of the image.
– The alt tag for a particular image is dependent on the context. If an image is used in 2 different places; each image’s alt-text may be different since because its alt-text depends on its context.
– Do not include “photo of” or “image of” in beginning of your alt-text
– If no alt-text needed, place a space in the value of  in your code or the media uploader in WordPress.
– Resources
W3’s decision tree for determining what alt text to use
W3’s description on decorative images

URL/link names:

See guides from 18F, Adobe, and Google for more information and Will’s email from 2017-11-24 for recommendations on URLs in print media.


– If you’re writing our URL for a link ; write https://cpl.org for the url.
– a trailing slash is not necessary (i.e. )https://cpl.org/research-learning
– If you’re instructing people to download a specific file and there’s a file extension at the end of the url (e.g. https://cpl.org/application-to-cards.pdf) do not include a trailing slash.
– Write urls in all lower-case letters. cpl.org not CPL.ORG
– If you’re mentioning a file with an extension (e.g. https://cpl.org/application-to-cards.pdf), remember the file name is case sensitive and the url must match the file name
– Generally use
– (More to come regarding proper file names for our digital assets)

linking to a URL on the same page:

If you need to link to a specific section or part a page rather than the entire page, customize the following two snippets:

Our section on recent obituaries

has directions how to obtain recent obituaries.

This is our section on recent obituaries.

You can swap out the div element with h3, li , or other html elements

Content formats

– Make content as HTML instead of PDFs or DOCS (see guides by the US Federal government’s 18F , University of Waterloo’s Web Resources, and the UK’s Goverment Digital Service.)

Why:
Text on pdfs is optimized so that pdfs so that is displayed only in one format – print.
Browsers don’t natively render them; users often cannot adjust the size of the text on PDFs or DOCS without enlarging the entire screen. PDFs do not automatically readjust the text size to the size of the screen, forcing users to scroll in multiple directions.

When to publish as PDFs:
– Document has complex math equations

Installation of our WordPress theme:

Pre-requisites: git, node, and grunt (ask will for help)

Directions:
clone from https://gitlab.com/cpl/tempera-nocopyrt

Do not make edits directly to the CSS files, please first edit the SCSS files instead.
Edit the SCSS in the stylesheets folder
then run grunt sass in the tempera-nocopyrt folder to generate the CSS files with your changes.

Code style/structure:

It’s a combination of best practices from WordPress
, U.S. Web Design Standards, the Vox Accesssibility Guide, 18F Front End Guide, the NYPL Design Toolkit and more.

CSS:

Please read WordPress’ CSS standards and 18F’s Front-End Guide also has good rules regarding naming.

Creating new selectors:
– use - to separate words when specifying selectors e.g. “continue-reading-link”);

– Use Semantic Naming – name your selector by describing its function or the role that it serves; not by its appearance. For example, don’t include a color in the name because the color may change later. Try not to name it based on the content since we may also use the selector in other contexts in the future (bad: purple-writers-and-readers-card; better: writers-and-readers-card; even better: event-card; best: ? )

* If you need to avoid conflicts with the parent theme and are unable to overwrite it (REVISIT THIS – will); prepend cpl to the beginning of your new selector.
e.g. “cpl-button-action”

– Do not use camelCase and underscores in CSS.
There are exceptions to this. A handful of selectors in our parent theme and gravityforms already use underscores.

– Be as specific as possible in your selector if you’re using multiple elements in the selector.

Ask yourself: Am I going to reuse this code on another page or post? If yes, I strongly encourage you to make a CSS Rule instead of writing an in-line rule. Do not use style="") within the browser.

Javascript:

Be consistent; WordPress’ JS code is not consistent.

Patterns/components:

Patterns are pieces of code that can be reused across different pages to create a consistent design and minimize time to recreate content.
The City of Boston issued a Press Release why they created a pattern library.

Buttons:

cpl-button – general button.

Use cpl-button as well as one of the other following classes:

cpl-button-action – yellow, used for action (e.g. Register for a class)

cpl-button-status – pink, used for status

Example:
Use to signify a strong action (submit a form, submit a search result)

e.g.:
Access Lynda.com

Alerts:

alert – general alert button class

use alert as well as one ofthe other following classes:

alert-info – informational (e.g. “the Reading Garden is closed for the season”)

alert-warning – A closure or other drastic notice

Temporarily Closed

The Eastman Reading Garden is currently closed for the season.

A smaller Alert!


Common elements

Main heading – H1

Each page must have a H1 and in nearly all cases on our site, they are the title of the page/post and are automatically generated by WordPress.

Body content, typically within paragraphs

strong, emphasized text in a paragraph class

header 2

header 3

header 4

header 5

strong header 2


strong header 3


strong header 4


strong header 5

    A unnumbered list

  • doe
  • a deer
  • a female deer
  • a pocket full of..
    A numbered list like ranked pizza toppings

  1. mushrooms
  2. ham
  3. green eggs
  4. peppers

Press F1 to continue.

TODO: