Addresses are used to list physical locations.

When to Use

• Address elements are used specifically for mailing/shipping/billing addresses or the physical location of a building/lot/land.

When Not to Use

• Do not use the address element to denote anything else but a physical address.

Usability

• Use logically within the content.
• Work with a content strategist to help set address placement and standards.

Accessibility

• Use the <address> element instead of a stylized <p> element.

A verbatim statement described differently from other content.

When to Use

• Interviews and news content, blockquotes make the most sense in these types of content.
• Dramatic content breaks. Blockquotes are used to help break up content on the page in conjunction with other page elements, such as images, videos, and other components.

When Not to Use

• Do not use the blockquote for content other than a quote.

Usability

• Don’t overuse them. Add them for effect, not to utilize for every quote.
• A blockquote includes verbatim content in quotes. Outside of the quote is a dash with the quote person/entity with an optional next line to denote their title or other unique identifiers.

Accessibility

• Use the <blockquote> element. When citing an entity or using a quote from another location, add cite=”add url” in the <blockquote>.

When to Use

• Always use the PDS color palette for official pa.gov sites and services.

When Not to Use

• Default is to use the color palette unless specifically directed otherwise for your project.

Usability

• .base-offwhite is for backgrounds with dark text (.base-darkgray).
• .base-darkgray is for backgrounds with light text (.base-offwhite).
• .alert-green and .alert-red must use .base-white for text.
• .alert-gold must use .base-black for text.
• Any .alert color is only used for alerts.
• .link-focus is the color used for focus states.
• .base-lightgray is used in navigation with .brand-blue being the color of links in the navbar. .brand-blue is also the hover state color of the nav links with the link text turning to .base-white.

Accessibility

WCAG 2.1 AA and AAA Color Combinations.

Use dividers to define thematic breaks between paragraphs.

When to Use

• Dividers are used to separate content on a page and are used primarily to break up long pages of text, or to separate titles from other content.

When Not to Use

• Table substitution. Do not use dividers as a way to create tables.

Usability

• Judiciously use on long content pages to help break up the content section.

Accessibility

• Do not add any additional ARIA or additional attributes to the <hr>.

Section titles that structure content.

When to Use

• Page titles will always be a <h1> element.
• For content page header organization, the next level element after a <h1> page title is used will be <h2>.
• For subheads, use a <h3> after a <h2> element is used for page headers.
• For additional headers in long content structures, use the additional <h4>, <h5>, and <h6> elements. These additional elements should rarely be used.
• Regarding typeface, always use Montserrat for <h2>, <h3>, <h4>, <h5>, and <h6> elements. Only use the Fungo typeface if specifically directed to do so, otherwise a <h1> will always be Montserrat.

When Not to Use

• Use a <h1>, <h2>, and occasionally <h3> for establishing page structure in this order. Do not use improper nesting.
• For example, do not use a <h1> then a <h3> right afterward. Follow the proper order of headers.
• Do not use bold sentences in place of a header. Headers add structure to the page and will be recognized by Assistive Technology. Bold sentences may look like a header variation, but bold should only be used to emphasize content, not as a faux header.

Usability

• Use proper order and nesting. A page should always have a <h1> starting off the content. Do not put any other header elements before it. Do not mix the logical use of headers. Headers should always descend on the page.
• Multiple <h2> elements can exist on the page and with children headers, but ensure that any subhead <h3> elements are properly nested under them. The existence of other <h2> elements on the page denotes multiple sections of separate content blocks with their own subheads.
• The default font is Montserrat. Do not use Fungo unless specifically directed.

Accessibility

• Write clear header titles.
• Do not add any other ARIA attributes to the header elements.

Icons are used in conjunction with content to communicate meaning.

• The PDS uses a subset of Font Awesome Opens In A New Window icons on the project. They are available for use in src/img. If you need additional icons, use Font Awesome Opens In A New Window in your project. There are some mandatory icons, which are part of select components, that are also packaged in the source files.

When to Use

• When and where custom icons are detailed in the usage of a certain component.
• Use of icons is limited in content and only when appropriate to your project.
• How to Use: use PDS icons available in src/img or add Font Awesome to your project Opens In A New Window. The PDS uses icons in two ways:
  • SVG in HTML img elements.
  • SVG in CSS backgrounds.

When Not to Use

• Do not use icons to replace content that can be written out.

Usability

• Refer to Icon Usability from Nielsen Norman Group Opens In A New Window for more details.

Accessibility

• Provide descriptive text when an icon is meaningful or has an action associated with it. Do not provide additional text when the icon is decorative.
• See Images – Accessibility for Teams Opens In A New Window and Accessibility – Font Awesome Opens In A New Window.

Descriptive text that appears under photos and illustrations.

When to Use

• Contextual caption. Add an image caption to an image/photo/illustration when it makes sense for your content strategy.

When Not to Use

• External interactive content. Do not use with <iframes> to external content.

Usability

• Make sure to add descriptive alt text to your image and ensure your caption aligns to your alt text. You can use a caption to add more content that wouldn’t be appropriate for an alt text description.
• Use both. You can give your image good alternative descriptions and extended captions.

Accessibility

• Add a caption by wrapping an <img> or <canvas> element with a <figure> element and adding a <figcaption>.
• Write good alt="" alternative description for images. Refer to Moz’s article on alt text Opens In A New Window for more information.
• Use the following documentation for images:
  • Be precise: The alt text should describe the content in the image accurately.
  • Keep it concise: A short phrase or sentence will be enough for many images.
  • Imagine you couldn’t see the image. What description is necessary for the reader to understand the information presented in the image?
  • If an image is simply decorative, then the alternative text can just be the word “null” or “decorative.”
  • If you have infographics or images of text (e.g., charts and tables), the alt text should state all of the information provided. Alternatively, you can provide a text version of the information.
  • Avoid using “image of” at the beginning of the description. It’s not necessary since the screen reader will already announce that it is an image.

Links connect citizens to a different page or further information.

When to Use

• In context. When and where it makes sense to link to another resource.

When Not to Use

• Buttons and Link styling. Do not mix link styling with button styling.

Usability

• Visual Indication. Always underline your links.
• External Links. Add the external link icon at the end of your link if it goes to a resource outside of pa.gov. Open those links in new tabs.
• Internal Links. Open internal links in the same tab.
• Contextual Link Labels. Don’t label links as “Click Here” or “Click Me.” Give contextual link labels.
• When linking to an internal document (such as MS Word Document or a PDF), at the end of the link text, add parentheses with the applicable file extension for download.
• When linking to an external document that is not part of the Commonwealth of Pennsylvania’s document repository, also add parentheses with the applicable file extension after the link text and before the external link icon.
• Acceptable formats for Microsoft Office documents: (docx), (pptx), (xlsx), and other MS office output files.
• Acceptable format for PDF files: (pdf).
• When linking to specific and unique output files for download, consult the content developers of those files for the applicable file extension to use and denote in hyperlinks.

Accessibility

• Citizens should be able to tab to navigate between links.
• Citizens should be able to activate a link when pressing "Enter" on their keyboard.
• Citizens should be able to identify links without relying on color alone.
• Citizens should be able to activate hover and focus states with both a mouse and a keyboard.

A block of text.

When to Use

• Narrative content. If you need to create text on the page, use a paragraph.

When Not to Use

• If it’s supporting content structures. Do not style paragraphs to mimic any of the other components in this system (tables, FAQ accordions, lists, etc.)

Usability

• Use paragraph blocks, not one paragraph. Be sure to use both <p> and </p> to encapsulate a paragraph. Do not use <br/> elements to create paragraphs.
• Headers are not paragraphs. Do not wrap a paragraph with a header element instead of a <p> element.

Accessibility

• Do not add any additional ARIA attributes to the <p> element.

Type formatting for websites.

When to Use

• There are specific rules and use cases for font weights and styles on the elements in which they are used.

When Not to Use

• The only deviation from using Montserrat and the associated rules would be to use the typeface Fungo, which must be directly specified in your project.

Usability

• Montserrat Light Italic – Use in the Blockquote element (the quote).
• Montserrat Medium – Use in the Blockquote element (the source).
• Montserrat Regular – Use in body copy, see paragraph element.
• Montserrat Regular Italic – Use in body copy and the Image Caption element.
• Montserrat Bold – Use in body copy and in headlines, see header elements.
• Our REM system is based on 18px instead of 16px. In order to correlate a specific pixel size to REM value, use this formula: (X/18). X is the desired pixel size divided by 18. The resulting number is your REM value.

Accessibility

• Do not add additional ARIA attributes to the <p>, <em>, and <strong> HTML elements.
• The base body copy text is 18px, which forms the new basis for our REM measurements. This aids in the readability of the text.
• Unless directly specified in a style element or pattern, all body copy and type are set to 18px/1rem.