Component: Grids

[jeffmaher]

Stories

• As a reader of a guide, I want to see grids so that I can get easy to understand summarizes of information.

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]

Visual design

Here's what I have thus far:

Usage

This layout is best suited for lists where each item:

• Contains a header and a brief paragraph of body text (500 characters or less.)
• Has consistent formatting.
• Would benefit from extra visual impact. (For example, cute icons next to "Forms of harassment" might not be appropriate given the context.)

Given the above, there are only a few places in our current guides where this layout makes sense:

Discovery playbook

• "Client roles" in Section 2.1
• The sprint team members in Section 2.2 (This section is incomplete.)

Employee Handbook

• Our core values
• Guiding principles

That list is a lot shorter than I thought it would be when I suggested this component!

Component API

Given the number of properties in each column, I'm not sure how simple we can make this component from an editor's perspective.

Perhaps we could have separate variables for the start and end of the grid container?

{% grid-start columns="3" %}
  {% grid-column "icon", "This is my headline", "This is some body text" %}
  {% grid-column "anotherIcon", "This is another headline", "This is more body text" %}
  {% grid-column "thirdIcon", "The final headline", "The last bit of body text" %}
{% grid-end %}

Or maybe editors could specify everything in YAML? Like so:

---
sampleGrid:
  - icon: icon
     headline: This is my headline
     body: This is some body text
  - icon: anotherIcon
     headline: This is another headline
     body: This is more body text
  - icon: thirdIcon
     headline: The final headline
     body: The last bit of body text
---

{% grid items=sampleGrid %}

Looks a little nicer, but using a language with significant white space could be a big source of user error.

(See the Component API section in this comment for some ideas on how to let editors freely switch between icons.)

Status

I've committed an example to the storybook branch, and I can open a draft PR if we want to keep talking about it. At the very least, it would be nice to have a different layout for Bloom's core values and guiding principles so they can really stand out.

Alternatively, we might want to avoid the hassle and move this component out of scope. I'll deprioritize this for now but will keep thinking about how to simplify the templating markup.

[jrubenoff]

A component API update

I realized 11ty has custom shortcodes and simplified this a bit.

I have this markup working locally:

{% Grid 3 %}
  {% GridColumn "hospital", "Phase 1: Procurement" %}
    Coordinating with donor hospitals to procure organs from deceased donor patients who meet clinical criteria for donation.
  {% endGridColumn %}
  {% GridColumn "person-rolodex", "Phase 2: Match & Recovery" %}
    Matching the procured organ(s) with a patient on the waiting list to receive that organ, and overseeing surgical recovery of the organ(s).
  {% endGridColumn %}
  {% GridColumn "car-front", "Phase 3: Transport & Transplant" %}
    Transporting the recovered organ to the transplant center in sufficient time so that it can be transplanted successfully.
  {% endGridColumn %}
{% endGrid %}

(The number up top, e.g. Grid 2 refers to the number of columns. You would write Grid 3 to produce a 3-column grid.)

The above markup produces the following:

@admoorgit I'll plan to open a PR for this once #20 is merged. Let me know if:

• This component makes sense to you (see the "Usage" section in my last comment for more context)
• The markup above seems too complicated for non-engineers

[jeffmaher]

@admoorgit to review the PR that is coming soon.

[jeffmaher]

Combining #16 into this one.

[admoorgit]

@jrubenoff walked through this yesterday and it looked good to me!