secondaryBackground

SecondaryBackground is a design and development term used to describe a secondary background color chosen to fill surfaces that are not the main page canvas. It helps create visual hierarchy and depth by distinguishing elements such as cards, panels, drawers, tooltips, and modal backdrops from the primary background while maintaining overall color harmony. In design systems, secondaryBackground is typically implemented as a color token that differs from the primary background in hue, brightness, or saturation, and may also use subtle transparency to achieve layered effects.

Usage and purpose

SecondaryBackground supports readability and organization by providing a distinct but cohesive surface for content. It is commonly applied to UI surfaces that sit above the core background but should not compete with foreground text and controls. When used consistently, it helps users infer elevation and grouping, improving the navigation and comprehension of complex interfaces.

Implementation considerations

In code and design tokens, secondaryBackground is defined as a named color value. Common implementations include CSS variables (for example, background-color: var(--secondary-background)) or token files in JSON or YAML (for example, "secondaryBackground": "#f0f2f5"). Designers often select values with lower saturation or moderate transparency to keep surfaces visually light while preserving contrast with nearby text.

Guidelines

Ensure sufficient contrast between text or icons placed on secondaryBackground and the surface itself, especially in different themes or lighting conditions. Maintain consistency with the brand palette and with the primary background. Consider accessibility and test in light and dark modes to avoid readability issues. Related concepts include primaryBackground, surface, and elevation in a design system.