Component: Table of Contents

[jeffmaher]

Stories

• As a reader of a guide, I want to see what sections are in the guide so that know if the guide has the information I'm looking for.
• As a reader of a gude, I want to be able to navigate to different sections so that I can get to the information I want to read.

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

• [x] UX: Component design is drafted and shared for review
• [ ] Dev: Component design is reviewed and approved
• [x] 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 I'm making

• We're breaking up each guide into multiple pages. These guides are quite long, and it would be easy for the reader to lose their place if it were all on one page.
• Thus, this component is separate from #8. Site Navigation will let readers visit different sections of the guide, while the Table of Contents will help them navigate the current page.

Design constraints

The outline for a single guide section can be quite long:

Ideally we'd avoid a situation where the Table of Contents exceeds the height of the page content, since that doesn't look great. (This page on 18F is one example.)

We also want to prevent this component from taking up a lot of space on small screens.

Markup

This feels like a great opportunity to use a <details> / <summary> pattern. It lets us keep the screen real estate for this component small by default.

Design

Here is an initial visual design:

Default state

Expanded state

The plus icon rotates as the component expands.

Development Status

• I've committed this component to the storybook branch.
• I have this working locally in 11ty using the markdown-it-anchor and eleventy-plugin-nesting-toc plugins. I'll open a PR once #5 and #6 are finished.

Open questions

@admoorgit I really like having numbered sections in the employee handbook. (See the above screenshots.) But for the discovery playbook, it doesn't look great:

Maybe it's be a good idea to remove the section numbers for the discovery playbook? Let me know what you think.

[admoorgit]

@jrubenoff yes!

• The 1.1, 1.2, etc will be removed once we're done drafting the doc, since this new paradigm will replace it
• the green links on green BG doesn't hit minimum contrast requirements, so I'd consider a white bg for the expanded version
• I say this full well knowing the default BW green isn't 508c, so I'll give you a new hex to replace it with
• We may want to keep the font size on the smaller side (16-18 if it's not already) to minimize scrolling with longer lists — we can connect on specifics
• Suggest changing language to "In this chapter"

[jrubenoff]

@admoorgit Here's a version addressing all of the above. It has bold text, so it complies with AA Large:

Even with the extra padding, it still takes up less space than the previous design given the smaller font size. LMK what you think!

[admoorgit]

Howdy @jrubenoff ! Spoke with Jeff on Friday and here's where we landed:

• Let's take this out of the accordion and make it persistent. We shouldn't make people take an action (in this case, a click) in order to see what's on the page. It's ok if they need to scroll past, or they may see the section they want and click on it immediately, and it did its job!
• OK to leave in a call out box so it's distinct
• Shrink the numbers so you can tighten things up further.
• What is the hover state for the links? In the nav I said it's fine to remove the underline by default, but here it makes more sense
• Would it make sense to break this into 2 columns to save space on wide screens, or is that needlessly complicated? If we're concerned some of these chapters have a ton of sections, that could be a remedy. Not a request, but something to think about

Let me know if you have questions!

• a.

[jrubenoff]

Single-column layout:

Multi-column layout (collapses to one column on smaller screens:)

@admoorgit All your other feedback should be addressed in the above screenshots. Let me know which you prefer!

[jeffmaher]

@admoorgit to hop into today.

[admoorgit]

@jrubenoff I dig I dig! I prefer 2-column that collapses into single at smaller widths.

2 tweaks, and no need for me to review again unless you have a question:

• Please make the header background green w/ white text (what is currently: "What's in this chapter?") — this'll make it stand out a bit more and draw the eye better.
• Re: ^ — I talked with Corey (content) and we rec changing "Chapters" to "Sections", and changing that heading copy to "In this section". No need for colon.

This is looking really good! You rock!

• a.

[jeffmaher]

Waiting for review from @admoorgit and a merge conflict for @SMakaiTakori or @LynnHerrick9 .

[admoorgit]

Approved over here: https://github.com/bloom-works/guides-template/pull/34#pullrequestreview-1511585440

[SMakaiTakori]

I resolved the conflicts in this PR and it is now merged!