Improve expand box ("accordion") visibility

[plumbis]

Spinning out of #473-

expand shortcode blocks are easy to miss The expand shortcode is used to hide blocks of text by default. However, in practice these blocks are really easy to miss when reading or scanning a doc, so I think the content hidden by them very rarely gets viewed.

A specific case where this hurts is when a search result is hidden in one of these blocks. e.g. searching the docs for EnvironmentConfig yields one page result that takes you to docs.crossplane.io/latest/software/install. If you then use your browser to "find on page", you get 0 results. EnvironmentConfig looks to not actually be on that page at all, but it's actually hidden underneath the "feature flags" expand block.

Can the expand blocks be made more visually noticeable?

[plumbis]

In dark mode the boxes are white on black so I don't think we need to address them there (feedback welcome)

[jbw976]

Dark mode is my default and I still miss these boxes all the time. Yes, they are very visually noticeable in the sense that I can see the white box on the page, but discovering that it has content inside of it and I can/should expand it to see the content is something I constantly miss.

So at least in dark mode, the problem doesn't seem to be that the boxes themselves are not visible - we just don't see that we're supposed to do anything with them.

Perhaps there's a way to make the expanding action more noticeable? the expander icon is far away on the right from the text, so maybe it's harder to notice because of that?

What else could be done to make it obvious that you can take action on this box to expand it? can they be auto expanded when search results are contained within them? 🤔

[plumbis]

@jbw976 noticed today they are easier to read when they are inside a callout/hint box.

Need to investigate if we can move all expands into hint boxes or just restyle.

[jbw976]

I continue running into this problem of it being hard to notice the expand accordion boxes and at least one other community member does too 😂 https://github.com/crossplane/crossplane/discussions/5271#discussioncomment-8203393

[plumbis]

(direct link for reference)

I'm open to ideas on how to improve, but I'm not sure I have any. Do you have any examples of sites (even if they aren't docs) that do this well?

I'm reluctant to remove the collapsable feature since it just moves the problem around (e.g., "oh, i didn't see the link to the external reference") or dilutes the content (i.e., adds a ton of noise)

[jeanduplessis]

I'm currently at a loss on a quick tweak to improve the component to stand out visually without being a distraction.

Maybe with a slight background color change: Before: After:

I would also make the argument we should have these content areas expanded by default. With the content collapsed, it's not searchable by the native browser find/search (Cmd+F) functionality. If I'm on a page an looking for a specific keyword that's in a collapsed accordion, then I might not be able to find it easily.

[jeanduplessis]

I managed to chat with my former colleague, @quinnkeast, on this topic, and he kindly shared some thoughts that could help resolve this challenge. Below are Quinn's thoughts.

---

• Generally speaking, accordions are a good pattern for complex content because they support progressive disclosure. Docs pages are quite often inherently content-heavy. Sections like "All Crossplane customization options" would be overwhelming if expanded by default, and is exactly the kind of content that should be collapsed by default.
  • Since this is a systematic pattern, it feels to me like it's a generally all-or-nothing thing: all accordions are always collapsed or always expanded by default. And since the goal of the accordions is to progressively disclose content when appropriate, like the above, I think it should be collapsed by default.
• When designing for mostly text-based content, hierarchy is everything. Part of what makes it hard to identify the accordions while scanning is that the nature of the design right now elevates several different, non-interactive elements to roughly the same level of hierarchy: the tips, the warnings, and the code blocks. Then, the accordion toggles are a level below all of these in the hierarchy.
  • This can't be solved by adding backgrounds or similar: that would simply elevate it to the same level of hierarchy as all the other blocks.
  • Instead, the design solution here is probably to make it much more clear that it is a separate, interactive element. Specific things I'd do here include making it the link colour and underlined, move the caret to the beginning of the line (it isn't useful as an affordance at the end), and show the caret as "collapsed" to start.
  • Bonus would be to improve how spacing is handled between elements, so it's literally set apart from the content that follows.
  • Here's a quick semi-interactive example of how I might propose redesigning the accordions: https://www.figma.com/proto/VFGorerSqEjXRwMVrg2diC/Untitled?page-id=0%3A1&type=desi[…]i-1&scaling=min-zoom&starting-point-node-id=1%3A16&mode=design
  • This turns into a bit of a rabbit trail of other improvements—refining the overall hierarchy of things like tips and headings.
• If the goal of these accordions is purely progressive disclosure, that in turn suggests it should be used sparingly and consistently.
  • Only use it for content that's complex, extensive, or potentially overwhelming (align to the user's goals at a given page). If it doesn't align with the idea of progressive disclosure, use other techniques for setting it apart or giving it a lower level of hierarchy.
  • Only include it at the end of a section of content, when possible.
• Finally: it does seem like there may be a path to enable searching within accordions and auto-expanding them... here's an example: https://github.com/alphagov/govuk-frontend/issues/2697

However, in practice these blocks are really easy to miss when reading or scanning a doc, so I think the content hidden by them very rarely gets viewed.

If it's a goal for the content to be viewed, then the content should not be in an accordion. I would anticipate very infrequent viewing and wouldn't consider views alone to be a performance metric for this. Instead, I'd want to see if someone can find an answer that's found within an accordion when they're explicitly looking for that answer. E.g. ask a user to answer a question that requires viewing an accordion's content to answer it, but don't mention anything about the accordions. If the page and content is designed properly, then they should be able to drill in without thinking consciously about it. This would be an example of a page where perhaps both the content and visual design could be improved at the beginning.