USWDS-Site - Disabled styles: Create guidance for disabled elements best practice

[amyleadem]

Summary

Once the landscape analysis for disabled styles is completed in uswds/uswds#5117 and we have determined our recommended guidance, we should create public documentation that:

1. Creates guidance for when to use (or not use) disabled styles
2. Demonstrates recommended code patterns
3. Shares supporting research

[amyleadem]

@jaclinec For housekeeping, I went ahead and assigned this issue to you, but realized that it might be a duplicate of #2145. Feel free to close this issue if that is true!

[jaclinec]

@amyleadem It's not a duplicate so we're good! I am going to reassign to @sarah-sch per our PI planning decisions, but she and I will both work closely on this. Thanks!

[jaclinec]

I've begun a draft of disabled states content for the site: https://docs.google.com/document/d/11K16g1qmqh9aU-ebSFtn_WRCVjB6lmBVLno5Vs854Ig/edit?usp=sharing

Next, I will share with the team for feedback, and begin drafting research findings that we will link from the site to Github.

[jaclinec]

I've drafted what will be the publicly sharable, published disabled states research findings Github wiki content that we may link to from the site. We are following the model we used for the Link component research findings in the Github wiki. For now it is just a draft in a Google doc. We can move it to the wiki when it's a final draft.

Thank you @annepetersen for already reviewing and revising the content. Please, @thisisdano and one Content Strategist should also take a pass @bonnieAcameron @sarah-sch

8/14/2023 update: I am moving this part of the issue (drafting publicly shareable research findings) to #2243 to break up this work.

[jaclinec]

We've taken a look at the suggested places for site updates as well as drafted guidance content as a team and this issue needs review for the following questions:

• Are the places I've identified on the site the right ones? Are there any missing sites? - Someone in CS and Engineering please review(@bonnieAcameron @sarah-sch @amyleadem @mahoneycm @mejiaj )
• How does the drafted guidance content look? What changes are needed? - CS (@sarah-sch @bonnieAcameron )
• Does our current code match what we are proposing? What changes are needed? - Engineering
• How might we tackle these updates in a phased manner so work doesn't stall? - @annepetersen , @thisisdano , CS

[mahoneycm]

@jaclinec I left a couple of comments on the code placement in the docs.

We currently do not have any patterns displaying acceptable usage of disabled form elements. It might be beneficial to show an example but, on the other hand, we also recommend avoiding using disabled forms so I'm not sure if it's better to lead by example and exclude one?

[jaclinec]

We decided we are going to take a phased rollout approach to updating/creating disabled states guidance for the website since it affects so many pages and the work has become too large to capture in one issue.

I am breaking up this issue into manageable pieces:

• Phase 1 guidance rollout: Disabled States: Phase 1 guidance rollout #2246
• Phase 2 guidance rollout: Phase 2 rollout of disabled states guidance #2247
• Phase 3 guidance rollout: Phase 3 rollout of disabled states guidance #2248
• Sharing research findings in Github wiki: Review draft of publicly shareable disabled states research findings to publish to site and Github #2243

As far as determining if our code matches what we are proposing/our guidance, my thought is to tackle that for each phase of the rollout. Open to suggestions from @amyleadem @mahoneycm @mejiaj

This issue can likely be closed as we are carrying the work into the issues above.

[mahoneycm]

The site currently uses reusable content blocks for information that is valuable on multiple pages. I wonder if something like this might be valuable on component pages that can be disabled, or if it'd be better to provide component specific guidance. Might help to reduce the lift if we're able to provide general disabled guidance and include what's necessary on the pages of components that can be disabled.

State variants example

The state variant guidance below is featured on all utility pages that feature state variants

[jaclinec]

@mahoneycm I like the idea of being able to use content blocks for multiple pages to lighten the load, but after writing draft guidance for several components already, it feels somewhat necessary to customize guidance for each component. I'm handing this off to the CS team so definitely open to other opinions around that.

I'm closing this issue as done and the work will continue in the separate phases as outlined in the issues above. Thanks, all!