Content and media

Neighborhood components give content a consistent structure: an eyebrow, a title, supporting copy, a call to action and media. These guidelines help that content read well on every brand and every screen size, whichever platform it’s published from.

Writing for components

• Eyebrows are short labels above a title, such as a category or “New”. Keep them to a few words.
• Titles say the one thing a visitor should take away from the section. Lead with what matters to them.
• Subtitles add a second line of context. Leave them out when the title stands on its own.
• Body copy supports the title. Short paragraphs scan better, especially on mobile.
• Calls to action start with a verb and say where they lead: “Shop faucets”, “Find a store”, “See the warranty”. Avoid “Learn more” and “Click here”, which don’t make sense on their own.

Length

Neighborhood doesn’t cut text off. Long titles and copy wrap onto more lines and make the section taller, so a headline that fits on desktop can take several lines on a phone. The one exception is Badge, which can shorten long text with an ellipsis.

Preview your real copy in Storybook at the XS viewport before it goes live. Put it in the Content controls and check that it still reads well.

Headings

The Text component sets the heading level and the look separately:

• tag sets the level: h1 to h6, or p, span and div for other text.
• variant sets the look: eyebrow, title, subtitle, body or supporting.

<nbhd-text
  slot="title"
  tag="h1"
  variant="title"
  >Faucets made for everyday</nbhd-text
>
<nbhd-text
  slot="subtitle"
  tag="h2"
  variant="subtitle"
  >Six finishes, one easy install</nbhd-text
>

Choose the level from the page’s structure, not the size you want:

• Use one h1 per page, usually the title of the first section.
• Use h2 for the title of each section after that, and h3 for headings inside a section.
• Don’t skip levels. An h4 straight after an h2 confuses visitors using screen readers.
• Use div or p for eyebrows, which label a title rather than act as a heading.

Calls to action, buttons and links

Images

Alt text

Images are treated as decorative unless you give them alt text. For every image that carries meaning, write alt text that says what the image shows, in the context of the page:

• Describe what matters. “Matte black kitchen faucet with pull-down sprayer”, not “faucet” or “image of a faucet”.
• Don’t repeat the text around it. If the title already says it, the alt text can add detail or be shorter.
• Leave alt empty only for images that are purely decorative, such as a background texture.

Size and shape

• Card has an aspect-ratio setting: landscape (498 × 280px, the default), square (498 × 498px) or portrait (280 × 373px).
• Card List and Jumbotron list recommended image sizes for each breakpoint on their component pages.
• If your image isn’t already resized to fit, turn on the component’s cropping option, and use image-focus to choose which part of the image stays in view.

Loading and Widen

• Set loading="lazy" on images further down the page, so they load as the visitor scrolls. Keep the default, eager, for images visible when the page opens.
• For images hosted on Widen, set provider="widen". Neighborhood then requests the image at the size it’s shown, serves WebP where the browser supports it, and applies cropping from crop and image-focus. Without provider="widen", the image is used exactly as uploaded.

Video

• Sources: Video plays Widen, YouTube, Vimeo and MP4 videos, and detects which from the address.
• Describe it. Use alt to name the video; screen readers use it as the video’s label.
• Autoplay always plays muted, and shows a play/pause button. Use it only for short, silent loops. For anything a visitor should watch and hear, turn on controls instead, which turns autoplay off.
• A poster image, set with poster, shows before the video plays.
• Captions: MP4 videos can’t show captions. For video with speech, use YouTube or Vimeo with captions turned on, or provide a transcript. See Accessibility.

Rich text

Slots that hold body copy, such as content, accept regular HTML: paragraphs, lists, bold and links. Wrap it in a Text component:

<nbhd-text
  slot="content"
  tag="div">
  <p>Every faucet includes:</p>
  <ul>
    <li>A lifetime limited warranty</li>
    <li>Tools-free installation</li>
  </ul>
</nbhd-text>

Keep formatting simple. Headings inside body copy should follow the page’s heading order.

Changing built-in text

Some components come with their own English text: button labels such as “Next”, names that screen readers announce such as “Close dialog”, and messages such as “{count} results”. Each one is a property, so you can change it for a different language or a different tone. Most of your content goes in slots and needs nothing extra.

<nbhd-pagination
  total-pages="12"
  previous-label="Anterior"
  next-label="Siguiente"
  page-label="Página {page}"
  label="Paginación"></nbhd-pagination>

Where a default contains {count}, {page} or {index}, keep the placeholder in your text; the component replaces it with the number. Text the component shows on screen is marked visible; the rest is announced by screen readers only.

Set the page’s language with lang on the <html> element, such as <html lang="es">, so screen readers pronounce the text correctly.

On Pagination’s Previous and Next buttons and the Filters Reset and Done buttons, the screen reader name follows a changed visible label, unless you also set the matching -aria-label.

A few messages can’t be changed yet: Upload’s announcements and error messages about added, removed and rejected files, and Select’s message when the maximum number of options is chosen. Request a change if your site needs them in another language.