USWDS-Site: Fix component pages from audit (Phase 1) #2149

amyleadem · 2023-06-22T22:18:03Z

Summary

Updated component pages according to the findings reported in the code/developer content audit (Google Docs 🔒)

To make the review process more manageable, the changes will be implemented in phases.

⚠️ Before merge, we should update all NNNN-NN-NN changelog dates.

Related issue

Closes #2099

Preview link

Solution

Update code according to the findings in code/developer content audit (Google Docs 🔒).

Please note that all items highlighted yellow in the spreadsheet will be investigated/discussed in the last phase of the component page fixes.

Testing and review

Confirm that all updates are accurate and make sense
Confirm that all meaningful updates have a related changelog
- "Meaningful" updates here mostly applied to adding or removing documentation about variants, dependencies, etc. Copy tweaks to add clarity were not considered meaningful, but a case could be made for them to be included.
Confirm grammar and spelling for all updates

- There is no .usa-alert---no-heading class in the CSS

- Reorganize based on priority and relevancy

- point users to appropriate utilities pages - break content into smaller sections

- Fix link with site.baseurl

- No longer needed since it is added dynamically

amyleadem · 2023-06-26T15:17:32Z

_components/button/guidance/implementation.md

Note
Reorganized the content here a bid to add bolded summaries and make meaning a bit more clear.
Also re-ordered these tasks based on relevancy/priority.

amyleadem · 2023-06-26T15:21:39Z

_components/character-count/guidance/accessibility.md

@@ -1,2 +1 @@
- **Associate the character count message to the input.** Use `aria-describedby` on the input to allow the message to be announced to those using screen readers.
- **Use the `aria-live` attribute on character count message.** Use `aria-live="polite"` so that updates to character count message are also announced when using a screen reader.


Note
Removed the aria-live item because it is added dynamically and no user-action is required

_patterns/language/guidance/accessibility.md

…mponent-audit-fixes

mejiaj

Nice fixes in this PR. I tested for:

PR preview lists the following, but I didn't see any code changes for them in this PR:

Breadcrumb
Combo box
Data viz
Date pcker

I also see language pattern got updated, but not seeing it in PR description.

_components/accordion/guidance/accessibility.md

_components/button-group/guidance/variants/segmented/accessibility.md

_components/button/guidance/implementation.md

_data/changelogs/component-banner.yml

mejiaj · 2023-07-17T16:45:47Z

_patterns/language/guidance/accessibility.md

Is there a preview link for this? Not seeing immediately where it appears.

Added a preview link to the PR description.

https://federalist-ead78f8d-8948-417c-a957-c21ec5617a57.sites.pages.cloud.gov/preview/uswds/uswds-site/al-component-audit-fixes/components/language-selector/

I'm not seeing this section on the language selector page? Am I misunderstanding?

I got mixed up. These changes should have been added to the accordion page. The language content changes have been reverted in 3f5c877.

Looks like the _patterns/language directory just includes content that was copied from accordion content (and other sections). We should investigate if we can remove this directory because it does not look like it is being used.

I'm going to be out the next two weeks, but happy to help if this gets held until then!

I've opened up Issue #2289 so that we can investigate the directory question at a later time.

_components/button-group/guidance/variants/segmented/accessibility.md

_components/button/guidance/implementation.md

_components/card/guidance/implementation.md

_components/collection/collection.md

Co-authored-by: James Mejia <[email protected]>

amyleadem

@mejiaj Thanks for the thorough review. I believe I have addressed all of your comments. I had one question for you in this comment. Please let me know if you have questions.

_components/accordion/guidance/accessibility.md

_components/button-group/guidance/variants/segmented/accessibility.md

_components/card/guidance/implementation.md

amyleadem · 2023-07-17T17:47:20Z

_patterns/language/guidance/accessibility.md

Added a preview link to the PR description.

https://federalist-ead78f8d-8948-417c-a957-c21ec5617a57.sites.pages.cloud.gov/preview/uswds/uswds-site/al-component-audit-fixes/components/language-selector/

mahoneycm

I noticed a couple changes noted in the spreadsheet were missing from the demo. If these were decided against, maybe we can update the spreadsheet to reflect!

_components/accordion/guidance/accessibility.md

mahoneycm · 2023-09-01T16:21:58Z

_patterns/language/guidance/accessibility.md

I'm not seeing this section on the language selector page? Am I misunderstanding?

_components/accordion/guidance/accessibility.md

mahoneycm · 2023-09-01T16:28:10Z

_components/card/guidance/implementation.md

add-aspect mixin still missing backticks

Thanks. Added backticks in 1b5f36c

_components/button/guidance/implementation.md

…mponent-audit-fixes

- This class is no longer used in component code

- These changes were intended for accordion guidance

- Remove redundant info entry

amyleadem

@mahoneycm @mejiaj Thanks for all your comments. This is ready for re-review.

amyleadem · 2023-09-27T16:03:26Z

_components/alert/alert.md

Note
Alphabetized the variants and added emergency variant.

_patterns/language/guidance/accessibility.md

amyleadem · 2023-09-27T17:00:45Z

_components/accordion/guidance/accessibility.md

@@ -1,4 +1,3 @@
 - **Code header areas in the accordion as buttons.** Using a `<button type="button">` assures accordions are usable with both screen readers and keyboards.
- **Use `aria-expanded` on buttons to express an accordion’s default state.** Buttons should state if they are expanded by default with `aria-expanded="true"`. The `aria-expanded="false"` attribute will be added to other buttons when the accordion is initialized by the JavaScript.


Note
This content was moved to the implementation section with some edits

amyleadem · 2023-09-27T17:01:22Z

_components/alert/alert.md

Note
Added usa-alert--emergency and alphabetized variants

amyleadem · 2023-09-27T17:02:26Z

_components/card/guidance/implementation.md

+- **Control card size and layout with USWDS utilities.** The card component works well with [layout grid utilities]({{ site.baseurl }}/utilities/layout-grid/). The `usa-card-group` block is functionally a wrap-able `grid-row`, and each individual `usa-card` is a `grid-col`. This means you can use a grid utility like `tablet:grid-col-4` to set a four-column size on a card at `tablet` width. You can also set custom grid gaps on a `usa-card-group` using `grid-gap` utilities.
+
+    Since the Design System grid is based on flexbox, you can use [flex positioning utilities]({{ site.baseurl }}/utilities/flex/) on the card group. The default alignment is stretch (stretch aligns the top and bottom of each card in a row), but the `flex-align-start` utility can set the alignment to the top of the row.


Note
Broke this into two paragraphs for readability and added links to relevant resources

amyleadem · 2023-09-27T17:08:24Z

_patterns/language/guidance/accessibility.md

I got mixed up. These changes should have been added to the accordion page. The language content changes have been reverted in 3f5c877.

Looks like the _patterns/language directory just includes content that was copied from accordion content (and other sections). We should investigate if we can remove this directory because it does not look like it is being used.

…mponent-audit-fixes

mahoneycm

Lgtm! Thank you for tackling those changes and for the detailed change notes! Made re-review much easier 💯

…mponent-audit-fixes

Amy Leadem added 20 commits June 22, 2023 15:03

Add brackets to id to suggest placeholder

92ec60a

Add backticks to usa-accordion reference

28380fc

Remove redundant aria-expanded item

3ab95ba

Add missing alert variants

f72ddee

Update accordion dependencies

850e37c

Add missing alert variants

6433316

Remove alert no header example

fd661b9

- There is no .usa-alert---no-heading class in the CSS

Add backticks to .mil and .gov references

66c1893

Update banner aria-label copy

634a3d0

Remove usa-layout-grid dependency for banner

8730523

Fix broken code tag in component-package.html

1400823

Remove type=button from copy

8372683

Remove backtick from -button-stroke-width

c853c4d

Add bolded headings to button implementation

4cb3f57

- Reorganize based on priority and relevancy

Add links to card implementation section

0a5cd61

- point users to appropriate utilities pages - break content into smaller sections

Add link to add-aspect mixin - card implementation

4d412af

- Fix link with site.baseurl

Remove note about adding aria-live

ef11d79

- No longer needed since it is added dynamically

-Add clarity to no JS section in character count

19e2ec8

Add dependency to usa-checkbox

41c7a90

Add changelogs for #2149

9742fbd

amyleadem changed the title ~~USWDS-Site: Fix component pages from audit~~ USWDS-Site: Fix component pages from audit (Phase 1) Jun 23, 2023

Add period to usa-collection--condensed variant

685ec8e

amyleadem commented Jun 26, 2023

View reviewed changes

_patterns/language/guidance/accessibility.md Outdated Show resolved Hide resolved

amyleadem marked this pull request as ready for review June 26, 2023 15:39

amyleadem requested review from mahoneycm, mejiaj, bonnieAcameron and sarah-sch June 26, 2023 15:40

amyleadem removed the request for review from sarah-sch July 13, 2023 14:42

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

d5e304b

…mponent-audit-fixes

mejiaj suggested changes Jul 17, 2023

View reviewed changes

amyleadem and others added 4 commits July 17, 2023 10:28

Update wording for 2149

2368218

Co-authored-by: James Mejia <[email protected]>

Restore type='button'

90d9c79

Add changelog entry for #2149

4eee1c3

Restore type='button'

1adfaa0

amyleadem commented Jul 17, 2023

View reviewed changes

amyleadem requested a review from mejiaj July 17, 2023 18:13

mahoneycm suggested changes Sep 1, 2023

View reviewed changes

Amy Leadem added 10 commits September 26, 2023 15:39

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

ed1f733

…mponent-audit-fixes

Add backticks to usa-accordion

d627036

Combine aria-expanded items into one

f9683a3

Add backticks to add-aspect

1b5f36c

Rewrite note about usa-button--disabled class

54120b2

- This class is no longer used in component code

Revert _patterns/language updates

3f5c877

- These changes were intended for accordion guidance

Alphabetize alert variants

4998ad3

- Remove redundant info entry

Un-bold "section" from Official websites use .mil

f5736a5

Simplify copy for adding button styles to links

95781f5

Edit changelogs

225e56d

amyleadem commented Sep 27, 2023

View reviewed changes

amyleadem requested a review from mahoneycm September 28, 2023 18:49

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

69e2204

…mponent-audit-fixes

mahoneycm approved these changes Oct 20, 2023

View reviewed changes

amyleadem added 3 commits November 20, 2023 07:28

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

5126235

…mponent-audit-fixes

Update changelog dates

0820336

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

2274e04

…mponent-audit-fixes

mejiaj approved these changes Nov 20, 2023

View reviewed changes

mejiaj merged commit 41912e5 into main Nov 20, 2023

mejiaj deleted the al-component-audit-fixes branch November 20, 2023 20:59

		@@ -1,2 +1 @@
		- Associate the character count message to the input. Use `aria-describedby` on the input to allow the message to be announced to those using screen readers.
		- Use the `aria-live` attribute on character count message. Use `aria-live="polite"` so that updates to character count message are also announced when using a screen reader.

		@@ -1,4 +1,3 @@
		- Code header areas in the accordion as buttons. Using a `<button type="button">` assures accordions are usable with both screen readers and keyboards.
		- Use `aria-expanded` on buttons to express an accordion’s default state. Buttons should state if they are expanded by default with `aria-expanded="true"`. The `aria-expanded="false"` attribute will be added to other buttons when the accordion is initialized by the JavaScript.

		- Control card size and layout with USWDS utilities. The card component works well with [layout grid utilities]({{ site.baseurl }}/utilities/layout-grid/). The `usa-card-group` block is functionally a wrap-able `grid-row`, and each individual `usa-card` is a `grid-col`. This means you can use a grid utility like `tablet:grid-col-4` to set a four-column size on a card at `tablet` width. You can also set custom grid gaps on a `usa-card-group` using `grid-gap` utilities.

		Since the Design System grid is based on flexbox, you can use [flex positioning utilities]({{ site.baseurl }}/utilities/flex/) on the card group. The default alignment is stretch (stretch aligns the top and bottom of each card in a row), but the `flex-align-start` utility can set the alignment to the top of the row.

USWDS-Site: Fix component pages from audit (Phase 1) #2149

USWDS-Site: Fix component pages from audit (Phase 1) #2149

Uh oh!

Conversation

amyleadem commented Jun 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related issue

Preview link

Solution

Testing and review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amyleadem Jul 17, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amyleadem Jul 17, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mahoneycm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mahoneycm left a comment

amyleadem commented Jun 22, 2023 •

edited

Loading

amyleadem Jul 17, 2023 •

edited

Loading

amyleadem Jul 17, 2023 •

edited

Loading