Standardizing the HFLA Design System

[Aveline-art]

Dependency

• Post Homepage launch when we recruit a new design team.

Overview

With the new design system coming up, we need a way to relay to the team on what the intentions are behind the new designs.

Detail

While we sometimes have to decide things on an "as-needed" emergency basis, the entire team benefits when we have firmer guidelines on utilizing the new designs because it reduces the amount of back and forth between team members, speeding up production.

See also:

• Componentize the website #577,
• Finish dev documentation of Design System #1416,
• Figma

Action Items

• Discuss the new design system more in-depth so that there is a group understanding
• Create an issue for one of the checkboxes in the Components section below
• Add the link to the issue you made into the Components section (so the issue does not get made twice).
• As part of the auditing/researching/recommendations issue, include the following as Action Items (you can add additional Action Items as you see fit):

    - [ ] Search and find where each component is by looking at the pages that are live on the website and also in [Figma](https://www.figma.com/file/0RRPy1Ph7HafI3qOITg0Mr/Hack-for-LA-Website?node-id=3464%3A0) for not yet live pages.
    - [ ] Questions to answer/consider when working on this issue:
      - [ ] Where should the component live? In other words, which file should the CSS for the component be in? Does this file need to be created?
      - [ ] What are the differences between the classes that are located on the specific pages? Document those differences 
      - [ ] If they don't appear the same, should we rationalize them and make them the same across the page they show up on? 
      - [ ] Should the class(es) be renamed to be clearer?
  - [ ] If research is necessary, summarize your research
  - [ ] Summarize your recommendations for how to standardize the component and its code
  - [ ] Have a Merge Team member or a Technical Lead to review and sign off on your analysis and recommendations
  - [ ] Have a Product Manager review and sign off on your recommendations
  - [ ] (Optional) Write a new issue for a developer to implement your recommendations.
    - [ ] Here is the [How to create issues](https://github.com/hackforla/website/wiki/How-to-create-issues) wiki page for how we write issues on the Hack for LA Website Team
    - [ ] Ask a Merge Team member or Technical Lead if you need help with writing an issue. 
    - [ ] Include this in the Action items of your issue
```
 - [ ] Come up with a standard way to implement the CSS side (and, if applicable, HTML) of each component
 - [ ] Implement the CSS side (and, if applicable, HTML) of each component
 - [ ] Create/update a wiki for the design system component
 - [ ] Update the GitHub action that will emphasize the use of the system
```

Guidance on how to make the issues

• The auditing, researching, and recommendations for how to standardize the component can all be in one issue.
  • The issue for auditing, researching, and recommendations can be either a small or medium issue depending on the number of instances of each component on the webpage. For example, since accordions only show up twice throughout the website, if I were to write an issue for auditing, researching, and recommendations for the accordions, I would label it as a small issue.
    • Note: Some issues have already been written for this epic (they are linked in the Components section)

Components

• Accordions standardized
  • Accordions standards discussed (Accordion Component Standardization #1407)
  • Audit accordions on website and in codebase
  • Accordions standardized css and html implemented
  • In the wiki, add a Components: Accordion wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Buttons standardized (Button Project Board)
  • Button standards discussed (button default #1352)
  • Buttons audited (Audit all buttons on hackforla.org website #1921)
  • Button html/CSS implemented
    • Complete refactor/standardization of all buttons within Home Page #2104
    • Complete refactor/standardization of all buttons within Communities of Practice/Program Areas Page #2158
    • Complete refactor/standardization of all buttons within Sitemap/Events Page #2159
    • Complete refactor/standardization of all buttons within Join Us Page #2165
    • Complete refactor/standardization of all buttons within Wins Page #2187
  • In the wiki, add a Components: Buttons wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Cards css standardized
  • Cards standards audited (Design System: Audit Page Card CSS/HTML standard #2061)
  • Cards html implemented (Design System: Standardize Page Cards #2226)
  • In the wiki, add a Components: Cards wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Colors css standardized - Color Standardization Project Board
  • In the wiki, add a Components: Colors wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Dropdowns css standardized
  • Dropdowns standards discussed
  • Audit dropdowns on the website and in the codebase
  • Dropdowns html implemented
  • In the wiki, add a Components: Dropdowns wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Filter tags css standardized
  • Filter tags standards discussed
  • Audit filter tags on the website and in the codebase
  • Filter tags html implemented
  • In the wiki, add a Components: Filters wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Header container css standardized(Standardize code for header layout  #1898, )
  • Header container standards discussed (Standardize code for header layout  #1898, )
  • Header container html implemented (Standardize code for header layout  #1898, )
  • In the wiki, add a Components: Header Container wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Input fields css standardized
  • Input fields standards discussed (UI/UX Design for Checkboxes/Inputs #1398, )
  • Audit input fields on the website and in the codebase
  • Input fields html implemented
  • In the wiki, add a Components: Input Fields wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Modals css standardized
  • Modals standards discussed
  • Audit modals on the website and in the codebase
  • Modals html implemented
  • In the wiki, add a Components: Modals wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Sticky side nav css standardized
  • Sticky side nav standards audit (Design System: Audit Sticky Side Nav element #2173)
  • Sticky side nav html implemented (Design System: Standardize Sticky Side Nav #2174)
  • In the wiki, add a Components: Sticky Side Nav wiki page
  • Audit design system classes/code in Figma to make sure they match the codebase
• Typography css standardized (Implement Design system heading typography in the code base  #1743, )
  • Fixing all the typography on the website will become it's own epic for devs. A new dev issue will be written as each of the Design Team "Design System Audit: Text Elements:" issues are completed and added to the new epic in order to track them.

Resources/Instructions

• Componentize the website #577
• Finish dev documentation of Design System #1416
• Figma
• Standardized Components wiki page (explains how the standardized components should work in general): https://github.com/hackforla/website/wiki/Standardized-Components

Historical information

• Create the design system pages #1927
  • Note: We are no longer updating/maintaining the Design System webpages. Read the decision record on Maintaining the Design System webpages for more info.

[daniellex0]

Thank you for doing this @Aveline-art!! Getting dev buy-in is very important with implementing design systems, so I reallyyy appreciate that you all are getting involved!

As I mentioned today the button scss classes have been standardized, but not the HTML - I did just notice that even just on the top of the homepage, the "Join Us" button is a < button > tag and the "Submit your pitch" button is < a href >. I honestly didn't delve into the HTML tags with the design system, I only standardized classes. And I don't know much about tag selections, I mostly know about classes. I do see in Bootstrap buttons that they use a variety of tags too... So I guess it depends on the kind of button in question..?

As for other components, the other most common components on our pages are page cards (the large, usually white cards that contain most of the content on the site), which are also standardized for the most part.

As an aside- there is '.small-card' class that I left in the bottom of the card file- David Rubinstein's previous class in the file. I wasn't sure if all different kinds of cards should be in this file, but decided against it for now. There are a ton of different cards on our site, but most haven't been reused yet beyond the one page they are in so it can be better not to jump ahead and componentize until you know something actually needs to be reused. At least not to the extent that I componentized the variants of the buttons and page cards with all of the reusable classes for variants, because that is good for reusable components with several different colors and sizes, but overkill for a component that only has one look. It's fine to standardize the code for these kinds of no-variant components though if you think it would make it easier to reuse in the future (and again, this would be for components that you would expect you might reuse- not ones that are definitely one-offs).

So the important components to standardize and reuse are ones that are used on more than one page, especially ones with variants. There are actually not that many on our site all things considered- buttons and page cards are the main ones, so those are the two I standardized. As I mentioned to @Aveline-art and @abuna1985 when we met about this, there are some others that I could use help standardizing like the volunteer cards that have large versions here and small versions here. And another different example is accordions like the one in the bottom of Getting Started, which have just one size- so I guess the code is fine as-is and can just be reused? Or does CSS like this need to be standardized more/made easier to reuse..? I think this is more of a developer preference question..?

Sorry I know this is a lot... btw @jbubar and @averdin2 I can meet with you guys to give an overview about design systems if you want, the same as I did with @Aveline-art and @abuna1985 - let me know

[abuna1985]

1. Awesome. Can't wait to get started. Thank you @Aveline-art for making this issue and @daniellex0 for providing a summary of our progress so far. Once everyone feels up to speed on the situation, we need to figure how we will determine what will be added as a component. If we have instructions, a list of questions to ask before you add a component, and an established process for adding components, then I think everyone will use it. We basically need to give them no excuse to not use this tool.

2. I think the key to this to be consistently used by the whole team is the documentation/reference site. It looks like the Solid (Buzzfeed) design system website is built using Jekyll. Since the look of the website won't change over time, we can just build templates for the page and use a JSON file (an idea brought by @Aveline-art during our brainstorming) to populate the documentation site. This is not the only road we need to walk down, But we should probably determine how the site will be built and how we can make the update process as easy for everyone as possible.

3. For the HTML <a><button> standard, It seems like the solid design system just provides both HTML examples of <a>/<button> use cases. See the screenshot below:

Maybe we do something similar?

[daniellex0]

@jbubar You didn't make anything more complicated, don't worry about it!! Truly I am very happy if you guys talk about the design system as much as possible, because it builds up awareness and ensures it will be used!

Ok we'll coordinate a meeting :)

I'm working on the component library designs with @ktlevesque19 this week, and will then have some ready for dev review/comments/suggestions since y'all will be the ones using it, and when it's done it'll go to development.

@abuna1985 awesome response, thank you for all of that-

1. Great, I like this thinking for adding new components in the future
2. This is way above my dev knowledge, but I'm sure it's all good haha
3. Great point, I didn't notice that!!

[Aveline-art]

After Thursday's backend meeting, we have come to the conclusion that a proposal is needed on how to incorporate the design system webpages into our website. Should the new webpages be like the projects page (one template, multiple yml files), separate pages that lives in the pages directory, or some other configuration? Should all these pages be worked on in a separate branch like the wins-feature-1 branch?

We will follow up with this by consulting @cnk so that we may better assess our options. Also, we will have a follow-up meeting with the development team and @daniellex0 to outline the goals with the design system pages. The goals will be added either here or a new issue. Once the above two are done, we will continue the discussion on the next Thursday meeting.

Topics for goals:

• User experience
• Re-usability
• Ease of maintenance
• Etc.

[abuna1985]

Notes from meeting with @cnk on 7/11/2021

@hackforla/website-merge

Infrastructure

• @cnk 1 benefit of staying within the current Jekyll site (website repo) is that we will have access to current CSS files and styling available.
• @cnk initial inclination was just to do it as static pages
• @akib asked why static?
  • @cnk with a collection, you need data. You need a template that renders that structure collections. That can get complicated.
• @cnk proposed is it enough for using a collection/template within this site?
• @ExperimentsInHonesty asked if we should make another repo?
  • @cnk agreed it was possible to move the CSS from the actual site to the repo. The only issue is if any updates locally, they can get out of sync. @cnk suggests leaving it in the website repo
• @daniellex0 asked if we could convert multiple pages to one page at a later time if needed?
  • @cnk confirmed this was possible
• @akibrhast asked what about AWS for hosting a staging site for the design system website?
  • @cnk We would need a dedicated DevOps team to maintain the staging site. That may not be feasible right now.

Collection

• @jbubar suggestion for collection

  button collection
      small 
          title
          HTML
      medium
          title
          HTML
      large
          title
          HTML

• proposed properties for YAML: name, description, HTML(code)
• @averdin2 Is a template too restrictive for this situation? An example would be we have <a class="btn">button example #1</a> and <button class="btn">button example #2</button>
  • @akibrhast solution:

   button
     title
    description
    render
        HTML
            code(<button>)
            text
        HTML
            code (<a>)
            text

Template

• use <code> to show HTML (It will still need to be escaped to show up properly like so:
  <code>&lt;button class=&quot;btn btn-small&quot;&gt;This is a button&lt;/button&gt;</code>
  converts to
  <button class="btn btn-small">This is a button</button>
• endless scroll on-page - @averdin2 believes it may lead to confusion. The dev team agrees is not really needed.
• @jbubar suggested we move to horizontal top page navigation.
  • The team felt sidebar navigation would be beneficial since this is a reference site. It should stay on the side.

Adding To the Design System

• @cnk how do you envision designing and implementing a new design? Who initiates adding components within the design system? design/dev?
  • @daniellex0 an example. A developer notices an element that needs to be added to the design system. They let the design team know and begin the process.
  • @ExperimentsInHonesty suggested when a style needs to be moved to the main or a designer notices an element used in multiple pages but is not currently in the design system. Then we can start the process of adding the element.

Final Notes

• @cnk was eventually sold on and approves collection/template rendering within jekyll

Further Research

• Nested menu (needs to be researched to see how we can have 3 levels nested navigation menus within Jekyll)
• Search functionality within Jekyll (to be added later/not needed in version 1)

[JessicaLucindaCheng]

We are no longer updating/maintaining the Design System webpages. Read Maintaining the Design System webpages for more info.

[JessicaLucindaCheng]

The arrow to show more for a card on the About page is different than the accordion on the Getting Started page.

Click here to see the arrow to show more for a card on the About page in mobile view

Click here to see the accordion component on the Getting Started page

Mobile View

Desktop View

• The differences between the arrow to show more for a card on the About page and the accordion on the Getting Started page are
  • The arrow to show more for a card on the About page
    • Is only seen in mobile and tablet views, and not in desktop view (when using developer tools to view the page)
    • Doesn't have a line under the heading
    • Each arrow to show more is in it's own, individual card
  • The accordion on the Getting Started page
    • Is seen in mobile, tablet, and desktop view (when viewing the page using developer tools)
    • The header is underlined for each section of the accordion
    • The accordion has multiple sections all together in one card

[JessicaLucindaCheng]

• Issue Writing Progress: I need to finish editing this issue to be even more clearer
• Issue Writing Blockers: None
• Issue Writing Availability: 6 hours
• Issue Completion ETA: Wednesday, April 12, 2023

To Dos

• @JessicaLucindaCheng needs to edit the epic more to make it clearer for dev leads.
• Have the dev leads read the epic to make sure it is clear and sign off on it
• Have PMs read epic to make sure it is clear too and sign off on it