Document the standard for link weights

[Scotchester]

As discussed in #262, the standard for the font weight of links was not documented.

This PR proposes some language to do that.

This language was written by me and has not been vetted by any designer. Therefore, I definitely need some designer review on this PR :)

Additions

• Copy about link weight

Changes

• Modifies webfont example classes to also style li children

Review

• @nataliafitzgerald
• @stephanieosan
• @caheberer
• @jimmynotjim

Screenshots

Todos

• Explore an alternate technical approach in CF, like setting all links to medium by default and then override back to regular for inline links. Might be tricky, though. And doesn't affect this PR.

Checklist

• [x] Changes are limited to a single goal (no scope creep)
• [x] Code can be automatically merged (no conflicts)
• [x] Code follows the standards laid out in the front end playbook
• [x] Passes all existing automated tests
• [x] New functions include new tests
• [x] New functions are documented (with a description, list of inputs, and expected output)
• [x] Placeholder code is flagged
• [x] Visually tested in supported browsers and devices
• [x] Project documentation has been updated (including the "Unreleased" section of the CHANGELOG)

[nataliafitzgerald]

@Scotchester

I'm glad to see you're documenting this!

• What if we add the section about font weights to the "Body text and links" section as it's own paragraph. In other words remove the "A note about font weight" heading.
• Also, I think we can safely remove the blurb about Georgia since we agreed that we are no longer using Georgia on our website (moving forward). But, if you don't think we're ready to remove this yet it's fine to leave it.
• For the "Body text and links" heading could we go up to H3 and for the "Paragraph links" and "List links" headings go up to an H4?
• Did you consider calling the "Paragraph links" "Inline links" instead? The reason I ask is that it seems to me that the defining characteristic is not that these are in a paragraph but that these are in a sentence (surrounded by paragraph text). Even if there was a link within a bullet list sentence, it would still get the Avenir Next Regular styling unless the whole bullet is the link.
• In terms of Wagtail it seems like what changes the styling (currently) is whether you input a link in a "Links" field (Text/URL) or whether you input a link within a rich text field. Links that are added in the "Links" field are not necessarily a list of links (there can be one or more than one). I can see from looking at the code, though, that the style name for these are "list list__links" so I imagine that's the genesis for this name. Still we should probably remove the bullets from the visual example shown in the screenshot. That way we don't confuse users in terms of what we mean here.
• If we do go with "Paragraph links" lets use the word "paragraph" in the first sentence of the content to the left (instead of "body").
• Will you be documenting the way these types of links appear at mobile, specifically the list links?

[Scotchester]

What if we add the section about font weights to the "Body text and links" section as it's own paragraph. In other words remove the "A note about font weight" heading.

OK, will do.

Also, I think we can safely remove the blurb about Georgia since we agreed that we are no longer using Georgia on our website (moving forward). But, if you don't think we're ready to remove this yet it's fine to leave it.

I didn't realize/remember that we decided to do that. Even for "long read" articles and such? If so, it can certainly be removed.

For the "Body text and links" heading could we go up to H3 and for the "Paragraph links" and "List links" headings go up to an H4?

This usage is consistent with many (but not all) other pages on the DM. Since it's inconsistent, I'll go ahead and update it here, but all headings should get a 2nd look as part of removing the custom parts of the type hierarchy in the DM.

Did you consider calling the "Paragraph links" "Inline links" instead? The reason I ask is that it seems to me that the defining characteristic is not that these are in a paragraph but that these are in a sentence (surrounded by paragraph text). Even if there was a link within a bullet list sentence, it would still get the Avenir Next Regular styling unless the whole bullet is the link.

I didn't consider that, because all I did was remove the superfluous typeface names from those headings, but that makes sense. I'll make that change.

In terms of Wagtail it seems like what changes the styling (currently) is whether you input a link in a "Links" field (Text/URL) or whether you input a link within a rich text field. Links that are added in the "Links" field are not necessarily a list of links (there can be one or more than one). I can see from looking at the code, though, that the style name for these are "list list__links" so I imagine that's the genesis for this name. Still we should probably remove the bullets from the visual example shown in the screenshot. That way we don't confuse users in terms of what we mean here.

Good point; I'll remove the bullets. I think it also might help to rename the section to "Standalone links". What do you think about that?

If we do go with "Paragraph links" lets use the word "paragraph" in the first sentence of the content to the left (instead of "body").

Changing it to "Inline links", so I'll add "inline" to the content on the left, as well.

Will you be documenting the way these types of links appear at mobile, specifically the list links?

I was only focused on adding documentation of the link weight issue. Would you please open a new issue for documenting the behavior of standalone links on small screen sizes?

[nataliafitzgerald]

@Scotchester

• Eliminating the use of Georgia for long content was discussed in a Design Manual meeting (months back) and consensus was that that we would use Avenir Next on pages moving forward. Georgia isn't even available within Wagtail so we've already been moving in that direction. There are pages out there that still use Georgia but those are mostly legacy pages or internal tools that are not maintained within Wagtail. Here's where this was discussed: https://github.com/cfpb/design-manual/issues/347. It does not look like this change was ever documented in the Design Manual.

• Once you're done with the changes I'm happy to take a look at the full page from a headings perspective and make any needed adjustments.

• "Inline links" and "Standalone links" makes sense to me.

• Yes, I can add an issue for documenting the behavior of standalone links on small screen sizes?

[nataliafitzgerald]

@Scotchester @jimmynotjim - What's the next step with this issue?

[Scotchester]

@nataliafitzgerald I update this PR to address your feedback.

Separately, it looks like there's a bunch of next steps mentioned in that issue #347 that need to be followed-up-on.

[nataliafitzgerald]

The next step from https://github.com/cfpb/design-manual/issues/347 that seems most ready to be worked on would be to remove Georgia from the Design Manual. From what I can tell, we've stopped using it for text on DM pages. But there are instances of images on the Typography page that still include Georgia. So these will need to be updated (to Avenir Next) and we will need to remove Georgia from the type hierarchy.

Interestingly it seems as though we may have updated CF in advance of updating the DM to remove Georgia and so we have things like this:

Correcting these glaring issues on the "Typography" page would probably be a good next step. I created an issue for this: https://github.com/cfpb/design-manual/issues/499

[jimmynotjim]

@nataliafitzgerald haha, we made Avenir Next the default body copy in Capital Framework, so when this project was updated it auto updated to using Avenir as the body copy instead of Georgia. As far as I know, there is not a single instance of Georgia being used in Capital Framework at this point.

[Scotchester]

Updates requested by @nataliafitzgerald have been made.

[nataliafitzgerald]

@Scotchester This looks good. The first sentence may be a little more complex than it needs to be. What do you think of this reordering and simplification?

"Links should be Regular weight when inline with other text (e.g., within a paragraph), but should be Medium weight when standing alone (e.g., in a call to action or list of links). Links are always underlined."

[Scotchester]

The point of the first sentence is, in concert with the bits under variations, to make it clear that links are not always underlined (specifically, links in headings and navigation are not). I don't mind rewording it, but we should not state "Links are always underlined." without qualification.

[jimmynotjim]

Quick question, possible wrench. If there's a link in a full width text, but it's on it's own line, it's displayed at the regular weight. I don't think there's much we can do to single them out, because they're wrapped in a paragraph tag, but I wanted to call it out and see what people think.

In this specific example I think the full width text should really be an info-unit that spans the full content, but I don't know that we can fix that here. Are there other situations of single links within the full width text that aren't bold?

[Scotchester]

There are definitely other situations like that, yeah, but that's not an issue to deal with in this PR, that's an issue for cfgov-refresh. This PR documents the standard we want to see in the world.

[jimmynotjim]

Agreed, I just wanted to call attention to it and make sure that it should indeed be bold.

[nataliafitzgerald]

@jimmynotjim - To clarify, by "bold" do you mean "Avenir Next Medium"?

[jimmynotjim]

@nataliafitzgerald yes

[Scotchester]

@nataliafitzgerald Any further thoughts on rewording that sentence before we merge?

[nataliafitzgerald]

@Scotchester - Yes, what you have is fine. I tried an alternative but I'm also fine with moving forward with what you have.

"Links should be Regular weight when inline with other text (e.g., within a paragraph), but should be Medium weight when standing alone (e.g., in a call to action or list of links). Inline and standalone links are always underlined."

[Scotchester]

Hmm... "Inline and standalone links are always underlined" still feels like it could refer to navigation links. (Navigation links stand alone.) I'm going to go ahead and merge with what I proposed. Thanks for the feedback!