Usage guidelines

Introduction

The page introduction will be the first item on the page and will consist of an initial highlighted paragraph followed by an additional content. It should be a brief introduction to the component, explaining what it is, what it’s for and how it works. It could also include a note on what variants are available and how they differ from the default version.

Structure

This section is a description of what the component consists of (the atoms which make up a molecule), the order those items should appear in, and whether or not those items are mandatory or optional. Explain here if any variants consist of alternative items and whether or not there are different requirements as far as what is and isn’t mandatory or optional.

Placement

This section describes where the component exists on a page – is it part of the header or footer? Is it only for use in form journeys? Does it form part of a wider pattern (and, if so, how does it fit in with that pattern)? Are the different variants designed to be used in different locations on the page?

Accessibility

Some components may contain features which have a bearing on accessibility. This section should call those out, detailing particular use of Aria attributes, considerations around colour contrast and so on. It should also clearly explain what existing patterns are followed and why, listing the relevant WCAG Success Criterion where applicable.

Occasionally, WCAG rules may have been considered and dismissed for particular reasons; usually this will not be the case, but there are rules which contradict each other, so explanation should be given as to which rules should apply, and which one has been followed and why.

Also include details about heading hierarchy, ensuring that correct semantic patterns are used both within the component itself and within the page as a whole.

Interactions and animations

This section describes what happens when people use a component – does anything move, expand, or change colour when users hover or click on part of the component? If so, that detail belongs here. The section should also describe what happens when animations are turned off; for example, does an item snap into place rather than transitioning?

Non-JS requirements and considerations

Use case and exception scenarios

This section should explain when a component should be used, for example which journeys it should be used in, whether or not it is for use within form or brochureware pages, for example.

Most rules have exceptions, so details should be given of where a component should not be used; for example, 'this component can be used within form journeys, but not those within modals'.

Labels and headings

Some components have fixed headings and labels, or ones which have to be changed via the locale files, so this detail should be called out here. You should also include information about maximum character lengths, whether heading weights can be changed and so on.

Valid, error and disabled states

Form elements will need to include additional designs for when the inputs are valid, errored or disabled. Generally, these should be the same as the Framework standard valid / error / disabled states, in which case this section only needs to state ‘Follows standard Framework patterns’, however any differences should be explained, along with any reasoning behind the differences.

Design notes

This section is intended to call out any specific design requirements and should not just replay detail which is available in the Sketch file. Instead, it should include information which is relevant to non-designers, anything from colour restrictions, how many grid columns a component should occupy at various breakpoints, to absolute minimum / maximum widths, differences from standard spacing, suitable colour combinations or anything else purely design-related and not included elsewhere in the usage guidelines.

Usage guidelines example content

The following is an example of content which should be included in Framework component usage guidelines. They are only loosely based on the help utility section to give an idea of what should be included in each section of the document and are not an accurate reflection of patterns or usage of the actual component.

---

Introduction

The help utility section permits the display of contact information for project teams at a glance. It works by containing a call us panel and an FAQ panel in a pair of matched show/hide areas.

The layout can be either side-by-side or stacked, with column widths and ordering variable depending on the number of phone numbers or a team's other specific requirements.

Structure

• Contains FAQ and Call Us molecules, both of which are mandatory.
• The child elements can be aligned either as 50:50 or 67:33 splits or stacked depending on the balance of content they contain – see Design notes for further information.
• The child elements can be ordered to suit individual project requirements.
• Both child elements should adhere to their own usage guidelines when used within the help utility section.

Placement

• Should only be used at the bottom of a page, as the last section before the footer.

Accessibility

• The colours used have been selected to afford the highest possible contrast between elements (WCAG2.1, SC 1.4.3: Contrast (Minimum)).
• All buttons follow the minimum 44px height rule, with suitable contrast between default, hover and focus states (WCAG2.1, SC 2.4.7: Focus Visible).
• All headings should be relevant and follow semantic patterns – main <h2> for ‘Need Some Help’, <h3>s for ‘Call Us’ and ‘FAQs’ and <h4>s below that where necessary states (WCAG2.1, SC 2.4.6: Headings and Labels).
• All animations can be turned off either using a site-specific cookie or browser / machine settings (WCAG2.1 SC 2.3.3: Animation from Interactions).
• Specific Aria attributes are used to call out when the FAQ, Call Us or both sections are open or closed to help visitors using assistive technologies.
• If the FAQ part spans either eight columns or full width, do not forget that the copy must only run across seven columns in order to ideally keep line lengths below 80 characters (WCAG2.1, SC 1.4.8).

Interactions and animations

• Both child elements transition to full height when their triggers are clicked, with the open/close chevrons also animating.
• The show / hide interactions work independently of each other, not in tandem as a concertina.
• When animations are switched off, the height changes are instant.

Non-JS requirements and considerations

• When JavaScript is unavailable, the help utility section is displayed permanently open, with both the FAQ and Call Us panels also fully open.
• See individual component documentation for more detail.

Use case and exception scenarios

• The help utility section should contain the only FAQ and Call us sections on a page.
• There may be occasions where legal small print is requested to be included between the help utility section and the footer; in this instance, challenge and check the requirement as appropriate before overriding the default placement.

Labels and headings

• The title (set by default as "Do you need some help?") can be changed depending on project team requirements.

Valid, error and disabled states

• Follows standard Framework patterns.

Design notes

• Content width ratios can vary depending on which content requires prioritisation:

  • Desktop: 50:50 (6 cols + 6 cols), 67:33 (8 cols + 4 cols), 33:67 (4 cols + 8 cols)
  • Tablet: 50:50 (4 cols + 4 cols), full width (stacked)
  • Mobile: Full width (stacked)

• Colour options are restricted for usability reasons to:

  • White background with Base Blue triggers
  • Base Blue with Abeille Assurances Blue triggers
  • Base Grey with Abeille Assurances Blue triggers
• Font colours within the FAQ and Call us panels should be as per their standard component usage.