Progressive disclosure
Progressive disclosures are a design pattern that hides and shows information based on user interaction. They should be used sparingly, only when it's necessary to truncate information.
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.
Pair icons with text
Pair progressive disclosure icons with descriptive text to provide context.
Progressive disclosure UI patterns
The following table outlines common progressive disclosure solutions in use at GitHub.
| Component | Icon | Usage | Notes |
|---|---|---|---|
| Chevron icon |  | When elements of content are collapsed and can be toggled open | Do not use this icon to trigger dropdown menus or navigation; the caret icon is the more suitable for this. |
| Fold/Unfold icon |  | Signify that there is content (typically text) to be revealed | Should generally stand alone, rather than being paired with text |
| Ellipsis icon |  | For toggling truncated inline text content | Do not use this icon to trigger dropdown menus or navigation; the Kebab icon is the more suitable for this. |
| Text-only toggles | Usage of this solution is discouraged, as generally icons or icon+text pairings provide better accessibility and more information | ||
| Kebab |  | N/A | For toggling inline dropdowns and menus |
| Caret |  | N/A | Refrain from using this icon as a progressive disclosure solution |
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 the “up” state when expanded and the “down” state when collapsed. This icon is quite flexible, and can stand alone, or be paired with text.
Chevron icon used to display more branches in mobile view
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 dropdown 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
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
Ellipsis icon
The ellipsis icon is used for toggling truncated inline text content. Its primary purpose is to serve as a method that designers to use to curtail bodies of texts, but sometimes other types of information.
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 ellipsis
Caution:
- While visually similar, the ellipsis 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 emerge in your design, or you believe a certain solution should be made into a component, reach out to the #primer channel on Slack to discuss how you can submit your code or idea. You may also reach out by opening an issue to the Design Systems team directly on GitHub.