USWDS-Site: Enhance what's new page layout #3115

amyleadem · 2025-02-18T17:39:15Z

Summary

Enhanced the layout and content on the What's new page to improve organization.

Note

This is a follow up to the prototype work in PR #3094. This PR:

Refines the code from the prototype to meet standards.
Isolates the changes into separate steps to reduce review burden. This PR includes only the layout updates.

Additionally, this PR builds on the updates found in PR #3064. Because of this, I propose the following merge order:

USWDS-Site - What's new: Create posts_short directory and add new items #3064
1. Adds short post content type and creates new posts
USWDS-Site: Enhance what's new page layout #3115 (This PR)
1. Updates the layout of the what's new and all news pages
Add a consolidated What's New changelog view #3091
1. Adds consolidated changelog and updates existing changelog data

Related issue

Closes #3113

Preview link

Major changes

Re-organized the layout for the what's new page and added new card content
Added variables in config.yml to set the current version of USWDS Compile and the USWDS design kit
Added a jump-links.html include
Added new include options for site cards and post previews

Testing and review

General

Confirm the layout matches the approved prototype
Confirm the layout looks good in different browsers and screen widths
Confirm copy is free from error and matches the USWDS voice
Confirm product version numbers are up-to-date
Confirm all links work as expected
Confirm news feed shows posts in the expected order (newest first)
Confirm no regressions in post styles
Confirm the header structure on both pages matches expectations

Devs

Confirm code meets standards for reusability and readability
Confirm no regressions in other implementations of the site-card include

…ats-new-layout-update

…wds/uswds-site into al-whats-new-layout-update

amyleadem · 2025-02-18T22:42:27Z

pages/whats-new/overview.md

-columns:
-  - title: New users
-    source: New Users
-  - title: Total users
-    source: Users
-  - title: Page views
-    source: Pageviews


Note
I removed this because I could not find it being used anywhere.

amyleadem · 2025-02-18T22:43:00Z

pages/whats-new/overview.md

-changelog:
-  key: about-whats-new


Note
Removed the page's changelog to make room for the consolidated changelog.

amyleadem · 2025-02-18T22:43:57Z

pages/whats-new/overview.md

+<div class="bg-gray-5 padding-3 margin-top-4">
+  <h2 class="whats-new__heading margin-top-0" id="latest-releases">Latest releases</h2>
+  <ul class="usa-card-group whats-new-card-group">
+    <li class="{{ product_grid_list_classes }}">
+      {% include site-card.html
+        subheading="Design system"
+        heading="USWDS"
+        body="The official U.S. design system, enabling the government to build fast, accessible, mobile-friendly websites."
+        linkText=uswds_link_text
+        linkUrl="https://github.com/uswds/uswds/releases"
+        subheadingElement="span"
+        linkClasses="padding-x-105"
+      %}
+    </li>
+    <li class="{{ product_grid_list_classes }}">
+      {% include site-card.html
+        subheading="Compilation tool"
+        heading="USWDS Compile"
+        body="A tool that makes it easy to customize and compile USWDS Sass into browser-readable CSS."
+        linkText=uswds_compile_link_text
+        linkUrl="https://github.com/uswds/uswds-compile/releases"
+        subheadingElement="span"
+        linkClasses="padding-x-105"
+      %}
+    </li>
+    <li class="{{ product_grid_list_classes }}">
+      {% include site-card.html
+        subheading="Design assets"
+        heading="USWDS for designers"
+        body="The official USWDS design kits in Sketch and Figma."
+        linkText=uswds_design_kit_link_text
+        linkUrl="https://www.design_kit.com/community/file/1440921849343185329"
+        subheadingElement="span"
+        linkClasses="padding-x-105"
+      %}
+    </li>
+  </ul>
+</div>


Note
I could not use site-card-list.html here because I needed to pull site data for this card content. I could not do this in the front matter. If you see a better way, let me know!

Confirming it's not possible to pass data into front matter in Jekyl without plugins or potentially hacky work arounds. This is something I've struggled with in the past.

I see includes that use site data.

https://github.com/search?q=repo:uswds/uswds-site+site.+language:HTML+path:/%5E_includes%5C//&type=code

amyleadem · 2025-02-18T22:47:42Z

_includes/post-preview.html

+    {% if include.category %}
+      <p class="post-category site-subheading">
+        {{ post.tags[0] }}
+      </p>
+    {% endif %}


Note
On the main what's new page, I removed the tag eyebrow to conserve vertical real estate. I added it back in on the "All news and updates" page. Flag if you would like this changed.

amyleadem · 2025-02-18T22:48:13Z

_includes/post-preview.html

+    {% if include.date %}
+      {% include post-meta.html %}
+    {% endif %}


Note
On the main what's new page, I removed the date to conserve vertical real estate. I added it back in on the "All news and updates" page. Flag if you would like this changed.

amyleadem · 2025-02-18T22:59:02Z

@mejiaj @mahoneycm Tagging you both first for review to review the merge strategy outlined in the PR description and confirm that the approach makes sense. Additionally, I am interested in getting initial review of the code approach to identify if there is any major rework needed. I expect that there might be some content and design tweaks, but hoping the layout is nice and solid. Let me know if you have any questions!

mahoneycm

A couple questions and an update to a link!

Overall, looking and working great 👍

mahoneycm · 2025-02-19T18:14:01Z

pages/whats-new/overview.md

+<div class="bg-gray-5 padding-3 margin-top-4">
+  <h2 class="whats-new__heading margin-top-0" id="latest-releases">Latest releases</h2>
+  <ul class="usa-card-group whats-new-card-group">
+    <li class="{{ product_grid_list_classes }}">
+      {% include site-card.html
+        subheading="Design system"
+        heading="USWDS"
+        body="The official U.S. design system, enabling the government to build fast, accessible, mobile-friendly websites."
+        linkText=uswds_link_text
+        linkUrl="https://github.com/uswds/uswds/releases"
+        subheadingElement="span"
+        linkClasses="padding-x-105"
+      %}
+    </li>
+    <li class="{{ product_grid_list_classes }}">
+      {% include site-card.html
+        subheading="Compilation tool"
+        heading="USWDS Compile"
+        body="A tool that makes it easy to customize and compile USWDS Sass into browser-readable CSS."
+        linkText=uswds_compile_link_text
+        linkUrl="https://github.com/uswds/uswds-compile/releases"
+        subheadingElement="span"
+        linkClasses="padding-x-105"
+      %}
+    </li>
+    <li class="{{ product_grid_list_classes }}">
+      {% include site-card.html
+        subheading="Design assets"
+        heading="USWDS for designers"
+        body="The official USWDS design kits in Sketch and Figma."
+        linkText=uswds_design_kit_link_text
+        linkUrl="https://www.design_kit.com/community/file/1440921849343185329"
+        subheadingElement="span"
+        linkClasses="padding-x-105"
+      %}
+    </li>
+  </ul>
+</div>


Confirming it's not possible to pass data into front matter in Jekyl without plugins or potentially hacky work arounds. This is something I've struggled with in the past.

pages/whats-new/overview.md

_includes/site-card.html

mahoneycm · 2025-02-19T18:19:30Z

pages/whats-new/overview.md

-  - title: Page views
-    source: Pageviews
+lead: |
+  Stay up to date on the latest U.S. Web Design System (USWDS) product launches, learn how to use the design system, and dive deeper into our monthly call topics.


thought: This is tipping into fine pen review but is learn how to use the design system appropriate here?

The links here seem less "how to" than other guidance pages on the site. Just a thought!

@finekatie @ceperkins Sending this comment to you for input.

@mahoneycm to confirm, this isn't a blocker right?

I'd say it's not meant literally as a "how to" page, but people can find their way from here to learn how to use the design system. @ceperkins would you agree?

mahoneycm · 2025-02-19T18:21:50Z

pages/whats-new/overview.md

+{% assign monthly_call = site.data.monthly-calls.videos[0]  %}
+{% capture monthly_call_heading %} {{ monthly_call.date }}: {{monthly_call.title}} {%- endcapture %}
+{% capture monthly_call_image %} {{site.baseurl }}/img/uswds-logo/4c-lg-on-black.svg {%- endcapture %}
+{% capture monthly_call_url %} {{ site.baseurl }}/about/monthly-calls {%- endcapture %}


Praise: Very cool to see this working! Having this card be dynamic with the latest monthly calls is a great addition!

Co-authored-by: Charlie Mahoney <[email protected]>

amyleadem · 2025-02-19T22:00:59Z

@finekatie and @ceperkins tagging you for review on the page copy and layout. Note that the changelog pieces from the prototype will be coming in a follow-on PR (but will all be released at the same time).

Let me know if you have questions!

finekatie

Left comment about link to Figma releases page link.

finekatie · 2025-02-20T14:54:50Z

pages/whats-new/overview.md

+        heading="USWDS for designers"
+        body="The official USWDS design kits in Sketch and Figma."
+        linkText=uswds_design_kit_link_text
+        linkUrl="https://github.com/uswds/uswds-for-designers/releases"


My only issue with linking here is that the text says "USWDS design kits in Sketch and Figma" - but on the releases page I don't see anything about Sketch. That would confuse me if I was looking for the design kit for Sketch. What can we do?

That's a good note. Wondering if we just need to add a line to the release notes to signal that Sketch still exists in the package, there just aren't any changes. Alternatively, we could consider shifting the card copy to be more focused on Figma. Curious to hear thoughts.

Yeah this is a Dan/Matt question. Not a blocker though.

mejiaj

@amyleadem love the new look.

I've added a small comment to improve clarity of the new jump links include. This is the only issue I found.

Please take a look at the items marked polish or thought. These aren't required changes, but highlighting because they could have helped increase maintainability.

mejiaj · 2025-02-21T14:49:37Z

_includes/jump-links.html

issue (non-blocking): We already have a jump links component in _includes/accessibility-tests/jump-links.html.

We should avoid repeating ourselves in the future and create a more flexible jump links component that can be reused. This would allow you to re-use the reduced motion styles and avoid setting them in multiple places, like accessibility-tests.html.

mejiaj · 2025-02-21T14:51:19Z

_includes/jump-links.html

@@ -0,0 +1,25 @@
+<!-- Turn on smooth scroll animation for anchor links -->


issue: Can you add a comment with a brief description and where this is used?

Are there any settings related to this component?

Added a comment in 84d5637

mejiaj · 2025-02-21T15:08:22Z

_includes/jump-links.html

+<ul class="site-checklist-jump-links">
+  {% for link in page.jump_links %}
+    <li>
+      <a href="#{{ link.href | default: link.text | downcase | slugify }}">


polish: Is downcase needed here? Slugify in Jekyll docs says it already handles lowercase.

Slugify

Convert a string into a lowercase URL "slug".

Suggested change

<a href="#{{ link.href | default: link.text | downcase | slugify }}">

<a href="#{{ link.href | default: link.text | slugify }}">

More polish: You could improve readability by saving this in a variable.

{% for link in page.jump_links %} {% assign link_href = link.href | default: link.text | slugify %} <li> <a href="#{{ link_href }}">

Made these updates in 84d5637

mejiaj · 2025-02-21T15:14:12Z

_includes/jump-links.html

+        <svg class="usa-icon" aria-hidden="true" role="img">
+          <use href="{{ site.baseurl }}/assets/img/sprite.svg#arrow_downward"></use>
+        </svg>
+        {{ link.text }}


thought: If link.text is always available this is fine, but without checking for it you could run into issues.

For example
If it isn't passed you'll still have a list item, link, and icon but it'll be empty and the href will be broken (unless link.href exists).

It feels to me like link.text should be mandatory here. Any objection to leaving it as is?

mejiaj · 2025-02-21T15:20:33Z

_includes/post-preview.html


-    <{{ include.heading | default:"h2" }} class="post-preview__title">
+    <{{ include.heading | default:"h2" }} class="post-preview__title {{ include.headingClasses }}">


polish: Where's this class needed? What happens when headingClasses is empty?

I see an empty space in the what's new preview

 <h3 class="post-preview__title ">

Added a conditional for include.headingClasses in 9961107

mejiaj · 2025-02-21T15:26:32Z

_includes/site-card.html

thought: Something for next time. This component could benefit from using capture to avoid having so many settings. It also gives flexibility to the author by using the markup that they need.

For example:

 {% capture card_heading %} <div>A subheading</div> <h3>The heading</h3> {% endcapture %}  <header class="usa-card__header"> {{ include.card_heading }} </header>

mejiaj · 2025-02-21T15:27:24Z

_includes/site-card.html

    - heading: String heading for a single card.
+    - headingElement: The heading HTML element type.
+    - subheading: String subheading for a single card.
+    - subheadingElement: The subheading HTML element type.
    - body: String body that gets placed in a paragraph tag.
+    - image: The card image.
+    - imageAlt: The alt tag for the image.
    - linkUrl: String for the link url.
    - linkText: String link label.
+    - linkClasses: Classes for the link element.


issue: Are all these settings required or are some optional?

Added notes about required vs optional in 5d18a6c

mejiaj · 2025-02-21T15:37:13Z

css/custom-styles/_whats-new.scss

+  .site-subheading {
+    color: color("gray-warm-10");
+  }
+
+  .usa-card__heading {
+    line-height: unset;
+  }
+
+  .usa-card__body,
+  .usa-card__header,
+  .usa-card__footer {
+    @include at-media("tablet") {
+      width: 100%;
+    }
+
+    @include at-media("desktop-lg") {
+      @include grid-col(7);
+    }
+  }
+
+  .usa-card__media {
+    @include u-padding(4);
+    background-image: url("../img/monthly_call_bg.png");
+    background-position-y: center;
+    background-size: 15rem;
+    display: flex;
+    justify-content: center;
+
+    @include at-media("tablet") {
+      position: relative;
+      width: 100%;
+    }
+
+    @include at-media("desktop-lg") {
+      @include grid-col(5);
+      @include u-padding(6);
+      position: absolute;
+    }
+  }
+
+  .usa-card__img {
+    background-color: initial;
+    max-width: 10rem;
+
+    @include at-media("desktop-lg") {
+      max-width: 15rem;
+    }
+  }
+
+  .usa-card__img img {
+    object-fit: initial;
+  }
+
+  .usa-button {
+    @include u-bg("gold-30v");
+    @include u-margin-top(1);
+    @include u-text("blue-warm-90");
+  }
+}
+


issue (non-blocking): General partials, like typography and card, would have been better places for this.

One could unintentionally add conflicting global styles.

mejiaj · 2025-02-21T16:10:16Z

pages/whats-new/overview.md

+-->
+{% assign monthly_call = site.data.monthly-calls.videos[0]  %}
+{% capture monthly_call_heading %} {{ monthly_call.date }}: {{monthly_call.title}} {%- endcapture %}
+{% capture monthly_call_image %} {{site.baseurl }}/img/uswds-logo/4c-lg-on-black.svg {%- endcapture %}


polish: Using assign seems more appropriate for these short links.

Suggested change

{% capture monthly_call_image %} {{site.baseurl }}/img/uswds-logo/4c-lg-on-black.svg {%- endcapture %}

{% assign monthly_call_image = site.baseurl | append: '/img/uswds-logo/4c-lg-on-black.svg' %}

Updated the captures to assigns in 333d592

finekatie

I think the Figma/Sketch copy needs a look by Dan/Matt, and we might want to get their feedback on Charlie's question about "learn how to use the design system" but those are not blockers for me. I approve!

…wds/uswds-site into al-whats-new-layout-update

amyleadem · 2025-02-21T20:44:33Z

@mejiaj This is ready for your re-review

amyleadem added 6 commits February 18, 2025 10:36

Create jump-links include

175a065

Add version vars for other USWDS products

5924b46

Add post-preview.html conditionals for category and date

6b0ff00

Add

e4f32f4

Update layout for pages and add new styles

9bb0485

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

7eb1062

…ats-new-layout-update

amyleadem mentioned this pull request Feb 18, 2025

USWDS-Site - What's new: Create posts_short directory and add new items #3064

Open

amyleadem added 5 commits February 18, 2025 12:08

Merge branch 'al-whats-new-directory-change' of https://github.com/us…

98d834a

…wds/uswds-site into al-whats-new-layout-update

Run prettier

e0ce487

Merge branch 'al-whats-new-directory-change' of https://github.com/us…

e7af702

…wds/uswds-site into al-whats-new-layout-update

Remove consolidated changelog code

5397251

Add id for #latest-releases

6b3b66a

amyleadem mentioned this pull request Feb 18, 2025

USWDS-Site - What's new: Prototype phase 2 of what's new page #2967

Open

amyleadem added 6 commits February 18, 2025 15:14

Remove unnecessary classes from jump-links.html

bde2472

Rename posts.scss -> whats-new.scss

3e85a9e

Rename whats-new-card-group

542f519

Remove unnecessary include.listItemClasses

9b5dda3

Remove unnecessary span

a6010e4

Clean up site-card/site-card-list.html

aa2bc2f

amyleadem commented Feb 18, 2025

View reviewed changes

Update all news title -> "All news and events"

97aff1a

amyleadem commented Feb 18, 2025

View reviewed changes

amyleadem marked this pull request as ready for review February 18, 2025 22:54

amyleadem requested review from mejiaj and mahoneycm February 18, 2025 22:56

mahoneycm requested changes Feb 19, 2025

View reviewed changes

Fix figma link

0e261c1

Co-authored-by: Charlie Mahoney <[email protected]>

amyleadem assigned finekatie and ceperkins and unassigned finekatie and ceperkins Feb 19, 2025

amyleadem requested review from finekatie and ceperkins February 19, 2025 21:52

Update design kit link to point to release notes

35c5eb4

finekatie reviewed Feb 20, 2025

View reviewed changes

Update subheading default element to span

d698d30

amyleadem requested review from mahoneycm and finekatie February 21, 2025 14:29

mejiaj reviewed Feb 21, 2025

View reviewed changes

finekatie approved these changes Feb 21, 2025

View reviewed changes

amyleadem added 5 commits February 21, 2025 13:03

Add comment about include purpose; improve readability

84d5637

Wrap include.headingClasses in conditional

9961107

Annotate required/optional for site-card vars

5d18a6c

Replace capture with assign

333d592

Merge branch 'al-whats-new-directory-change' of https://github.com/us…

f5b91d3

…wds/uswds-site into al-whats-new-layout-update

amyleadem requested a review from mejiaj February 21, 2025 20:43

amyleadem linked an issue Feb 21, 2025 that may be closed by this pull request

USWDS-Site - What's new: Build production code for phase 2 prototype #3113

Open

		@@ -0,0 +1,25 @@
		<!-- Turn on smooth scroll animation for anchor links -->

	<a href="#{{ link.href \| default: link.text \| downcase \| slugify }}">
	<a href="#{{ link.href \| default: link.text \| slugify }}">


		<{{ include.heading \| default:"h2" }} class="post-preview__title">
		<{{ include.heading \| default:"h2" }} class="post-preview__title {{ include.headingClasses }}">

	{% capture monthly_call_image %} {{site.baseurl }}/img/uswds-logo/4c-lg-on-black.svg {%- endcapture %}
	{% assign monthly_call_image = site.baseurl \| append: '/img/uswds-logo/4c-lg-on-black.svg' %}

USWDS-Site: Enhance what's new page layout #3115

Are you sure you want to change the base?

USWDS-Site: Enhance what's new page layout #3115

Conversation

amyleadem commented Feb 18, 2025 • edited Loading

Summary

Related issue

Preview link

Major changes

Testing and review

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem Feb 18, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem Feb 18, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem commented Feb 18, 2025

mahoneycm 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

amyleadem commented Feb 19, 2025

finekatie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem Feb 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

amyleadem Feb 21, 2025 • edited Loading

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

Choose a reason for hiding this comment

finekatie left a comment

Choose a reason for hiding this comment

amyleadem commented Feb 21, 2025

amyleadem commented Feb 18, 2025 •

edited

Loading

amyleadem Feb 18, 2025 •

edited

Loading

amyleadem Feb 18, 2025 •

edited

Loading

amyleadem Feb 20, 2025 •

edited

Loading

amyleadem Feb 21, 2025 •

edited

Loading