search

uswds / uswds-site

USWDS website and documentation
https://designsystem.digital.gov
Other
194 stars 145 forks source link

USWDS-Site - Feature request: Checklist page follow-up #2438

Open mejiaj opened 9 months ago

mejiaj commented 9 months ago

[!TIP] Please turn checklist items into issues to track work.

Spike

Low effort

Medium effort

High effort

mahoneycm commented 9 months ago

Additional future enhancement ideas I had while reviewing:

1: accessibility.md frontmatter

I'm curious if we could reduce duplicative content in the front matter for the accessibility markdown files. Some of the values are the same across all components and the others could potentially be dynamic dependent on component.name.

Same values:

Could we set the following frontmatter via a accessibility-test layout?

Different / dynamic Values:

Could these be set dynamically using the component name?

Update 2/22/24

I attempted to find a way to use external yaml data as frontmatter for components and their accessibility pages. The goal was to reduce duplicative frontmatter and pave the way for automating these files in the future.

This appears to not be possible without additional plugins to allow liquid syntax in frontmatter. Due to the scope of the issue increasing, I think it's fine to leave for now. Luckily, there isn't a ton of duplicate frontmatter.

mahoneycm commented 9 months ago

2: Removing child sections from subnav

In general, I like removing child sections from the subnav and relying on the in-page nav to provide jump links to these sections. I'm curious how this pattern will affect pages where the in-page nav has been deactivated and what we could do to standardize.

Component pages without in-page nav

mahoneycm commented 9 months ago

3: Accessibility test snippet

Instead of copying the accessibility-test yaml snippet from the readme file, it'd be nice to have a snippet similar to the changelog new entry and new log shortcuts.

I believe this is a local change but maybe we could include the instructions? Just a thought.

mejiaj commented 8 months ago

~Assigning to myself to refine issue.~

I've broken out the tasks into their own sections based on LOE.

maggiewachs commented 2 months ago

@mahoneycm related to your follow up comments here — the component checklists / YAML files are incredibly useful for testing USWDS components, and as templates for defining our own manual checklists for custom components and workflows (I work with the WECMS team, and though we use the CMS design system, we often refer to USWDS guidance). You all are doing great work here, thank you!

This thread has me wondering if in the future, checklist tests could be organized more like a unit test library, where tests are defined once and are reusable (like "Focus indicators are clearly visible").

I realize that would be an undertaking, but wanted to float it as an idea. There are so many manual checklists in the world, but not many (or any?) tools for creating them in our own documentation.

mejiaj commented 1 week ago

Thanks for the feedback @maggiewachs.

The idea of organizing them so that the tests are more reusable is a good idea. We'll have to spike that issue in the future.

In the meantime I've cleaned up the issue tasks and (hopefully) made it more actionable so we can continue this work.

CC @amyleadem @mahoneycm