Summary list

[amyhupe]

Use this issue to discuss the summary list component.

[stevenaproctor]

@NickColley @dashouse @amyhupe We are going to use this code for our add to list pattern but in our pattern there is no key-value pair. There is just a value used for the <dt> and then the actions. Adding a key like 'Name' would be quite repetitive. Here's a screenshot.

We thought about using a <ul> but that meant nesting lists in lists. What do you all think about using the same summary list for a list without a key-value pair but associated actions?

[stevenaproctor]

Or is there a way of grouping all the <dd>s under a single <dt>?

<dl>
  <dt>Directors</dt>
  <dd>Sydney Russell
    <ul>
      <li>Change</li>
      <li>Remove</li>
    </ul>
  </dd>
</dl>

[stevenaproctor]

@timpaul @dashouse Thanks for talking through the add to list pattern and possible code today. I will take a look at the <ul> solution. Expect a contribution soon 😸

[NickColley]

We've updated the summary list component recently:

1. to fix issues with long words not wrapping (thanks @dwybourn for also raising)
2. to ensure that if there's only one 'action item' that it's not put into a list. (thanks @Fenwick17 for raising)

Make sure you're on version 2.7.0 of GOV.UK Frontend to get these improvements.

Update: v2.8.0 has even better support for word wrapping so please upgrade to 2.8.0 :)

[NickColley]

We've had a contribution so that people can remove the visited state from the action (Change) links.

We've decided to merge this so service teams can add classes manually but are interested if we could improve any guidance based around this.

You can read how they got on here: alphagov/govuk-frontend#1233 (comment)

[tmakin]

The intermediate div between the dl and dt raises WCAG validation warnings on the Deque validator
https://dequeuniversity.com/rules/axe/3.0/dlitem
https://www.w3.org/TR/WCAG20-TECHS/H40.html

I'm curious to know whether this intermediate element is considered a spec violation. If not I will report issue to Deque and suggest they relax their validation rules to check for a dl which is not a direct parent for the dt.

<dl class="govuk-summary-list">
  <div class="govuk-summary-list__row"> <!-- Deque doesn't like this line -->
    <dt class="govuk-summary-list__key">
      Name
    </dt>
    <dd class="govuk-summary-list__value">
      Sarah Philips
    </dd>
    <dd class="govuk-summary-list__actions">
      <a class="govuk-link" href="#">
        Change
        <span class="govuk-visually-hidden"> name</span>
      </a>
    </dd>
  </div>
</dl>

[dashouse]

@tmakin Thanks for the comment. The issue is being flagged on an old version of the spec, a <div> inside a <dl> is considered a valid way of grouping a <dd> and <dt> - see https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

You'll find a few of issues raised about this on aXe and other validatiors. We suggest omitting from your tests or making a note to ignore it.

[tmakin]

@dashouse Many thanks, that reference clears things up.

Looks like axe are on the case already:
dequelabs/axe-core#262

[edwardhorsford]

Is it possible to have some items with an action menu and some not? If I don't provide on one, but I do on others, the border doesn't extend fully across.

[edwardhorsford]

I can possibly provide an empty array to actions.items, but this then results in an empty ul, which isn't ideal. Possibly a check for count of items in actions.items could solve this?

[edwardhorsford]

I added a pr to fix the empty ul - #1259

[edwardhorsford]

I wonder if we could have a new component (or alt version of this one) for simplified key-value pair display.

Right now I think many services / teams will be using separate paragraphs for each item - I suspect key-value pair with description lists would be more appropriate.

Some examples:

Service manual

GOV.UK

This sort of display is often used for 'metadata' type information about a page / service / piece of content.

[edwardhorsford]

Another example of dd from govuk search:

[ChrisBAshton]

Hello 👋 we're implementing a design that's based on the summary list pattern:

We can accomplish this by passing something like this to the summary list:

items: {
  field: index + 1,
  value: sanitize(
    "<h4 class='govuk-heading-s govuk-!-margin-bottom-0'>#{attachment.title}</h4>"\
    "#{render('components/attachment_meta')}"
  )
}

However, that's quite ugly/brittle - and I do have misgivings about the rendered HTML. Currently the output would be something like this:

<dl>
  <dt>1</dt>
  <dd><h4>Foo</h4>Unique ref</dd>
</dl>

Semantically, it should just be an ordered list:

<ol>
  <li><h4>Foo</h4>Unique ref</li>
</ol>

The summary list component doesn't tie itself to the description list/terms/descriptions markup - at least not by name - so in theory there's nothing stopping us rendering an <ol> instead of a <dl> under certain conditions.

@benthorner & I were wondering if there's a need here that the summary list component isn't currently meeting, and could be expanded to support? For example, we also use numbers as keys in Collections Publisher, although sometimes we use words like "AND" or "OR", so it's not quite as straightforward.

We're proposing, for consideration, an optional numbered: (true|false) attribute, which when true would render an <ol> rather than a <dl> and automatically prefix each item with a number. We could then call the summary list component more cleanly, i.e.:

numbered: true,
items: {
  field: attachment.title,
  value: render('components/attachment_meta')}
}

The field would automatically be rendered as an <h4>, and the value associated with it (by being rendered beneath it), so it is behaviourally very similar to the current offering.

Would this be worth considering including in the design system?

[timpaul]

Thanks @ChrisBAshton and @benthorner - It's an interesting use case that that we'd not considered. We'd need to see some more evidence of a need for this from other teams I think, before we considered supporting it.

[lfdebrux]

I'd like to request a style change/option to the summary list component, to have the first column be 33.3333% in width instead of 30%.

This would make it easier to have other content around the summary list be visually aligned with it. Currently if you have things such as cards above the summary list, you can't use the grid system to align the "seams".

[chris-weston]

When using the summary list without actions there is a lot of space left on the right hand side. Could the other columns use this available space to wrap their content less?

[hannalaakso]

@chris-weston Thanks for your comment.

You can customise the widths of columns in the summary list using the width override classes.

We have an open issue to document in the Design System website how to do this: alphagov/govuk-design-system#1196 (the issue links to the table component that shows an example you can use to do this in the summary list). Feel free to comment on that issue if you have any thoughts on it.

[chris-weston]

Hi @hannalaakso thanks for the reply, yes I did try using 'govuk-!-width-one-half' on the key in my row, but it seemed as though it was something that could be added at the row level, or even the summaryList level to apply it to all.

[terrysimpson99]

A discussion on slack has just arisen about adjusting the width in the summary list. A similar discussion about 'Check answers' resulted in an update to guidance: alphagov/govuk-design-system#1835

Can that update also be applied to the summary list guidance?

[calvin-lau-sig7]

On 31 January 2023, we released the Summary card as a new variant within the Summary list component.

See the release notes for GOV.‌UK Frontend v4.5.0 to find out more.

[barry-moj]

@joelanman When will the updates implemented into v4.5.0, specifically around the summary cards for multiple lists, be implemented into the prototyping kit? Sorry if it is in there, but struggling to get the styling to appear like it does on the Summary List components page.
Cheers

[joelanman]

@barry-moj in v13, Frontend is a plugin, you can update it in Manage Prototype > Plugins. In v12, you have to update the version in package.json

[barry-moj]

Cheers Joe!

[CharlotteDowns]

We ran an external accessibility audit for some of the components and patterns in GOV.UK Frontend in May 2023. In that audit, we included an example of the Summary list (card) component. We’re adding results from that audit here so that we can:

• document, discuss and address the findings
• inform future contributors of the findings

Two accessibility issues raised

Issue 1: WCAG A

Delete work history' isn't specifying for which card it applies

The ‘Delete work history’ links for each section, rely on surrounding content to understand their context and which work they will be deleting. As the link is not marked up in the same list item, table cell, or using different methods of aria, the link requires a user to move their focus to understand which work history they will be deleting.

More detail in this issue:

• #3673

Issue 2: WCAG A

'Change [row heading]' link doesn't give full context for the summary card it applies to

The ‘change’ links have been provided with additional link text to inform users of screen reading assistive technologies that they relate to the different questions i.e., ‘job title’. However, additional context is required to understand their whole purpose as to which section and work they relate to. For example, a user would need to navigate backwards to locate the heading to which they are sectioned under, and as there are multiple ‘change job title’ links, this can be confusing for users.

More detail in this issue:

• #3674

[jrbarnes9]

Hi. As I understand it, this new statement on WCAG 2.2 guidelines should be an 'OR' statement, rather than 'AND'. For example: "...are at least 24px by 24px in size, or have adequate spacing"

Because in this case, the action links in the component examples have a height of 23px so they are not "at least 24px by 24px in size".

...but they do meet the WCAG 'spacing' exception:

if a 24 CSS pixel diameter circle is centered on the bounding box of each, the circles do not intersect another target or the circle for another undersized target;

[shabana-ali]

Hello,

With the addition of multiple action links, I have noticed that on a two-thirds column layout, the links stack when the viewport width is 1280 CSS pixels wide and the page is zoomed to 150%. The WCAG 2.2 success criterion 2.5.8 Target Size (minimum) is met.

Would you consider revising the 20% width set for govuk-summary-list__actions:

.govuk-summary-list__actions {
    width: 20%;
    text-align: right;
}

Obviously this is dependant on the text length of the links. The HMRC Add to a list pattern handles this although they only have 2 description values.

[JeennJeenn]

Hi all.
I had an interesting design dilemma that I would like to share along with a request to add in a customisation to the summary card component as a standard design example.

I was designing a "review and submit" page to have at the end of a application review journey. The user would go through and review several different pieces of information and select to confirm or query the information.
The 'yes/no' answer is the only value that the user can change throughout the journey. They cannot change the information they are reviewing.
On the review page, I needed a way to display the 'yes/no' answer from the user along with the option to change their answer as well as the information they were reviewing.

We had a few iterations on this before we got it right.
Our first iteration made the user believe that they could update the information itself through clicking the change action.

We needed a way of detaching the change action from the information and attaching it to the confirmation value.
We explored summary list, summary card components as well as tables and they almost worked, but not quite fitting all criteria.

In the end we made two tweak to the standard summary card component.
We used the summary card component as the grey header colour was important to group the information correctly.
We added the 'yes/no' value by the user in the heading of the summary card next to the main header question.
We removed the separation line in between the information values to bundle them up together and making them show as one piece of information.

When retesting this, we could confirm that our users no longer believed they could update the information, but instead expected to be able to change the 'yes/no' value that they selected throughout the journey.

We had managed to attach the change action to the value and detach it from the information.

So we would like for this customisation to be added into the component as a valid option as these two small changes completely changed how our users viewed the component and their expectation to the change action.
We have tested this on both big and small screen size. We have it rendering the same as the values within a summary list, so the question, value and change link sit from top to bottom within the header row.

It would be interesting if anyone has had a similar requirement and how you solved it.