Component: Checklist

[jeffmaher]

Stories

• As a reader of a guide, I want to checklists so that I can concisely and easily see items that I should add to my or my team's to do list when using guidance from a guide.

Notes

• See the component doc for more information
• This ticket covers both design and development tasks. Change assignee of the ticket based on who has the next action, and remove the person or people that no longer have an action. It's expected that a ticket will get passed back and forth a few times.

Done When

• [ ] UX: Component design is drafted and shared for review
• [ ] Dev: Component design is reviewed and approved
• [ ] Peer UX: Compontent design is reviewed and approved
• [ ] Dev: Component style and markup is developed and shared for PR review
• [ ] Dev: Documentation on how to use component is drafted
• [ ] UX: Component style and markup is reviewed and approved
• [ ] Peer Dev: Component style and markup is reviewed and approved
• [ ] Component is available for use

[jrubenoff]

Assumptions

As per our GDoc discussion, I'm assuming this is not an interactive checklist. So, we don't need to let readers check or uncheck each item.

Design

Here's what I have right now:

After converting the guide to Markdown, I noticed the Key Questions sections looked weird and unstyled next to the checklist component. So I created a new Key Questions component... it's the same, except with a different icon and background color.

@SMakaiTakori I've kept these two components separate, even though they're so similar. That's because I think authors benefit from really clear guidance on when to use specific components. But if you want to use this pattern for other types of content later on, we could combine the two into a single "Fancy List" component (or something similar.)

Component API

How might we create a single source of truth for this component while keeping it easy for non-engineers to edit? Here are 2 options I can think of.

(Both examples use Nunjucks. I'm assuming we'll have a "playground" of example components that authors can copy and paste from, so they won't need to remember specific markup patterns.)

Option 1

Use separate partials for the beginning and end of the list, like so:

{{ checklist-start }}
- Item One
- Item Two
- Item Three
{{ checklist-end }}

This seems really simple for authors. But a single component spread across multiple partials is more annoying to maintain.

Option 2

{% set checklistContent %}
- Item One
- Item Two
- Item Three
{% endset %}

{{ checklist items=checklistContent }}

This seems neater from a dev perspective. But if there are multiple checklists on a page, the authors will need to remember to replace checklistContent with a unique variable name. That seems annoying

@jeffmaher @SMakaiTakori Let me know what sounds best here.

Status

I've committed an example to the storybook branch. I've also created a Nunjucks template locally in an 11ty instance (although we still need to decide upon the component API above.)

I can open a PR with just these components once #5 and #6 are done.

[SMakaiTakori]

I've kept these two components separate, even though they're so similar. That's because I think authors benefit from really >clear guidance on when to use specific components. But if you want to use this pattern for other types of content later on, we >could combine the two into a single "Fancy List" component (or something similar.)

@jrubenoff It does sound beneficial to keep both components, I like this idea! The checklists look nice and clean.

Regarding the Component API, I am leaning more towards making this as user friendly as possible for authors with option 1. If we go with option 2, we would have to have the guidance written somewhere for replacing the variable and that seems like it could be a lot for a non dev.

What do you think @jeffmaher ?

[jeffmaher]

+1 to what @SMakaiTakori said.

[jeffmaher]

Review from @admoorgit needed on this one, and then a review @LynnHerrick9

[admoorgit]

@jeffmaher these look good to me. Off to @LynnHerrick9 for review!

[LynnHerrick9]

@jeffmaher I have finished review and approved

[SMakaiTakori]

@SMakaiTakori to handle merge conflicts