website icon indicating copy to clipboard operation
website copied to clipboard

Published 20 hours ago • verified publisher icon hackforla

Standardizing the HFLA Design System

Open Aveline-art opened this issue 4 years ago • 55 comments
trafficstars

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:

Action Items

  • [x] 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
    • [x] Accordions standards discussed (#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)
    • [x] Button standards discussed (#1352)
    • [x] Buttons audited (#1921)
    • [x] Button html/CSS implemented
      • #2104
      • #2158
      • #2159
      • #2165
      • #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 (#2061)
    • [ ] Cards html implemented (#2226)
    • [ ] In the wiki, add a Components: Cards wiki page
    • [ ] Audit design system classes/code in Figma to make sure they match the codebase
  • [x] 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
  • [x] Header container css standardized(#1898, )
    • [x] Header container standards discussed (#1898, )
    • [x] Header container html implemented (#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 (#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 (#2173)
    • [ ] Sticky side nav html implemented (#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
  • [x] Typography css standardized (#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

  • #577
  • #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

Aveline-art avatar Jun 27 '21 20:06 Aveline-art

@jbubar @averdin2 @daniellex0

Hi! I went ahead and made a bigger issue for this to hold a bigger discussion beyond just buttons. Everything looks good, I think, for us to open issues about changing the buttons once we decide what the standards for buttons will be (when to use it, when not to use it, what tags do we use it for, etc). But if there is any thing we want to talk about in terms of other components, we can totally start talking here!

Also, it sounds like @jbubar wants the dev team to make a proposal for the other teams to sign off on? Can we start this now or should we hold off until we get all the components?

Aveline-art avatar Jun 27 '21 21:06 Aveline-art

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

daniellex0 avatar Jun 28 '21 02:06 daniellex0

@daniellex0 I am up for that! If you and @Aveline-art meet, let me know and I will jump in. Also, my apologies if I made things more complicated with the way I brought it up in the meeting

jbubar avatar Jun 28 '21 04:06 jbubar

  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:

Screenshot 2021-06-28 120544

Maybe we do something similar?

abuna1985 avatar Jun 28 '21 19:06 abuna1985

@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!!

daniellex0 avatar Jun 30 '21 01:06 daniellex0

@daniellex0 Not sure if this meeting has happened yet, but I would like to be roped in when things get scheduled

averdin2 avatar Jun 30 '21 18:06 averdin2

@daniellex0 I would also like to take part in the meeting for this if it hasn't happened yet!

arghmatey avatar Jun 30 '21 20:06 arghmatey

@averdin2 @arghmatey Sure thing!

daniellex0 avatar Jul 01 '21 00:07 daniellex0

Update: There was not an opportunity to go over this issue during the backend meeting on 7/1/2020 due to time constraints

Potential Next Steps: Based of https://github.com/hackforla/website/issues/1850#issuecomment-871039223 on the 29th jun 2021

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.

Let's schedule to talk about this next thursday(July 8th 2020) backend meeting with all parties involved . If everyone is ok with that ?

akibrhast avatar Jul 02 '21 19:07 akibrhast

@akibrhast Sure that works, I can join Thursday's backend meeting (although I hope it doesn't take up time from other important backend topics like the onboarding automation). Maybe we can discuss the backend-related topics of the design system during the meeting, and I'll also schedule another meeting with you all about the HfLA site design system overall. I'll send a when2meet now to figure out availabilities.

daniellex0 avatar Jul 06 '21 18:07 daniellex0

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?

Aveline-art avatar Jul 10 '21 15:07 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.

Aveline-art avatar Jul 11 '21 19:07 Aveline-art

reached out to @cnk to find out what she thinks about using Jekyll and she came to meeting. Thinks its feasible to have each component have its own yml page

ExperimentsInHonesty avatar Jul 11 '21 20:07 ExperimentsInHonesty

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)

abuna1985 avatar Jul 11 '21 20:07 abuna1985

@abuna1985

Please add update using this template (even if you have a pull request)

  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) ask for help at a Tuesday or Sunday 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, August 3, 2021 at 7:53 AM.

Note: This comment was created as part of a GitHub Action during its trial phase. If you find this GitHub Action to be disruptive/unhelpful, or if you believe there might be a bug, please leave a comment on this issue. All feedback will be used to further improve it. Thank you for your time.

github-actions[bot] avatar Aug 06 '21 14:08 github-actions[bot]

  1. Progress: Currently in the research/delegation phase. Created 1 issue on page card standardization (#2061)
  2. Blockers: None
  3. Availability: Friday Afternoon & Sunday Morning
  4. ETA: TBD
  5. Pictures: None so far

abuna1985 avatar Aug 06 '21 19:08 abuna1985

@abuna1985

Please add update using this template (even if you have a pull request)

  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) ask for help at a Tuesday or Sunday 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, August 10, 2021 at 12:10 AM.

Note: This comment was created as part of a GitHub Action during its trial phase. If you find this GitHub Action to be disruptive/unhelpful, or if you believe there might be a bug, please leave a comment on this issue. All feedback will be used to further improve it. Thank you for your time.

github-actions[bot] avatar Aug 13 '21 07:08 github-actions[bot]

Update 8/14/2021

  1. Progress: Completed #1352. Created issue #2061, #2104.
  2. Blockers: No difficulties encountered.
  3. Availability: Sunday afternoon, Tuesday evening, Thursday evening.
  4. ETA: 4 weeks
  5. Pictures: N/A

abuna1985 avatar Aug 15 '21 00:08 abuna1985

@abuna1985

Please add update using this template (even if you have a pull request)

  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) 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, August 17, 2021 at 12:02 AM PST.

github-actions[bot] avatar Aug 20 '21 07:08 github-actions[bot]

@abuna1985

Please add update using this template (even if you have a pull request)

  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) 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, August 24, 2021 at 12:03 AM PST.

github-actions[bot] avatar Aug 27 '21 07:08 github-actions[bot]

@abuna1985

Please add update using this template (even if you have a pull request)

  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) 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, August 31, 2021 at 12:02 AM PST.

github-actions[bot] avatar Sep 03 '21 07:09 github-actions[bot]

  1. Updated/Created #2112, #2113, #2198, #2199, #2200, #2204, #2205 to standardize the color variables within the site. Updated issues within the initial comment.
  2. Life
  3. Should be able to focus on this Monday afternoon/evening and Tuesday/Thursday evening.
  4. We should have all the relevant issues ready in the next 2 weeks. The implementation may take a month or 2.

abuna1985 avatar Sep 05 '21 15:09 abuna1985

@abuna1985 did you use the label collaborative work because this issue is an epic? Or because you did this issue with another person

ExperimentsInHonesty avatar Sep 08 '21 19:09 ExperimentsInHonesty

Because it is an epic. Should I remove the tag? And should I create a separate Epic label @ExperimentsInHonesty ?

abuna1985 avatar Sep 10 '21 06:09 abuna1985

@abuna1985

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) 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, September 14, 2021 at 12:02 AM PST.

github-actions[bot] avatar Sep 17 '21 07:09 github-actions[bot]

@abuna1985 this issue is pinned to the issues homepage Did you pin it or someone else?

ExperimentsInHonesty avatar Sep 19 '21 00:09 ExperimentsInHonesty

@ExperimentsInHonesty I did pin it. I thought pinning an issue was individual, not for the whole group. My apologies.

abuna1985 avatar Sep 19 '21 07:09 abuna1985

Progress

  1. Moved some PR for issues within here to completion. No new issues were created.
  2. Time
  3. Should have some time Tuesday to update issues and determine remaining focuses
  4. ETA: TBD

abuna1985 avatar Sep 19 '21 07:09 abuna1985

@abuna1985

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) 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, September 21, 2021 at 12:02 AM PST.

github-actions[bot] avatar Sep 24 '21 07:09 github-actions[bot]

@abuna1985

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, September 28, 2021 at 12:02 AM PST.

github-actions[bot] avatar Oct 01 '21 07:10 github-actions[bot]