Progressive disclosure

These guidelines summarize how GitHub implements progressive disclosure—an interaction design pattern that hides/displays information. This article also contains information regarding guiding principles, best practices, and implementation support.

The following table outlines common progressive disclosure solutions in use at GitHub. For more in depth analysis and usage guidelines, please refer to Progressive Disclosure User Interface Patterns.

ComponentIconUsageNotes
ChevronchevronWhen elements of content are collapsed and can be toggled openDo not use this icon to trigger a dropdown menus or navigation; the Caret icon is the more suitable for this.
Expand/ Collapse IconexpandSignify that there is content (typically text) to be revealedShould generally stand alone, rather than being paired with text
Ellipses IconellipsesFor toggling truncated inline text contentDo not use this icon to trigger a dropdown menus or navigation; the Kebab icon is the more suitable for this.
Text-only TogglesUsage of this solution is discouraged, as generally icons or icon+text pairings provide better accessibility and more information
KebabkebabN/AFor toggling inline dropdowns and menus
CaretcaretN/ARefrain from using this icon as a progressive disclosure solution

Guiding Principles

Maintain Context for Users

When designing interfaces that incorporate progressive disclosure, refrain from creating interactions that drastically disorient the user’s initial point of focus.

Progressive Disclosure vs Navigation

It's important to understand the differentiation from progressive disclosure and navigation patterns, as the two share “cousin” elements that can be confusing when deciding which one to implement.

Please refer to these guidelines as they detail in-use solutions, and outline best practices for implementation. For more clarity, refer to the Support section of this article for more information.

Pair Icons with Text When Possible

Pair progressive disclosure icons with descriptive text to provide context.

Implement Only as Necessary

Progressive disclosures should be used sparingly, when it’s necessary to truncate information for the general layout/design.

Progressive Disclosure UI Patterns

Chevron Icon

The Chevron Icon is used when elements of content are collapsed and can be toggled open. Typically this icon is positioned vertically, and alternates between “up” and “down” states. This icon is quite flexible, and can stand alone, or be paired with text.

Chevron icon used to display more branches in mobile view

Do: utilize appropriate text in scenarios to provide clarity
Don't: use the chevron to trigger dropdowns

Caution:

  • The chevron should not be used as a call-to-action for drop down menus
  • It should not be used for pagination, or indicate directional actions

Fold/Unfold

This icon is used to signify that there is content that can be toggled open and closed. It is typically surrounded by text content above and below it. There are currently versions of this icon that expand the context in a singular direction, but are only used in GitHub’s code review editor.

Fold/Unfold Icon used in Profiles context

Do: Use this icon to show content expansion in the code editor
Don't: pair this icon with lengthy text

Caution:

  • This icon should generally be used to signify the expansion of text content
  • Generally this icon is not displayed with accompanying text

Ellipses Icon

The ellipses icon is used for toggling truncated inline text content. It’s primary purpose is to serve as a method that designers to use to curtail bodies of texts, but sometimes other types of information.

Do: use this icon to give users the option to toggle the amount of text being displayed
Don't: substitute a Kebab icon in the place of an ellipses

Caution:

  • While visually similar, the ellipses icon is different from the kebab icon, which is used for dropdown menus or general call-to-actions. Be careful not to confuse them for one another.
  • This icon generally stands alone within inline bodies of text.

Support

Iterate and Componentize

If or when certain progressive disclosure patterns in your design emerge, or you believe a certain solution should be made into a component, reach out to the #design-systems channel on Slack to find out more on submitting your code or idea. You may also reach out by opening an issue to the team the team directly on Github.

Requesting Feedback

Progressive Disclosure can be tricky to implement, and certain designs may test the bounds of our design guidelines in unique scenarios. If you have further questions or require clarity on implementation, please reach out to the #design-systems channel on Slack.

Edit this page on GitHub
1 contributorashygee
Last edited by ashygee on August 14, 2019