Skip to main content

Installation

The Blue Water Design System is available as a web component library that can be used in any framework or vanilla JavaScript project. This guide covers installation and setup for different scenarios.

Prerequisites​

  • Node.js 16.x or later
  • npm 7.x or later

Package Installation​

Install the core package:

npm install bluewater --registry=https://pkgs.dev.azure.com/USSDevelopment/_packaging/AlliancePackages/npm/registry/

Angular Integration​

The Blue Water Design System provides first-class support for Angular through a dedicated Angular package.

1. Install Angular Package​

npm install bluewater-angular --registry=https://pkgs.dev.azure.com/USSDevelopment/_packaging/AlliancePackages/npm/registry/

2. Import Styles​

There are optional styles you can add to your angular.json:

{
  "styles": [
    "node_modules/bluewater/styles/variables.css",
    "node_modules/bluewater/styles/typography.css",
    "node_modules/bluewater/styles/classes.css",
    "node_modules/bluewater/styles/table.css"
  ]
}
  • Variables imports the default values for all our design tokens.
  • Classes imports all our css utility classes.
  • Typography imports the Inter font family and sets our default typography styles.

3. Initialize in App Config​

Add the provideBlueWater provider to your app.config.ts:

import { ApplicationConfig, provideZonelessChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
import { provideBlueWater } from 'bluewater-angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(), 
    provideRouter(routes), 
    provideBlueWater()
  ]
};

4. Use Components​

You can now use Blue Water components in your Angular templates:

<bw-button>Click me</bw-button>
<bw-input label="Name"></bw-input>

Non-Angular Usage​

For non-Angular projects, you can use Blue Water components in two ways:

Option 1: Lazy Loaded Bundle​

This approach loads all components as a single bundle, which is ideal for applications using most of the component library.

  1. Import the styles:
<link rel="stylesheet" href="node_modules/bluewater/styles/variables.css">
<link rel="stylesheet" href="node_modules/bluewater/styles/typography.css">
<link rel="stylesheet" href="node_modules/bluewater/styles/classes.css">
<link rel="stylesheet" href="node_modules/bluewater/styles/table.css">
  1. Initialize the components:
<script type="module">
  import { defineCustomElements } from 'bluewater/loader';

  // Optional: Configure global settings
  window.blueWater = {
    defaultTimeZone: 'UTC',
    experimentalIsoStringFix: true,
    experimentalValueChange: true
  };

  // Initialize all components
  defineCustomElements();
</script>
  1. Use components in your HTML:
<bw-button>Click me</bw-button>
<bw-input label="Name"></bw-input>

Option 2: Individual Custom Elements​

This approach allows you to load only the components you need, which is ideal for applications using a subset of the component library.

  1. Import the styles (same as Option 1)

  2. Import and register individual components:

<script type="module">
  import { defineCustomElement as defineButton } from 'bluewater/components/bw-button';
  import { defineCustomElement as defineInput } from 'bluewater/components/bw-input';

  // Register only the components you need
  defineButton();
  defineInput();
</script>
  1. Use the registered components in your HTML:
<bw-button>Click me</bw-button>
<bw-input label="Name"></bw-input>

Material Icons​

BwIcon relies on the material icon library. The angular provider automatically imports this for you, but in non-angular projects you will need to add a link in the head of your html.

<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200">

Leaflet​

BwMap relies on leaflet. The angular provider automatically imports this for you, but in non-angular projects you will need to add a link in the head of your html.

<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css">

Configuration Options​

The following configuration options are available:

OptionTypeDefaultDescription
timezonestringundefinedDefault timezone for date/time components
iconsbooleantrueWhether to load Material Icons
experimentalISOStringFixbooleanfalseFix for ISO string handling in date components
experimentalValueChangeFixbooleanfalseFix for value change events in form components

Best Practices​

  1. For Angular projects, use the bluewater-angular package for the best integration experience
  2. For non-Angular projects:
    • Use the lazy loaded bundle if you're using most of the components
    • Use individual custom elements if you only need a few components
  3. Include the required styles (variables, typography, and classes) if you will be exclusively using the Blue Water Design System for your UI
  4. Configure the timezone if your application needs to work in a hard coded time zone
  5. Consider enabling experimental fixes if you encounter specific issues with date handling or value changes