CMG Home Loans Dotcom Design System

A React component library and design token system extracted from production cmgfi.com.

Storybook: home-loans-ds.cmgfinancial.ai npm: @cmgfi/home-loans-ds

Overview

The Home Loans Dotcom Design System (Home Loans DS) provides:

• Design tokens — CSS custom properties covering color, spacing, typography, elevation, and iconography
• 68 components — atoms, molecules, organisms, and navigation built to match cmgfi.com pixel-for-pixel
• Two brand themes — CMG (base) for cmgfi.com and CMGHL (retail) as an opt-in override layer
• 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 cmgfi.com 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 | Font Awesome 6 free-solid (peer dependency) + 8 custom calculator-mode SVGs shipped from this package | | Docs / QA | Storybook v8 |

Installation

npm install @cmgfi/home-loans-ds

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

npm install react react-dom \
  @fortawesome/react-fontawesome \
  @fortawesome/fontawesome-svg-core \
  @fortawesome/free-solid-svg-icons

Optional peer dependency (only if you use <Map> with Google Maps):

npm install @googlemaps/js-api-loader

Usage

1. Import tokens and styles

Once, in your app root (e.g. main.tsx or App.tsx):

import '@cmgfi/home-loans-ds/tokens';   // base (CMG) design tokens
import '@cmgfi/home-loans-ds/styles';   // compiled component styles + webfonts

2. (Optional) Apply the CMGHL retail brand override

Loaded after the base tokens, this re-aliases the tertiary color palette from aqua (CMG) to green (CMGHL):

import '@cmgfi/home-loans-ds/tokens';
import '@cmgfi/home-loans-ds/tokens/cmghl';   // ← override, loaded AFTER base
import '@cmgfi/home-loans-ds/styles';

Preview the brand delta in the Brand themes section of Storybook.

3. Import components

import { Button, Heading, Text, SiteHeader, SiteFooter, MortgageCalculator } from '@cmgfi/home-loans-ds';

export default function HomePage() {
  return (
    <>
      <SiteHeader contactNumber="800-501-2001" />
      <main>
        <Heading level={1}>Welcome home.</Heading>
        <Text size="large">Apply online in about 15 minutes.</Text>
        <Button variant="primary" size="lg">Get Started</Button>
      </main>
      <SiteFooter />
    </>
  );
}

4. Use icons

Font Awesome 6 free-solid icons are imported directly — no global stylesheet needed:

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
import { faChevronRight } from '@fortawesome/free-solid-svg-icons';

<FontAwesomeIcon icon={faChevronRight} />

For consistent sizing with the design system's icon tokens, use the wrapped <Icon> component:

import { Icon } from '@cmgfi/home-loans-ds';
import { faPhone } from '@fortawesome/free-solid-svg-icons';

<Icon icon={faPhone} size="md" color="primary" />

The 8 calculator-mode glyphs (mortgage, savings, biweekly, qualifying, purchase, short/long, rent-vs-buy, buydown) ship as React components directly from this package:

import { MortgageIcon, BiWeeklyIcon } from '@cmgfi/home-loans-ds';

<MortgageIcon />

Component library

Atoms (20)

Foundational UI primitives.

| Component | Description | |---|---| | Button / ButtonLink | Primary, secondary, tertiary, and link variants (4 sizes) | | Link | Inline and standalone hyperlink styles | | Heading | h1–h6 with color/level controls | | Text | Body text with size, weight, and color variants | | Icon | Token-sized FontAwesome wrapper with color slots | | Divider | Horizontal/vertical rule (3 emphasis levels) | | Spinner | Loading spinner (3 sizes, 4 colors) | | Label, HelperText, ErrorText | Form-label primitives | | Input, NumericInput, Textarea, Select, Checkbox, Radio | Form controls | | Avatar | Initials + image circle | | Logo | CMG / CMG Home Loans lockup | | PlayButton | Video play overlay (3 sizes, 2 variants) | | CalcIcons | 8 calculator-mode SVG glyphs |

Molecules (27)

Composed from atoms.

| Component | Description | |---|---| | FormField | Label + input + helper + error wrapper | | SearchInput | Search input with leading icon and clear button | | CTAStrip | Multi-CTA banner (3 layouts, 3 surfaces) | | Breadcrumb | Hierarchical page path | | AlertBanner | Severity alert banner (info / success / warning / error) | | Card | Generic content card (4 elevations) | | FeatureWithIcon | Icon + heading + description block | | IconCard | Icon-anchored card variant | | StatBlock | Big-number stat block | | HowItWorksStep | Numbered/iconed step (horizontal/vertical) | | VideoContainer, VideoCard | Video poster + play button | | LoanProductCard, LoanOfficerCard | Product / LO summary cards | | NavTab, NavTabGroup | Tabbed navigation primitives | | NavDropdown | Click-to-open dropdown menu | | ReviewSummary | Stars + count + caption | | TestimonialQuote | Quoted testimonial block | | AccordionItem | Single accordion row | | Tooltip | Hover tooltip (4 placements) | | CalcRow, CalcResultPanel, DonutChart | Calculator primitives | | StateMap, Map | US state SVG and Google-Map embed | | ImageCopyBlock | Image + copy two-column block |

Organisms (17)

Page-level sections composed from molecules and atoms.

| Component | Description | |---|---| | HeroWithCTA | Marketing hero with optional CTAs and overlay | | HeroWithVideo | Hero with video background or side-by-side video | | HeroSlim | Compact one-line hero | | MortgageCalculator | Basic + advanced mortgage calculator | | HowItWorksSection | Multi-step process section | | FeatureListSection | Feature-icon grid (2/3/4 columns) | | ImageCopyBlockSection | Image + copy section wrapper | | FAQAccordion | FAQ list with single or multi-open mode | | LoanProductGrid | Loan-product card grid | | LoanProductTabPanel | Tabbed loan-product panel | | ReviewsWidget | Aggregated reviews summary band | | TestimonialsCarousel | Auto-rotating testimonial slider | | FindLoanOfficerSearch | Search form for loan officers | | LoanOfficerResults | LO search-results grid | | LoanOfficerBar | Sticky LO contact bar | | CtaSection | Full-bleed CTA section (5 surfaces) | | HomeAppPromo | iOS/Android app-store promo block |

Navigation (4)

Site chrome.

| Component | Description | |---|---| | SiteHeader | Desktop utility band (phone + social + language + login) | | SiteNavigator | Desktop primary nav bar (logo + items + utility actions + CTA) | | SiteNavigatorMobile | Mobile drawer (slide-out left, expandable rows) | | SiteFooter | Site-wide footer with link columns, social, and legal |

Design tokens

All design tokens are CSS custom properties defined in dist/tokens/tokens.css. The full reference lives under the Tokens section of Storybook.

| Category | Examples | |---|---| | Color (palette) | --color-green-50 → --color-green-900 (primary); --color-teal-* (secondary); --color-aqua-* (tertiary base); --color-gray-* (neutrals) | | Color (semantic) | --color-text, --color-text-secondary, --color-background, --color-surface, --color-border, --color-focus-ring, --color-primary, --color-secondary, --color-tertiary | | Spacing | --spacing-02 → --spacing-40 (numeric); --spacing-xxxs → --spacing-xxl (named aliases) | | Typography | --font-family-body (Open Sans); --font-family-heading (Kadwa); .text-h1 → .text-h6; .text-[xl\|large\|normal\|small]-[bold\|semibold\|regular] | | Elevation | 4 shadow depth levels + 1 scrim overlay | | Iconography | --icon-size-sm / --icon-size-md / --icon-size-lg / --icon-size-xl |

Brand-theme delta

Per source-code audit of cmg.website-new, CMGHL re-aliases only the tertiary semantic tokens:

| Token | CMG base | CMGHL override | |---|---|---| | --color-tertiary | Aqua 500 #32A4AC | Green 500 #92C13B | | --color-tertiary-hover | Aqua 600 #2D949B | Green 600 #82AD34 | | --color-tertiary-active | Aqua 700 #25787E | Green 700 #6A8D2A |

The aqua palette (--color-aqua-*) remains available under both themes — only the semantic alias shifts.

Source-of-truth model

This design system is extracted from two complementary sources — neither alone is sufficient:

1. Live cmgfi.com is the visual ground truth. Production rendering = what users actually see.
2. cmg.website-new is the structural ground truth — the ADO repo behind cmgfi.com, with the SCSS variable names, Razor partials, and ViewComponents that inform prop signatures and variant inventories.

When a component renders incorrectly, the visual diff against cmgfi.com is the authoritative check.

Development

# Clone the repo
git clone https://github.com/cmg-pilot-program/home-loans-ds.git
cd home-loans-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

Releases are CI-driven — see RELEASING.md.

Contributing

1. Read CLAUDE.md at the project root before contributing — it defines the invariant component pattern and the read-only rule for cmg.website-new/
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-green-400)
5. Never derive a color via opacity or rgba(…, <alpha>) — use an explicit named color value
6. Update project-docs/PROGRESS.md before moving on from any task — stub entries count
7. Stories: tags: ['autodocs'] on every meta; AllStates always the last export; organisms need a Mobile story

License

Proprietary — CMG Financial. All rights reserved.