Designing with Neighborhood

Neighborhood is a code-first design system. There’s no Figma library: the components in Storybook and the values in these docs are the source of truth. What you see in Storybook is exactly what ships to a brand site.

That makes designing with Neighborhood mostly about working with what exists: choosing components, setting them up, and describing your design in the terms the system already uses.

Start from what exists

• Browse the components. Components lists everything available, and Component Status shows what’s ready for production.
• Try them in Storybook. Pick your brand in the toolbar, change the Content controls to your own copy, and switch the viewport to check each screen size. Storybook shows the real component, not a picture of it.
• Share what you see. The Storybook address keeps the story, brand and controls you set, so you can send a link instead of a screenshot.

Use the system’s values

• Colors, type and spacing come from Foundations and each brand page. Pick from those rather than eyeballing values.
• Name tokens, not values. Write “space 6” or “content primary” in a spec. Values differ between brands; token names don’t. Working with tokens explains how they’re named.
• Choose surfaces, not background colors. Each section sits on a surface such as Primary, Secondary or Inverse, and its text colors follow automatically. See Surfaces and color.
• Design for the breakpoints. Neighborhood’s layouts change at set widths, from XS (mobile) to XXL (desktop). Breakpoints lists them, and Storybook’s viewport menu previews each one.

Write specs in Neighborhood terms

A spec that uses component, setting and slot names can be built directly, without translation. For each section, give:

• The component and any settings, such as its variant and surface.
• The content for each slot: eyebrow, title, subtitle, body copy, call to action and media.
• Anything new, marked clearly as not yet in Neighborhood.

For example:

Section 2: Headline Content
  Surface: Inverse
  Eyebrow: New collection
  Title (h2): Faucets made for everyday
  Content: Find the finish and style that fit your kitchen.
  CTA: Shop faucets → /faucets

Content model lists the slots and settings for every component.

When something’s missing

Work through these in order:

1. Combine existing components. Many layouts can be built from Container, Flex, Text and the section components.
2. Ask for a change when a component is close but needs a new variant or setting.
3. Ask for a new component when nothing fits.

Requests and support explains what to include. A design that adds a pattern to Neighborhood, rather than one site, benefits every brand.

Check accessibility as you go

Neighborhood aims to meet WCAG 2.2 AA. The brand themes pair text and background colors that pass, so stay with surfaces and tokens where you can. Storybook’s Accessibility panel runs automated checks on each story. Accessibility covers what components handle and what your design still needs to get right, such as heading order and alt text.