Images

Images are used heavily throughout the site, but using them isn’t always straightforward. Below is some guidance on how we use images of various formats throughout the site.

Image formats

The primary image formats that work well for the web are SVG, JPG, PNG, and GIF. Choosing the correct format can speed up the site and lead to a better user experience. Here are some guidlines that we use when picking images on 18f.gsa.gov:

SVG: the fastest loading images. They are generally best suited for iconography, or less complex graphics. They can be added as a Jekyll include, or as an img tag with a source reference. SVGs added as Jekyll includes are rendered as valid html svg elements and can be styled using CSS.
JPG: best for photos and more realistic images.
PNG: best for text-heavy images, line art, or images with fewer colors.
GIF: should only be used for simple animations.

JPG, PNG, and GIF can only be added as an img tag with a source reference.

Using and optimizing JPG and PNG

Before adding images to the site, make sure that they are optimized for the web. Images should be as small as possible without reducing image quality.

Crop images to correct dimensions and size. Hero images can be large, but shouldn’t exceed 1040px, the max-width for the site.
Export it in the proper format. A good rule of thumb is that JPG is good for photographs and more realistic images, while PNG is best for text-heavy images, line art, or images with fewer colors.
Then it is time to compress your image.
- JPG: you may be able to do some initial compression within your image editor (e.g., Photoshop), establishing a good tradeoff between image quality and image size. For additonal compression, download ImageOptim to optimize the the image further.
- PNG: drop it into ImageOptim or ImageAlpha and reduce the color palette, establishing a good tradeoff between image quality and size. If the PNG has an alpha channel, turn it into a transparent PNG-8 instead.
Follow these steps to add to the repository.

Using SVGs

SVG is file type as well as a valid HTML element. What this means is that SVGs can be referenced as an img element that represents the SVG graphic as a whole or as an svg element that can be styled using CSS, like a font.

The prefered method for adding SVGs on 18f.gsa.gov is as a Jekyll include, as shown below. Follow these steps to use SVGs as regular images.

svg placeholder

```
  
  svg placeholder
```
To use an SVG as an include:
1. Add the SVG to the /_includes/svg/ directory.
2. In an include tag, reference the file path of the SVG relative to the _includes directory.
Accessibility

To follow accessibility guidelines, make sure that the SVG image file contains all the necessary markup to allow screenreader users to browse your site without difficulty. From the WCAG guidlines on creating accessibile SVGs:
- title: Provides a human-readable title for the element that contains it. The title element may be rendered by a graphical user agent as a tooltip. It may be rendered as speech by a speech synthesizer.
- desc: Provides a longer more complete description of an element that contains it. Authors should provide descriptions for complex or other content that has functional meaning.
If the SVG is a presentation only image, meaning that it is assistive, but not necessary to provide context within the site, add the following attributes to the svg tag itself:
- role="img"
- aria-hidden="true"

SVG include catalog

This is a list of all of the SVGs that are available as includes (in the _includes directory). All icons are set to their default sizes.

svg placeholders

```
  
svg placeholders
```
As mentioned above, the icons defined above are set to their default size. For some icons this is defined as by the width and height attributes on the SVG. For the smallest icons, it is set by the .icon class on the SVG itself.

Adding images

To add images to the site:

Add the image to the assets directory. - Blog images go in the /assets/blog/ directory. The subdirectories are organized by topic, so place the image in the directory that pertains to blog post’s primary topic. For detailed information on adding images to the blog, see Blog. - All other images can go in the /assets/img/ directory.
Reference the file path in an image tag, making sure to prefix the path with {{ site.baseurl }} and adding alt text for accessibility purposes.

Example of successful image reference with alt text

Example of successful image reference with empty alt text

Example of failed image with alt text

Example of failed image without alt text

  
#### Example of successful image reference with alt text
<img src="{{ site.baseurl }}/assets/img/logos/18F-Logo-S.png" alt="18F logo" />

#### Example of successful image reference with empty alt text
<img src="{{ site.baseurl }}/assets/img/logos/18F-Logo-S.png" alt="" />

#### Example of failed image with alt text
<img src="{{ site.baseurl }}/assets/img/logos/18F-Logo-Small.jpg" alt="18F logo" />

#### Example of failed image without alt text
<img src="{{ site.baseurl }}/assets/img/logos/18F-Logo-Small.jpg" />

The primary way to use both site and blog-specific images is to directly call the image path in an img tag.
- The `` insures that the path is relative to the root of the directory.
- Ensure that each image has alt text for improved site accessibility.
- If the image is presentational only, empty alt text can be added, like so: alt="".

Image lists

This pattern associates text with an icon to break up text blocks improve user understanding.

svg placeholder

Respect for government workers

Civil servants have tremendous knowledge about what it takes to achieve their agency’s mission. We help clear technical and governmental hurdles to better serve the public.
svg placeholder

Human-centered design

We listen to real users to understand their needs and build things that will be useful to them — without sacrificing technical or regulatory requirements.

  
<ul class="icon-list-wrapper">
  <li class="icon-list">
    <figure class="icon-list-image">svg placeholder</figure>
    <div class="icon-list-text">
      <p class="p-bold">Respect for government workers</p>
      <p>Civil servants have tremendous knowledge about what it takes to achieve their agency’s mission. We help clear technical and governmental hurdles to better serve the public.</p>
    </div>
  </li>
  <li class="icon-list">
    <figure class="icon-list-image">svg placeholder</figure>
    <div class="icon-list-text">
      <p class="p-bold">Human-centered design</p>
      <p>We listen to real users to understand their needs and build things that will be useful to them — without sacrificing technical or regulatory requirements.</p>
    </div>
  </li>
</ul>

This component is not available as a Jekyll include. To use it, copy the code snippet above and update the icon, title, and body text accordingly.

Additional resources:
- SCSS references

NSF SBIR UI style guide