Brightspot UI

@brightspot/ui is a library of ready-made interface pieces — buttons, widgets, icons — plus a full set of colors and styles (light, dark, and high-contrast) for the screens inside the Brightspot CMS.

The CMS's own interface is built from this UI library, and we're gradually moving the rest of it over. It is also published so individual Brightspot projects can use it.

What do you want to do?

• Fix or change the CMS UI
• Use the UI library in a project
• Improve the UI library itself

Fix or change the CMS UI

The CMS interface lives in src/legacy/tool-ui/. Edit files there and preview them in a running CMS one of two ways.

You'll need: Node 22 (nvm use 22), Yarn 1, a local brightspot checkout, and yarn install then yarn build run once here. The CMS bundle imports some library components from the build output, so rerun yarn build after changing them.

Editor tip: In VSCode, the recommended extensions autocomplete the btu-* classes as you type. See the VSCode setup notes.

Fast way — live preview (for everyday edits)

1. Start the CMS backend (in your brightspot/ folder):

   docker compose up -d
   

2. Start the live preview (here):

   cd src/legacy/tool-ui
   yarn server:local
   

3. Open the dev server — note the :8080, not plain localhost:

   https://localhost:8080/cms/
   

   Click through the certificate warning (local cert — normal).

Now edit anything in src/legacy/tool-ui/src/ and the browser updates on its own — no rebuilding.

Seeing 502 errors? The CMS backend isn't reachable — check the docker step.

Seeing The 'btu-…' class does not exist after a pull? Run yarn install here. New utilities can arrive with new dependency versions — icon names come from lucide-static — and a pull updates the code without updating what's installed. Running it at the repo root installs the src/legacy/tool-ui/ workspace too, so one command covers both.

Full way — build the real package (for a final check only)

Slower, but produces the actual file the CMS ships. Needs two temporary edits in brightspot — don't commit them.

1. Build the package (here):

   ./gradlew publishToMavenLocal
   

2. Point brightspot at your build:

   • site/build.gradle — add mavenLocal() under repositories

   • platform/brightspot-dependencies/build.gradle — change the cms-tool-ui line to:

     api 'com.brightspot.ui:cms-tool-ui:9999-SNAPSHOT'
     

3. Rebuild and run (in brightspot/):

   ./gradlew docker
   

4. Check it at https://localhost/cms/, then undo the two edits when done.

Use the UI library in a project

Starting a new frontend package? @brightspot/ui-builder scaffolds the build (Vite) and wires up this preset for you. The steps below are for adding the library to a build you already have.

You'll need: a frontend using TailwindCSS v3.

yarn add -D @brightspot/ui

If you don't already have one, create a Tailwind config file at the root of your frontend — tailwind.config.mjs:

// tailwind.config.mjs
export default {
  content: ['./src/**/*.{js,ts,html,java}'], // wherever your markup lives, including Java that builds class lists
}

Then add @brightspot/ui as a preset. One line pulls in everything — all colors, styles, and components:

// tailwind.config.mjs
import preset from '@brightspot/ui'

export default {
  presets: [preset],
  content: ['./src/**/*.{js,ts,html,java}'],
}

Leave plugins empty — the preset already registers every component's plugin, so listing them again double-registers.

To use a component, import it (it self-registers its btu-* element), then use the tag. Import from the components/ subpath with the .js extension — not the deep dist/ path:

import '@brightspot/ui/components/badge/Badge.js'

<btu-badge>Draft</btu-badge>

On a CMS page, the CMS defines only a few of these elements itself. Import every other element your plugin uses, including ones your Java renders through the generated com.brightspot.ui.dari classes. Using these in a plugin lists which ones the CMS defines.

Browse every component, with live examples, at ui.brightspot.com. The site shows only the newest release. To browse the version you have installed (6.8.1 or later), serve the copy that ships in the package and open http://localhost:6006:

npx http-server node_modules/@brightspot/ui/dist/storybook -p 6006

Opening its index.html straight from disk doesn't work, because browsers block its scripts on file://.

Point your AI coding agent at the docs

The package ships docs written for coding agents, matched to the installed version: llms.txt at the package root, one page per component in docs/components/, and the Custom Elements Manifest. Agents don't find them on their own, so add this to your project's AGENTS.md or CLAUDE.md:

## @brightspot/ui

This project uses `@brightspot/ui` web components (`btu-*` tags). Before writing or changing code that uses them,
read `node_modules/@brightspot/ui/llms.txt` and the component pages it links to. They match the installed version,
so prefer them over what you remember about this library.

Without a local install, give the agent https://ui.brightspot.com/llms.txt, which describes the newest release.

Improve the UI library itself

Adding or fixing a component, style, or color.

You'll need: Node 22 (nvm use 22), Yarn 1.

Where things live:

• src/ — the UI library (components, styles, colors); this is what gets published.
• src/legacy/tool-ui/ — the CMS interface (see the first section).
• tool-ui/ — packaging only.

Build and preview components in the catalog — no CMS needed:

yarn storybook

Before committing:

yarn build              # compile everything
yarn check:conventions  # check the rules
yarn format             # tidy formatting
yarn test:storybook     # run tests

House rules — when you touch one of these areas, read its guide in .ai/ first:

See CONTRIBUTING.md for documentation standards.

Releases are automatic: merge to main, and a version is tagged and published for you.