Version 1.0.0

Legend

Legends (also known as keys) help users understand the relationship between data and its visual representation.

Three different legends. A categorical legend showing browser types, a sequential legend showing age, and a diverging legend showing sentiment. Three different legends. A categorical legend showing browser types, a sequential legend showing age, and a diverging legend showing sentiment.

Anatomy#


Image illustrating through labels the component parts of three different legends, a categorical legend, sequential legend, and diverging legend. Parts include the legend title, legend label, and color. Sequential and diverging legends can either have a smooth gradient called a color scale, or individually stepped color called a binned color scale. Image illustrating through labels the component parts of three different legends, a categorical legend, sequential legend, and diverging legend. Parts include the legend title, legend label, and color. Sequential and diverging legends can either have a smooth gradient called a color scale, or individually stepped color called a binned color scale.

Options#


Key example of a stacked bar chart with browser on the y-axis and visitors on the x-axis, and a three-color operating system categorical legend across the top.

Categorical color#

Categorical color legends make it clear as to which color maps to which item.

Key example of a stacked bar chart with browser on the y-axis and visitors on the x-axis, and a binned color scale sequential legend across the top for age.

Sequential color#

Sequential color legends show how colors map to a continuous scale. Ordinal scales are divided into specific pieces (bins), while interval and ratio scales are smooth gradients.

Key example of a diverging bar chart with browser on the y-axis, and a discrete color scale diverging legend across the top for sentiment.

Diverging color#

Diverging color legends show how colors map to a continuous scale that includes a meaningful midpoint. Ordinal scales are divided into specific pieces (bins), while interval and ratio scales are smooth gradients.

Key example of a categorical, sequential, and diverging legend, each shown in both horizontal and vertical orientations.

Orientation#

Legends can have horizontal or vertical orientation. Whenever possible, orient the legend to match the chart.

Behaviors#


Key example of a legend that doesn't have enough horizontal space to display all the items in one row, so two of the five items have been wrapped to a second line, each aligned with the item above it.

Wrapping#

When there isn’t enough space, wrap legends to ensure that dimension values are shown.

Key example of a legend that does not have enough horizontal space to display all the items in one row, so three of the five items have been aggregated into a single item titled "All others". Hovering on "All others" exposes a tooltip to display the list of aggregated values.

Overflow#

When dimension values are aggregated, a tooltip should display the list of values.

Key example of a legend that does not have enough horizontal space to display all the items in one row, each item has been truncated. Hovering on a truncated item exposes a tooltip with the full name.

Truncation#

Avoid truncating legends whenever possible. If truncation is necessary for your use case, use a tooltip to show the full name of the dimension value.

Usage guidelines#


Sort legends consistently#

Legends should be intuitive to understand. If a chart presents color in a certain order, its legend should mirror that order. In other use cases (e.g., a line chart), use another meaningful order, such as the last values or the average of all values.

Key example of a chart with the legend correctly sorted to match the color order in the chart.
Key example of a chart with the legend incorrectly sorted, the colors are not in the same order as the colors on the chart.

Be careful of distorting scales#

Legends help users understand how a variable is displayed on a chart, so they follow the same rule that a chart would: to be true to the data.

For example, if you break a ratio scale into categories to make it ordinal, and those categories are not equally sized, the legend should reflect that through more than just labels.

Key example of a legend that has correctly distorted the bin sizes in the legend to match the sizes of the bins.
Key example of a legend where the bins are varying sizes but the legend shows them incorrectly as the same size.

Changelog#


DateNumberNotes
Nov 08, 20191.0.0
  • This component has been added to the website

Design checklist#


N/A

All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

N/A

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.