Brightspot UI

About

Brightspot UI is a package of custom web components and styles to provide a basis for building new CMS components. It uses TailwindCSS for styling and LitElement for web components.

If you're developing a Brightspot CMS plugin or creating custom CMS UI for your project, then you've come to the right place!

Getting Started

Note: To get the best developer experience we recommend using VSCode editor. The marketplace of extensions that are available provide code formatting and intellisense for all the TailwindCSS classnames and our plugins, etc. The VSCode setup is documented here.

Prerequisites

Your codebase needs to be compatible with

• TailwindCSS v3

Installation

1. Install the Brightspot ui node module as a devDependency

   yarn add -D @brightspot/ui

2. Create a tailwind.config file and add Brightspot ui as a preset. More on TWCSS presets here.

   // (Typescript example) contents of tailwind.config.ts
    export default {
      ...
      presets: [require('@brightspot/ui')],
      ...
    }

   // (Javascript example) contents of tailwind.config.js
    export default {
      ...
      presets: [require('@brightspot/ui/dist/tailwind.config.js')],
      ...
    }

3. Build your frontend

Using Plugins

Brightspot UI comes with a variety of TailwindCSS plugins to make styling simpler and declarative. Visit the Storybook to see the available plugins.

To use our plugins, include them in your TailwindCSS config as usual. Plugin files are provided in both Typescript and Javascript variants and are available under the dist path in the platform-ui module.

An example of including a plugin:

// your tailwind.config.ts
  ...
  plugins: [
    require('@brightspot/ui/dist/tailwind-plugin-theme.ts'),
    ...

Web Components

Brightspot UI includes custom web components built with LitElement. FOUC (Flash of Unstyled Content) prevention is handled automatically when you import the components.

Import components in your JavaScript/TypeScript:

import '@brightspot/ui/dist/components/widget/Widget'

See the Storybook documentation for detailed usage examples and API references.

Examples

We use Storybook for interactive previewing of our ui components. Launch that in the browser by running:

  yarn storybook

Development

Prerequisites

• Node.js v22+
• Yarn 1 (classic)

Layout

This repo ships two surfaces inside one published @brightspot/ui npm package:

• src/ — the modern design system (web components, Tailwind plugins, presets). Built by yarn build into dist/.
• src/legacy/tool-ui/ — the brightspot CMS frontend (JS, CSS, webpack, tests). Has its own package.json. Built by (cd src/legacy/tool-ui && yarn build) into src/legacy/tool-ui/src/main/webapp/dist/.

The publish flow (yarn prepack) builds both.

Component-only work (no CMS needed)

yarn storybook

Opens Storybook at http://localhost:6006. Iterate on src/ components and Tailwind plugins without booting the CMS.

CMS integration work

The brightspot CMS consumes @brightspot/ui from npm. Two workflows for local iteration:

Fast loop: webpack-dev-server (recommended for JS/CSS edits)

1. Start the CMS in docker as usual (from brightspot/):

   ./gradlew docker

2. Start the dev server (from platform-ui/src/legacy/tool-ui/):

   yarn server:local

   Proxies to localhost (or ~/.brightspot/local-url if set), serves freshly compiled assets at /cms/dist/, and injects x-brightspot-dev: 1 on proxied requests so the CMS returns unhashed asset paths.

3. Open the CMS at the dev-server URL (https://localhost:8080/cms/) instead of the docker URL. Edit files in src/legacy/tool-ui/src/; changes hot-reload in the browser.

Full WAR rebuild (for the modern src/ surface, or final smoke)

yarn server:local only serves src/legacy/tool-ui/. For edits to the modern surface in src/, or to validate against the actual WAR build:

1. Link the package (once per machine, from platform-ui/):

   yarn link

2. Consume the link (in brightspot/cms/tool-ui/):

   yarn link @brightspot/ui

3. Edit, then rebuild whichever surface changed:

   yarn build                              # for src/ edits
   (cd src/legacy/tool-ui && yarn build)   # for src/legacy/tool-ui/ edits

4. Rebuild the CMS WAR and roll it into tomcat (from brightspot/):

   ./gradlew :cms-tool-ui:yarnBuild
   ./gradlew docker

5. Smoke at https://localhost/cms/ (apache, port 443).

Unlink when done

# in brightspot/cms/tool-ui:
yarn unlink @brightspot/ui && yarn install --force

# in platform-ui:
yarn unlink

Releases

@brightspot/ui ships via release-please. For migration-track prereleases (-cms-ui-migration.N), bump the version, publish to npm, then update the consumer pin in brightspot/cms/tool-ui/package.json and rerun yarn install there.