18F UI style guide

Components

Buttons

Style on white

Style on dark

Using anchor tags instead of buttons

Normal

  •   
    #### Style on white
    <section class="usa-grid">
      <button class="usa-button">Normal</button>
      <button class="usa-button-hover">Hover</button>
      <button class="usa-button-active">Active</button>
      <button class="usa-button-focus">Focus</button>
      <button class="usa-button-disabled">Disabled</button>
    </section>
    
    #### Style on dark
    <section class="background-dark usa-grid">
      <button class="usa-button usa-button-secondary">Normal</button>
      <button class="usa-button-hover usa-button-secondary">Hover</button>
      <button class="usa-button-active usa-button-secondary">Active</button>
      <button class="usa-button-focus usa-button-secondary">Focus</button>
      <button class="usa-button-disabled usa-button-secondary">Disabled</button>
    </section>
    
    #### Using anchor tags instead of buttons
    <a class="usa-button usa-button-secondary" href="">Normal</a>
    
    
  • Our button styles closely resemble those defined by the U.S. Web Design System. We have overriden them in places to more closely align the look and feel with the 18F Brand.

    Additional resources:


The site breadcrumb can be used to establish a sense of place within the site. It is only included in the primary layout by default, but can be added to any layout or custom page as needed.

Specifying all attributes

Specifying only needed attributes

parent_permalink is set as a page attribute in this example, so it doesn’t need to be directly included.


Project cards

The card component is used as a preview for project pages, but could be adapted to meet additional needs if necessary. The design is unique to 18f.gsa.gov, but leans heavily on the stylistic foundation of the U.S. Web Design System and 18F Brand guidelines.

  •   
    <div class="usa-grid-full">
      <section class="usa-flex usa-flex-wrap">
        {% include card-project.html project='fec-gov' %}
        {% include card-project.html project='hhs-states' %}
        {% include card-project.html project='dhs-myuscis' %}
      </section>
    </div>
    
    
  • To use cards, reference the file path slug in the projects directory. Use another project as a template to fill in all of the necessary fields.

    Each project card has a number of properties. The only required properties are:

    • image_src: the project image field, and is the image portion of the card
    • image_alt: the project image_accessibility field. Will be used to set the alt attribute on the provided image
    • agency: the project agency field. This will be the uppercase text
    • tagline: the project subtitle field and what appears to be the title of the card
    • description the project excerpt and what appears as the body of the card
    • link: the project permalink. This is where clicking on the card will take you
    • columns: How many columns the cards should occupy. The only valid options are 2 and 3. If nothing is specified, the cards will default to 3 columns


Sticky subnavigation

The sticky subnavigation is a pattern that is used frequently throughout the site to make larger bodies of content easier to navigate. The About page is good example of the sticky subnavigation in the live site.

What is it?

  • A secondary navigation field that exists on the left side of a page, adjacent to a corresponding field of content.
  • It is “sticky”, which means that its position isn’t absolute or static, but is both, depending on the user’s location on the page.
  • It provides a sense of location by updating the active section of content that the user is viewing.

Heading one

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Heading two

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

  •   
    <div class="usa-grid-full">
      <aside class="usa-width-one-third sticky sticky-subnav sticky-subnav-styleguide">
        {% include navigation.html subnav=true %}
      </aside>
      <section class="usa-width-two-thirds">
        <h3 id="heading-one">Heading one</h3>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
        <h3 id="heading-two">Heading two</h3>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      </section>
    </div>
    
    
  • How to use

    1. Add the classes sticky and sticky-subnav to the element that you want to be sticky.
    2. Make sure that sticky.js is included in the page. If you are working on the 18F site, it is included on every page by default.
    3. Make sure that the element that is receiving position: sticky is a child of an element with a greater height. If it is not, it will never appear to be stuck.

    Use of the Design System

    There are a few classes that we are using for the sticky subnavigation on the 18F site:

    • The usa-sidenav-list class, in conjunction with the usa-current class. This is mostly taken wholesale from the Design System, but does contain slight overrides to better fit with the 18F Brand.
    • The usa-accordion class and accompanying accordion styles. We have added to this set of styles with a nav-accordion class that more accurately reflects the look and feel of the site.
    • The usa-width-one-third grid class to define the width of our navigaton field. This isn’t necessary, but is a convention throughout the site.

    What to add where

    To add items to the subnavigation define the subnavigation items directly within page frontmatter, as a set of nav_items:

      subnav_items:
        - text: Heading one
          permalink: /styleguide/sticky-subnavigation/#heading-one
        - text: Heading two
          permalink: /styleguide/sticky-subnavigation/#heading-two
    


Testimonials and fun facts

Testimonials and fun facts are used throughout the site to highlight the impact 18F has made with our partner agencies. You can find the styling used on the home page, how we work, and various project pages.

18F has helped us [build something] that lead to [improved thing] resulting in [impact] within our agency. - [name], [position], [agency]
The day [platform] launched, [x-number]organizations were already using the data and API to enhance existing tools or build new products to better serve their customers.
  •   
    
    <div class="testimonial-blockquote">
      18F has helped us [build something] that lead to [improved thing] resulting in [impact] within our agency.
        <span>- [name], [position], [agency]</span>
    </div>
    
    <div class="funfact-blockquote">
      The day [platform] launched, [x-number]organizations were already using the data and API to enhance existing tools or build new products to better serve their customers.
    </div>
    
    
    
  • How to use

    • For a testimonial: Add the class testimonial-blockquote to the element (ex. div) that holds the quote. This will place the large quote mark before the content. Place the name, position, and agency within the <span> tag. This bolds, adds color, and removes italics to the text.
    • For a fun fact: Add the class funfact-blockquote to the element (ex. div) that holds the information. This has similar styling to a testimonial but adjusted for just text.