How it fits together
How tokens, brand themes and components combine into a brand site, and where each kind of change happens.
Neighborhood has four layers, and each builds on the one before it. Knowing which layer a change belongs in tells you who makes it and which sites it reaches.
The four layers
- Tokens are named values for color, type, spacing and the rest of the visual scale, such as
--nbhd-color-text-primaryor--nbhd-space-4. Working with tokens covers them in detail. - Brand themes give the tokens each brand’s values. The Moen theme sets the brand’s main color to Deep Blue and its fonts to Denim and Family; the Master Lock theme sets its own.
- Components are built entirely from tokens. They have no colors or fonts of their own, so they take on whichever brand theme the page loads.
- Your site loads one brand theme, places components on the page and fills them with its own content.
The result: the same component, with the same markup, looks like Moen on a Moen site and like Master Lock on a Master Lock site.
Where each change happens
| If you need to change… | It happens in | Made by | It reaches |
|---|---|---|---|
| A brand’s colors, fonts or spacing | The brand theme | Neighborhood | Every site on that brand |
| How a component looks or works | The component | Neighborhood | Every site that uses it, on every brand |
| A new kind of section or element | A new component | Neighborhood | Any site that adopts it |
| The content, layout or components on a page | Your site | Your project team | That site only |
Changes made in Neighborhood ship in a new package release, listed in the changelog. Each site picks up a release when its team updates the Neighborhood packages, so sites control when changes arrive.
What this means for you
- Designers design with existing components and token names. A spec that names “Headline Content on an Inverse surface” works on every brand, because the brand theme supplies the values.
- Developers don’t write brand CSS for components. You load the brand theme, use the components, and style only your own elements, with tokens.
- Product and content teams start new sites and pages from finished, tested components. Most of the work is choosing components and writing content, and improvements to a component arrive with the next update.
When a change you need belongs in Neighborhood rather than your site, Requests and support explains how to ask for it.