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 includes 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

Select Code
<ul class="accordion" data-accordion="container" data-allow-all-closed="true" role="tablist">
	<li class="accordion-item is-active" data-accordion-item="" role="presentation">
		<a aria-controls="accordion1ID" aria-expanded="true" aria-selected="true" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 1</a>
		<div tabindex="0" aria-hidden="false" aria-labelledby="accordion1Label" class="accordion-content" data-tab-content id="accordion1ID" 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="accordion2ID" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 2</a>
		<div tabindex="0" aria-hidden="true" aria-labelledby="accordion2Label" class="accordion-content" data-tab-content id="accordion2ID" 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="accordion3ID" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 3</a>
		<div tabindex="0" aria-hidden="true" aria-labelledby="accordion3Label" class="accordion-content" data-tab-content id="accordion3ID" 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>

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 it 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 types 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> ensures 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.

Accordion Menu Unstyled

Select Code
<ul class="vertical menu accordion-menu -unstyled" data-accordion-menu data-submenu-toggle="true" data-multi-open="false">
	<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>
			<li>
				<a href="#!">Item 1d</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>
			<li>
				<a href="#!">Item 2c</a>
			</li>
			<li>
				<a href="#!">Item 2d</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" data-multi-open="false">
	<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>
			<li>
				<a href="#!">Item 1d</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>
			<li>
				<a href="#!">Item 2c</a>
			</li>
			<li>
				<a href="#!">Item 2d</a>
			</li>
		</ul>
	</li>
	<li>
		<a href="#!">Item 3</a>
	</li>
</ul>

Faq Accordion

Select Code
<ul class="accordion -unstriped" data-accordion="faq" data-allow-all-closed="true" role="tablist">
	<li class="accordion-item is-active" data-accordion-item="" role="presentation">
		<a aria-controls="accordion1ID" aria-expanded="true" aria-selected="true" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 1</a>
		<div tabindex="0" aria-hidden="false" aria-labelledby="accordion1Label" class="accordion-content" data-tab-content id="accordion1ID" 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="accordion2ID" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 2</a>
		<div tabindex="0" aria-hidden="true" aria-labelledby="accordion2Label" class="accordion-content" data-tab-content id="accordion2ID" 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="accordion3ID" aria-expanded="false" aria-selected="false" class="accordion-title" href="#!" id="accordionFaqItem1Label" role="tab">Accordion 3</a>
		<div tabindex="0" aria-hidden="true" aria-labelledby="accordion3Label" class="accordion-content" data-tab-content id="accordion3ID" 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 Variations

WARNING!

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.

Select Code
<div data-alert data-closable tabindex="0" role="alertdialog" class="callout alert">
	<p class="h3"><strong>WARNING!</strong></p>
	<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" 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>

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

When to Use

  • Alerts are to be used for time-sensitive notifications to your entire audience. These alert messages can always be turned off by the user. There are three main types of alerts:
    • Emergency Messages are used as a notification required to inform users of an emergency situation.
    • System Status Messages are used as a notification required to inform users of the status of a system, typically for outages and updates.
    • Validation Messages are used as a notification required to inform users of missing information or the successful completion of a task.
  • Alerts appear under the hero section on page layouts with a hero section with a background image. Alerts appear above the top of the website on page layouts without a hero section with a background image.

When Not to Use

  • For long forms, use the inline validation for form controls instead of using an alert to inform the user of missing or inaccurate information submitted.
  • Do not overuse alerts. If an emergency notice appears on the homepage of a website, craft a comprehensive message rather than adding several separate messages.
  • Do not create alerts that users cannot close.

Usability

  • Consider the user’s next steps. When a user is required to do something in response to an alert, explain the needed actions and make the task as easy as possible. Think about how much context to provide in the message.
    • For example, a notification of a system change may require more contextual information than a validation message. Write the message in concise, easy-to-understand language. Avoid jargon and computer code.
  • Be polite and concise in error messages. Ensure messages clearly communicate intention and meaning to maximize user comprehension.
  • Alerts are opportunities for effective user engagement. Users will read a message that helps resolve an error, even if documentation is not read. Include educational material in your error message.
  • Do not overuse alerts. Too many notifications will overwhelm and/or annoy the user and likely be ignored.
  • Always allow a user to dismiss a notification.
  • Understand the context of a message for a user. Do not include notifications unrelated to the user’s current goals. Always strive to create clear and meaningful alerts.

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".
  • Do not visually hide alert messages and then make them visible when needed. Users relying on Assistive Technologies may be able to perceive the hidden alert messages.

Alert Success

SUCCESS!

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.

Select Code
<div data-alert data-closable tabindex="0" role="alertdialog" class="callout success">
	<p class="h3"><strong>SUCCESS!</strong></p>
	<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" 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

NOTICE!

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.

Select Code
<div data-alert data-closable tabindex="0" role="alertdialog" class="callout warning">
	<p class="h3"><strong>NOTICE!</strong></p>
	<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" 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

Select Code
<button class="button -primary">
	Submit
</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 (e.g., 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. 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.

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>
	Submit
</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>
	Submit
</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>
	Submit
</button>

Cards

Add Alt Text

This is a title

This is a sub heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ornare nulla accumsan ut cras magna enim massa ornare at.

This is a link
Select Code
<div class="card">
	<img src="assets/toolkit/images/bg/hero-bg-small.jpg" alt="Add Alt Text">
	<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. Ornare nulla accumsan ut cras magna enim massa ornare at.</p>
			<a href=#! class="button -primary">
				This is a link
			</a>
		</div>
	</div>
</div>

When to Use

  • A card is a multipurpose container. A card can be used for calls to action, news posts, and housing lists of links, among others. A card works well inside of sections on a page when multiple cards are horizontally (and vertically for mobile displays) aligned. One card is best when used for a singular purpose.
    • For example, a card that shows an image, headline, and some text with a button to “Read More” works well for a news post. Taking that same news post card and adding another news post in the same card below the initial content does not work well.

When Not to Use

  • Do not nest navigation within a card. Do not use pagination, breadcrumbs, image carousels, or <nav> elements within the card.
  • Do not nest cards within cards.
  • Only add cards to modals when it makes logical sense.
  • Do not use if more than one idea/call-to-action will display in a card.
    • For example, do not place a list of links within the same card used to create a news post pattern.
  • Do not make content in a card scrollable. Card content should be completely viewable.
  • Do not use inline links within the card. The card should be the link.

Usability

  • Follow logical user flow and test for usability when creating card patterns.

Accessibility

  • Follow the accessibility guidelines for custom-coded elements in a card.

Form Controls

Checkbox

Historical Figures
Select Code
<fieldset class="form-group">
	<legend>Historical Figures</legend>
	<label class="check-group" for="checkbox1">
		<input type="checkbox" checked="checked" id="checkbox1">One
		<span class="checkmark"></span>
	</label>
	<label class="check-group" for="checkbox2">
		<input type="checkbox" id="checkbox2">Two
		<span class="checkmark"></span>
	</label>
	<label class="check-group" for="checkbox3">
		<input type="checkbox" id="checkbox3">Three
		<span class="checkmark"></span>
	</label>
	<label class="check-group" for="checkbox4">
		<input type="checkbox" id="checkbox4" disabled>Four
		<span class="checkmark"></span>
	</label>
</fieldset>

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 its for="" attribute.
  • The title attribute can replace <label>.

Date Input

Select Code
<fieldset class="form-group ">
	<label for="date-picker-1">Date input (MM/DD/YYYY)</label>
	<input type="text" id="date-picker-1" maxlength="10" />
</fieldset>

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.

File Upload

Upload File Single
Upload File Multiple
Select Code
<fieldset class="form-group">
	<legend>Upload File Single</legend>
	<label class="button -secondary" for="fileUpload1">Upload File</label>
	<input type="file" id="fileUpload1" />
</fieldset>
<fieldset class="form-group">
	<legend>Upload File Multiple</legend>
	<label class="button -secondary" for="fileUpload2">Upload File</label>
	<input type="file" id="fileUpload2" />
</fieldset>

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

Radio

Historical Figures
Select Code
<fieldset class="form-group">
	<legend>Historical Figures</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>

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>.

Select

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>

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 dropdowns 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 (e.g., 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.

Text Area

Select Code
<fieldset class="form-group">
	<label for="text-area">Text area label</label>
	<textarea id="text-area" name="text-area"></textarea>
</fieldset>

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.

Text Input

Helpful error message
Helpful success message
Select Code
<fieldset class="form-group ">
	<label for="input-type-text">Text Input label</label>
	<input type="text" id="input-type-text" />
</fieldset>
<fieldset class="form-group ">
	<label for="input-active">Text Input Active</label>
	<input type="text" id="input-active" class="-active" value="Value" />
</fieldset>
<fieldset class="form-group ">
	<label for="input-focus">Text Input Focused</label>
	<input type="text" id="input-focus" class="-focus" />
</fieldset>
<fieldset class="form-group -error">
	<label for="input-error">Text Input Error</label>
	<span class="form-message" role="alert" id="input-error-message">Helpful error message</span>
	<input type="text" id="input-error" />
</fieldset>
<fieldset class="form-group -success">
	<label for="input-success">Text Input Success</label>
	<span class="form-message" role="alert" id="input-success-message">Helpful success message</span>
	<input type="text" id="input-success" />
</fieldset>

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 challenges 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.

Time Input

Select Code
<fieldset class="form-group ">
	<label for="time">Time Input (hh:mm)</label>
	<input type="text" id="time" maxlength="5" />
</fieldset>

Single time input is appropriate for most times.

When to Use

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

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.

Validation

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>

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 to be used as an addition to a card or put multiple types of calls to action 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 because they all apply for use in a card.

Grid Framework

6 columns
6 columns
12/6/4 columns
12/6/8 columns
Select Code
<div class="row">
	<div class="columns small-6">6 columns</div>
	<div class="columns small-6">6 columns</div>
</div>
<div class="row">
	<div class="columns medium-6 large-4">12/6/4 columns</div>
	<div class="columns medium-6 large-8">12/6/8 columns</div>
</div>

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

The Foundation 6 Flex Grid works very similarly to its 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 percent browser usage rule. If a browser still has 2 percent 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

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">
		<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 -secondary" data-open="exampleModal1">Click me for a modal</button></p>

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 percent of the viewport, but include minimum and maximum widths 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.

Tables

Table

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
Select Code
<table class="hover">
	<caption class="sr-only">Table Title</caption>
	<thead>
		<tr>
			<th>Table Heading 1</th>
			<th>Table Heading 2</th>
			<th>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>
	</tbody>
</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 have more than two levels of headers. Each header should be given a unique id and each data cell should have a header 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.

Tags

Static Content Static Content Closable Hyperlink Hyperlink Closable
Select Code
<span class="label">Static Content</span>

<span class="label" data-closable>
	Static Content Closable
	<button class="close-button" aria-label="Close / Delete" data-close>
		<span aria-hidden="true" aria-label="close">&times;</span>
	</button>
</span>

<a href="#!" class="label">
	Hyperlink
</a>

<a href="#!" class="label" data-closable>
	Hyperlink Closable
	<button class="close-button" aria-label="Close / Delete" data-close>
		<span aria-hidden="true" aria-label="close">&times;</span>
	</button>
</a>

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

When to Use

  • Similar to a static tag, an interactive tag indicates the specific content category associated with the information the tag displays.
    • For example, the tag of “policy” would appear at the top of the search results page for a search query of “government home inspection policy.”
    • When used in a search to return categorized content, an interactive tag can be closed to remove search results solely categorized by that tag.
  • To filter search results with one or more tags associated with specific categories of content.
  • To indicate the number of new/unread notices or items within a container.

When Not to Use

  • Avoid using tags in the same page areas buttons appear.
  • Do not use interactive tags in place of static tags. Interactive tags are meant to be removed to help filter search results by discarding any content tags associated with a specific categorization.
    • For example, a search query of “department of agriculture budget plan” may return the interactive tags of “agriculture,” “budget,” and “plan” because some of that content may have multiple associated tags. If a user removes the “plan” tag, the content solely associated with that specific tag will be removed, while the content with additional category tags will remain.

Usability

  • Users frequently confuse tags with buttons. Always conduct usability testing to make sure your tag implementation is not causing frustration.
  • Disable hover, focus, and active styles if your tags are not interactive.
  • Do not mix interactive tags and static tags. Once you establish a pattern for how tags behave on your website, users will expect that behavior every time.
  • Do not overdo it. If everything on a page is called out as important, then nothing draws unique attention.

Accessibility

  • Use ARIA live regions to highlight dynamically loaded content. When tags are used to highlight new content that is dynamically loaded onto a page, use ARIA live regions to alert screen readers of the change.