Component: Callout

[jeffmaher]

Stories

• As a reader of a guide, I want to easily see important information so that I make sure to read what is most important.

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]

From the GDoc:

This component styles the playbook’s “lightbulb” sections, but it’s extensible to any paragraph we want to give special emphasis.

Assumptions I'm making

• We want to let authors swap out the lightbulb icon in this component for something else, depending on the context.

Visual design

Here's what I have:

Markup

At first, I thought an <aside> might be appropriate here. But the lightbulb sections seem like they're directly related to the main content: you can't pull them out without losing important context. So I'm just using a <section> tag instead.

For screen readers, I added a visually hidden <h3> to distinguish this component from the main content. Alternatively, we could add a title attribute to the icon SVG.

Component API

How might we make this component easy for non-engineers to edit?

Letting authors swap out icons raises some questions here. Where will the icons come from?

Idea 1

I've been using Bootstrap Icons for this project thus far. We could:

• Import the bootstrap-icons NPM package into the guides repo
• Write in our documentation that authors can search the Bootstrap Icons site for the symbol they'd like to use
• Let them reference the icon like so:

{% callout "This is the content of my callout.", "box2-heart" %}

Idea 2

We could simplify things by:

• Choosing 3-5 icons we might want to use with callouts
• Adding them to our /assets/ folder
• Mentioning the icon choices in our documentation

Idea 3

We could move icon customization out of scope.

@jeffmaher @SMakaiTakori Let me know what you think!

[jrubenoff]

Forgot to mention the status of this on my end:

I've committed an example of a Callout 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.

[jeffmaher]

Awaiting review from assignees ( @SMakaiTakori , @jeffmaher )

[SMakaiTakori]

For screen readers, I added a visually hidden <h3> to distinguish this component from the main content. Alternatively, we could add a title attribute to the icon SVG.

@jrubenoff If we can, I would prefer to add a title attribute directly to each SVG rather than the hidden <h3> just to keep with common accessibility practices.

[SMakaiTakori]

Component API

How might we make this component easy for non-engineers to edit? Letting authors swap out icons raises some questions here. Where will the icons come from?

Idea 2

We could simplify things by:

• Choosing 3-5 icons we might want to use with callouts
• Adding them to our /assets/ folder
• Mentioning the icon choices in our documentation

@jrubenoff Great ideas! I think we should go with Idea 2. I feel like it would be simpler to store some icon images so that authors can have choices. This will keep it simple for authors while also making it easier to add or swap out images in the future if needed. Thoughts @jeffmaher ?

[jeffmaher]

Question for @jrubenoff and @SMakaiTakori : Would would it look like for a document author to add this into a Markdown file? Would it be the Nunjucks component or some other markup?

[jeffmaher]

@LynnHerrick9 to handle merge conflicts, then done!

[SMakaiTakori]

@SMakaiTakori will handle these conflicts.