18F UI style guide



These are the main page templates that exist on 18f.gsa.gov:

Primary template

Located at _layouts/primary.html, this is the template that is most frequently used in 18f.gsa.gov. It is responsible for creating content pages like /code-of-conduct/ to guides-style pages such as /join/.

Example of primary template. Found at Join.

Primary template front matter

The primary template uses Jekyll front matter heavily to account for variations within the site. Below are the the potential front matter attributes that you can use. Some are listed as (optional). These can be used to alter the appearance of a page.

Attribute Type What it does
title String Title for the page visible in blue banner at the top of the page
permalink String Path that the page renders relative to the site’s baseurl
layout String Should be set to primary
lead String (optional) Large white text that renders on the top blue banner
banner_cta Boolean (optional) Set to false by default. Generates a light blue call to action banner when set to true.
subnav_items Object (optional) Navigation items object that contains a list of subnavigation items that contain a permalink and text. Renders a sticky subnav on the left side of the page.
subnav_title String (optional) Set if you want the subnav title or breadcumb text to differ from the page title.
hero Boolean (optional) Enables a hero image in the banner. Defaults to true, so set to false to hide the image
image String (optional) Path to hero image. This image will also display on blog post preview cards
image_alt String (optional) Accessibility text for the image
image_figcaption String (optional) A caption that will be displayed on top of the image
breadcrumb Boolean (optional) Set to false by default. Specify true to enable the breadcrumb. If set to true, set subnav_title if the breadcrumb text differs from the page title. View breadcrumb component

How we work page

/how-we-work page is similar to the primary template but with a few adjustments that help to highlight how we support our customers. We pull these components:

  • Project cards are placed at the bottom of the page to highlight past work and to bring users to /what-we-deliver.View project cards component
  • Testimonal quote is used within the body of the content. Bringing the voices of our partner agencies front and center is a top priority. View testimonial component

Project page template

Located at _layouts/project-page.html, this is the template for creating new project pages as well as project cards that show up at /what-we-deliver/.

Example of project page template. Found at FEC project page.

Add a project page

  1. Determine if the project is a service or a product and find the corresponding directory
  2. Create a new file within either the _products_projects or _servicess_projects directory and name it with the following format: [agency acronym]-[project-name].md.
  3. Copy the project page template to that file. Here you can build out the page to include:
    • Main content on the project’s background and 18F’s approach
    • The sidebar for at-a-glance information like the project’s website or GitHub repos. To do this, update the front matter related to the sidebar. If you don’t want something to show up in the sidebar, remove it from the front matter
    • Testimonials or fun facts styling within the body of the page
  4. Replace all relavent front matter fields. To see if a field is required, see the project page schema.
  5. If you’re adding an image, make sure to check out tips on picking a project page image. If you’re not adding an image, make sure to specify an image_icon property in the front matter, and reference an SVG available in the SVG catalog like so:
      image_icon: gavel.svg

Blog post template

Located at _layouts/post.html, this is the template for creating new blog posts.

Example of a blog post template. Found at NASA's journey with the U.S. Web Design Standards.

There is extensive documentation for how to publish a blog post on the wiki and an example blog post to assist with adding metadata and frequently used blog components. A deeper dive into those components is available at Blog.


The layout and grid structure inherits from the U.S. Web Design System and makes some slight adjustments. Layout changes are not overrides of the Design System, but a handful of CSS classes have been added to compliment the Design System.

Class name What it does
usa-width-tablet A class that allows certain content, namely the project cards, and the blog previews to respond at a different breakpoint, $tablet-screen (768px).
usa-flex Wrapper class that sets display: flex, and can be used to create more flexible layouts.
Classes used with usa-flex usa-flex-baseline, usa-flex-end, usa-flex-pull-right, usa-flex-always, usa-flex-wrap, usa-flex-vertically-top, usa-flex-pull-right, and usa-flex-vertically-bottom.
usa-grid-reversed This class can be used to alternate the order that content appears in mobile vs desktop screen widths.
content-wide In the Design System, the primary way to improve readability is via the usa-content class, which limits content to 75 characters. Instead of relying on this mechanism, the site wraps site content with the content-focus class, limiting the entire grid to roughly 100 characters.
content-focus When the the grid needs to be wider, content-wide is used and the content width is controlled by using partial grid layouts.

This attribute is found in the contact and project pages on the 18F site. This feature provides at-a-glance information.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

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.