USWDS-Site: Fix component pages from audit (Phase 2) #2162

amyleadem · 2023-07-05T15:35:07Z

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 #2151

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

- Update list of icon sizes - Update links for icon list colors

amyleadem · 2023-07-05T17:14:47Z

_components/file-input/guidance/implementation.md

@@ -1,5 +1,5 @@
 - **Initialization properties.**  JavaScript will create most elements for file input. To get a file input to initialize, add the class name `usa-file-input` to `<input type="file" />`.
 - **Interaction.** When a user selects or drags documents to the file input, the file name and a thumbnail preview are listed.
 - **Using the `accept` attribute.** You can allow certain files by placing an accept attribute on the `<input/>`. If a file type is not accepted, the file will not be attached and the file input will display a message. [Learn more about the accept attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) [mozilla.org].
- **Internet Explorer/Edge.** These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
+- **Internet Explorer and older versions of Edge.** These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.


Is this note still needed? Wondering if it can be considered outdated.

In practice, does the file-input component remove the drag instructions if implemented on these browsers?

If it's still a feature of the component, I feel we should leave it.

_components/list/guidance/when-to-consider-something-else.md

- Add clarity to usa-hint note

amyleadem · 2023-07-05T18:21:09Z

_components/file-input/guidance/usability.md

@@ -1,3 +1,3 @@
 - **Allow multiple file formats.** Not everyone has access to the same software. Be flexible with file types to avoid unnecessary software requirements.
- **Prefer one file per input.** Some users might not know how to select multiple files in a file browser. Additionally, iOS does not allow multiple-file selection using the Files app.


Note
Removed the iOS note because I was able to select multiple files and images in iOS.

amyleadem · 2023-07-05T18:27:18Z

_components/header/header.html

-  <li>
-    <strong>Use the gov banner on all federal websites.</strong> We recommend
-    that all federal government websites include the “official government website”
-    banner and a logo or site name.
-  </li>


Note
I removed notes about the banner component on the header page because the content seemed outdated and I worried that mixing component guidance might lead to confusion.

If we want to keep something here - maybe it would be good to convert some of this content to a site-note that recommends using both the banner and logo/site name on your page?

amyleadem · 2023-07-05T18:30:20Z

_components/header/header.html

-    The Design System uses semantic header and nav elements with
-    <code>role="banner"</code> and <code>role="navigation"</code> respectively.
-    <code>role="banner"</code> is your masthead.
-  </li>
-  <li>


Note
Removed this because we do not use either roles in our banner or header component examples.

mahoneycm

Confirming the relevant changes from the audit sheet have been made and free from spelling or grammatical errors!

I left a few comments weighing in on some of the pending items. Let me know if I can be of any more assistance if you want to divvy up any research items!

mahoneycm · 2023-07-06T19:15:53Z

_components/file-input/guidance/implementation.md

@@ -1,5 +1,5 @@
 - **Initialization properties.**  JavaScript will create most elements for file input. To get a file input to initialize, add the class name `usa-file-input` to `<input type="file" />`.
 - **Interaction.** When a user selects or drags documents to the file input, the file name and a thumbnail preview are listed.
 - **Using the `accept` attribute.** You can allow certain files by placing an accept attribute on the `<input/>`. If a file type is not accepted, the file will not be attached and the file input will display a message. [Learn more about the accept attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) [mozilla.org].
- **Internet Explorer/Edge.** These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
+- **Internet Explorer and older versions of Edge.** These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.


In practice, does the file-input component remove the drag instructions if implemented on these browsers?

If it's still a feature of the component, I feel we should leave it.

mahoneycm · 2023-07-06T19:25:52Z

_components/header/header.html

+    <strong>Add a skip navigation link before the header.</strong> Include skip navigation links to allow users with
+    screen readers to bypass long navigation lists. Make sure you include an <code>id</code> at the beginning of your
+    main content and that it matches the skip navigation link. Find more <a
+      href="http://webaim.org/techniques/skipnav/">information on these links</a> at WebAIM.


I like this idea! Do we have any usa-skipnav documentation? I can't seem to find any.

mahoneycm · 2023-07-06T20:30:28Z

_components/header/header.html

-      >http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/.</a
-    >
+    <a
+      href="http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/">http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/.</a>


This article isn't much newer, but I like the reasoning here:

The first heading on your site should be the one that best describes the content of your page. Sometimes this is your logo–but most of the time it’s not. ¹

Footnotes

https://www.fastcompany.com/3016894/should-your-tag-be-your-logo#:~:text=The%20first%20heading%20on%20your,organize%20information%20and%20orient%20users. ↩

_components/icon-list/icon-list.md

_components/list/guidance/when-to-consider-something-else.md

Revising for conciseness. We could use "communicate" instead of "explain" if you like that better.

Adding "skip navigation" to make link text more descriptive

editing for conciseness

_components/file-input/guidance/implementation.md

_components/modal/guidance/accessibility.md

…mponent-audit-fixes-2

mejiaj

Added a few comments, otherwise LGTM.

mejiaj · 2023-07-14T18:35:00Z

_components/header/header.html

  </li>
  <li>
-    If you’re using a logo that’s text, use an <code>em</code>, not an
+    <strong>Don't use an H1 for your logo.</strong> If you’re using a logo that’s text, use an <code>em</code>, not an


Reflects what's shown in example:

Default header preview

mejiaj · 2023-07-14T18:36:19Z

_components/header/header.html

-      >http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/.</a
-    >
+    <a
+      href="http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/">http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/.</a>


I'm included to keep it because:

Link still works

Site is a good resource

Guidance reflects what's actually shown in USWDS header

mejiaj · 2023-07-14T18:38:43Z

_components/header/header.html

-      href="https://www.usertesting.com/blog/site-navigation-tree-testing"
-      >https://www.usertesting.com/blog/site-navigation-tree-testing</a
-    >
+      href="https://help.usertesting.com/hc/en-us/articles/115003372331-What-is-Tree-Testing">https://help.usertesting.com/hc/en-us/articles/115003372331-What-is-Tree-Testing</a>


Let's keep for now. Created a new issue to follow-up on this #2187.

_components/modal/guidance/implementation.md

…mponent-audit-fixes-2

amyleadem · 2023-07-14T21:36:50Z

@mejiaj and @mahoneycm I believe I addressed all your concerns. Let me know if I missed anything.

…mponent-audit-fixes-2

mahoneycm

Looks great! Thanks Amy

mejiaj · 2023-10-12T18:52:44Z

@amyleadem can you fix conflicts? Otherwise looks good to merge.

…mponent-audit-fixes-2

amyleadem added 15 commits June 30, 2023 12:17

Add formatting to footer variant classes

a1d0f71

Add bolded headers to header accessibility

b617e74

Remove content unrelated to header

9c8865b

Update icon list variants descriptions

931992f

- Update list of icon sizes - Update links for icon list colors

Fix formatting on icon accessibility code samples

9af346d

Add documentation for usa-input-group--success

6e090bd

Add backticks to for attribute

99459b4

Add clarity to hint text header

ec39db4

Add missing space

1d68936

Add clarity to hide icons from screen readers section

e33193f

Add periods to class names

f55e4c6

Add clarity to input prefix implementation section

b73717c

Remove redundant quotes

f11342b

Add missing usa-link dependencies

e7a5b9f

Update code styling for link encoding example

693b9f0

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

amyleadem added 5 commits July 5, 2023 08:48

Add backticks to id on modal accessibility

a9048f8

Add documentation for usa-list--unstyled variant

3f8cc0d

Add bolded statements to list implementation

525c9b7

Small copy edits to modal implementation section

a93b439

Update text to say 'older versions of' edge

43654be

amyleadem commented Jul 5, 2023

View reviewed changes

_components/list/guidance/when-to-consider-something-else.md Show resolved Hide resolved

amyleadem added 3 commits July 5, 2023 10:37

Add changelog items for #2162

1af64ed

Standardize code presentation

26c92c4

Remove note about file input in iOS.

06c6c55

- Add clarity to usa-hint note

amyleadem commented Jul 5, 2023

View reviewed changes

Add clarity to icon list variant copy

53841a8

amyleadem requested a review from sarah-sch July 5, 2023 22:26

mahoneycm reviewed Jul 6, 2023

View reviewed changes

sarah-sch added 3 commits July 11, 2023 16:13

Update usability.md

47eacd6

Revising for conciseness. We could use "communicate" instead of "explain" if you like that better.

Update header.html

7cacf39

Adding "skip navigation" to make link text more descriptive

Update header.html

2591df0

editing for conciseness

sarah-sch reviewed Jul 11, 2023

View reviewed changes

_components/file-input/guidance/implementation.md Show resolved Hide resolved

_components/modal/guidance/accessibility.md Outdated Show resolved Hide resolved

amyleadem added 3 commits July 11, 2023 16:04

Add clarity to file input accept attribute section

190e3a6

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

1825a35

…mponent-audit-fixes-2

Add clarity to modal implementation copy

4745cac

mejiaj mentioned this pull request Jul 14, 2023

USWDS-Site - Documentation: Header has an old link that redirects to homepage #2187

Open

mejiaj requested changes Jul 14, 2023

View reviewed changes

sarah-sch approved these changes Jul 14, 2023

View reviewed changes

amyleadem added 2 commits July 14, 2023 14:24

Restore note about using <a> for JS fallback

a7e3b52

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

f4c3ed0

…mponent-audit-fixes-2

amyleadem requested review from mejiaj and mahoneycm July 14, 2023 21:36

mejiaj approved these changes Jul 17, 2023

View reviewed changes

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

c142315

…mponent-audit-fixes-2

amyleadem mentioned this pull request Aug 3, 2023

USWDS - Bug: Accessibility - Multiple unnamed banner landmarks #2226

Open

2 tasks

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

08ce1df

…mponent-audit-fixes-2

amyleadem requested a review from thisisdano August 3, 2023 15:22

mahoneycm approved these changes Sep 1, 2023

View reviewed changes

amyleadem added 3 commits November 20, 2023 08:08

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

8f5bac8

…mponent-audit-fixes-2

Update changelog dates

3afcf63

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

fe79cc9

…mponent-audit-fixes-2

mejiaj approved these changes Nov 20, 2023

View reviewed changes

mejiaj merged commit a166f65 into main Nov 20, 2023
11 checks passed

mejiaj deleted the al-component-audit-fixes-2 branch November 20, 2023 19:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS-Site: Fix component pages from audit (Phase 2) #2162

USWDS-Site: Fix component pages from audit (Phase 2) #2162

amyleadem commented Jul 5, 2023 •

edited

amyleadem Jul 5, 2023 •

edited

mahoneycm Jul 6, 2023

amyleadem Jul 5, 2023 •

edited

amyleadem Jul 5, 2023 •

edited

amyleadem Jul 5, 2023

mahoneycm left a comment

mahoneycm Jul 6, 2023

mahoneycm Jul 6, 2023

mahoneycm Jul 6, 2023

mejiaj left a comment

mejiaj Jul 14, 2023

mejiaj Jul 14, 2023

mejiaj Jul 14, 2023

amyleadem commented Jul 14, 2023

mahoneycm left a comment

mejiaj commented Oct 12, 2023

		@@ -1,3 +1,3 @@
		- Allow multiple file formats. Not everyone has access to the same software. Be flexible with file types to avoid unnecessary software requirements.
		- Prefer one file per input. Some users might not know how to select multiple files in a file browser. Additionally, iOS does not allow multiple-file selection using the Files app.

USWDS-Site: Fix component pages from audit (Phase 2) #2162

USWDS-Site: Fix component pages from audit (Phase 2) #2162

Conversation

amyleadem commented Jul 5, 2023 • edited

Summary

Related issue

Preview link

Solution

Testing and review

amyleadem Jul 5, 2023 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem Jul 5, 2023 • edited

Choose a reason for hiding this comment

amyleadem Jul 5, 2023 • edited

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Footnotes

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

amyleadem commented Jul 14, 2023

mahoneycm left a comment

Choose a reason for hiding this comment

mejiaj commented Oct 12, 2023

amyleadem commented Jul 5, 2023 •

edited

amyleadem Jul 5, 2023 •

edited

amyleadem Jul 5, 2023 •

edited

amyleadem Jul 5, 2023 •

edited