Digital Style Guide

Standards, Code Snippets, & Assets

1.0.7

Navigation

<header class="site-header" role="banner">
  <a href="https://planninglabs.nyc/" class="labs-beta-notice hide-for-print">A beta project of NYC Planning</a>
  <div class="grid-x grid-padding-x">
    <div class="branding cell medium-auto shrink">
      <a href="http://www1.nyc.gov/site/planning/index.page" class="dcp-link"><img src="https://raw.githubusercontent.com/NYCPlanning/logo/master/dcp_logo_772.png" alt="NYC Planning" class="dcp-logo"></a>
      <a class="site-title">Product <small class="site-subtitle show-for-medium">Description of Product</small></a>
    </div>
    <div class="cell auto hide-for-medium text-right">
      <button class="responsive-nav-toggler hide-for-print" data-toggle="menu">Menu</button>
    </div>
    <nav role="navigation" class="cell medium-shrink responsive show-for-medium hide-for-print" id="menu" data-toggler=".show-for-medium">
      <ul class="menu vertical medium-horizontal">
        <li><a href="/">One</a></li>
        <li><a href="/">Two</a></li>
        <li class="external-nav-item"><a href="mailto:email@example.org">Email</a></li>
      </ul>
    </nav>
  </div>
</header>

Buttons

Buttons can be created with minimal markup by adding the .button class. Primary buttons are a11y-orange with white text, and should be used sparingly for primary user actions that need to be very noticeable. For secondary tasks, add the .secondary class to make a light gray button with orange text.

<a class="button" href="#">Primary action</a>
<a class="button secondary" href="#">Secondary action</a>
Primary action Secondary action

Size classes can be added to your button to change its size.

<a class="button tiny" href="#">Tiny</a>
<a class="button small" href="#">Small</a>
<a class="button" href="#">Default</a>
<a class="button large" href="#">Large</a>
Tiny Small Default Large

The .expanded class makes the butto tak up the full width of its container.

<a class="button expanded" href="#">Such Expand</a>
Such Expand

Use the right tag

Since buttons can be used for many purposes, it's important to use the right tag. Use the <a> tag if the button is a link to a document, another page, or an anchor within the page. Use the <button> tag if the button performs an action that changes something on the current page.

Label buttons with clear actions

Generic or misleading button text can be frustrating for users. A button’s text should clearly describe its action. Use verbs whenever possible instead of "Yes" or "OK" so buttons don't rely on the context of titles or prompts.

Bad:

Would you like to delete this?

Good:

Would you like to delete this?

Disabled buttons

The .disabled gives buttons a faded appearance and the not-allowed cursor property. This only adds visual style; it doesn't disable any actions. For <button> elements, you can add the disabled attribute to both style and actually disable it. Mark links as disabled for assistive technology by adding the aria-disabled attribute.

<a class="button disabled" href="#" aria-disabled>Disabled link</a>
<button type="button" class="button" disabled>Disabled button</button>
Disabled link

Button groups

Wrap buttons in a container with the .button-group class to associate a set of related actions. These buttons will be separated by a 1-pixel border. Size and color classes can be applied to the group as a whole.

<div class="button-group small secondary">
  <a class="button">One</a>
  <a class="button">Two</a>
  <a class="button">Three</a>
</div>
One Two Three

Expanded button groups

The .expanded class will make the group fill the width of its container (maximum of six buttons).

<div class="button-group small secondary expanded">
  <a class="button">One</a>
  <a class="button">Two</a>
  <a class="button">Three</a>
</div>
One Two Three

Stacked button groups

Make a button group vertical with the .stacked class. The responsive .stacked-for-small class makes the group vertical on small screens only, and .stacked-for-medium makes the group vertical on medium and small screens. These classes are good for button groups confined to small spaces at certain screen sizes. 

<div class="button-group small secondary stacked">
  <a class="button">One</a>
  <a class="button">Two</a>
  <a class="button">Three</a>
</div>
One Two Three

Menus are lists of links. Add the .menu class to a <ul> element containing <li> elements containing bold links.

<ul class="menu">
  <li><a href="#">One</a></li>
  <li><a href="#">Two</a></li>
  <li><a href="#">Three</a></li>
  <li><a href="#">Four</a></li>
</ul>

Active menu item

Add the .is-active class to a menu's <li> to highlight that item as active.

By default, menu items align to the left. They can also be aligned to the right with the .align-right class, aligned to the center with the .align-center class, or take up the full width with the .expanded class.

<ul class="menu">...</ul>
<ul class="menu align-right">...</ul>
<ul class="menu align-center">...</ul>
<ul class="menu expanded">...</ul>

By default, menus are horizontally. Add the .vertical class to switch a menu's default orientation. The responsive .[size]-[orientation] classes allow you to re-orient a menu at different screen sizes.

<ul class="menu vertical medium-horizontal large-vertical">
  <li><a href="#">One</a></li>
  <li><a href="#">Two</a></li>
  <li><a href="#">Three</a></li>
  <li><a href="#">Four</a></li>
</ul>

Tabs

Use tabs to alternate between views within the same context. Keep tab labels short. All tab content should be related and logically divided so users can easily predict what's in a given tab. If there aren't clearly distinct groupings, tabs are likely the wrong UI for navigating the content.

<ul class="tabs">
  <li class="tabs-title"><a href="#">One</a></li>
  <li class="tabs-title is-active"><a href="#" aria-selected="true">Two</a></li>
  <li class="tabs-title"><a href="#">Three</a></li>
  <li class="tabs-title"><a href="#">Four</a></li>
</ul>

Do not use tabs when users need to compare the info in multiple tabs. Having to switch back and forth puts an added burden on the user and lowers usability.

Do not use tabs unless they all fit on one row at all screen sizes.

Switching tabs

Tabs can be implemented by reloading the page with different content on click or by showing/hiding content with JavaScript. Reloading the page is less desirable, as it can cause the scroll position to jump. JavaScript improves the user's experience by seamlessly swapping the tabs content.

Foundation's JavaScript makes switching tabs easy. Put all tabs content in a container with the .tabs-content class. Each piece of content in the container needs the .tabs-panel class and a unique ID. The href of each tab link should match the ID of a tab panel. Alternatively, the ID can be specified with the attribute data-tabs-target.

<ul class="tabs" data-tabs id="example-tabs">
  <li class="tabs-title is-active"><a href="#panel1" aria-selected="true">Tab 1</a></li>
  <li class="tabs-title"><a data-tabs-target="panel2" href="#panel2">Tab 2</a></li>
</ul>
<div class="tabs-content" data-tabs-content="example-tabs">
  <div class="tabs-panel is-active" id="panel1">
    <p>Vivamus hendrerit arcu sed erat molestie vehicula. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus.</p>
  </div>
  <div class="tabs-panel" id="panel2">
    <p>Suspendisse dictum feugiat nisl ut dapibus.  Vivamus hendrerit arcu sed erat molestie vehicula. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor.  Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor.</p>
  </div>
</div>

Vivamus hendrerit arcu sed erat molestie vehicula. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus.

Suspendisse dictum feugiat nisl ut dapibus. Vivamus hendrerit arcu sed erat molestie vehicula. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor.

Pagination

Pagination lets users click through related content, like search results or news posts. Add the class .pagination to a <ul> containing <li> elements containing <a> elements. Add the .current class to highlight the current list item, or .disabled to subdue it. Pagination should be centered with the .text-center class.

Pagination should be nested inside a <nav> with the attributes aria-label="Pagination" to explain the purpose of the component to assistive technologies. Content with the .show-for-sr class should also be added to provide more context to screen readers.

<nav aria-label="Pagination">
  <ul class="pagination text-center">
    <li class="pagination-previous disabled">Previous</li>
    <li class="current"><span class="show-for-sr">You're on page</span> 1</li>
    <li><a href="#" aria-label="Page 2">2</a></li>
    <li><a href="#" aria-label="Page 3">3</a></li>
    <li class="ellipsis"></li>
    <li><a href="#" aria-label="Page 42">42</a></li>
    <li><a href="#" aria-label="Page 43">43</a></li>
    <li><a href="#" aria-label="Page 44">44</a></li>
    <li class="pagination-next"><a href="#" aria-label="Next page">Next</a></li>
  </ul>
</nav>