Document new and existing link modifiers in Design System

[36degrees]

What

In alphagov/govuk-frontend#2183 we're going to be introducing new classes for links:

• govuk-link--inverse for white links to use on dark backgrounds
• govuk-link--no-underline for links without underlines

These should be documented on the links section of the typography page in the Design System so that users know how and when to use them.

There are also a couple of existing undocumented link styles which we should consider documenting:

• govuk-link--muted for grey links (which are rarely used – we could also consider deprecating this class and its mixin)
• govuk-link--text-colour for black (text coloured) links – more often the mixin is used for navigational links, like back link, breadcrumb, and the links in the footer.

Finally, there are the govuk-link-style-error and govuk-link-style-success mixins for error (red) and success (green) link styles, which have no corresponding modifier class. We should consider whether these modifiers should exist, and if so add them to GOV.UK Frontend and document them.

Why

With the new link styles and hover states being introduced in #2183, there's a little extra complexity that needs to be considered when users roll their own link modifiers.

These modifiers cover a couple of common cases where users would currently need to implement their own link modifiers. Document them so they know they exist and can use them.

Who needs to know about this

Chris, Ollie, Calvin

Done when

• Decide which link modifiers should be documented
• Decide whether any link modifiers should be deprecated
• Add guidance for link modifiers with examples

[christopherthomasdesign]

Showing my working out... Figuring out what the use case is for each of these and how / where to document it:

govuk-link--inverse for white links to use on dark backgrounds

• Use case: use for custom components or patterns with darker backgrounds
• This class is currently only used in the header component, where it's overridden slightly to remove the underline. Other examples of inverse links are not in the Design System itself, just the backlog e.g. interruption card – could we link to something like the discussion for a backlog item?
• I think this is definitely worth including, we’ve seen lots of teams use this kind of style
• Probably worth mentioning in the guidance that users should make sure the background colour that has a 4:5:1 contrast ratio with the white text
• For the example – should we set the whole background on the example body to blue? Looks ok, though the blue background clashes with the grey line in a slightly uggly way…

govuk-link--no-underline for links without underlines

• Use case: use for navigational components that include lots of links in one place, that persist over several pages, and where the placement and content makes it clear that they are links
• Had a first go at adapting our existing guidance here: #1578 (comment)

govuk-link--muted for grey links

• Personally happy to leave these undocumented in the Design System site because I’m not sure there’s a strong use case for them.
• They’re not currently used by any component or pattern in the Design System that I’m aware of. We used to use them for the feedback links at the bottom of pages on GOV.UK, but they’ve been replaced by the current blue banners.
• I’m not proposing removing them right now, but we may want to revisit them in the future and see if teams are using them.

govuk-link--text-colour for black (text coloured) links

• Use case: use for ‘quiet’ navigational components?
• I’m not sure there’s a coherent use case for this either, though I think there is sometimes a need. It may be a style we want to reserve for certain components that need to fade into the background a little more i.e. back buttons and breadcrumbs.
• I guess it’s like secondary navigation? Even then it gets messy to define cos you could argue a side navigation is secondary navigation and we generally don’t style those in black.

govuk-link-style-error and govuk-link-style-success mixins

I feel less sure about these, I don't know how useful they'd be. Have we seen them used outside of the components they're used in the Design System (error summary and notification banner)???

———

I suppose with the last four (govuk-link—muted, govuk-link--text-colour, govuk-link-style-error, govuk-link-style-success) you could just document those in Frontend docs. So they’re accounted for. But they’re less visible to most users. The reason being we think the use cases aren’t clear enough or they’re unlikely to be used much.