cplorg.bigscoots-staging.com Web Standards

Focusing on code (HTML, CSS, PHP, and JS) and content structure on cplorg.bigscoots-staging.com 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 2023-07-24 Principles: Following the principles in our strategic plan, we: “provide […]

Focusing on code (HTML, CSS, PHP, and JS) and content structure on cplorg.bigscoots-staging.com


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 2023-07-24

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:

Typeface:

– Use Work Sans

Content and Links:

  • Use the proper HTML elements. Mozilla’s MDN on elements has a comprehensive review.
  • Use the heading element to structure your content.
  • Do not skip headings (e.g. h1 to h3) (source Mozilla MDN Heading Element); Generally Use H2 for a new section (H1 is the page title); and then H3 for ‘child’ or of a particular topic that you used with an H2
  • Do not use <strong> or <b> to signify a new section in your text. Use a new heading tag to designate a new section.
  • Use the <ol> tag for ordered lists and <ul> for unordered lists. Do not write 1. 2. 3, to make a list
  • 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”.

Language:

We must designate non-English language for accessibility and search purposes. This can be done by:

  1. Select the text that will be in the other language
  2. Go to the advanced block toolbar settings and select language
  3. Insert the language code that will be used. The language code is two letters. Find the language code by visiting this wikipedia list and using the code under the 639-1 column.

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; per Penn State’s Links Guide. The Nielsen Group also has more do’s and don’ts; including minimizing the phrase ‘Read More’ Gian Wild also has additional contexts and criticisms of WCAG for links.

Do not use the title attribute unless it is an iframe (references: Axesslab info on title attribute and MDN on title Attribute)

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” )

Alt text:

Alt-text provides the context, meaning, and function of images and illustrations to patrons with limited or no vision.

  • 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, leave the alt-text field blank
  • Resources:

URL/link names:

The following practices are based on guides from 18F, Adobe, and Google.

For writing out a URL; write https://cplorg.bigscoots-staging.com or https://www.cplorg.bigscoots-staging.com for the url.
  • – All urls on cplorg.bigscoots-staging.com that begin with www. should be accessible if you omit www. However, remember some of our patrons may not know that it’s unnecessary to begin a url with www, so use your best judgement based on spacing constraints 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://cplorg.bigscoots-staging.com/application-to-cards.pdf); do not include a trailing slash.
  • – Write urls in all lower-case letters. cplorg.bigscoots-staging.com not CPL.ORG
  • – If you’re mentioning a file with an extension (e.g. https://cplorg.bigscoots-staging.com/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 an underscore do not use blank spaces in folder or file names)
  • – If you are linking to another website, do not use URL shorteners like bit.ly, tinyurl.com. Use the url that appears in the browser once the page is finish loading. Do not link to Twitter (“t.co/”)

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: Later selections
has directions how to obtain recent obituaries
. 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 Government Digital Service.) Why:
  • Text on pdfs is optimized for 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.

Our WordPress theme:

Ask Will Skora for assistance; directions at https://gitlab.com/cpl/ernesto

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, 10up’s Best Practices, and more.

CSS:

Please read WordPress’ CSS standards. 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”); – 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. Generally prepend cpl to the beginning of your new selector. e.g. “cpl-button-action”
  • or elements of within a block, use __ to separate a new component;
  • for a modifier, kind of the block; use — to distinguish it; this is known as the Two Dashes style of BEM
  • 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.

Javascript:

Above all, be consistent. Wordpress’ JS code is not consistent. We use ES5 (2021-10 Update: Will be transitioning to ES6 as we dropped IE support) Use Double quotes.

PHP:

ACF field names:

  • separate words by underscores
  • all lower case
  • name the field based what data is inside, not the purposes it’s used for (because it could be reused in the future);

Custom Post Types:

They should be registered outside the theme in a plugin; the post_type name should be singular. More information at Sal Ferrarello’s CPT Best Practices

Blocks and Block Patterns:

Blocks and Block 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.

Block Patterns consist of multiple blocks

Buttons:

(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-button-status (the buttons have not yet been updated to represent the updated BEM naming status) e.g.: Access Lynda.com

Alerts:

Alerts are used to signify a particular scenario that is typically unique to the user or to the subject on the page. More context is available at US Design System

Examples include: locations have lengthy

Developed as a group block and found in the pattern inserter

More information at https://gitlab.com/cpl/cpl-blocks/-/issues/7

Announcements

Announcements are a custom post type, very similar to an alert but are not contextual to a specific page; they are applicable to the entire library announcement criteria: Used to announce time-sensitive closures, news, and emergencies.
  • no ‘title’ or lead-in
  • no programming announcements.
technical considerations
  • uses a paragraph block;
  • the styling lives outside of the block editor (for now);
A smaller Alert! (courtesy of fontawesome)

Common Blocks

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

heading 2

heading 3

heading 4

heading 5
A unnumbered list
  • doe
  • a deer
  • a female deer
  • a pocket full of..

Lesson plan for learning about Cooking with:

  1. mushrooms
    1. shitake
    2. oyster
    3. penny bun
      1. organic penny bun
        1. those grown in the midwest
        2. those grown in the south, different soil conditions, need to cook longer
      2. factory-grown penny bun
  2. hams
  3. pepperoni
  4. peppers
Press F1 to continue.

All code is geared for recent versions (chrome, firefox, and Edge); IE11 support is being phased out

TODO: Add recommended image ratios (below x by X)