Show nested options description in table caption

[colinrotherham]

We don't currently show the description field for nested macro options

It's quite useful to see it, although touches on:

• Investigate allowing headings within table captions govuk-frontend#3881

[netlify]

✅ You can preview this change here:

Name	Link
🔨 Latest commit	4df4123
🔍 Latest deploy log	https://app.netlify.com/sites/govuk-design-system-preview/deploys/65734929063314000841ed83
😎 Deploy Preview	https://deploy-preview-2929--govuk-design-system-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[colinrotherham]

Versus some description fields which don't add much more info:

[christopherthomasdesign]

If we already have options descriptions, and they’re helpful, I think it makes sense to show them like this. It might save users having to scroll back up for more context.

As noted above, this change is less useful in cases where our descriptions aren’t very user-friendly. But I think that’s an argument for improving the descriptions, not an argument against this change. By exposing them like this we might learn a few things about whether users get confused by it.

[36degrees]

LGTM. Can we remove [SPIKE] from the PR title if we're going to merge this as-is.

[colinrotherham]

LGTM. Can we remove [SPIKE] from the PR title if we're going to merge this as-is.

@36degrees Nice, thanks. My only hesitations were around:

1. Some descriptions need improving above
2. Investigation into headings within table captions hasn't happened yet

But if neither of those are concerns it's ready to go

[colinrotherham]

Thanks @CharlotteDowns

Here's a full list of all the component options (with nested options tables) and their descriptions:

Breadcrumbs items

Array of breadcrumbs item objects.

Accordion items

An array of sections within the accordion.

Accordion heading

The heading of each section.

Accordion summary

The summary line of each section.

Accordion content

The content of each section.

Date input items

An array of input objects with name, value and classes.

Date input formGroup

Options for the form-group wrapper.

Character count formGroup

Options for the form-group wrapper.

Character count countMessage

Options for the count message.

Cookie banner messages

The different messages you can pass into the cookie banner. For example, the cookie message and the confirmation message.

Cookie banner actions

The buttons and links that you want to display in the message. actions defaults to button unless you set href, which renders the action as a link.

Error summary errorList

The list of errors to include in the summary.

Footer meta

Object containing options for the meta navigation.

Footer items

Array of items for use in the meta section of the footer.

Footer navigation

Array of items for use in the navigation section of the footer.

Footer items

Array of items to display in the list in navigation section of the footer.

Footer contentLicence

The content licence information. Defaults to Open Government Licence (OGL) v3 licence.

Footer copyright

The copyright information, this defaults to Crown Copyright.

Checkboxes formGroup

Options for the form-group wrapper.

Checkboxes items

Array of checkbox items objects.

Checkboxes conditional

Provide additional content to reveal when the checkbox is checked.

Header navigation

An array of navigation item objects.

File upload formGroup

Options for the form-group wrapper.

Text input prefix

Options for the prefix element.

Text input suffix

Options for the suffix element.

Text input formGroup

Options for the form-group wrapper.

Table rows

Array of table rows and cells.

Table head

Array of table head cells.

Pagination items

The array of link objects.

Pagination previous

A link to the previous page, if there is a previous page.

Pagination next

A link to the next page, if there is a next page.

Select items

Array of option items for the select.

Select formGroup

Options for the form-group wrapper.

Tabs items

Array of tab items.

Tabs panel

Content for the panel.

Summary list rows

Array of row item objects.

Summary list key

The key of each row.

Summary list value

The value of each row.

Summary list actions

The actions of each row.

Summary list items

Array of action item objects.

Summary list card

Options for the summary card. If any of these options are present, a summary card will wrap around the summary list.

Summary list title

Data for the summary card header.

Summary list actions

The actions of each summary card.

Summary list items

Array of action item objects.

Radios formGroup

Options for the form-group wrapper.

Radios items

Array of radio items objects.

Radios conditional

Provide additional content to reveal when the radio is checked.

Task list items

Array of tasks within the task list.

Task list title

Object containing the main title for the task.

Task list hint

Object containing a hint for the task.

Task list status

Object containing the status of the task.

Textarea formGroup

Options for the form-group wrapper.

Fieldset legend

Options for the legend.

[CharlotteDowns]

@colinrotherham the full list above doesn't include:

Text input label

Options for the label component.

Text input hint

Options for the hint component.

(The hint example is one of the screenshot examples above)

Do you know why that might be and if there are any others I might be missing from the list.

[colinrotherham]

Ahh sorry @CharlotteDowns, that makes sense though

The components hint and label are the only ones that don't exist on the site:

https://design-system.service.gov.uk/components/hint – ❌ Page not found
https://design-system.service.gov.uk/components/label – ❌ Page not found

Will only be those two missing for that reason

[CharlotteDowns]

I've pulled all the macro descriptions into this google sheets document with a column for which ones I suggest we change and drafted suggestions [DRAFT - still working on it].

[colinrotherham]

Thanks @CharlotteDowns

Since we merged #2928 we might not need to be so specific in the descriptions

Repeating "array", "object" types etc

[CharlotteDowns]

I have completed drafting all the descriptions that I suggest we change as part of this merge.

Component/pattern	Object	Current Title	Current description	Change?	Proposed description
Accordion	items	Options for items array objects	An array of sections within the accordion.	TRUE	The items within sections of the accordion.
Accordion	heading	Options for items heading object	The heading of each section.	TRUE	The heading of each accordion section.
Accordion	summary	Options for items summary object	The summary line of each section.	TRUE	The summary line of each accordion section.
Accordion	content	Options for items content object	The content of each section.	TRUE	The content of each accordion section.
Breadcrumbs	items	Options for items array objects	Array of breadcrumbs item objects.	TRUE	The items within breadcrumbs.
Date input	items	Options for items array objects	An array of input objects with name, value and classes.	TRUE	The items of each date input component.
Date input	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the date input component.
Date input	hint	Options for hint component	Options for the hint component.	TRUE	Can be used to add a hint to a date input component.
Character count	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the character count component.
Character count	countMessage	Options for countMessage object	Options for the count message.	TRUE	The message for the character count component.
Character count	label	Options for label component	Options for the label component.	TRUE	Can be used to add a label to a character count component.
Character count	hint	Options for hint component	Options for the hint component.	TRUE	Can be used to add a hint to the character count component.
Cookie banner	messages	Options for messages array objects	The different messages you can pass into the cookie banner. For example, the cookie message and the confirmation message.	FALSE
Cookie banner	actions	Options for messages actions array objects	The buttons and links that you want to display in the message. actions defaults to button unless you set href, which renders the action as a link.	FALSE
Error summary	errorList	Options for errorList array objects	The list of errors to include in the summary.	TRUE	The list of errors to include in the error summary.
Footer	meta	Options for meta object	Object containing options for the meta navigation.	TRUE	The section to add content before the standard footer component.
Footer	items	Options for meta items array objects	Array of items for use in the meta section of the footer.	TRUE	The meta items add content within a unordered list to the meta section of the footer component. These appear above any text or custom html in the meta section.
Footer	navigation	Options for navigation array objects	Array of items for use in the navigation section of the footer.	TRUE	The navigation section of the footer before a section break and the standard footer component.
Footer	items	Options for navigation items array objects	Array of items to display in the list in navigation section of the footer	TRUE	The items within the navigation section of the footer component.
Footer	contentLicence	Options for contentLicence object	The content licence information. Defaults to Open Government Licence (OGL) v3 licence.	TRUE	The content licence information within the footer component. Defaults to Open Government Licence (OGL) v3 licence.
Footer	copyright	Options for copyright object	The copyright information, this defaults to Crown Copyright.	TRUE	The copyright information in the footer component, this defaults to Crown Copyright.
Checkboxes	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the checkboxes component.
Checkboxes	items	Options for items array objects	Array of checkbox items objects.	TRUE	the items within the checkboxes component.
Checkboxes	conditional	Options for items conditional object	Provide additional content to reveal when the checkbox is checked.	FALSE
Checkboxes	hint	Options for hint component		TRUE	Can be used to add a hint to the checkboxes component.
Checkboxes	label	Options for label component		TRUE	Can be used to add a label to a checkboxes component.
Header	navigation	Options for navigation array objects	An array of navigation item objects.	TRUE	Can be used to add navigation to the header component.
File upload	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the file upload component.
File upload	label	Options for label component		TRUE	Can be used to add a label to the file upload component.
File upload	hint	Options for hint component		TRUE	Can be used to add a hint to the file upload component.
Text input	prefix	Options for prefix object	Options for the prefix element.	TRUE	Can be used to add a prefix to the text input component.
Text input	suffix	Options for suffix object	Options for the suffix element.	TRUE	Can be used to add a suffix to the text input component.
Text input	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the text-input component.
Text input	label	Options for label component	Options for the label component.	TRUE	Can be used to add a label to a text input component.
Text input	hint	Options for hint component	Options for the hint component.	TRUE	Can be used to add a hint to a text input component.
Text input	errorMessage		Options for the error message component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.	FALSE
Table	rows	Options for rows array objects	Array of table rows and cells.	TRUE	The rows within the table component.
Table	head	Options for head array objects	Array of table head cells.	TRUE	The head cells within the table component.
Pagination	items	Options for items array objects		TRUE	The items within the pagination component.
Pagination	previous	Options for previous object	A link to the previous page, if there is a previous page.	FALSE
Pagination	next	Options for next object	A link to the next page, if there is a next page.	FALSE
Select	items	Options for items array objects	Array of option items for the select.	TRUE	The items within the select component.
Select	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the select component.
Select	label	Options for label component		TRUE	Can be used to add a label to the select component.
Select	hint	Options for hint component		TRUE	Can be used to add a hint to the select component.
Tabs	items	Options for items array objects	Array of tab items.	TRUE	The items within the tabs component.
Tabs	panel	Options for items panel object	Content for the panel.	TRUE	The contents of each tab within the tabs component. This is referenced as a panel.
Summary list	rows	Options for rows array objects	Array of row item objects.	TRUE	The rows within the summary list component.
Summary list	key	Options for rows key object	The key of each row.	TRUE	The reference content (key) for each row item in the summary list component.
Summary list	value	Options for rows value object	The value of each row.	TRUE	The value for each row item in the summary list component.
Summary list	actions	Options for rows actions object	The actions of each row.	TRUE	The action link content for each row item in the summary list component.
Summary list	items	Options for rows actions items array objects	Array of action item objects.	TRUE	The items within the summary list component.
Summary list	card	Options for card object	Options for the summary card. If any of these options are present, a summary card will wrap around the summary list.	FALSE
Summary list	title	Options for card title object	Data for the summary card header.	FALSE
Summary list	actions	Options for card actions object	The actions of each summary card.	TRUE	The action link content for each summary card variant of the summary list component.
Summary list	items	Options for card actions items array objects	Array of action item objects.	TRUE	The items within the summary card variant of the summary list component.
Radios	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the radios component.
Radios	items	Options for items array objects	Array of radio items objects.	TRUE	The items within each radio component.
Radios	conditional	Options for items conditional object	Provide additional content to reveal when the radio is checked.	FALSE
Radios	hint	Options for hint component		TRUE	Can be used to add a hint to the radios component.
Radios	label	Options for label component		TRUE	Can be used to add a label to the radios component.
Task list	items	Options for items array objects	Array of tasks with the task list.	TRUE	The items for each task within the task list component.
Task list	title	Options for items title object	Object containing the main title for the task.	TRUE	The main title for the task within the task list component.
Task list	hint	Options for items hint object	Object containing a hint for the task.	TRUE	The hint for each task within the task list component.
Task list	status	Options for items status object	Object containing the status of the task.	TRUE	The status tag for each task within the task list component.
Textarea	formGroup	Options for formGroup object	Options for the form-group wrapper.	TRUE	Additional options for the form group containing the textarea component.
Textarea	label	Options for label component		TRUE	Can be used to add a label to the textarea component.
Textarea	hint	Options for hint component		TRUE	Can be used to add a hint to the textarea component.
Fieldset	legend		Options for the legend.	TRUE	The legend for the fieldset component.

[CharlotteDowns]

I've made suggestions for new descriptions in the above table. I'm handing this back over to the Frontend Squad but happy to be available for any clarification/further detail.

[domoscargin]

We should probably do a quick check on the first two bullet points in this comment:

• do screen readers list the heading in the list of headings they produce?
• do screen readers use the caption content as the label for the table in the list of tables they produce?

The descriptions look distinct visually. VoiceOver reads out the <h3> and the <span> within as one breathless thing though, which I'm not sure is a great experience for screenreader users. Especially on things like Cookie banner messages, where the title is

Options for messages array objects The different messages you can pass into the cookie banner. For example, the cookie message and the confirmation message.

I wonder if there's any way to organise things to conform to:

If you need paragraph or any other text between the heading and the start of the table, then make a separate heading and caption.

[colinrotherham]

@domoscargin This is the perfect feedback

What would you do? 😅

Hidden punctuation?
Different markup?

[domoscargin]

What would you do? 😅

Hidden punctuation? Different markup?

I think ideally different markup, but I don't have a solution off the top of my head. What about something like:

<h3>[table name]</h3>
<table>
{% if description %}
<caption>[description]</caption>
{% endif %}
</table>

[romaricpascal]

Putting it back in progress while the last comments get addressed.

[36degrees]

To try and unblock this, moving the description outside of the heading and making it a paragraph seems to do what we want (and makes sense to me) – is there a reason we've ruled that out?

<caption class="govuk-table__caption{% if table.slug == 'primary' %} govuk-visually-hidden{% endif %}">
  <h3 class="govuk-heading-m">
    {{ table.name | safe }}
  </h3>
{% if table.description %}
  <p class="govuk-body">{{ table.description | safe }}</p>
{% endif %}
</caption>

[36degrees]

Oh, I should have read that linked issue properly – I can see David's recommended against it, but I can't see why…

[colinrotherham]

@36degrees Yeah I've tried a hacky way to avoid multiple flow content in 4df4123

Dropping that commit would give us #2929 (comment) but not explored testing or reasons why