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 run once here.

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}'], // wherever your markup lives
}

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}'],
}

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>

To browse everything available, run the interactive catalog:

yarn storybook   # opens http://localhost:6006

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:

| Area | Guide | | ----------------------------------------------- | -------------------------------------- | | Naming (sizes, icons, events, CSS vars) | .ai/LESSONS-NAMING.md | | JSDoc and types | .ai/LESSONS-JSDOC.md | | Reusing the button primitive | .ai/LESSONS-BUTTON-REUSE.md | | Keeping plugin styles isolated | .ai/LESSONS-PLUGIN-ISOLATION.md | | Safelisting classes written at runtime | .ai/LESSONS-SAFELIST.md | | Preset vs Storybook config; adding a new plugin | .ai/LESSONS-TAILWIND-CONFIGS.md | | CSS custom properties + Tailwind gotchas | .ai/LESSONS-CSS-PROPS.md | | Writing Storybook stories | .ai/LESSONS-STORYBOOK.md | | Anchor positioning / popovers | .ai/LESSONS-ANCHOR-POSITIONING.md | | Reduced motion | .ai/LESSONS-REDUCED-MOTION.md | | Roving tabindex | .ai/LESSONS-ROVING-TABINDEX.md | | Composing components | .ai/LESSONS-COMPONENT-COMPOSITION.md |

See CONTRIBUTING.md for documentation standards.

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