USWDS-Site - What's new: Update post preview structure and styles #2979

amyleadem · 2024-11-20T22:38:38Z

Summary

Updated the post previews on what's new page. This PR changes the styling of the post previews and also allows for custom urls in the preview header link via preview_url.

Example:

preview_url: https://github.com/uswds/uswds/releases/tag/v3.9.0

Important

~~This PR includes sample posts to demo content. We need to remove all of the changed files inside the _posts/ directory before merge.~~ Removed demo posts in 61aaf20

Related issue

Closes #2953

Preview link

Problem statement

Content limitations:

The News and Updates feed is limited to posts only. The current post preview structure cannot accommodate a "blurb" content type that links to a non-post location.

Usability concerns:

Visually, post previews are very large. The large header text and vertical margins can make content difficult to scan.
Previews have two links that use different text for the same link location.

Accessibility concerns:

Post preview header is a link but doesn't look like one.
All post previews have the same generic "Continue reading" link text. This can make it hard for screen reader users to know where the link goes.
Post previews use a heading level that doesn't fit in the page hierarchy. The post previews use an h1 header for each post. This does not match the page hierarchy. The "What's new" page post previews should use an h3 and the "All news and updates" page should use an h2.
Posts have an unnecessary <article> wrapper. This makes sense for post previews, but not the post pages themselves.

Solution

Post previews:

Condensed the size of the previews and updated the structure to allow new content types:

Created the ability to designate a link for the preview to point to instead of a post. You can now use the preview_url data key in the pages front matter to set an alternate URL for the header link.
Removed the CTA link at the bottom of the preview post. Instead, we now rely only on the header link.
Updated header link styles to be smaller and look like links. They are now smaller, bolder, and show a text underline
Converted h1 headers to match the page hierarchy. They now are either an h2 or h3, depending on the page.
Shrunk vertical margins across the page.
Lightened the border between post previews.
Moved the date below the post.

Posts

Removed the wrapping <article> from the post page

Code

Created post-preview.html and pulled out all the "excerpt" conditionals from post.html. This was done to improve readability.
Moved utility classes from post.html to Sass

Testing and review

Confirm the structure of the post previews makes sense
Confirm the styles for the post previews make sense
Confirm no regressions in the styles or visual structure of posts

Accessibility

Post previews

Confirm header link styles meet a11y standards
Confirm header hierarchy meets standards

Posts

Confirm no a11y regressions on the post pages

…ats-new-post-previews

_posts/2024-10-15-sunsetting-uswds-1-0.md

_posts/2024-10-17-uswds-3.9.0.md

_posts/2024-10-19-accessibility-inclusive-user-experiences copy.md

_posts/2024-11-01-web-components-are-coming.md

jaclinec

Looks great! The only thing I wonder about is if we should display the date under the title and authors of each post, instead of at the bottom. I'm not sure I have a strong opinion either way, but wonder if there are considerations for screen reader users and zoom magnification users. Would it be better to display the date under the title/authors?

amyleadem · 2024-11-21T23:44:50Z

I moved the date above the post summary text. This is ready for re-review.

jaclinec

LGTM!

finekatie

looking great! approved.

- Remove unnecessary comment

amyleadem · 2024-11-25T21:12:56Z

@mejiaj and @mahoneycm, I believe I have addressed all of your comments. This is ready for re-review.

amyleadem · 2024-11-25T21:20:45Z

Update: I just restored the <article> wrapper based on @alex-hull's recommendation in this comment.

mejiaj

Overall LGTM, added some non-blocking comments. I can approve once resolved.

If you feel any don't apply or will be done in future work, feel free to resolve with a comment stating that.

mejiaj · 2024-11-26T20:50:44Z

_includes/post.html

praise: Much cleaner template, nice work.

I was going to say the same thing! Great work here Amy!

_posts/2024-10-17-uswds-3.9.0.md

mejiaj · 2024-11-26T20:54:53Z

_posts/2024-11-01-web-components-are-coming.md

question: This is notional content too, right?

Yes, these posts are all just notional content to demonstrate potential content types and test the new option to add a preview url.

mejiaj · 2024-11-26T20:57:49Z

css/custom-styles/_posts.scss

+  &__content p {
+    @include u-font("lang", "xs");
+  }


polish: This doesn't make much of a difference and could mean one less style to maintain.

Fair. I like that it adds a tiny bit more visual hierarchy, but happy to remove it if that is the team's preference. It is not a must-have for me.

It's really a tiny difference of 15.04px → 16px.

mahoneycm

LGTM! Great work here Amy!

mahoneycm · 2024-11-27T15:15:43Z

_includes/post.html

I was going to say the same thing! Great work here Amy!

finekatie

Thinking this looks really good! Approved.

amyleadem · 2024-11-27T17:12:18Z

@annepetersen and @thisisdano, this is ready for your review.

annepetersen

Completely a content item, but I'd love to stop using "Here is" or "Here you can" from the lead of any page. You can usually omit it and still accomplish what the lead needs to do. Tagging @finekatie to maybe include this in voice/tone/guide materials we're intermittently working on.

Not a blocker.

Otherwise, looks good! Would obvs need a changelog and real first post, replacing any notional material. 😅

finekatie · 2024-11-27T21:48:19Z

Completely a content item, but I'd love to stop using "Here is" or "Here you can" from the lead of any page. You can usually omit it and still accomplish what the lead needs to do. Tagging @finekatie to maybe include this in voice/tone/guide materials we're intermittently working on.

Not a blocker.

Otherwise, looks good! Would obvs need a changelog and real first post, replacing any notional material. 😅

Hi @annepetersen , I'd recommend taking it out and tweaking so the first sentence reads "Get the latest USWDS news and information here."

I've also drafted a bunch of posts (see #2989) for the page and to edit/approve content - some of which are already in the preview. There are three more for November and we can add more with the monthly call content as that's approved. :)

amyleadem · 2024-11-29T17:56:16Z

Update:

I updated the lead text according to @finekatie's recommendation (2b25d81)
I removed the notional posts to prepare for merge (I'll add a screenshot below for visual reference for the different post types) (61aaf20)
I did not include a changelog because none of the content meaning was changed on the page - only the styles and code structure. Let me know if you think it needs a changelog afterall.

Screenshot of styles for different post types:

finekatie

This works! Approved.

amyleadem added 7 commits November 20, 2024 15:20

Update post preview styles; allow custom preview url

647be14

Add sample posts

0e83a74

Merge branch 'main' of https://github.com/uswds/uswds-site into al-wh…

c77ea37

…ats-new-post-previews

Separate post.html and post-preview.html

7b360a4

Update content on sample posts

ca4c58f

Add underline to post-title link styles

3eebc4f

Refine styles for "news and updates"; remove h3 from in-page nav

4858824

amyleadem changed the title ~~Al whats new post previews~~ USWDS-Site - What's new: Update post preview structure and styles Nov 21, 2024

amyleadem requested review from jaclinec and finekatie November 21, 2024 17:44

amyleadem marked this pull request as ready for review November 21, 2024 17:44

amyleadem requested a review from a team as a code owner November 21, 2024 17:44

amyleadem added 2 commits November 21, 2024 10:47

Merge branch 'main' of https://github.com/uswds/uswds-site into al-wh…

3abcf7b

…ats-new-post-previews

Remove excerpt_link_text

ecadaf6

amyleadem commented Nov 21, 2024

View reviewed changes

_posts/2024-10-15-sunsetting-uswds-1-0.md Outdated Show resolved Hide resolved

amyleadem commented Nov 21, 2024

View reviewed changes

_posts/2024-10-17-uswds-3.9.0.md Outdated Show resolved Hide resolved

amyleadem commented Nov 21, 2024

View reviewed changes

_posts/2024-10-19-accessibility-inclusive-user-experiences copy.md Outdated Show resolved Hide resolved

amyleadem commented Nov 21, 2024

View reviewed changes

_posts/2024-11-01-web-components-are-coming.md Outdated Show resolved Hide resolved

Format code

95b14b6

jaclinec reviewed Nov 21, 2024

View reviewed changes

amyleadem added 4 commits November 21, 2024 16:27

Move date below byline

80e627a

Move utility clases off of post.html

f9ccd69

Restore measure-4 on post.html

f659984

Move utility classes off of post-content

39e8f6a

amyleadem requested a review from jaclinec November 21, 2024 23:44

jaclinec previously approved these changes Nov 22, 2024

View reviewed changes

amyleadem requested review from amycole501 and alex-hull November 22, 2024 14:11

finekatie previously approved these changes Nov 22, 2024

View reviewed changes

amyleadem added 4 commits November 25, 2024 08:19

Add comments to includes

41fd023

Replace excerpt_link_url > custom_url; Add comment

c4d016a

Create .post-meta subheading styles.

55d9f08

- Remove unnecessary comment

Move post styles to posts partial

fece742

amyleadem mentioned this pull request Nov 25, 2024

USWDS-Site: Restore posts README #2987

Open

amyleadem requested review from mejiaj and mahoneycm November 25, 2024 21:12

Add article wrapper to post.html; add include comment

cca2c85

Replace custom_url -> preview_url

0a1b612

mejiaj reviewed Nov 26, 2024

View reviewed changes

mejiaj previously approved these changes Nov 26, 2024

View reviewed changes

mahoneycm previously approved these changes Nov 27, 2024

View reviewed changes

_includes/post.html

Copy link

Contributor

mahoneycm Nov 27, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was going to say the same thing! Great work here Amy!

amyleadem requested a review from thisisdano November 27, 2024 15:54

finekatie added the Affects: Content Relates to content label Nov 27, 2024

finekatie previously approved these changes Nov 27, 2024

View reviewed changes

amyleadem requested a review from annepetersen November 27, 2024 17:11

annepetersen reviewed Nov 27, 2024

View reviewed changes

Format code

e9f2d18

amyleadem dismissed stale reviews from finekatie, mahoneycm, and mejiaj via e9f2d18 November 29, 2024 17:48

amyleadem added 2 commits November 29, 2024 10:50

Tweak lead copy

2b25d81

Remove demo posts

61aaf20

finekatie self-requested a review November 29, 2024 18:36

finekatie approved these changes Nov 29, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS-Site - What's new: Update post preview structure and styles #2979

USWDS-Site - What's new: Update post preview structure and styles #2979

amyleadem commented Nov 20, 2024 •

edited

Loading

jaclinec left a comment

amyleadem commented Nov 21, 2024

jaclinec left a comment

finekatie left a comment

amyleadem commented Nov 25, 2024

amyleadem commented Nov 25, 2024

mejiaj left a comment

mejiaj Nov 26, 2024

mahoneycm Nov 27, 2024

mejiaj Nov 26, 2024

amyleadem Nov 26, 2024

mejiaj Nov 26, 2024

amyleadem Nov 26, 2024

mejiaj Nov 26, 2024

mahoneycm left a comment

mahoneycm Nov 27, 2024

finekatie left a comment

amyleadem commented Nov 27, 2024

annepetersen left a comment

finekatie commented Nov 27, 2024

amyleadem commented Nov 29, 2024

finekatie left a comment

USWDS-Site - What's new: Update post preview structure and styles #2979

Are you sure you want to change the base?

USWDS-Site - What's new: Update post preview structure and styles #2979

Conversation

amyleadem commented Nov 20, 2024 • edited Loading

Summary

Related issue

Preview link

Problem statement

Solution

Post previews:

Posts

Code

Testing and review

Accessibility

Post previews

Posts

jaclinec left a comment

Choose a reason for hiding this comment

amyleadem commented Nov 21, 2024

jaclinec left a comment

Choose a reason for hiding this comment

finekatie left a comment

Choose a reason for hiding this comment

amyleadem commented Nov 25, 2024

amyleadem commented Nov 25, 2024

mejiaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mahoneycm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

finekatie left a comment

Choose a reason for hiding this comment

amyleadem commented Nov 27, 2024

annepetersen left a comment

Choose a reason for hiding this comment

finekatie commented Nov 27, 2024

amyleadem commented Nov 29, 2024

finekatie left a comment

Choose a reason for hiding this comment

amyleadem commented Nov 20, 2024 •

edited

Loading