Version 1.1.0

Legend

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

Anatomy#


Image illustrating through labels the component parts of four different legends, a categorical color legend, a sequential color legend, a diverging color legend, and a size legend. Parts include the legend title, legend label, and scale. 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 four different legends, a categorical color legend, a sequential color legend, a diverging color legend, and a size legend. Parts include the legend title, legend label, and scale. 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 color maps 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 scatter plot that maps the size of the points to the time per visitor spent in seconds on each website page with a corresponding size legend to the right of the chart.

Size#

Size legends show how the size of chart components map to a continuous scale. Ordinal scales are naturally divided, while interval and ratio scales are smooth gradients.

Key example of a categorical color, sequential color, diverging color, and size 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.

Use size for measures that have weight, quantity, or size#

Size legends are best when they can be mapped to natural mental models. Avoid using a size legend for measures that don’t have a natural association with size.

Key example of a scatter plot that maps page name to unique visitors on the y-axis and time per visit in seconds on the x-axis. A size legend properly maps time per visitors in seconds to size.
Key example of a scatter plot that maps page name to unique visitors on the y-axis and time per visit in seconds on the x-axis. Bounce rate (percent) is used improperly with a size legend.

Size objects according to their area#

Map the values of an object to its area, not the diameter or radius. This aligns with how people naturally process visual displays of information.

Key example that shows two circles. One labeled 1 with a diameter of 100 pixels and one labeled 3 with a diameter of 173 pixels.
Key example that shows two circles. One labeled 1 with a diameter of 100 pixels and one labeled 3 with a diameter of 300 pixels.

Changelog#


DateNumberNotes
Apr 28, 20201.1.0
  • Added an option for size legends with related usage guidelines
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.

Design tokens

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

Generated UI kit

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

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.