Lumen — BlueVolt Component Library

Lumen is BlueVolt's design system: a collection of framework-agnostic UI components built with native Web Components. Drop them into any app — vanilla JS, AngularJS, Angular, React, Vue — with no framework dependency.

Storybook

The Storybook is the source of truth for components. Each component page includes:

• Live interactive preview with all variants and states
• Full attribute reference
• Framework Code tab with copy-paste setup for HTML/ASPX, AngularJS, Angular 11, and Angular 18

Run it locally:

npm run storybook

Installation

Install from the public npm registry:

npm install @bluevolt-tech/lumen

No authentication or .npmrc configuration is required — the package is public.

Legacy apps that still have a @bluevolt-tech:registry=https://npm.pkg.github.com entry in their .npmrc from the GitHub Packages era can safely remove it. See docs/migration-guide-angular-apps.md for the step-by-step.

CDN (no build step)

Apps without a build pipeline (ASPX / MVC / plain HTML) can load Lumen directly via unpkg or jsdelivr:

<link rel="stylesheet" href="https://unpkg.com/@bluevolt-tech/lumen@latest/themes/base.css" />
<script type="module" src="https://unpkg.com/@bluevolt-tech/lumen@latest/dist/components/bv-button/bv-button.js"></script>

Pin to a specific version (@2.0.1 instead of @latest) in production. See docs/aspx-integration-guide.md for a full ASPX integration walk-through.

Prerequisite: load the Roboto font

Lumen uses Roboto (weights 400, 500, 600, 700). Add to your app's <head>:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap" rel="stylesheet">

Quick Start

Plain HTML / Vanilla JS

<!DOCTYPE html>
<html>
<head>
  <!-- 1. Base design tokens (colors, spacing, typography) -->
  <link rel="stylesheet" href="node_modules/@bluevolt-tech/lumen/themes/base.css" />

  <!-- 2. Load Roboto font (see Installation) -->
  <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap" rel="stylesheet">

  <!-- 3. Import components -->
  <script type="module">
    import '@bluevolt-tech/lumen/components/bv-button';
    import '@bluevolt-tech/lumen/components/bv-badge';
  </script>
</head>
<body>
  <bv-button variant="primary">Save changes</bv-button>
  <bv-badge variant="success">New</bv-badge>
</body>
</html>

Angular (18+)

1. Install the package:

npm install @bluevolt-tech/lumen

2. Add theme CSS to angular.json:

{
  "projects": {
    "your-app": {
      "architect": {
        "build": {
          "options": {
            "styles": [
              "node_modules/@bluevolt-tech/lumen/themes/base.css",
              "src/styles.css"
            ]
          }
        }
      }
    }
  }
}

3. Enable custom elements in your component:

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@bluevolt-tech/lumen/components/bv-button';
import '@bluevolt-tech/lumen/components/bv-badge';

@Component({
  selector: 'app-root',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: `
    <bv-button variant="primary">Save changes</bv-button>
    <bv-badge variant="success">New</bv-badge>
  `
})
export class AppComponent {}

4. Load Roboto font in index.html:

<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;600;700&display=swap" rel="stylesheet">

AngularJS (1.x)

See the Framework Code tab in Storybook for the complete AngularJS setup with CDN links and controller bindings.

Using Screens with Mock Data

Lumen ships reference screen implementations with mock data. Import both the screen component and its data:

import '@bluevolt-tech/lumen/components/bv-portal-layout';
import '@bluevolt-tech/lumen/components/bv-portal-header';
import '@bluevolt-tech/lumen/components/bv-filter-panel';
// ... other screen components

import { mockData } from '@bluevolt-tech/lumen/storybook/stories/screens/course-catalog.data';

// Use mockData to populate the screen initially, then swap with real API calls

The mock data shows the expected data shape for each screen. Once the layout renders correctly, replace it with your application's data source.

Theming

Include themes/base.css for the default BlueVolt theme. Override any token on :root:

:root {
  --bv-color-primary: #005fcc;
  --bv-color-primary-dark: #004499;
}

| Category | Prefix | Example | |------------|-------------------|-----------------------------------------------| | Colors | --bv-color-* | --bv-color-primary, --bv-color-danger | | Spacing | --bv-spacing-* | --bv-spacing-sm (8px), --bv-spacing-md (16px) | | Typography | --bv-font-* | --bv-font-size-sm, --bv-font-weight-bold | | Radius | --bv-radius-* | --bv-radius-sm, --bv-radius-full | | Shadow | --bv-shadow-* | --bv-shadow-sm, --bv-shadow-lg | | Transition | --bv-transition-* | --bv-transition-fast, --bv-transition-slow |

Events

All components dispatch events with { bubbles: true, composed: true } so they cross Shadow DOM boundaries and can be listened to on any ancestor element:

document.addEventListener('bv-page-change', (e) => {
  console.log(e.detail.page);
});

Browser Support

| Browser | Minimum Version | |---------|----------------| | Chrome | 67+ | | Firefox | 63+ | | Safari | 12.1+ | | Edge | 79+ |

Deployment

Library — public npm registry

The npm package (@bluevolt-tech/lumen) is published to the public npm registry. Publishing is triggered automatically by creating a GitHub release, which runs the publish-npm.yml workflow.

The DevOps setup (npm org, automation token, GitHub secret) is documented once at docs/npm-public-publishing-guide.md.

Build pipeline:

1. npm run build:tokens — Regenerates themes/base.css from token definitions
2. npm run build:components — Compiles TypeScript to JavaScript with CSS inlined
3. npm run build:types — Generates .d.ts TypeScript declaration files
4. npm run build:static — Copies themes, assets to dist/
5. npm publish — Publishes to GitHub Packages (triggered by prepublishOnly hook)

What gets published:

• dist/ — Compiled JS + TypeScript declarations
• themes/ — Theme CSS (base.css, generated from tokens/base.json; layouts.css, hand-maintained)
• assets/ — Static files (fonts.css, icons)

Local testing before publish:

npm run build              # Full build
npm pack                   # Creates tarball
cd /path/to/test-project
npm install /path/to/lumen/@bluevolt-tech-lumen-1.0.0.tgz

Storybook — Azure Blob Storage

The Storybook is hosted on Azure Blob Storage as a static website. Two deployments are maintained per release:

| URL path | Contents | Updated when | | ------------- | -------------------------------------------- | -------------------------------------------- | | /latest/ | Always the newest release build | Every release (moving pointer) | | /vX.Y.Z/ | Frozen snapshot for that exact semver tag | On release — one snapshot per released tag |

The full semver path (/v2.0.1/, not /v2/ or /v2.0/) matches the npm-installed version 1:1, so a consumer on @bluevolt-tech/[email protected] has a durable docs URL that will not change when v2.0.2 ships.

Deploying is triggered automatically by publishing a GitHub release. The deploy.yml workflow runs:

1. npm run build — generates tokens, compiles components, generates types.
2. Regenerates storybook/.storybook/versions.ts from the current git tag list via the prebuild-storybook npm hook (scripts/generate-versions.js).
3. npm run build-storybook -- --output-dir storybook-versioned with STORYBOOK_BASE_PATH=/vX.Y.Z/ — bakes the base path into asset URLs for the versioned blob subdirectory.
4. Copies dist/ into storybook-versioned/dist/ so component JS files are co-located with the Storybook.
5. Uploads the output to Azure Blob Storage under $web/vX.Y.Z.
6. Repeats steps 3–5 with STORYBOOK_BASE_PATH=/latest/ and uploads to $web/latest.

A version switcher dropdown in the Storybook toolbar auto-discovers all supported releases from git tags — cutting a new release is the only action needed for a new entry to appear.

Simulating the pipeline locally

To reproduce the exact production build before releasing:

# Step 1 — build tokens, compile components, generate types, copy static assets
npm run build

# Step 2 — build Storybook with /latest/ base path
# Windows Git Bash: MSYS_NO_PATHCONV=1 prevents path mangling of /latest/
MSYS_NO_PATHCONV=1 STORYBOOK_BASE_PATH=/latest/ npm run build-storybook -- --output-dir storybook-latest

# Step 3 — co-locate component JS (mirrors the pipeline cp step)
cp -r dist storybook-latest/dist

# Step 4 — serve under /latest/ to match blob structure
mkdir -p temp-serve/latest
cp -r storybook-latest/* temp-serve/latest/
npx http-server temp-serve -p 8080
# Open http://localhost:8080/latest/

Critical invariant: tokens/style-dictionary.config.cjs must have prefix: 'bv'. This generates --bv-* CSS variables that components reference. If the prefix is wrong, all components render unstyled.

How CSS tokens reach Storybook components

storybook/.storybook/preview.ts imports themes/base.css and themes/layouts.css directly. Vite bundles them into assets/preview-*.css, which is loaded inside the Storybook iframe. No separate <link> tags or script injection is needed.

Resources

• Storybook — component playground, API reference, and framework integration snippets (npm run storybook).
• docs/aspx-integration-guide.md — end-to-end walkthrough for adding a Lumen screen to a legacy ASPX page via unpkg.
• docs/migration-guide-angular-apps.md — one-time steps for Angular apps still on the old GitHub Packages registry.
• docs/npm-public-publishing-guide.md — DevOps setup for the public-npm publish pipeline (org, automation token, GitHub secret).
• docs/component-usage-scanner.md — GitHub Action that scans the org for bv-* usage and writes a report.
• Contributing to Lumen? — start at CLAUDE.md. It is the write-time rulebook: file structure, TypeScript rules, component/story patterns, the 9 pre-push gates, the review-process skills, and the semver policy.
• Questions or issues → reach out to the Lumen team or open an issue in this repository.