Figma plugin

Neighborhood for Figma brings the current release into a Figma file: its tokens become variables and styles, and its components become Figma components built on those variables. Each file picks the brands and features it needs.

It’s a one-way pull. The code and Storybook stay the source of truth, and nothing you make or change in Figma goes back to them. Re-run the plugin to pick up a new release.

The plugin is in beta. A small group of beta testers is trying it first, and it may change based on what they find. Ask to join the beta.

What lands in Figma

Variables use the same names as the tokens, and each one’s code syntax is its --nbhd-* custom property, so a spec written from Figma uses the names developers build with.

The components available are Button, Link, Input, Textarea, Select, Checkbox, Radio, Card, Text, Badge, List, Pagination, Headline Content, Hero Split, Jumbotron, Minitron, Humongotron, Navbar and Product Card. They share a Media Placeholder for their images and logos (see Add media); it isn’t a coded component.

Run the plugin

During the beta, the plugin is shared with a small group of beta testers. Once you’ve been added, there’s no password or anything else to enter.

1. In Figma, run Plugins → Neighborhood for Figma.
2. Version: the plugin loads the latest release and shows its version, such as Neighborhood v5.0.0. There’s nothing to change here. If a release comes out while the plugin is open, select Check for updates. Developer options are for the design system team.
3. Choose what to apply:
   • Brands: each becomes a mode on the Semantic and Component collections. The first time you run the plugin in a file, no brand is selected: choose the brands the file uses (at least one) before you can preview. Each selected brand gets its own pages (see What lands in Figma). The brand marked Default is the one the Component Library shows: the first selected brand in the list, reading left to right, not the first you clicked. Brands marked In file are already in this file.
   • Also remove brands from this file: only shown when the file has brands you haven’t selected, and it names them. It’s off unless you tick it. It deletes those brands’ modes and their generated pages, and each removal is listed in the preview for you to confirm. It only affects collections the plugin created.
   • Components: folded into one line that says how many are selected, with All and Clear. Expand it to choose components one by one, or tick a category heading, such as Actions or Forms, to select or clear that category. Anything your choice depends on stays ticked and is labelled required: for example, Card brings Button. After Clear, the count says how many are still required by other choices.
   • Advanced: variable collections, text and effect styles, and the docs pages. Everything is included unless you change it, and the line says what’s left out. A component still brings the variables and styles it uses.
   • The file remembers its selection for next time.
4. Preview changes: Preview and Apply are at the bottom of the plugin, and stay there as you scroll. Select Preview changes to see, under Review, what will be created, updated or taken over, for example “12 to create, 4 to update.” Nothing changes yet.
5. Apply. The button says how many changes it will make, such as Apply 16 changes. If the file already has something with the same name that the plugin didn’t create, it’s marked exists, not created by the plugin, and you tick a box under Review to take it over. Removals are confirmed the same way. While a button is disabled, the line beside it says why, such as “Choose at least one brand” or “Preview your changes first.” While it runs, the plugin counts through the components.
6. See what changed. The canvas goes to the first selected brand’s Foundations page (or, without one, to the components that were built), and the plugin says which page it’s showing. A Figma notification says what the apply changed: brands added or removed, components created, rebuilt or repaired, and pages regenerated. Select View to go back there. If the plugin left notes, the notification says so and View log opens them. The plugin lists the same changes, each with a Show link.

The file keeps a record of the last apply. With nothing selected, the right sidebar shows a Neighborhood for Figma button with the release, the date, the brands and who applied it; select it to reopen the plugin. The generated pages show the same details at the top.

View a brand or an inverse surface

• A brand’s components: open its <Brand> - Components page. Edit the main components on the Component Library page, not the instances on a brand page: the brand pages are regenerated. Colors, fonts, sizes and spacing follow the brand. Text case and line height can’t be variables in Figma, so they stay as built for the first brand in the brand list.
• A brand anywhere else: select a frame and set its Semantic and Component modes in the right sidebar.
• An inverse surface: set the frame’s Context mode to Inverse. The Surface=inverse variants of Card and the sections already do this.

Add media

Every image and logo in a component is a Media Placeholder: a gray frame with an image icon and a “Media” or “Logo” label, the same in every brand. In an instance of the component, either:

• put an image fill on the placeholder, or
• use the component’s Media property (Logo on Jumbotron and Navbar) to swap in your own component.

Then turn off Show hint, which appears on the component’s instance, to hide the icon and label. Both are kept when the plugin updates the file.

Files applied before the placeholders were added had plain gray rectangles there. The first update replaces them, so an image fill already put on one of those rectangles in an instance is reset; the preview lists the components this affects.

Update a file

Run the plugin again in the same file. It updates what’s there instead of making copies, and starts from the selection you used last time. Select Preview changes first to see what changed in the release.

Token changes reach Figma without a plugin update: the plugin always loads the current release.

What’s safe to change

• The plugin only changes variables, styles, components and pages it created, or ones you confirmed in the preview.
• Nothing you made is deleted. Tokens removed from a release, and brands or features you drop from your selection, stay in the file.
• Components are rebuilt in place, so instances and their overrides keep working. Layers and properties you add to an applied component are kept.
• A rebuild clears brand or surface modes set by hand on layers inside a component’s main definition, so the component always takes its brand from where it’s placed. Modes on instances in your designs are yours and are kept.
• You can move an applied component set to another page. The plugin finds it there and keeps updating it.
• Brand modes and brand pages are only removed when you tick Also remove brands from this file and confirm each removal.
• Frames on the brand pages that the plugin made are replaced when the release or your selection changes. Anything else you put on those pages is left alone.

Limitations

• Screen sizes: components and text styles use the base, small-screen values. Breakpoint values exist as variables but aren’t applied, except that full-width sections are built at 1440 with their large-screen values.
• Line height is a fixed percentage on each text style, not a bound variable.
• Button has no focus ring or icon-only version. Input is a fixed 320 wide, and has no read-only or required state.
• Some components aren’t in Figma yet. Check the component pages and Storybook for everything else, and for how each component behaves.

If something in Figma doesn’t match the component in Storybook, Storybook is right. Report it with both.

If it won’t connect

Check that you’re online, then select Check for updates. If it still won’t load, ask for help.

Next steps

• Designing with Neighborhood: design from the coded components and write specs in Neighborhood terms.
• Working with tokens: how token names are built.
• Storybook: the live components, on any brand.
• Requests and support: join the beta or report a problem with the plugin.