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 brightspot-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 or higher - Required for development and git hooks

Building the Package

To build the package, run yarn build from the package root to create the dist folder containing all the compiled assets.

Local Development with yarn link

For local development and testing, use yarn link to create a symlink between this package and your consuming project. This approach provides real-time updates as you make changes to the brightspot-ui source code.

Setting up the link

1. In the brightspot-ui package directory:

   yarn link

   This registers the package globally on your system for linking.

2. In your consuming project directory:

   yarn link @brightspot/ui

   This creates a symlink from your project's node_modules to the brightspot-ui package.

   Note Be sure this is done in the directory where the package.json file resides for the CMS UI. Currently that is at /cms/tool-ui. You will need to validate your changes via your locally running Brightspot Tool UI Webpack server. It will not work directly over Docker's Tomcat.

Working with the linked package

• From within this module, run yarn build to ensure the dist folder is updated with your changes.
• From within tool-ui of Brightspot CMS, restart your local webpack server (yarn server:local) to pickup the linked brightspot ui module changes.

Removing the link

When you're done with local development:

1. In your consuming project:

   yarn unlink @brightspot/ui
   yarn install --force

2. In the brightspot-ui package directory:

   yarn unlink

This restores your project to use the published version from npm.

Frequently Asked Questions

Q: How can I see examples of the components and theme?

A: See the "Examples" section above.

Q: Can I choose which Brightspot UI plugins my project uses?

A: You have full control over which plugins you include in the tailwind.config file. See the "using plugins" section above.