Brightspot styleguide

The Brightspot styleguide tool renders Brightspot CMS view data through Handlebars templates so front-end and theme developers can preview page and component markup without running the CMS. A project's styleguide directory holds Handlebars templates alongside JSON fixture files that stand in for real CMS view data; the tool resolves and substitutes that data, runs it through a Handlebars rendering pipeline with Brightspot-specific helpers, and serves or bundles the resulting HTML.

Key capabilities

• Renders JSON fixtures that stand in for Brightspot CMS view data through Handlebars templates, producing the same markup the CMS would produce for that view.
• Substitutes realistic placeholder data (text, dates, numbers, images) into fixtures so templates can be previewed without live content.
• Resolves configured image sizes and crops, including named crop overrides, so image markup matches production srcset/sizes output.
• Provides a Brightspot-specific set of Handlebars helpers for conditionals, math, list pagination, partial includes, nested view rendering, and internationalized message formatting.
• Runs a local development server for live preview, and a styleguide-bundle CLI that packages templates, generated data, and screenshots into a themed delivery zip.
• Injects an inspector overlay (togglable) that highlights which JSON field or template produced a given piece of rendered markup.

How it works

A styleguide project defines _config.json (styles, image sizes, navigation, theme variables) and, for each style, one or more Handlebars templates and example JSON fixtures. When a page is requested, either from the local development server or from the styleguide-bundle CLI, the tool loads the matching fixture, resolves _include and _template/_wrapper references between fixtures, substitutes placeholder data and resolved image attributes into the JSON, and compiles and renders the target template against that data using the Handlebars helper set. The rendered HTML is returned to the browser or, when bundling, written to a themed zip alongside the compiled front-end assets and optional Puppeteer screenshots.

Use cases

Previewing a template during front-end development

A theme developer building a new component template writes a JSON fixture with representative field values and a Handlebars template that renders it, then opens the local development server to see the rendered markup update as they edit the template. Fields left as placeholders (for example, {{words(3)}} in a fixture string) render with generated sample text so the layout can be reviewed without CMS content.

Packaging a theme for delivery

Once templates are ready, a developer runs styleguide-bundle with the project's root and build directories to produce a single zip containing the rendered styleguide UI, compiled assets, and (unless disabled) Puppeteer screenshots of every style and template combination—a self-contained artifact that can be reviewed or delivered without access to the original build environment.

Who this documentation is for

• Technical reference—for developers building or maintaining a styleguide project: the Handlebars helper reference, configuration format, and rendering behavior.