Components

Components form the basic building blocks of the PDS. We’ve identified and created the most commonly used components that are utilized in websites. Each of the components include the work component, a code snippet detailing its construction, usage considerations detailing when and when not to use an item, general usability considerations, and accessibility requirements.

Accordions

Accordion Container

An accordion is a list of headers that hide or reveal additional content when selected.

When to Use

  • If the citizen only needs a few, specific, contextual bits of information within a page.
  • If you only have a small space to display a lot of content.
  • If you are using an accordion menu, make sure to use on a page as part of a sidebar, not part of the modal or other nested elements.

When Not to Use

  • If citizens need to see all the content on the page, do not use the accordion.
  • If there is not enough content to warrant its use.
  • If you are using an accordion menu, use a regular sidebar menu if you don’t have any child pages that would exist in the accordion.

Usability

  • If you are using the accordion menu, the chevron is the button to activate the show/hide. Do not make the link headline into the trigger for the show/hide.
  • You can make the headline link to another page without activating the trigger to show/hide sub-links.
  • Use the Accordion Menu Unstyled as part of the side navigation pattern when you have site navigation that includes child pages under a parent page. This would replace the list view of the side navigation links with a more robust navigation system for mobile.
  • Use the Accordion Menu as part of the sidebar if you require robust sidebar navigation more than just a list of links. Each link should go to a unique page. The chevron should toggle the list of child pages only. When you open a link from the accordion menu that does have child pages, do not automatically expand the accordion.
  • The FAQ Accordion is to be used in main content areas or sidebar areas when/where applicable. The FAQ Accordion is intended for question and answer type of content. You can include links, images, and other rich media when appropriate.
  • When appropriate (six or more accordion sections), use the Primary Button component labeled "Expand All" with a title="Expand All Accordion Sections" after the accordion appears on the page.
  • Do not add the "Expand All" button to the Accordion Menu or Accordion Menu Unstyled, use it only for Accordion Container and FAQ Accordion.
  • Ensure the "Expand All" button does not create recursive patterns for citizens to get stuck in the Accordion Container and FAQ Accordion.

Accessibility

  • Code headline links in the accordion as buttons.
  • Using a <button> assures that accordions are usable with both screen readers and the keyboard.
  • Use aria-expanded on buttons to express an accordion’s default state.
  • Buttons should state if they are expanded by default with aria-expanded="true". The aria-expanded="false" attributes will be added to other buttons when the accordion is initialized by the JavaScript.
  • Use unique ids.
  • Each button has a unique name aria-controls="id" that associates the control to the appropriate region by referencing the controlled element’s id.
  • The accordion uses javascript to set the aria-hidden value of its content area.
  • Each content area will have its aria-hidden attribute set to either true or false by the component, depending on its corresponding button’s aria-expanded attribute. To ensure that your content is accessible in the event that the JavaScript does not load or is disabled, you should not set aria-hidden="true" on any of your content areas.
Select Code
<ul class="accordion" data-accordion="accordion-container-id" data-allow-all-closed="true" role="tablist">
	<li class="accordion-item is-active" data-accordion-item="" role="presentation">
		<a aria-controls="accordionContainerId1" aria-expanded="true" aria-selected="true" class="accordion-title" href="#!" id="accordionContainerItemId1Label" role="tab">Accordion 1</a>
		<div aria-hidden="false" aria-labelledby="accordionContainerItemId1Label" class="accordion-content" data-tab-content="" id="accordionContainerId1" role="tabpanel" style="display: block;">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie. Morbi et magna rutrum, pharetra augue a, maximus arcu. Vivamus mollis accumsan purus sed commodo. Aenean fringilla urna at enim tincidunt, vitae molestie velit euismod.</p><a href="#!">Example Link</a>
		</div>
	</li>
	<li class="accordion-item" data-accordion-item="" role="presentation">
		<a aria-controls="accordionContainerId2" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionContainerItemId2Label" role="tab">Accordion 2</a>
		<div aria-hidden="true" aria-labelledby="accordionContainerItemId2Label" class="accordion-content" data-tab-content="" id="accordionContainerId2" role="tabpanel" style="display: none;">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie. Morbi et magna rutrum, pharetra augue a, maximus arcu. Vivamus mollis accumsan purus sed commodo. Aenean fringilla urna at enim tincidunt, vitae molestie velit euismod.</p><a href="#!">Example Link</a>
		</div>
	</li>
	<li class="accordion-item" data-accordion-item="" role="presentation">
		<a aria-controls="accordionContainerId3" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionContainerItemId3Label" role="tab">Accordion 3</a>
		<div aria-hidden="true" aria-labelledby="accordionContainerItemId3Label" class="accordion-content" data-tab-content="" id="accordionContainerId3" role="tabpanel" style="display: none;">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie. Morbi et magna rutrum, pharetra augue a, maximus arcu. Vivamus mollis accumsan purus sed commodo. Aenean fringilla urna at enim tincidunt, vitae molestie velit euismod.</p><a href="#!">Example Link</a>
		</div>
	</li>
</ul>

Accordion Menu Unstyled

Select Code
<ul class="vertical menu accordion-menu -unstyled" data-accordion-menu data-submenu-toggle="true">
	<li>
		<a href="#!">Item 1</a>
		<ul class="menu vertical nested">
			<li>
				<a href="#!">Item 1A</a>
			</li>
			<li><a href="#!">Item 1B</a></li>
			<li><a href="#!">Item 1C</a></li>
		</ul>
	</li>
	<li>
		<a href="#!">Item 2</a>
		<ul class="menu vertical nested">
			<li><a href="#!">Item 2A</a></li>
			<li><a href="#!">Item 2B</a></li>
		</ul>
	</li>
	<li><a href="#!">Item 3</a></li>
</ul>

Accordion Menu

Select Code
<ul class="vertical menu accordion-menu -expanded" data-accordion-menu data-submenu-toggle="true">
	<li>
		<a href="#!">Item 1</a>
		<ul class="menu vertical nested">
			<li>
				<a href="#!">Item 1A</a>
			</li>
			<li><a href="#!">Item 1B</a></li>
			<li><a href="#!">Item 1C</a></li>
		</ul>
	</li>
	<li>
		<a href="#!">Item 2</a>
		<ul class="menu vertical nested">
			<li><a href="#!">Item 2A</a></li>
			<li><a href="#!">Item 2B</a></li>
		</ul>
	</li>
	<li><a href="#!">Item 3</a></li>
</ul>

Faq Accordion

Select Code
<ul class="accordion -unstripped" data-accordion="accordion-container-id" data-allow-all-closed="true" role="tablist">
	<li class="accordion-item is-active" data-accordion-item="" role="presentation">
		<a aria-controls="accordionFaqItemId1" aria-expanded="true" aria-selected="true" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 1</a>
		<div aria-hidden="false" aria-labelledby="accordionFaqItem1Label" class="accordion-content" data-tab-content="" id="accordionFaqItemId1" role="tabpanel" style="display: block;">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie. Morbi et magna rutrum, pharetra augue a, maximus arcu. Vivamus mollis accumsan purus sed commodo. Aenean fringilla urna at enim tincidunt, vitae molestie velit euismod.</p><a href="#!">Example Link</a>
		</div>
	</li>
	<li class="accordion-item" data-accordion-item="" role="presentation">
		<a aria-controls="accordionFaqItemId2" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionFaqItem2Label" role="tab">Accordion 2</a>
		<div aria-hidden="true" aria-labelledby="accordionFaqItem2Label" class="accordion-content" data-tab-content="" id="accordionFaqItemId2" role="tabpanel" style="display: none;">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie. Morbi et magna rutrum, pharetra augue a, maximus arcu. Vivamus mollis accumsan purus sed commodo. Aenean fringilla urna at enim tincidunt, vitae molestie velit euismod.</p><a href="#!">Example Link</a>
		</div>
	</li>
	<li class="accordion-item" data-accordion-item="" role="presentation">
		<a aria-controls="accordionFaqItemId3" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionFaqItem3Label" role="tab">Accordion 3</a>
		<div aria-hidden="true" aria-labelledby="accordionFaqItem3Label" class="accordion-content" data-tab-content="" id="accordionFaqItemId3" role="tabpanel" style="display: none;">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie. Morbi et magna rutrum, pharetra augue a, maximus arcu. Vivamus mollis accumsan purus sed commodo. Aenean fringilla urna at enim tincidunt, vitae molestie velit euismod.</p><a href="#!">Example Link</a>
		</div>
	</li>
</ul>

Alerts

Alert Danger And Variations

An alert keeps citizens informed of important and sometimes time-sensitive changes.

When to Use

  • Emergency Messages - As a notification required to inform citizens of an emergency situation.
  • System Status Messages - As a notification required to let citizens know the status of system they are engaged with, typically for outages and updates.
  • Validation Messages - As a notification required to let citizens know of missing information or successful completion of a task.

When Not to Use

  • Long forms - Use the inline validation for form controls instead of using an alert.

Usability

  • Consider next steps. When the citizen is required to do something in response to an alert, let them know what they need to do and make that task as easy as possible. Think about how much context to provide with your message. For example, a notification of a system change may require more contextual information than a validation message. Write the message in concise, human readable language; avoid jargon and computer code.
  • Be polite in error messages — don’t blame the citizen.
  • Alerts are an opportunity. Citizens will read a message that helps them resolve an error even if they generally won’t read documentation; include some educational material in your error message.
  • Don’t overdo it. Too many notifications will either overwhelm or annoy the citizen and are likely to be ignored.
  • Allow a citizen to dismiss a notification wherever appropriate.
  • Understand the citizen’s context. Don’t include notifications that aren’t related to the citizen’s current goal.

Accessibility

  • Use the proper ARIA role. If the message is not interactive, use the ARIA role="alert" to inform assistive technologies of a time-sensitive and important message. If the message is interactive, use the ARIA role="alertdialog" instead.
  • Don’t visually hide alert messages and then make them visible when they are needed. Citizens using older assistive technologies may still be able to perceive the alert messages even if they are not currently applicable.
Select Code
<div class="callout alert" data-closable role="alert">
	<h3><strong>WARNING!</strong></h3>
	<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras ut posuere ante. Donec non suscipit eros, a blandit lorem. Proin porta sapien pretium velit volutpat volutpat. Proin sit.</p>
	<button class="close-button" aria-label="Dismiss alert" type="button" data-close>
		<span aria-hidden="true" aria-label="close" role="button">&times;</span><br>
		<span aria-hidden="true" aria-label="close" role="label">close</span>
	</button>
</div>

Alert Success

Select Code
<div class="callout success" data-closable role="alert">
	<h3><strong>SUCCESS!</strong></h3>
	<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras ut posuere ante. Donec non suscipit eros, a blandit lorem. Proin porta sapien pretium velit volutpat volutpat. Proin sit..</p>
	<button class="close-button" aria-label="Dismiss alert" type="button" data-close>
		<span aria-hidden="true" aria-label="close" role="button">&times;</span><br>
		<span aria-hidden="true" aria-label="close" role="label">close</span>
	</button>
</div>

Alert Warning

Select Code
<div class="callout warning" data-closable role="alert">
	<h3><strong>NOTICE!</strong></h3>
	<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras ut posuere ante. Donec non suscipit eros, a blandit lorem. Proin porta sapien pretium velit volutpat volutpat. Proin sit.</p>
	<button class="close-button" aria-label="Dismiss alert" type="button" data-close>
		<span aria-hidden="true" aria-label="close" role="button">&times;</span><br>
		<span aria-hidden="true" aria-label="close" role="label">close</span>
	</button>
</div>

Buttons

Primary Button

Buttons are visually prominent calls to action.

When to Use

  • Important actions. Use buttons for the most important actions you want citizens to take on your site, such as Download, Sign up or Log out.

When Not to Use

  • Linking between a site’s pages. Use regular links instead.
  • If the action is less popular or less important. Less popular or less important actions may be visually styled as links.

Usability

  • Give an important action a distinctive style. Style the button most citizens should click in a way that distinguishes it from other buttons on the page.
  • Make sure buttons look clickable. Use color variations to distinguish static, hover, and active states.
  • Avoid using too many buttons on a page.
  • Use sentence case for button labels.
  • Keep button text short. Button text should be as short as possible with action words that clearly explain what will happen when the button is selected (for example: Download, View, or Sign up).
  • Lead with a verb. Make the first word of the button’s text a verb. For example, instead of Complaint filing label the button File a complaint.
  • When you have a page that takes up two entire viewport heights (and more), add the back to top button and enable smooth scrolling. Have the back to top button fade in using Javascript and have it appear after a citizen scrolls past the first viewport height (below the fold) and have it disappear when a citizen is within the first viewport height (above the fold).

How to Use

Primary Button

  1. Use on full-color backgrounds.

Secondary Button

  1. Use on photographic backgrounds.
  2. Always use a secondary button for the search button.

Accessibility

  • Buttons should display a visible focus state when citizens tab to them.
  • Use standard markup. Avoid using <div> or <img> tags to create buttons. Screen readers don't automatically know either is a usable button.
  • Screen readers handle buttons and links differently. When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space or Enter key triggers a button. Pressing the Enter key triggers a link.
Select Code
<button class="button -primary">Submit</button>

Primary Button Focus

Select Code
<button class="button -primary -focus">Submit</button>

Primary Button Hover

Select Code
<button class="button -primary -hover">Submit</button>

Primary Button Error

Select Code
<button class="button -primary -error">Submit</button>

Primary Button Disabled

Select Code
<button class="button -primary" disabled>Submit</button>

Secondary Button

Select Code
<button class="button -secondary">Submit</button>

Secondary Button Focus

Select Code
<button class="button -secondary -focus">Submit</button>

Secondary Button Hover

Select Code
<button class="button -secondary -hover">Submit</button>

Secondary Button Error

Select Code
<button class="button -secondary -error">Submit</button>

Secondary Button Disabled

Select Code
<button class="button -secondary" disabled>Submit</button>

Back To Top Button

Select Code
<button class="button -back-to-top">
	<i>
		<span class="show-for-sr">Triangle Icon</span>
	</i>
	Back to Top
</button>

Back To Top Button Focus

Select Code
<button class="button -back-to-top -focus">
	<i>
		<span class="show-for-sr">Triangle Icon</span>
	</i>
	Back to Top
</button>

Back To Top Button Hover

Select Code
<button class="button -back-to-top -hover">
	<i>
		<span class="show-for-sr">Triangle Icon</span>
	</i>
	Back to Top
</button>

Cards

Cards are containers used to organize high-level content.

When to Use

  • A card should only contain a single idea which may feature a call-to-action, or the option to navigate to more detailed content. The content of a card should be concise and offer only a preview of detailed content.

When Not to Use

  • Do not nest navigation within cards, use the appropriate component for navigation.
  • Do not nest cards within cards; add cards to modals only when it makes logical sense.
  • Do not use if you have more than one idea/call-to-action to display in a card.

Usability

Elements that can be used in a card are:

  • Main Title - A short and clear label that states the card's main message.
  • Meta information - Used to organize the cards. This can be a time stamp, category etc.
  • Description - A more thorough explanation of the idea and call-to-action. This text should be brief.
  • Image or Rich Media - Associated with the card and text, an image or rich media should contribute to the message.
  • Buttons - When a card requires a selectable action, or you want to emphasize that the card is a clickable object, you can use buttons.
  • Extra information - Any additional information that enhances the message of the card.
  • Not all of these elements are necessary for every card. You can choose the elements which you think best fit the purpose of the card. However, every card should have a main title. If multiple cards are placed on a page, they should be placed 16px apart on all sides.

Accessibility

  • Follow the accessibility guidelines for the elements listed above as they all apply for use in a card.
Add Alt Title

This is a title

This is a sub heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie..

This is a link
Select Code
<div class="card">
	<img src="./assets/toolkit/images/bg/hero-bg-small.jpg" alt="Add Alt Title">
	<div class="card-section">
		<h2 class="card-title">This is a title</h2>
		<p class="card-subtitle">This is a sub heading</p>
		<div class="card-content">
			<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer id auctor dui. Aenean posuere ante fermentum massa consequat iaculis. Praesent eget elit sit amet nibh interdum faucibus et vitae tellus. Nunc fermentum consequat diam. Quisque pellentesque leo risus, non rhoncus augue mattis vel. Sed placerat faucibus ipsum a molestie..</p>
			<a href="#!" class="button -primary">This is a link</a>
		</div>
	</div>
</div>

Form Controls

Checkbox

Checkboxes allow citizens to select one or more options from a visible list.

When to Use

  • When a citizen can select any number of choices from a setlist.
  • Toggles: When a citizen needs to choose “yes” or “no” on only one option (use a stand-alone checkbox). For example, to toggle a setting on or off.
  • Visibility of options. When citizens need to see all the available options at a glance.

When Not to Use

  • If there are too many options to display on a mobile screen.
  • Single-select only. If a citizen can only select one option from a list (use radio buttons instead).

Usability

  • Make the label selectable. Citizens should be able to tap on or click on either the text label or the checkbox to select or deselect an option.
  • List options vertically. Horizontal listings can make it difficult to tell which label pertains to which checkbox.
  • Use positive statements. Negative language in labels can be counterintuitive. For example, use “I want to receive a promotional email” instead of “I don’t want to receive promotional email.”
  • Use adequate touch targets. If you customize, make sure selections are adequately spaced for touch screens.

Accessibility

  • Customize accessibly. If you customize the text inputs, ensure they continue to meet the accessibility requirements that apply to all form controls.
  • Use a fieldset and legend for a checkbox group. Surround a related set of checkboxes with a <fieldset class="form-group">. The <legend> provides context for the grouping. Do not use fieldset and legend for a single check.
  • These custom checkboxes are accessible. The custom checkboxes here are accessible to screen readers because the default checkboxes are moved off-screen with position: absolute; left: -999em.
  • Use semantic ids. Each input should have a semantic id attribute, and its corresponding label should have the same value in it’s for="" attribute.
  • The title attribute can replace <label>.
Historical figures 1
Select Code
<fieldset class="form-group">
	<legend>Historical figures 1</legend>
	<label class="check-group" for="checkbox1">One
		<input type="checkbox" checked="checked" id="checkbox1">
		<span class="checkmark"></span>
	</label>

	<label class="check-group" for="checkbox2">Two
		<input type="checkbox" id="checkbox2">
		<span class="checkmark"></span>
	</label>

	<label class="check-group" for="checkbox3">Three
		<input type="checkbox" id="checkbox3">
		<span class="checkmark"></span>
	</label>

	<label class="check-group" for="checkbox4">Four
		<input type="checkbox" id="checkbox4" disabled>
		<span class="checkmark"></span>
	</label>
</fieldset>

Date Input

Single date input appropriate for most dates.

When to Use

  • Appropriate for most dates. Use this format for most dates, particularly memorized dates.

When Not to Use

  • Date ranges. Do not use to capture date ranges.

Usability

  • Semantic Markup. Follow the Date Input attributes.
  • Avoid dropdowns. It may be tempting to switch all or some of these text fields to dropdowns, but these tend to be more difficult to use than text boxes.

Accessibility

  • Follow input guidance. These text fields should follow the accessibility guidelines for all text inputs.
  • Don’t auto-advance focus. Do not use JavaScript to auto-advance the focus from one field to the next. This makes it difficult for citizens using keyboard navigation to correct mistakes.
Select Code
<fieldset class="form-group">
	<label class="" for="date-picker-1">Date input (mm/dd/yyyy)</label>
	<input type="text" id="date-picker-1" maxlength="10" />
</fieldset>

File Upload

A specialized button for attaching files.

When to Use

  • When a form requires file attachment(s) to be included.

When Not to Use

  • Avoid using single file upload more than once, use upload multiple files.

Usability

  • Use labels to denote what file types to accept and apply appropriate error messaging for non-supported file attachments.

Accessibility

  • Use the for="" attribute to denote what the label is used for, such as for=”custom_file”.
Upload File Single
Upload File Multiple
Select Code
<fieldset class="form-group">
	<legend>Upload File Single</legend>
	<label for="fileUpload1" class="button -secondary">Upload File</label>
	<input type="file" id="fileUpload1">
</fieldset>
<fieldset class="form-group">
	<legend>Upload File Multiple</legend>
	<label for="fileUpload2" class="button -secondary">Upload File</label>
	<input type="file" id="fileUpload2" multiple>
</fieldset>

Radio

Radio buttons allow citizens to see all available choices and select exactly one.

When to Use

  • Single selection: When citizens need to select only one option out of a set of mutually exclusive choices.
  • Limited choices: When the number of available options can fit onto a mobile screen.

When Not to Use

  • Multiple selections: Consider checkboxes if citizens need to select more than one option or if there is only one item to select.
  • Limited space: Consider a dropdown if you don’t have enough space to list out all available options.
  • Selecting none: If citizens should be able to select zero of the options.

Usability

  • Use the label as a target. Citizens should be able to tap on or click on either the text “label” or the radio button to select or deselect an option.
  • List items vertically. Options that are listed vertically are easier to read than those that are listed horizontally. Horizontal listings can make it difficult to tell which label pertains to which radio button.
  • Use adequate spacing. If you customize, make sure selections are adequately spaced for touch screens.
  • Set default values with caution. Setting a default value can discourage citizens from making conscious decisions, seem pushy, or alienate citizens who don’t fit into your assumptions. If you are unsure, leave nothing selected by default.

Accessibility

  • Customize accessibly. If you customize the radio buttons, ensure they continue to meet the accessibility requirements that apply to all form controls.
  • Use fieldset and legend. Group related radio buttons together with <fieldset class="form-group"> and describe the group with <legend>.
  • Use proper labels and attributes. Each radio button should have a <label>. Associate the two by matching the <label>’s for attribute to the <input>’s id attribute.
  • The title attribute can replace <label>.
Historical figures 1
Select Code
<fieldset class="form-group">
	<legend>Historical figures 1</legend>
	<label class="check-group" for="radio1">One
		<input type="radio" checked="checked" name="radio" id="radio1">
		<span class="radiobtn"></span>
	</label>
	<label class="check-group" for="radio2">Two
		<input type="radio" name="radio" id="radio2">
		<span class="radiobtn"></span>
	</label>
	<label class="check-group" for="radio3">Three
		<input type="radio" name="radio" id="radio3">
		<span class="radiobtn"></span>
	</label>
	<label class="check-group" for="radio4">Four
		<input type="radio" name="radio" id="radio4" disabled>
		<span class="radiobtn"></span>
	</label>
</fieldset>

Select

Dropdowns allow citizens to select one option from a temporary modal menu.

When to Use

  • Use sparingly. Use the dropdown component only when a citizen needs to choose from about seven to 15 possible options and you have limited space to display the options.

When Not to Use

  • Fewer than seven options. Use radio buttons instead.
  • More than 15 options. If the list of options is very long. Let citizens type the same information into a text input that suggests possible options instead.
  • If you need to allow citizens to select more than one option at once. Citizens often don’t understand how to select multiple items from dropdowns. Use checkboxes instead.
  • Site navigation - Use the navigation components instead.

Usability

  • Test dropdowns thoroughly with members of your target audience. Several usability experts suggest they should be the “UI of last resort.” Many citizens find them confusing and difficult to use.
  • Avoid making options in one dropdown menu change based on the input to another. Citizens often don’t understand how selecting an item in one impacts another.
  • When most citizens will (or should) pick a particular option, make it the default: <option value>Default</option>.
  • Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Offer a “submit” button at the end of the form instead. Citizens often change their choices multiple times. Auto-submission is also less accessible.

Accessibility

  • If you customize the dropdown, ensure it continues to meet the accessibility requirements that apply to all form controls.
  • Make sure your dropdown has a label. Don’t replace it with the default menu option (for example, removing the “State” label and just having the dropdown read “Select a state” by default).
  • Avoid auto-submission.
  • Don’t use JavaScript to automatically submit the form (or do anything else) when an option is selected. Auto-submission disrupts screen readers because they select each option as they read them.
Select Code
<fieldset class="form-group">
	<label for="options">Dropdown label</label>
	<select name="options" id="options">
		<option value>Default</option>
		<option value="value1">Option A</option>
		<option value="value2">Option B</option>
		<option value="value3">Option C</option>
	</select>
</fieldset>

Text Area

A large input meant for capturing qualitative information.

When to Use

  • Use in forms where capturing more in-depth information is required.

When Not to Use

  • Do not use in place of a text input.

Usability

  • Give the text area at least three lines worth of input space with the ability to drag the bottom right corner larger. Make sure to include validation to prevent input of code.

Accessibility

  • Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio.
Select Code
<fieldset class="form-group">
	<label for="text-area">Text area label</label>
	<textarea id="text-area" name="text-area"></textarea>
</fieldset>

Text Input

Text inputs allow citizens to enter any combination of letters, numbers, or symbols. Text input boxes can span single or multiple lines.

When to Use

  • Unpredictable or freeform responses. If you can’t reasonably predict a citizen’s answer to a prompt and there might be wide variability in citizens’ answers.
  • Input simplicity. When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a calendar picker.
  • Pasted content. When citizens want to be able to paste in a response.

When Not to Use

  • Predetermined input options. When citizens are choosing from a specific set of options.

Usability

  • Use fields appropriate to the length of the input. The length of the text input provides a hint to citizens as to how much text to write. Do not require citizens to write paragraphs of text into a single-line input box; use a text area instead.
  • Consider the mobile context. Text inputs are among the easiest type of input for citizens using desktops, but are more difficult for citizens using mobile.
  • Wait to validate. Only show error validation messages or stylings after a citizen has interacted with a particular field.
  • Avoid using placeholder text that appears within a text field before a citizen starts typing. If placeholder text is no longer visible after a citizen clicks into the field, citizens will no longer have that text available when they need to review their entries. (People who have cognitive or visual disabilities have additional problems with placeholder text.)
  • There are two classes provided for input messaging; success and error. Those classes are available to display the appropriate message to the citizen with the correct styling.
  • Each input should be surrounded by an element with the class name of field-group (in this case, the <fieldset> element is used). When a specific error or success is needed to be displayed related to that form element, include a <span class="form-message"> inside the parent class field-group, and extend this parent with a class of -error or -success for their respective visuals.

Accessibility

  • If you customize the text inputs, ensure they continue to meet the accessibility requirements that apply to all form controls.
  • Most browsers’ default rendering of placeholder text does not provide a high enough contrast ratio.
  • Avoid breaking numbers with distinct sections (such as phone numbers, Social Security Numbers, or credit card numbers) into separate input fields. For example, use one input for a phone number, not three (one for area code, one for local code, and one for number). Each field needs to be labeled for a screen-reader and the labels for fields broken into segments are often not meaningful.
Helpful error message
Helpful success message
Select Code
<fieldset class="form-group">
	<label for="input-type-text">Text Input label</label>
	<input id="input-type-text" name="input-type-text" type="text">
</fieldset class="form-group">

<fieldset class="form-group">
	<label for="input-active">Text Input label</label>
	<input class="-active" id="input-active" name="input-active" type="text" value="Value">
</fieldset class="form-group">

<fieldset class="form-group">
	<label for="input-focus">Text Input Focused</label>
	<input class="-focus" id="input-focus" name="input-focus" type="text">
</fieldset>

<fieldset class="form-group -error" role="group">
	<label for="input-error">Text Input Error</label>
	<span class="form-message" role="alert" id="input-error-message">Helpful error message</span>
	<input class="-error" id="input-error" name="input-error" type="text" aria-describedby="input-error-message">
</fieldset>

<fieldset class="form-group -success" role="group">
	<label for="input-success">Text Input Success</label>
	<span class="form-message" role="alert" id="input-success-message">Helpful success message</span>
	<input class="-success" id="input-success" name="input-success" type="text" aria-describedby="input-error-message">
</fieldset>

Time Input

Single time input appropriate for most times.

When to Use

  • Appropriate for most times. Use this format for most time.

When Not to Use

  • Time ranges. Do not use to capture a range of time.

Usability

  • Semantic Markup: follow the Time Input attributes.
  • It may be tempting to switch all or some of these text fields to dropdowns, but these tend to be more difficult to use than text boxes.

Accessibility

  • Follow input guidance: These text fields should follow the accessibility guidelines for all text inputs.
  • Don’t auto-advance focus: do not use JavaScript to auto-advance the focus from one field to the next. This makes it difficult for citizens who only use their keyboard to navigate and correct mistakes.
Time Input (hh:mm)
Time Input with extras (hh:mm)
Select Code
<fieldset class="form-group">
	<legend>Time Input (hh:mm)</legend>
	<div class="input-group" role="group">
		<label for="time" class="show-for-sr">Time of Day (hh:mm)</label>
		<input id="time" class="input-group-field" type="text" maxlength="5">
	</div>
</fieldset>
<fieldset class="form-group">
	<legend>Time Input with extras (hh:mm)</legend>
	<div class="input-group">
		<label for="timeExtras" class="show-for-sr">Time of Day (hh:mm)</label>
		<input id="timeExtras" class="input-group-field" type="text" maxlength="5">
		<div class="input-group-button">
			<label for="ampm" class="show-for-sr">AM/PM</label>
			<select name="ampm" id="ampm">
				<option value>AM/PM</option>
				<option value="value1">AM</option>
				<option value="value2">PM</option>
			</select>
		</div>
		<div class="input-group-button">
			<label for="timezone" class="show-for-sr">Timezone</label>
			<select name="timezone" id="timezone">
				<option value>Timezone</option>
				<option value="value1">Option A</option>
				<option value="value2">Option B</option>
				<option value="value3">Option C</option>
			</select>
		</div>
	</div>
</fieldset>

Validation

Stating validation requirements upfront, with live feedback, means citizens won't be left guessing.

When to Use

  • Generally, use the validation component for account creation tasks, or as a list of errors for a form in addition to form validation errors.

When Not to Use

  • They are meant to convey pertinent information about a particular task, not be to used as an addition to a card or put multiple types of call to actions in them.
  • Do not put an alert in a modal or card.

Usability

  • Limit the contents to the following:
    • Header
    • Paragraph
    • List
  • Always include a close icon. Allow the citizen to close the validation component even if they still have pertinent tasks to complete.

Accessibility

  • Follow the accessibility guidelines for the elements listed above as they all apply for use in a card.
Select Code
<div class="callout -small alert" role="alert">
	<p class="callout-title"><strong>Alert Title</strong></p>
	<ul>
		<li><i class="icon-check"></i>Use at least one uppercase character</li>
		<li>Use at least one numeric value</li>
	</ul>
</div>

<div class="callout -small alert" data-closable role="alert">
	<p class="callout-title"><strong>Alert Title Closeable</strong></p>
	<ul>
		<li><i class="icon-check"></i>Use at least one uppercase character</li>
		<li>Use at least one numeric value</li>
	</ul>
	<button class="close-button" aria-label="Dismiss alert" type="button" data-close>
		<span aria-hidden="true" aria-label="close" role="button">&times;</span><br>
		<span aria-hidden="true" aria-label="close" role="label">close</span>
	</button>
</div>

Grid Framework

Our grid system is based on Foundation’s Flex Grid.

The Foundation 6 Flex Grid works very similarly to their standard float grid, but includes a number of useful features only possible with flexbox, like horizontal and vertical alignment, automatic sizing, and easier source ordering. The flex grid is only supported in Chrome, Firefox, Safari 6+, IE10+, iOS 7+, and Android 4.4+. Flexbox is supported in Android 2, but not reliably enough for use with this grid.

When to Use

  • We follow the 2% browser usage rule; if a browser still has 2% general usage, we will support that browser. This grid system has been chosen to support older browsers without significant polyfills.

When Not to Use

  • You should always use this grid system. Deviation to another system can have adverse effects on using the PDS in your project.

Usability

Accessibility

  • When using the grid system, follow Foundation 6’s site documentation for any new developments regarding accessibility.

Modals

Modals are used to display content in a layer above the app/website.

When to Use

  • Deliberate disrupting action. Use modals when appropriate to disrupt a task/action when the citizen wants to explore another task.
  • Provide a lot of contextual information without taking up main screen space.

When Not to Use

  • Choose the right component. If you're using a Modal for a system alert that the citizen must acknowledge, consider using a validation component (for forms) or an alert.
  • Do not use for show/hide content. Use an accordion component.
  • No pop-ups. It’s very easy to make modals into timed pop-ups. Do not force citizens to engage with a modal they haven’t triggered.

Usability

  • They are as wide as 50% of the viewport, but include a minimum and maximum width to avoid going too narrow or too wide. Modals always have an equal amount of space at the top and bottom to account for the height of the close button.

Accessibility

  • Modal has role="dialog".
  • When the modal is open, everything behind it has HTML attribute aria-hidden="true", so assistive technology won't read out the underlying page. The best way to do this is to give the modal and the page separate wrapper elements and toggle aria-hidden="true"/aria-hidden="false" on the main page's wrapper depending on whether or not the modal is open.
  • Modal contains an HTML heading.
  • Modal has an aria-labelledby attribute whose value is the id of the modal’s heading.
  • Follow the accessibility guidelines for the elements nested within a modal.

Select Code
<div class="reveal" id="exampleModal1" data-reveal aria-labelledby="modal1_label" aria-modal="true" role="dialog">
	<h2 id="modal1_label">This is a headline</h2>
	<p class="lead">This is a subheadline</p>
	<p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Et placeat quo fugit quas, fuga modi culpa omnis dolores illo autem reiciendis atque minima distinctio earum, veniam dicta voluptatibus. Quasi, sit?</p>
	<button class="close-button" data-close aria-label="Close modal" type="button">
		<span aria-hidden="true" aria-label="close" role="button">&times;</span><br>
		<span aria-hidden="true" aria-label="close" role="label">close</span>
	</button>
</div>
<p><button class="button" data-open="exampleModal1">Click me for a modal</button></p>

Tables

Table

A table shows tabular data in columns and rows.

When to Use

  • Tabular data. When you need tabular information, such as statistical data.

When Not to Use

  • Non-tabular data. Depending on the type of content, consider using other presentation formats such as definition lists or hierarchical lists.

Usability

  • Keep it simple. Tables are great at displaying tabular data. Minimal visual styling helps surface this information more easily.

Accessibility

  • Simple tables can have two levels of headers. Each header cell should have scope="col" or scope="row".
  • Complex tables are tables with more than two levels of headers. Each header should be given a unique id and each data cell should have a headers attribute with each related header cell’s id listed.
  • When adding a title to a table, include it in a <caption> tag inside of the <table> element.
Table Title
Table Heading 1 Table Heading 2 Table Heading 3
Table Cell 1 Table Cell 2 Table Cell 3
Table Cell 1 Table Cell 2 Table Cell 3
Table Cell 1 Table Cell 2 Table Cell 3
Table Cell 1 Table Cell 2 Table Cell 3
Select Code
<table class="hover">
	<caption>Table Title</caption>
	<thead>
		<tr>
			<th scope="col">Table Heading 1</th>
			<th scope="col">Table Heading 2</th>
			<th scope="col">Table Heading 3</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>Table Cell 1</td>
			<td>Table Cell 2</td>
			<td>Table Cell 3</td>
		</tr>
		<tr>
			<td>Table Cell 1</td>
			<td>Table Cell 2</td>
			<td>Table Cell 3</td>
		</tr>
		<tr>
			<td>Table Cell 1</td>
			<td>Table Cell 2</td>
			<td>Table Cell 3</td>
		</tr>
		<tr>
			<td>Table Cell 1</td>
			<td>Table Cell 2</td>
			<td>Table Cell 3</td>
		</tr>
	</tbody>
</table>

Tags

Tags can focus attention on important content or content that might otherwise be missed.

When to Use

  • To indicate what information being displayed is associated with a certain category (example: "Policy" would be a tag that would appear at the top of the search results page when a search query for "government home inspection policy" would be returned).

When Not to Use

  • Confusion with buttons. Avoid tags if they might appear in the same area of the page as buttons.
  • New or updated content. To call attention to new or updated content, consider changing the background color of the object itself or experiment with changing the font-weight.
  • When citizens already expect content to be updated frequently, for example on a site. For example, on a site dedicated to breaking news. In this case, placing the new content at the top may be enough.

Usability

  • Citizens frequently confuse tags as buttons. Always conduct usability testing to make sure your particular implementation is not causing frustration.
  • If your tags aren’t interactive, disable hover, focus, and active styles.
  • Don’t mix interactive and static tags. Once you establish a pattern for how tags behave on your site, citizens will expect that behavior every time.
  • Don’t overdo it. If everything on a page is called out as important, nothing commands unique attention.

Accessibility

  • Use ARIA live regions to highlight dynamically loaded content. When tags are used to call out new content that is dynamically loaded onto a page, be sure to use ARIA live regions to alert screen readers of the change.
Primary Label
Select Code
<span class="label">Primary Label</span>