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
Last updated 2019-12-04
Following the principles in our strategic plan, we:
“provide equal access to a vast range of information and
- “actively embrace new ways to adapt the Library to the
changing needs of the people we serve.”
- “offer collections that are of interest to our users in ways
that are most convenient for them.”
- “are passionate about providing library service to our
- “conduct all interactions with respect and can be counted
on to do the right thing in a fair and equitable manner.”
– 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.
– 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.
– Ensuring patrons have access to content through means that are accessible to them.
– 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.
When using instructive language on the website, do not solely rely on direction or color.
E.G. Do not say “Click on the yellow button” or “Complete the form above”; instead say “select the registration button”.
– Use Proxima Nova
Content and Links:
– Ideally, use the proper HTML elements. Mozilla’s MDN on elements has a comprehensive review.
– Use the heading element to to structure your content.
– Do not skip headings (e.g. h1 to h3) (source Mozilla MDN Heading Element)
– Do not use
<b> as headings or to creating sections; use a heading.
Do not use “Click Here” or other directional language for URLs.
Do not include the verb as a part of the URL text; according to Penn State’s Links Guide. The Nielsen Group also has more do’s and don’ts.
Gian Wild also has additional contexts and criticisms of WCAG for links.
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 has suggestions how to avoid ‘read more’ type links.
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 the same 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
– W3’s decision tree for determining what alt text to use
– W3’s description on decorative images
– For writing out a URL; write
https://www.cpl.org for the url.
– All urls on cpl.org should be accessible if you omit www. However, remember some of our patrons do not know that it’s not necessary to begin a url with www, so you can use your best judgement based on spacing whether to include www).
– a trailing slash at the end of the url is not necessary
– 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.
– 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.
– in file names and page names, omit articles (a, an, the) and conjunctions (for, but, of) unless it is a part of the CPL brand (e.g. CLE FOR GOOD)
– (More to come regarding proper file names for our digital assets)
– use present tense of verbs; no gerunds (e.g. /make-crafts instead of /making-crafts)
– separate words by a hyphen instead of underscores (do not use spaces in paths and file names)
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:
You can swap out the div element with h3, li, or other html elements
- Text on pdfs is optimized so that pdfs so that is displayed only in one format: print.
- Browsers don’t natively render them;
- PDFs do not automatically readjust the text size to the size of the screen, forcing users to scroll in multiple directions and lose their place.
When to publish as PDFs:
– Document has complex math equations
Our WordPress theme:
Ask Will Skora for assistance; directions at https://gitlab.com/cpl/tempera-nocopyrt
Creating new selectors:
- to separate words when specifying selectors e.g. “continue-reading-link”);
– A handful of selectors in our parent theme and gravityforms already use underscores.
– We’re transitioning to more BEM-based naming schema and code structure
– Name components by using singular nouns (e.g. cpl-button; NOT cpl-buttons)
– 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: card-event; best: ? )
– Use one selector and one declaration per line
* Many components are prefixed with cpl- to avoid conflicts with the parent theme and any plugins.
cpl to the beginning of your new selector.
Be liberal with commenting.
Ask yourself: Am I going to reuse this code on another page or post? If yes, I strongly encourage you to ask Will to make a css rule in the stylesheet; Do not use
style="") within the browser.
Above all, be consistent.
WordPress’ JS code is not consistent.
We use ES5.
Use Double quotes.
Be consistent; follow WordPress’ PHP coding standards
Single quotes unless you need to escape.
Use the WordPress-Core coding standards if your PHP is going into WordPress.
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.
These are generally prefixed by
(in this instance, we’re using this often muddled term to describe 2 distinct actions: a very prominent link or a button. Use the
button element (traditional sense of toggling statuses, changing a feature on a page and DOES NOT direct a user to a new page). Use the
a element for prominent links; there’s also the input element that is used
for submitting forms.
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 an event, submit a form); typically will drive the user to a new site or complete an action that will direct them to a new page.
cpl-alert – general alert button class
use cpl-alert with one the other following classes:
cpl-alert-info – informational, long-term announcement (e.g. “the Reading Garden is closed for the season”)
cpl-alert-warning – A sudden closure or something more dire.
The Eastman Reading Garden is currently closed for the season.
A smaller Alert! (courtesy of fontawesome)
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
- A unnumbered list
- a deer
- a female deer
- a pocket full of..
- A numbered list like ranked pizza toppings
- green eggs
Press F1 to continue.
Add recommended image ratios