The Anatomy of a Listing

We have two main variations of listing, a 'Standard' and 'Visual'. The Standard listing is more 'informational' and used in a linear page layout. The Visual listing is a bit more 'showy' with more emphasis on the media imagary and it tends to be used in conjuntion with more creative page layouts

All listings share a common HTML structure, this allows for easier integration into a CMS. If you need a custom listing type then we recommend extending the styles of one of the existing listing types. Do this by keeping the same structure as one of our listing types and then add a custom override class which you can style in your integration style sheet.

Each listing is made up of a header, optional media (an image usually), a body and sometimes a footer. In turn these can can be comprised of different sub components such as sub titles, icon lists or even additional 'Call To Actions' aka CTA's.

Standard Listing

Let's run through the standard list item and explore some of the ways we can put listings together.

Simple listing with media

Keeping it simple for the moment, consider a standard listing in the most common configuration. It consists of a only one link, the main title link, an media image and a short body description.

Example:

Show Code

          <article class="bc-list-item-standard">
            <a href="#1232">
              <div class="bc-list-item-media">
                <img src="../img/dummy/650x354-img-1.jpg" width="300" height="169" alt="">
              </div>
              <header class="bc-list-item-header">
                <h2 class="bc-list-item-title">Main title text, this should describe the links
                  destination page</h2>
              </header>
              <div class="bc-list-item-body">
                <p>A listings description, we recommend this is short and sweet maximum 190
                  characters, just enough to add some value to the user.</p>
              </div>
            </a>
          </article>
          <article class="bc-list-item-standard">
            ...
          </article>

Accessibility and UX

For good UX we want the whole item to be clickable but we want to do this without having lots of links to the same place (i.e we don't want to wrap the image in one link, the title in another, etc) because this is bad for UX and accessibility.

But... We have a slight problem, we want our image to appear above the text on mobile meaning we need our image first in the HTML.

Why is this a problem?
- Well, because it means that screen reader users and search engines will associate the alt text of the image as the most important link text. This is not helpful or accessible unless maybe if the image contains text can be considered the core link text, but usually this is repeated as part of the title.

So, it's important that you provide a null/empty alt text for your images (alt=""), but only when used in 'image first listings', like those found in SUI or similar scenarios where it makes sense. This ensures that the list item title is the first thing associated with the link and, as with all links, the link text must describe the nature of the links target page.

Isn't this bad? I've always been told images must have an alt text?
- Yes and no, they must have alt attribute, otherwise a screen reader will read out the filename of the image, imagine that!

Providing actual text is the base line rule but there are exceptions when it makes logical sense for accessibility. In this context, the alt text of the image becomes the core link text. We could 'tick a box' and provide an alt text that matches the main title but then our poor screen readers would have to read the same content twice! Null/Empty alt atrributes allows assistive technologies to ignore images that we, as authors, don't deem worthly.

Change your design so images don't come first!
- Accessibility should not limit creativity and this performs very nicely screen readers, we of course check with real people using real assistive technologies :-)

Listing with additional call to action

This is the same as the previous examples but includes an additional call to action link used in a scenario where a user may have read the informational text and wants to go stright to the 'action'.
Note, that the body text isn't clickable in this example, see the code for for more info.

Show Code

Which bit(s) should I wrap my links around?

If the list item is only providing a main title link then we recommend wrapping the link around all of the content, including the media as we saw in the previous example.

If the the list item has a main title link and additional link(s) inside the the body then you can wrap the title link around the media and the header and link other items indidually within the body or footer of the list item.

          <article class="bc-list-item-standard">
            <a href="#3452">
              <div class="bc-list-item-media">
                <img src="../img/dummy/630x354-img-3.jpg" width="300" height="169" alt="">
              </div>
              <header class="bc-list-item-header">
                <h2 class="bc-list-item-title">Main title text, this should describe the
                  links destination page</h2>
              </header>
            </a>
            <div class="bc-list-item-body">
              <p>A listings description, we recommend this is short and sweet maximum 190
                characters, just enough to add some value to the user.</p>
              <p>
                <a class="bc-icon-link-block-md" href="#2352">
                  <svg class="bc-svg bc-svg-right-dir bc-dir" aria-hidden="true">
                    <use xlink:href="#icon-right-dir"></use>
                  </svg>Direct link to a related call to action
                </a>
              </p>
            </div>
          </article>
          <article class="bc-list-item-standard">
            ...
          </article>

Textual listing with borders and icon lists

Listing can be used without media but adding a class of bc-list-item-has-no-media, they can be used in conjunctiona with our icons lists and can be seperated with a border by adding a class of bc-list-item-has-border.


Show Code

          <article class="bc-list-item-standard bc-list-item-has-no-media bc-list-item-has-border">
            <a href="#23523">
              <header class="bc-list-item-header">
                <h2 class="bc-list-item-title">Location name</h2>
                <h3 class="bc-list-item-subtitle">Additional location infomation</h3>
              </header>
            </a>
            <div class="bc-list-item-body">
              <dl class="bc-svg-dl bc-svg-dl-lg">
                <dt>
                  <svg class="bc-svg bc-svg-phone" aria-hidden="true">
                    <use xlink:href="#icon-phone"></use>
                  </svg>
                  <span class="sr-only">Telephone number</span>
                </dt>
                <dd>+44 000 000 1233</dd>
                <dt class="bc-fax-lb">
                  <svg class="bc-svg bc-svg-print" aria-hidden="true">
                    <use xlink:href="#icon-print"></use>
                  </svg>
                  <span class="sr-only">Fax number</span>
                </dt>
                <dd>+44 000 000 1234</dd>
                <dt>
                  <svg class="bc-svg bc-svg-mail" aria-hidden="true">
                    <use xlink:href="#icon-mail"></use>
                  </svg>
                  <span class="sr-only">Email</span>
                </dt>
                <dd>
                  <a href="mailto:mail@britishcouncil.xx">mail@britishcouncil.xx</a>
                </dd>
              </dl>
            </div>
          </article>
          <article class="bc-list-item-standard bc-list-item-has-no-media bc-list-item-has-border">
            ...
          </article>

Another example

This example combines images and icons and an experimental bc-list-item-note for things like prices or tags etc.