Component: Resources

[jeffmaher]

Stories

• As a reader of a guide, I want links to other relevant resources so that I can learn more about the topic at hand.

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
• [x] 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 right now:

I'm assuming I can programmatically set the icon based on the URL's extension and domain. That is: a doc icon for a Google Doc, a PDF icon for PDFs, etc. I've never done that in 11ty before, so I might need some help (or, worst-case-scenario, we could just use the same icon for every public link.)

The lock icon is meant to indicate an invite-only doc. I'm assuming it's impossible to programmatically detect whether a GDoc is private, so authors will need to manually specify private links.

Assumptions I'm making

These buttons are so big because I'm assuming:

• Document titles will be, at most, ~60 characters long
• This section will contain 6-8 links at most

If that's not true, I'd want to make this component more visually lightweight.

I'm also assuming that:

• Many links in this section will be private (since this is true for the majority of discovery playbook links)

Development Status

This is basically a nicely styled <ul>. I've committed an example to the storybook branch, and can open a draft PR with just this component once #5 and #6 are done.

Component API

This is a tricky one, given that each resource has multiple properties.

Here's what I have running in my local 11ty instance, which I'm not happy with:

{{ resources.render({
  headline: "Examples of Bloom research plans",
  links: [
    {
      title: "Link One",
      url: "https://bloomworks.digital",
      private: true
    },
    {
      title: "Link Two",
      url: "https://18f.gsa.gov"
    },
  ]
})}}

I just realized I can use pseudo-elements to add the icon, so in the coming days I will try to simplify it to something that uses pure Markdown, like this:

{% set resourceList %}
- [Link One](https://bloomworks.digital)
- [Link Two](https://18f.gsa.gov)
{% endset %}

{% resources links=resourceList %}

@jeffmaher @SMakaiTakori Let me know if you have any comments or questions!

[jeffmaher]

@SMakaiTakori to take a peak today/tomorrow, @jeffmaher can review tomorrow too.

[jrubenoff]

A component API update

I remembered that 11ty has paired shortcodes. So I've gotten this markup working locally:

{% resourceGroup %}
  {% publicResource "Bloom Works Homepage", "https://bloomworks.digital/" %}
  {% publicResource "18F Guides", "https://18f.gsa.gov/guides/" %}
  {% privateResource "Private Google Doc", "https://docs.google.com" %}
{% endresourceGroup %}

That code outputs the following:

Seems straightforward IMO. But please feel free to suggest any ways to make it simpler for non-engineers! (cc: @admoorgit)

[SMakaiTakori]

A component API update

I remembered that 11ty has paired shortcodes. So I've gotten this markup working locally. Seems straightforward IMO. But please feel free to suggest any ways to make it simpler for non-engineers! (cc: @admoorgit)

@jrubenoff Thanks for including the link to the paired shortcodes documentation, that was very helpful! I haven't used these shortcodes before but it does seem pretty intuitive to me.

The resulting design looks good to me. Although, I wonder if we would need to include some kind of key if we are marking some guides as private ? Just using the image shouldn't cause confusion but it might for some, thoughts on this @admoorgit ?

[admoorgit]

I like these! Only potential issue is if someone has a load of resources, it could get a lil beefy.

• Let's shrink the icons by about 35-50% so there's more space for content.
• Ideally we'd have consistent heights across rows, and consistent widths regardless of content. So 50%ish each w/ padding, which looks good
• Would LOVE to able to group by doc type — so all private are in a group, all PDF, etc. Don't need to have headers necessarily, just be in order
• OK to change color of private docs only to black or gray, and all links that are accessible by all as green
• Re: key @SMakaiTakori I think color change and a more substantive lock icon could work to differentiate without the need for a key, and I'd almost be temped to add [Bloom Works staff only] or something similar at the end of the text link. Thoughts?

[jrubenoff]

@admoorgit Here's a revision:

Re: this comment:

Would LOVE to able to group by doc type — so all private are in a group, all PDF, etc.

I thought about that but I'm not sure that's the best presentation for the content. Two examples:

• On page 20 of the playbook, if you kept public and private documents separate, the "Child Welfare DCYF compensation trigger process" and "Child Welfare DCYF compensation process" docs would be visually separated from each other.
• If there are a lot of resources in one section, and the reader's trying to find a specific doc, scanning an alphabetical list seems easier than trying to remember its file type or privacy status.

Let me know what you think!

[SMakaiTakori]

• OK to change color of private docs only to black or gray, and all links that are accessible by all as green
• Re: key @SMakaiTakori I think color change and a more substantive lock icon could work to differentiate without the need for a key, and I'd almost be temped to add [Bloom Works staff only] or something similar at the end of the text link. Thoughts?

@admoorgit I think having a darker color for the private docs is a great idea. I'm not crazy about adding more words to the title to specify it's only for staff since there doesn't seem to be a lot of room if the titles end up being long. Maybe if the [Bloom Works staff only] text is in a much smaller font, we could add that without it feeling too crowded 🤔.

I feel like the color change, along with the lock icon should be enough to let users know it is different and private, screen readers will be able to pick it up from the image alt as well.

I'm assuming the functionality for the private doc button is that the user clicks on this and they have to log in, in order to access it? @jeffmaher

[jeffmaher]

@jeffmaher and @admoorgit to review. @jrubenoff to submit a PR in the meantime.

[jrubenoff]

Update from a Zoom call: @admoorgit is good with this design. I'll open a PR soon.