How to write a Component Request

This explains how to write a component request in GitHub so that a programmer can build that component to spec.

1. Design Read In

Step 1 is to go through every page with the designer of the project. Write design notes in README.md or DESIGN_NOTES.ms file. I normally have headings like this.

    ## Design Notes
    
    ### Global
    // Notes for things like menu, footer etc._
    
    ### Home
    
    ### About
    
    ### Contact
    
    ### Mobile

Some things to look for and ask the designer for during the read in:

• Hover states?
• Any special animations?
• Any z-index thing to be aware of?
• Anything isn’t obvious (custom cursors for example)?
• Long text edge cases
• Consistency of breadcrumbs
• What we need from design team to proceed? SVGs?
• How many fonts, and have they been purchased?
• Mobile/Tablet edges cases? Big wide screen?
• Any mix blend modes being used?
• Page Transitions?

2. Component request drafts

Then I write a list of components needed, along with their props in the COMPONENTS.md file. This is a draft of the more detailed component requests written later. It’s supposed to help you figure out everything you need and any overlaps in components.

Generally this file looks like this.

# Components 

    - [ ] site-logo
    
    - [ ] block-work
      - image
      - title
      - to
    
    - [ ] panel-menu
      - name
      - isOpened
      - slot: used with a site-breadcrumb
    
    - [ ] progress-bar
      - event: `is-complete` on complete

When writing out these component drafts, some questions to consider:

• Naming the component read:
  • https://twitter.com/MaOberlehner/status/1309463090434641921
  • https://vuejs.org/v2/style-guide/#Order-of-words-in-component-names-strongly-recommended
• Is this component used in more than one place?
  • If it is then make it a component. Otherwise perhaps it’s just code at the Page level? If in doubt, make it a component.
• What props should it have? If it’s an array of things, I generally call that prop items as a convention.

3. Component Request in Github

Once you’ve got the CR drafts done, you can start writing them in detail as a GitHub issue. See example here.

Some questions to consider and answer for each component:

• Where is it used. Explain for context.
• Is the screenshot showing anything that could be confusing? Try to keep them as simple and obvious as possible.
• Link to design prototype or any animation examples.
• Developer notes
  • Include detail on how you’d like the component built.
  • Do you think it should use flexbox or grid? Anything special? I try to think how I’d build it, and explain some thinking around that. Perhaps even give a code example of the hardest part.
  • What type of element should it be? <nav>, <div> ?
  • What CSS vars (like gap or color) to use?
• Does this component need to support any slots? If so, what is the expected use for the slot?
• Are there any child components that are required to be used? A common one is <nuxt-link> but you might have some custom ones needed, like a search box or block used in a grid component.
• Use GitHub labels for “easy”, “medium” or “hard” depending on how much effort it would take for the average dev on your team to build. This helps people pick components they have time to tackle.

The repo has a GitHub Issue Template included which will prompt you for the above points too.