Surfaces and color

Set a surface and components choose background, text and link colors that read well together.

A surface is the background a section sits on, together with the text and link colors that read well on it. Choose the surface, and the components inside it pick matching colors for you, on every brand.

The five surfaces

Surface	What it is	Use it for
`primary`	The brand’s main light background	The default for most sections
`secondary`	An alternate light background	Setting a section or card apart from the ones around it
`inverse`	The brand’s dark or high-emphasis background	Heroes, feature sections and footers
`inverse-secondary`	An alternate dark background	A dark section next to another dark section
`none`	No background of its own	Letting the surface behind the component show through

Each brand sets its own surface colors. On Moen, for example, secondary is Moen Light Blue and inverse is Deep Blue. Each brand page shows its surface colors.

Set a surface

Components that make up a section, such as Headline Content, Hero Split and Card, take a surface attribute:

<nbhd-headline-content surface="inverse">
  <nbhd-text slot="title" tag="h2" variant="title">Built to last</nbhd-text>
  <nbhd-cta slot="cta" href="/warranty">See the warranty</nbhd-cta>
</nbhd-headline-content>

Smaller components, such as Text, Link, CTA and Button, don’t take a surface. They use the colors of the nearest surface around them, so the title and call to action above switch to their inverse colors automatically.

To give several components one surface, wrap them in a Container:

<nbhd-container surface="inverse">
  <nbhd-text>Readable on the inverse surface.</nbhd-text>
  <nbhd-button variant="secondary">Find a store</nbhd-button>
</nbhd-container>

Nesting sections

Most section components default to surface="primary" and paint their own background. Put one inside an inverse Container and it shows a primary background, not the Container’s inverse one.

Set surface="none" on the inner component to let the outer surface show through:

<nbhd-container surface="inverse">
  <nbhd-headline-content surface="none">
    <nbhd-text slot="title" tag="h2" variant="title">Uses the Container's inverse surface</nbhd-text>
  </nbhd-headline-content>
</nbhd-container>

As a rule, set the surface on the outermost component of a section, and set surface="none" on section components inside it. Container, Flex and Search already default to none.

Some components with media, such as Jumbotron and Minitron, also have a content-surface attribute. It sets the surface of the content panel that sits over or beside the media, separately from the component’s own surface.

Your own content on a surface

When you style your own elements inside a surface, use the context color tokens. They change with the surface they sit on, the same way the components’ colors do:

.promo-note {
  color: var(--nbhd-context-color-text-secondary);
}

Token	Use it for
`--nbhd-context-color-text-primary`	Main text
`--nbhd-context-color-text-secondary`	Supporting text
`--nbhd-context-color-text-subtle`	Low-emphasis text, such as captions and metadata
`--nbhd-context-color-text-accent`	Text in the brand’s primary color, for emphasis

A fixed color, or a token such as --nbhd-color-text-primary that doesn’t change with the surface, can become unreadable on an inverse surface.

Designing with surfaces

Start with primary. Most sections need nothing else.
Alternate to separate. Switch between primary and secondary to separate sections that sit next to each other, instead of adding borders or rules.
Use inverse for emphasis. Save it for the sections that should stand out, such as a hero, a key message or the footer. A page that’s mostly inverse has nothing standing out.
Name the surface in specs. Write “Headline Content, surface Inverse” rather than a color value, so the design holds on every brand.

Contrast

Neighborhood aims to meet WCAG 2.2 AA. Each brand theme chooses its surface colors and the text colors that go with them to be used together, so staying with surfaces is the most reliable way to keep text readable.

When you add your own colors, check their contrast against the surface:

Body text: at least 4.5:1.
Large text (24px and up, or 18.66px and up in bold): at least 3:1.
Icons, borders of form fields and other interface elements: at least 3:1.

The color swatches in Colors and on each brand page show the contrast ratio for each color.