Design System: Audit Page Card CSS/HTML standard

[abuna1985]

Overview

We need to finalize the base HTML/CSS for the .page-card and classes so we can apply the standard to all the cards within the HfLA website

Action Items

• [x] Find all instances of the HTML, CSS, or (inclusive) JS code for .*-card (.page-card, .small-card, .project-card, .wins-card) class.
  • [x] Document all instances on a spreadsheet in our drive with (insert column names) (insert something about which folder in the drive)
• [x] Research online on what the standards are in terms of HTML tags, accessibility, etc for this component.
• [x] Do a write-up on your research as a comment on this issue.
  • [x] ~Link this comment into your pull request.~ This action item was removed because a pull request is not needed, since no code changes are made.
  • [x] Also, include this comment on the spreadsheet (merge cells might help in making this comment more visible to a viewer)
• [x] Edit the first item on #2226 to include a link to the spreadsheet.
• [x] When ready, @ mention hackforla/website-merge in a comment to review your work and include:
  • [x] A link to the spreadsheet you created
  • [x] A link to the comment where you did a write-up on your research

Merge Team

• [ ] Release dependency on #2226

Resources/Instructions

/* Current default for page-card*/
.page-card {
    border-radius: 20px;
    overflow: hidden;
    width: 100%;
  }

Spreadsheet link: https://docs.google.com/spreadsheets/d/10-c3jpf4vtXKcwLiBC4Z3wqN777xlxbErHS4QNq-e8o/edit#gid=1157217661

[sheltoG]

@abuna1985
Please rewrite the overview as a user story

Ex: We need to do x for y reason.

[abuna1985]

The overview has been updated

[ExperimentsInHonesty]

@abuna1985 the last checkbox sentence is unfinished. It says "Once consensus is reached, we can create an issue to" can you update that, plz

[abuna1985]

@ExperimentsInHonesty Last action item has been updated.

[JessicaLucindaCheng]

@Sparky-code At the time you self-assign an issue, make sure to write in a comment the following:

• Availability: "How much time will you have this week to work on this issue?"
• ETA: "When do you expect this issue to be completed?"

[Sparky-code]

Availability: 2hrs on Sun, 7-9p M/W/F next week ETA: Next Thursday

[Sparky-code]

Progress Update: Spreadsheet made and added to the drive under the audits folder. Research is in progress. Avail: Friday afternoon ETA: Friday EOD Potential Blocker: clarification on last couple of items in issue checklist

@abuna1985 Can you clarify the dependency items in this issue? I see that I'm being asked to add the spreadsheet link when I finish this issue but I'm not sure what you mean by 'release dependency' - is that just deleting the 'dependency' header and linked issue number? Thanks!

[JessicaLucindaCheng]

@Sparky-code Adam is no longer part of the Website Team, so please refer questions to Saumil, Tamara, and me. I edited the release dependency action item for merge team to deal with after this issue is closed and move the sub-action item to edit issue #2226 for you to complete as part of this issue.

"Release dependency on #2226 " means to check off the dependency in the issue 2226 and move the issue out of the Ice Box into the New Issue Approval.

[Sparky-code]

Progress Update: Found more relevant info as I was reading through resources, synthesize and summarize is taking longer than I thought. Avail. ~1hr/day M-F (Plus on call on wedneday ETA: This friday 4/01 Potential Blockers: creating a clear document from a lot of new information in a timely manner, dont expect this to be the case.

[Sparky-code]

@hackforla/website-merge

Link to folder in H4LA Drive

Link to Write-up [Additional Resources] Link to Spreadsheet

Key Points

• Cards require a bit of special consideration for their use, as there is not a standard element or design pattern. Article elements might be something to look into as a semantic standard ARIA element if alternative code is required.

• Use card containers as targets for link click events to create larger targets and better card UX.

• Refine the alt texts to not overload TTS readouts. Reduce tab stops where possible, both Chrome and Firefox provide accessibility inspectors for testing this.

For further research > start here.

Basic Walkthrough

• Make sure you have tabbing focus indicators for all elements that need to be highlighted.

• Every img you add to your site needs to have an alt attribute. If the image is informational, set the alt equal to a descriptive alternative for that image.

• If the image is decorative or redundant to adjacent text, set alt="", which conveys to assistive technology users that the image isn’t necessary for understanding the page.

• Avoid using generic strings like photo, image, or icon as alt values, as they don’t communicate valuable content to the user. Be as descriptive as possible.

• You can add class="visuallyhidden" with descriptive text to give more context to a button or link's purpose.

Ref: WCAG 2.1 guidelines

Here are a couple of great resources for visual examples with markup sections. Here and Here. There is a full list of resources at the bottom of the document.

Creating Accessible Cards Accessibility can’t always be in stride with your designs but every improvement makes a difference.

Core principles for creating accessible web design: Clarity - improve navigation by designing clear layouts and distinct calls to action. Robust Design - Design to accommodate a wide range of users. Specificity - Support assistive technologies specific to your platform, just as the standards of touch, keyboard, and mouse.

More specifically, the US Government’s digital standards give us guidelines for implementing cards as part of our design.

Cards should be actionable, as they are summaries of more detailed information. Cards are responsive. Card images should be as well.

Card elements should not be used decoratively. Card content should not be redundant. Cards should not be skeuomorphic.

Use unordered lists and list items. Use a ul for a card group and an li for each card. This formatting allows screen readers to enumerate the items in the card group and allows shortcuts between list items.

Use the appropriate heading level for your page. Update heading level based on the content of your page to make sure card headings is in the correct, logical outline order.

Use CSS to order the media element. Logically, the media element should follow the header element. Don’t re-organize the markup to reverse their order.

Clarity in function. Avoid redundant functionality and reduce tab stops, cards are not miniature pages. Headings should begin in sections, most everything in a card should follow the heading in the source code, creating smooth navigation for a screen reader.

It is important to use semantic HTML (aka POSH - Plain Old Semantic HTML). Using the most appropriate element for a given use includes the built-in accessibility associated with the given element. (i.e. using a <button> vs a <div> to create a play button).Using appropriate semantics allows you to be more adept with tabbing through the elements of a page and accessing the element with the keyboard. This function is essentially free when proper semantics are used.

This website provides some excellent examples of how to implement accessible code. A few key techniques:

Describing Images. When everything becomes conveyed via speech, brevity is important. You can highlight and silence images for screen readers using positive or empty alt values. Is the image explicitly important?

Affordance. The user should know the degree of interactivity that an element has, can they click anywhere on a card? Only the button/image? Using pseudo-content tricks we can place a link that stretches over the entire card while retaining the ability to interact with individual elements.

Using JS we can use the cards container as a proxy for a link when clicked, while the keyboard user keeps access through the original card link. A more thorough walkthrough can be found here. It's important to add this functionality using JavaScript so that in the event of JS failure, the card still functions normally.

Content Tolerance. Wherever an interface 'breaks' when too much or too little content is provided, we are restricting what contributors can say, thought clarity may make this argument somewhat redundant.

It is important to allow flexibility in input without making the card ugly or difficult to scan. We can create common margins using Owl Selectors. Note that we are managing margins in an algorithmic way here, using position and context rather than specific element properties.

Calls to action. Multiple ‘read more’ links become useless when taken out of context in an aggregated glossary. Explicit calls to action can be productive. Including a decorative ‘read more’ link within a (click anywhere-able) card eliminates issues with aggregation and redundant functionality. Using (aria-hidden) will hide this element from assistive tech as the button is just for show, implying explicit functionality that is already baked into the card.

[JessicaLucindaCheng]

@Sparky-code I don't have access to this document: Link to Write-up [Additional Resources]

Please make sure the document is in the HackforLA.org website Google Drive.

[Sparky-code]

@JessicaLucindaCheng Should be good to go, I'd mixed up the google account I was working from. Theres a Design Systems folder in the drive under audits that I've added a link to in my initial comment

[answebdev]

Review ETA: 4/1/2022 (end of day) Availability: 2 hours

[answebdev]

@Sparky-code After double-checking the instances of the HTML, CSS, or JS code for the .*-card (.page-card, .small-card, .project-card, .wins-card) class with the spreadsheet, I found another instance of the .page-card class in _sitemap.scss (line 33) that is not on the spreadsheet:

https://github.com/hackforla/website/blob/eb4c4c37a05fd6aad51c3d2b69cede73d07c584d/_sass/components/_sitemap.scss#L33

This looks like another instance that should be added to the spreadsheet, but I wanted to point that out first.

[Sparky-code]

@answebdev nice catch, thanks - just added to the spreadsheet now.

[answebdev]

@Sparky-code Great! You're welcome.

[JessicaLucindaCheng]

@JessicaLucindaCheng Availablity: 6 hours Review ETA: Tue, April 5, 2022

[JessicaLucindaCheng]

@Sparky-code Good job with the write-up and identifying all the cards.

• [x] I left comments and suggestions in your Write-up. Please take a look in the Doc.
• [ ] As for the Spreadsheet,
  • [ ] I think it needs more details and specifics of what needs to be changed for each card so that the developer working on the next issue (#2226) can standardize all the cards. Here is an example of a spreadsheet: https://docs.google.com/spreadsheets/d/1n3va-1kwGOCTP4JaXpL3TjgvS_2RWDkurb8PyCJSp-0/edit#gid=0. The columns you decide upon may be different and would need to fit with this audit.
  • [ ] I think it needs to be better organized, such as having the following columns (you may decide on a different organization/columns): Class Name, File (the class is in), Webpage(s) (It is used in), Recommendation, etc. If you want, you can start a new tab in the spreadsheet with the columns you think would make sense and maybe fill in one row. Then, I can take a look before you fill in the rest of the info.
  • [ ] I think the comment for the write up should be at the top of the spreadsheet instead of the bottom, so it doesn't get missed.

[JessicaLucindaCheng]

@SAUMILDHANKAR @tamara-snyder Could you also do a review of the write-up and spreadsheet? The links are in this comment https://github.com/hackforla/website/issues/2061#issuecomment-1083518792. Mostly, I'm not exactly sure what columns should be in the spreadsheet. (See my comments/review: https://github.com/hackforla/website/issues/2061#issuecomment-1089749420.)

[Sparky-code]

@JessicaLucindaCheng Thanks for all the great feedback. I've gone through the write up in response to your comments and made a template in the spreadsheet. I had a few questions based on your feedback:

• Are you asking for recommendations for each instance of *.-card?
• Alt. Does this apply to refining/producing components of each as an .md file (similar to the page-card.md file in design systems. There are some notes in that .md file that make it seem like it will be required for each instance of many of the card types?
• It sounds like the requirements of this issue are expanding significantly, depending on the answers to the other questions. I want to clarify whether this is a high level audit of standards and relevant methods or a specific audit of those standards in relation to individual files/components (beyond tracking their locations and attributes), or both?
• The template for the spreadsheet, is that being expanded by the next issue or should I be trying to set that up to be further populated by the next issue?

I'll keep an eye out for feedback from Saumil and Tamara since I think we're on the same page about being not quite sure what all needs to be included in the spreadsheet.

Thanks!

[JessicaLucindaCheng]

Are you asking for recommendations for each instance of *.-card?

I don't know if that makes the most sense. For me, I think it makes more sense to look at each card on a page and audit it that way. For reference, this was the issue from the button audit: https://github.com/hackforla/website/issues/1921. I think the goal for this issue (in terms of the spreadsheet) is similar but for cards. Also, I think your audit may need to include HTML.

Alt. Does this apply to refining/producing components of each as an .md file (similar to the page-card.md file in design systems. There are some notes in that .md file that make it seem like it will be required for each instance of many of the card types?

We should ask Bonnie at the Sunday All Team meeting about those md files because I'm not sure if those files are supposed to be edited as part of this audit. Though, maybe it was since Adam wrote to open a pull request but there was no mention of editing the md files nor even a link to them in the resources section, so I'm not sure. As far as I understand this issue, you are just auditing the cards and doing research. I don't think you are supposed to edit anything in the codebase.

It sounds like the requirements of this issue are expanding significantly, depending on the answers to the other questions. I want to clarify whether this is a high level audit of standards and relevant methods or a specific audit of those standards in relation to individual files/components (beyond tracking their locations and attributes), or both?

I think both. The specific audit would be in the spreadsheet. I think the high level would be included in your write-up. For example, here is a reference to what I think a high level audit could be: https://github.com/hackforla/website/issues/1352#issuecomment-877676139. (It was a link in #1921).

I think this issue was supposed similar to what issue #1352 and issue #1921 combined were for buttons. Also, I think the large issue was written vaguely because it was to encourage you to figure out a plan on how to approach it yourself and do it. Though, I think it could have been a bit more prescriptive as to what it wanted or at least given examples of other issues/spreadsheets/etc so you could have understood where this issue was going.

The template for the spreadsheet, is that being expanded by the next issue or should I be trying to set that up to be further populated by the next issue? I think the next issue (#2226) is to implement your specific recommendations for each card. I don't think they will add more recommendations to it but you may want columns for them to check off that it is updated or something like that.

I think you should bring this issue up at the Sunday meeting with Bonnie because I want to make sure you are heading in the right direction before you continue doing tons of work. Since this issue was written vaguely, I'm also not sure and only based what I wrote above on what I saw in similar issues that I linked to, which isn't a definitive answer. Though, @SAUMILDHANKAR may have more knowledge on this matter since he has been part of the team longer than I have and could chime in with his thoughts and answer the questions you asked me from his point of view.

[SAUMILDHANKAR]

@SAUMILDHANKAR ~~Review ETA: 4/10/22~~ Sorry, couldn't finish review yesterday Availability: Today 7-9 PM Revised review ETA: EOD 4/11/22

[tamara-snyder]

Availability: 2 hours Review ETA: Tuesday, 4/12/2022

[Sparky-code]

Progress Update: Finished Research, Gathered instances of cards across site, Template chosen for Spreadsheet Audit Blockers: Pending discussing with @JessicaLucindaCheng to discuss columns on spreadsheet, pending feedback from reviews on same ETA: TBD Avail 6hrs across M/F

[SAUMILDHANKAR]

@Sparky-code Sorry for the delay in my review and thanks for your awesome work on this issue so far. I understand the issue has been evolving as we go so this might not be a complete review but just want to share a few points that might be helpful:

• Thanks for bringing up this issue for discussion in the Sunday meeting and we can incorporate the suggestions so that the requirements are more well defined.

Are you asking for recommendations for each instance of *.-card?

• The recommendations for each instance of *.-card would be very helpful similar to what was done for issue 1921 as suggested by Jessica

It sounds like the requirements of this issue are expanding significantly, depending on the answers to the other questions. I want to clarify whether this is a high level audit of standards and relevant methods or a specific audit of those standards in relation to individual files/components (beyond tracking their locations and attributes), or both?

• I agree with Jessica that we should go for both. I understand this could mean increase in the size of this issue and we can adjust the size point label for this issue based on your feedback.
• I see the next steps would be a discussion on columns for the spreadsheet. Based on the write-up, I understand that there could be multiple recommendations for each instance, so either we go for multiple sub rows for each instance or multiple recommendations in a single cell. For me, multiple sub rows is more readable. Also, a column where we add the final decision for each (such as a yes/no if we want to make that change based on PM sign off) would be helpful.

Please let me know if any of my points above need more clarification. Look forward to further discussion on this. Thanks again for your great work!

[tamara-snyder]

Hi @Sparky-code, I just wanted to say that your write-up is very thorough and I learned a lot. You should totally publish a version of this on Medium.

In regards to the spreadsheet, it is looking a lot better! I agree with Jessica and Saumil about possibly needing a few changes on the columns.

A few thoughts:

• I think it would be clearer to use File Path instead of File Name since it'd be easier for whoever is working on the cards to find the relevant file in our project.
• Can you please clarify what the Name column in the Audit tab is for?
• It may be helpful to have a column for referencing relevant lines of code like in the CSS Standardization spreadsheet
• I like all of Saumil's column suggestions

Awesome work on this!

[JessicaLucindaCheng]

@Sparky-code The spreadsheet for the audit is definitely improved and looking good. In addition to the recommendations from Saumil and Tamara, I would like the following:

• Since all the cards may not need changes, so you may want to consider including a "Change (Y/N)?" column similar to the column in the audit spreadsheet for alt attributes: Alt Attribute Review
• I saw you add page-card.md but it's not actually a card and is more an information file about cards, so I don't think it needs to be included in the spreadsheet. (You can leave it at the bottom of the spreadsheet for now but wait to work on filling out the columns/info for page-card.md until we know for certain where the design system webpages are going.)
  • Also, I will ask Bonnie about the design system mds/webpages as overall/as a whole and where it's at and going at Sunday meeting. Based on that discussion, we can see if auditing the md file needs to be a part of this issue or is a separate issue. (I still think it's a separate issue but Bonnie may think differently.)

[github-actions[bot]]

@Sparky-code

Please add update using the below template (even if you have a pull request). Afterwards, remove the 'To Update !' label and add the 'Status: Updated' label.

1. Progress: "What is the current status of your project? What have you completed and what is left to do?"
2. Blockers: "Difficulties or errors encountered."
3. Availability: "How much time will you have this week to work on this issue?"
4. ETA: "When do you expect this issue to be completed?"
5. Pictures: "Add any pictures of the visual changes made to the site so far."

If you need help, be sure to either: 1) place your issue in the developer meeting discussion column and ask for help at your next meeting, 2) put a "Status: Help Wanted" label on your issue and pull request, or 3) put up a request for assistance on the #hfla-site channel.

_{You are receiving this comment because your last comment was before Tuesday, April 19, 2022 at 12:20 AM PST.}

[Sparky-code]

Progress: Not much, still have to go through and implement the changes and updates to the spreadsheet, got a bit tunnel-visioned on a school project and this took the hit time wise. Blockers: Just finding the time. Availability: M/W/F 6+hrs ETA: Hope to make solid progress this week.

[Sparky-code]

Progress: adding more detail to track locations of cards on each page, clarifying spreadsheet with input from reviews and linked audit references. Cross referencing and finding a few more instances I'd missed. Blockers: Having some issues with searching in VSC and would like to take some time to go over why these issues are happening and making sure i'm not missing anything else. Avail: Friday 2-3hrs ETA: Ongoing