BankCMG Design System

A bespoke React component library and design token system for the BankCMG / CMG Financial digital experience.

Storybook: bcmg-dc-ds.cmgfinancial.ai
npm: @cmgfi/bcmg-dotcom-ds

Overview

The BankCMG Design System (BCMG DS) provides:

• Design tokens — a single CSS custom-property file covering color, spacing, typography, elevation, and iconography
• 40+ components — atoms, molecules, navigation, and organisms built to pixel spec
• Full TypeScript support — a single rolled-up index.d.ts ships with the package
• Zero runtime overhead — CSS Modules only; no CSS-in-JS or runtime theming

Components are built from scratch to match the BankCMG design language exactly. No third-party component library is used under the hood.

Tech Stack

| Concern | Choice | |---|---| | Framework | React (peer dependency — not bundled) | | Language | TypeScript strict | | Build | Vite library mode (ESM + CJS) | | Styles | CSS Modules | | Icons | flowbite-react-icons (SVG React components) | | Docs / QA | Storybook v8 |

Installation

npm install @cmgfi/bcmg-dotcom-ds

Peer dependencies — install these in your consuming app if not already present:

npm install react react-dom flowbite-react-icons

Usage

Import tokens and styles once in your app root (e.g. main.tsx or App.tsx):

import '@cmgfi/bcmg-dotcom-ds/tokens';   // design tokens (CSS custom properties)
import '@cmgfi/bcmg-dotcom-ds/styles';   // component styles

Then import components where needed:

import { Button, NavBar, Footer } from '@cmgfi/bcmg-dotcom-ds';

Icons are imported directly from flowbite-react-icons — no global stylesheet needed:

import { ChevronRight } from 'flowbite-react-icons/outline';

Component Library

Atoms

Foundational, single-purpose UI elements.

| Component | Description | |---|---| | App Download Button | iOS / Android app store CTAs | | Backgrounds | Themed background wrappers | | Button | Primary, secondary, ghost, and link variants | | Content — Block List | Bulleted or numbered content block | | Content — Blockquote | Pull-quote block | | Content — Icon | Token-sized icon display | | Content — Image Block | Responsive image container | | Content — Logo | CMG / BankCMG logo lockup | | Content — Overline Block | Eyebrow overline text | | Content — Paragraph Block | Body copy block | | Content — Subtitle Block | Section subtitle | | Content — Title Block | Section heading | | Dropdown Button | Button with dropdown trigger | | Form Controls — Checkbox | Accessible checkbox input | | Hyperlink | Inline and standalone link styles | | Icon Button | Icon-only button with accessible label |

Molecules

Composed from atoms; reusable mid-level patterns.

| Component | Description | |---|---| | Accordion | Expandable/collapsible content section | | Accordion Item | Single accordion row | | Anchor Tabs | Tab bar that scrolls to page sections | | Block Heading | Section heading with optional overline and CTA | | Button Group | Horizontally grouped button set | | Cards — Branch Location | Nearby branch card with map data | | Cards — Comparison | Side-by-side feature comparison card | | Cards — Default | General-purpose content card | | Cards — LO Results | Loan officer search result card | | Cards — Multi Link | Card with multiple action links | | Cards — Search Results | Generic search result card | | Cards — Testimonial | Customer quote card | | Carousel | Horizontally scrollable item reel | | Content Highlight | Icon + heading + body callout block | | Filter Group | Multi-select tag filter row | | Global Message | Site-wide alert / info banner | | Highlight Item | Icon + label highlight pill | | Location Tooltip | Map pin tooltip with branch info | | Pagination | Page navigation control | | Profile Flyout | Loan officer profile hover card | | Regular Tabs | Standard tab navigation | | Social Media Buttons | Icon links for social channels |

Navigation

Full navigation system from atomic pieces to composite stories.

| Component | Description | |---|---| | Breadcrumbs | Hierarchical page path (aligns with NavBar at 1440px) | | MegaMenuCard | Promotional card inside mega menu panels | | MySiteSlot | Loan officer "my site" identity block | | TertiaryNavGroup | Grouped tertiary link section | | NavBar | Top navigation bar (desktop + mobile hamburger) | | MegaMenu | Full-width dropdown mega menu panel | | NavDrawer | 3-level mobile slide-out navigation | | Footer | Site-wide footer with link columns | | Complete Desktop Nav | Composite: NavBar + MegaMenu + Breadcrumbs | | Complete Mobile Nav | Composite: NavBar + NavDrawer + Breadcrumbs |

Organisms

Page-level sections composed from atoms and molecules.

Content

| Component | Description | |---|---| | Card Collection | Grid of content cards | | FAQ Section | Accordion-based FAQ layout | | Fifty Fifty | Two-column text + media section | | Form Section | Page-level form container | | Highlights Section | Icon highlight grid | | Text Block | Rich text content section |

Heroes

| Component | Description | |---|---| | Article Hero | Blog / article page hero | | Default Hero | Standard marketing hero | | Location Hero | Branch location page hero | | My Site Hero | Loan officer personal site hero | | My Site Team Hero | LO team hero variant | | Support Hero | Support / help center hero |

Modals

| Component | Description | |---|---| | Modal | Base modal with header, body, footer | | Profile Modal | Loan officer detailed profile modal | | Review Modal | Customer review submission modal |

Design Tokens

All design tokens are CSS custom properties defined in dist/tokens/tokens.css. Import via @cmgfi/bcmg-dotcom-ds/tokens.

| Category | Examples | |---|---| | Color | --color-navy-50 → --color-navy-900; --color-teal-*; --color-text, --color-text-secondary (semantic aliases) | | Spacing | --spacing-02 → --spacing-40; --spacing-xxxs → --spacing-xxl (named aliases) | | Typography | --font-family; .text-h1 → .text-h6; .text-[xl|large|normal|small]-[bold|semibold|regular] | | Elevation | 4 shadow depth levels + 1 scrim overlay | | Iconography | --icon-size-sm (12px) / --icon-size-md (14px) / --icon-size-lg (18px) / --icon-size-xl (24px) |

All token values are absolute px units — no root font-size configuration required. See the Tokens section in Storybook for the full reference.

Development

# Clone the repo
git clone https://cmg-financial.ghe.com/andyg/bcmg-dc-ds
cd bcmg-dc-ds

# Install dependencies
npm install

# Start Storybook dev server (http://localhost:6006)
npm run dev

# Build the library
npm run build

# Build Storybook static site
npm run build-storybook

Contributing

1. All components follow the invariant pattern defined in CLAUDE.md — read it before contributing
2. Every component requires React.forwardRef, a displayName, and ...props spread
3. CSS Modules only — no hardcoded hex values or pixel spacing; token vars exclusively
4. Use semantic color aliases (--color-text, --color-focus-ring) — never raw palette steps (--color-navy-400)
5. Update PROGRESS.md before moving on from any task — stub entries count
6. Stories: tags: ['autodocs'] on every meta; AllStates always the last export

License

Proprietary — CMG Financial. All rights reserved.