@bluevolt-tech/lumen

v2.0.0

Published

2 days ago

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.

0High
0Medium
0Low

andersonmendezbv

Lumen — BlueVolt Component Library

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 GitHub Packages:

npm install @bluevolt-tech/lumen

Prerequisites

1. Configure npm to authenticate with GitHub Packages

Create or edit ~/.npmrc:

@bluevolt-tech:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Replace YOUR_GITHUB_TOKEN with a GitHub personal access token that has read:packages scope.

2. 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 — GitHub Packages

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

Build pipeline:

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

What gets published:

dist/ — Compiled JS + TypeScript declarations
themes/ — Generated CSS files (base.css, layouts.css)
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:

| URL path | Contents | Updated when | |----------|----------|--------------| | /latest/ | Always the newest build | Every release | | /v{major}/ | Stable major version | On major/minor releases |

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

npm run build — generates tokens, compiles components, generates types
npm run build-storybook -- --output-dir storybook-latest with STORYBOOK_BASE_PATH=/latest/ — bakes the base path into asset URLs for the blob subdirectory
Copies dist/ into storybook-latest/dist/ so component JS files are co-located with the Storybook
Uploads the output to Azure Blob Storage under $web/latest
Repeats steps 2–4 with STORYBOOK_BASE_PATH=/v{major}/ for the versioned deployment

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)
Questions or issues → reach out to the Lumen team or open an issue in this repository