Using the CBP Design System Web Components

Including the Web Components in Your Application

There are a couple strategies for including the CBP Design System web components in your site or application, detailed below.

$3

The CBP Design System web components (and React wrappers) are published to npm.

In modern JavaScript frameworks, you can use the native web components, which are framework-agnostic. To add the CBP Design System web components to your project, do the following:

- Add the package to your package.json under "devDependencies" (e.g., "@cbpds/web-components": "latest",) and run npm install or
- Run npm install @cbpds/web-components --save-dev
- Import the web components loader in your framework's top-level file such as App.js|jsx|tsx or main.js|jsx|tsx.
- Call defineCustomElements() to initialize the loader and register the web components (to be lazy loaded when used).

``javascript
import { defineCustomElements } from '@cbpds/web-components/dist/loader';
defineCustomElements();
`

If you are using Typescript in your codebase, you may need to make your project aware of the web components before you can compile your code successfully. In many cases, this can be accomplished simply by adding the web component definitions to your tsconfig.json's includes (after npm install has been run). E.g.,

`json
"include": [
"src",
"node_modules/@cbpds/web-components/dist/types/components.d.ts"
]
`

$3

For sites not running in a node.js environment or requiring a build step, the web components may be included via script tag:

- Put a script tag referencing the loader module in the head of your index.html or template file.
- This file is a loader, which registers all of the design system components and lazy-loads individual components as needed.
- Note: ESM modules must be delivered over SSL/https.
- Then you can use the web components (custom elements) anywhere in your template, JSX, html, etc.

You can use UNPKG (an open source global content delivery network that mirrors npm) for testing, but it should never be used for production apps.

Referencing the latest version:

`html

`

Referencing a specific version:

`html

`

Ideally, your application should reference a central, organization-hosted copy of the files or pull the package's dist/cbp-web-components directory into your application's "assets" directory and reference them as such:

`html

`

Using the Web Components

Once the CBP Design System web components have been included in your site or application, they may be used in HTML, JSX, etc.

It is recommended that the cbp-app web component is used to wrap the entire contents of your application or site template to include the global CSS variables (design tokens) that are used throughout the design system for styling the components.

To get started quickly, you may copy the markup from one of our "template" stories to wrap your application or site content.

Here's an example of a button component:

`html
fill="solid"
color="primary"
>
Default

`

Fonts and Assets

Regardless of how you include the web components (either method above), you'll still need some assets that are part of the CBP Design System package but are not encapsulated in the cbp-app web component or any others:

Copy the files in node_modules/@cbpds/web-components/dist/assets/ to your application /assets directory. (This may be automated with a "copy" command in your application). This directory includes the Roboto font files, their CSS font face definitions, and the CBP Seal, which is used in multiple places and may be referenced as a favicon.

The Roboto font family is part of the CBP Design System standards, but must be linked manually in your application's as well.

Copy and paste the following into your index.html or template file:

`html



`

These CSS files assume a directory structure of:

- webroot
- assets
- css
- fonts
- roboto
- roboto-mono
- images

Any deviations from this structure may require editing of the linked CSS files and paths to the fonts.

If the path to your application's assets folder is different than "./assets", you may also need to provide the paths as properties of the cbp-universal-header` component as part of your site/application template.