{"_id":"@cmgfi/home-loans-ds","_rev":"2-7f793308c682b2c47cada9d5897aaa55","name":"@cmgfi/home-loans-ds","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@cmgfi/home-loans-ds","version":"0.1.0","_id":"@cmgfi/home-loans-ds@0.1.0","maintainers":[{"name":"andyg-cmg-xd","email":"andyg@cmgfi.com"}],"homepage":"https://github.com/cmg-pilot-program/home-loans-ds#readme","bugs":{"url":"https://github.com/cmg-pilot-program/home-loans-ds/issues"},"dist":{"shasum":"46d24cd61cb3828c2ef216cc5e7ee32bb35e3fbb","tarball":"https://registry.npmjs.org/@cmgfi/home-loans-ds/-/home-loans-ds-0.1.0.tgz","fileCount":19,"integrity":"sha512-a3deqo0n7xfrxvPrX89EJ+rrS0+1ARX8T6Y4Vz9Sle+Bos0Fw/iBDCVBXL/DejpBJ/S9hhFXd929bjtiUkVUgA==","signatures":[{"sig":"MEUCIA/lpv4DojyQosGIFVQBVEfIm6Z78cHTIBpZvfRP8rdUAiEAmPig/FqkPNNEh1AyhaUixashyW8zK3+eFy/eUG5y8+w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4453833},"type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./styles":"./dist/index.css","./tokens":"./dist/tokens/tokens.css","./tokens/cmghl":"./dist/tokens/cmghl.css","./data/us-states":{"types":"./dist/data/us-states.d.ts","import":"./dist/data/us-states.mjs","require":"./dist/data/us-states.cjs"}},"gitHead":"d7f85b761614370288844a3de2811068c8d9a3ef","scripts":{"dev":"storybook dev -p 6006","build":"vite build","postbuild":"mkdir -p dist/tokens && cp src/tokens/tokens.css dist/tokens/tokens.css && cp src/tokens/cmghl.css dist/tokens/cmghl.css && mv dist/us-states.d.ts dist/data/us-states.d.ts","prepublishOnly":"npm run build","build-storybook":"storybook build"},"_npmUser":{"name":"andyg-cmg-xd","email":"andyg@cmgfi.com"},"repository":{"url":"git+https://github.com/cmg-pilot-program/home-loans-ds.git","type":"git"},"_npmVersion":"11.5.2","description":"CMG Home Loans Dotcom Design System — React components extracted from cmgfi.com production","directories":{},"_nodeVersion":"22.18.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^5.0.0","react":"^18.0.0","react-dom":"^18.0.0","storybook":"^8.0.0","typescript":"^5.0.0","@types/react":"^18.0.0","vite-plugin-dts":"^3.0.0","@storybook/react":"^8.0.0","@types/react-dom":"^18.0.0","@vitejs/plugin-react":"^5.1.4","@storybook/react-vite":"^8.0.0","@storybook/addon-viewport":"^8.0.0","@storybook/addon-essentials":"^8.0.0","@storybook/addon-interactions":"^8.0.0","@fortawesome/react-fontawesome":"^0.2.2","@fortawesome/fontawesome-svg-core":"^6.5.2","@fortawesome/free-solid-svg-icons":"^6.5.2","@fortawesome/free-regular-svg-icons":"^6.5.2"},"peerDependencies":{"react":">=17","react-dom":">=17","@googlemaps/js-api-loader":">=1","@fortawesome/react-fontawesome":">=0.2","@fortawesome/fontawesome-svg-core":">=6","@fortawesome/free-solid-svg-icons":">=6"},"peerDependenciesMeta":{"@googlemaps/js-api-loader":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/home-loans-ds_0.1.0_1779902975518_0.44087967923916804","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cmgfi/home-loans-ds","version":"0.1.1","description":"CMG Home Loans Dotcom Design System — React components extracted from cmgfi.com production","repository":{"type":"git","url":"git+https://github.com/cmg-pilot-program/home-loans-ds.git"},"type":"module","exports":{".":{"import":"./dist/index.mjs","require":"./dist/index.cjs","types":"./dist/index.d.ts"},"./data/us-states":{"import":"./dist/data/us-states.mjs","require":"./dist/data/us-states.cjs","types":"./dist/data/us-states.d.ts"},"./tokens":"./dist/tokens/tokens.css","./tokens/cmghl":"./dist/tokens/cmghl.css","./styles":"./dist/index.css"},"scripts":{"dev":"storybook dev -p 6006","build":"vite build","postbuild":"mkdir -p dist/tokens && cp src/tokens/tokens.css dist/tokens/tokens.css && cp src/tokens/cmghl.css dist/tokens/cmghl.css && mv dist/us-states.d.ts dist/data/us-states.d.ts","build-storybook":"storybook build","prepublishOnly":"npm run build"},"peerDependencies":{"react":">=17","react-dom":">=17","@fortawesome/react-fontawesome":">=0.2","@fortawesome/fontawesome-svg-core":">=6","@fortawesome/free-solid-svg-icons":">=6","@googlemaps/js-api-loader":">=1"},"peerDependenciesMeta":{"@googlemaps/js-api-loader":{"optional":true}},"devDependencies":{"@storybook/addon-essentials":"^8.0.0","@storybook/addon-interactions":"^8.0.0","@storybook/addon-viewport":"^8.0.0","@storybook/react":"^8.0.0","@storybook/react-vite":"^8.0.0","@types/react":"^18.0.0","@types/react-dom":"^18.0.0","@vitejs/plugin-react":"^5.1.4","@fortawesome/fontawesome-svg-core":"^6.5.2","@fortawesome/free-solid-svg-icons":"^6.5.2","@fortawesome/free-regular-svg-icons":"^6.5.2","@fortawesome/react-fontawesome":"^0.2.2","react":"^18.0.0","react-dom":"^18.0.0","storybook":"^8.0.0","typescript":"^5.0.0","vite":"^5.0.0","vite-plugin-dts":"^3.0.0"},"publishConfig":{"access":"public"},"_id":"@cmgfi/home-loans-ds@0.1.1","gitHead":"961acbf16c2677938a893d1f2e8d8969b06d7337","bugs":{"url":"https://github.com/cmg-pilot-program/home-loans-ds/issues"},"homepage":"https://github.com/cmg-pilot-program/home-loans-ds#readme","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-fPVmgxTPTWHo4ts4oQCH2TtB6H9RUQlki5KWO9s4LHLkbR9YoAlk9VNPIVI++z4WenJ1pD8p9q/hh/M3G0sidQ==","shasum":"9dc499efd7c66bf4f104dc94402d4d0737cd8d3a","tarball":"https://registry.npmjs.org/@cmgfi/home-loans-ds/-/home-loans-ds-0.1.1.tgz","fileCount":19,"unpackedSize":4453833,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICdyLF3hTTuHkUxpMvfqg3Yqro5MDC4VmoZNsFPpHYqnAiB5xjG9El/XlLmFmNMGx5jlumLvhc/+Qc86AF5AhNX51A=="}]},"_npmUser":{"name":"andyg-cmg-xd","email":"andyg@cmgfi.com"},"directories":{},"maintainers":[{"name":"andyg-cmg-xd","email":"andyg@cmgfi.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/home-loans-ds_0.1.1_1779906054309_0.5310243595472866"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-27T17:29:35.408Z","modified":"2026-05-27T18:20:54.761Z","0.1.0":"2026-05-27T17:29:35.815Z","0.1.1":"2026-05-27T18:20:54.618Z"},"bugs":{"url":"https://github.com/cmg-pilot-program/home-loans-ds/issues"},"homepage":"https://github.com/cmg-pilot-program/home-loans-ds#readme","repository":{"type":"git","url":"git+https://github.com/cmg-pilot-program/home-loans-ds.git"},"description":"CMG Home Loans Dotcom Design System — React components extracted from cmgfi.com production","maintainers":[{"name":"andyg-cmg-xd","email":"andyg@cmgfi.com"}],"readme":"# CMG Home Loans Dotcom Design System\n\nA React component library and design token system extracted from production [cmgfi.com](https://www.cmgfi.com).\n\n**Storybook:** [home-loans-ds.cmgfinancial.ai](https://home-loans-ds.cmgfinancial.ai)\n**npm:** [`@cmgfi/home-loans-ds`](https://www.npmjs.com/package/@cmgfi/home-loans-ds)\n\n---\n\n## Overview\n\nThe Home Loans Dotcom Design System (Home Loans DS) provides:\n\n- **Design tokens** — CSS custom properties covering color, spacing, typography, elevation, and iconography\n- **68 components** — atoms, molecules, organisms, and navigation built to match cmgfi.com pixel-for-pixel\n- **Two brand themes** — CMG (base) for cmgfi.com and CMGHL (retail) as an opt-in override layer\n- **Full TypeScript support** — a single rolled-up `index.d.ts` ships with the package\n- **Zero runtime overhead** — CSS Modules only; no CSS-in-JS or runtime theming\n\nComponents are built from scratch to match the cmgfi.com design language exactly. No third-party component library is used under the hood.\n\n---\n\n## Tech Stack\n\n| Concern | Choice |\n|---|---|\n| Framework | React (peer dependency — not bundled) |\n| Language | TypeScript strict |\n| Build | Vite library mode (ESM + CJS) |\n| Styles | CSS Modules |\n| Icons | Font Awesome 6 free-solid (peer dependency) + 8 custom calculator-mode SVGs shipped from this package |\n| Docs / QA | Storybook v8 |\n\n---\n\n## Installation\n\n```bash\nnpm install @cmgfi/home-loans-ds\n```\n\n**Peer dependencies** — install these in your consuming app if not already present:\n\n```bash\nnpm install react react-dom \\\n  @fortawesome/react-fontawesome \\\n  @fortawesome/fontawesome-svg-core \\\n  @fortawesome/free-solid-svg-icons\n```\n\n**Optional peer dependency** (only if you use `<Map>` with Google Maps):\n\n```bash\nnpm install @googlemaps/js-api-loader\n```\n\n---\n\n## Usage\n\n### 1. Import tokens and styles\n\nOnce, in your app root (e.g. `main.tsx` or `App.tsx`):\n\n```tsx\nimport '@cmgfi/home-loans-ds/tokens';   // base (CMG) design tokens\nimport '@cmgfi/home-loans-ds/styles';   // compiled component styles + webfonts\n```\n\n### 2. (Optional) Apply the CMGHL retail brand override\n\nLoaded **after** the base tokens, this re-aliases the tertiary color palette from aqua (CMG) to green (CMGHL):\n\n```tsx\nimport '@cmgfi/home-loans-ds/tokens';\nimport '@cmgfi/home-loans-ds/tokens/cmghl';   // ← override, loaded AFTER base\nimport '@cmgfi/home-loans-ds/styles';\n```\n\nPreview the brand delta in the [**Brand themes**](https://home-loans-ds.cmgfinancial.ai/?path=/docs/brand-themes-overview--docs) section of Storybook.\n\n### 3. Import components\n\n```tsx\nimport { Button, Heading, Text, SiteHeader, SiteFooter, MortgageCalculator } from '@cmgfi/home-loans-ds';\n\nexport default function HomePage() {\n  return (\n    <>\n      <SiteHeader contactNumber=\"800-501-2001\" />\n      <main>\n        <Heading level={1}>Welcome home.</Heading>\n        <Text size=\"large\">Apply online in about 15 minutes.</Text>\n        <Button variant=\"primary\" size=\"lg\">Get Started</Button>\n      </main>\n      <SiteFooter />\n    </>\n  );\n}\n```\n\n### 4. Use icons\n\nFont Awesome 6 free-solid icons are imported directly — no global stylesheet needed:\n\n```tsx\nimport { FontAwesomeIcon } from '@fortawesome/react-fontawesome';\nimport { faChevronRight } from '@fortawesome/free-solid-svg-icons';\n\n<FontAwesomeIcon icon={faChevronRight} />\n```\n\nFor consistent sizing with the design system's icon tokens, use the wrapped `<Icon>` component:\n\n```tsx\nimport { Icon } from '@cmgfi/home-loans-ds';\nimport { faPhone } from '@fortawesome/free-solid-svg-icons';\n\n<Icon icon={faPhone} size=\"md\" color=\"primary\" />\n```\n\nThe 8 calculator-mode glyphs (mortgage, savings, biweekly, qualifying, purchase, short/long, rent-vs-buy, buydown) ship as React components directly from this package:\n\n```tsx\nimport { MortgageIcon, BiWeeklyIcon } from '@cmgfi/home-loans-ds';\n\n<MortgageIcon />\n```\n\n---\n\n## Component library\n\n### Atoms (20)\n\nFoundational UI primitives.\n\n| Component | Description |\n|---|---|\n| `Button` / `ButtonLink` | Primary, secondary, tertiary, and link variants (4 sizes) |\n| `Link` | Inline and standalone hyperlink styles |\n| `Heading` | h1–h6 with color/level controls |\n| `Text` | Body text with size, weight, and color variants |\n| `Icon` | Token-sized FontAwesome wrapper with color slots |\n| `Divider` | Horizontal/vertical rule (3 emphasis levels) |\n| `Spinner` | Loading spinner (3 sizes, 4 colors) |\n| `Label`, `HelperText`, `ErrorText` | Form-label primitives |\n| `Input`, `NumericInput`, `Textarea`, `Select`, `Checkbox`, `Radio` | Form controls |\n| `Avatar` | Initials + image circle |\n| `Logo` | CMG / CMG Home Loans lockup |\n| `PlayButton` | Video play overlay (3 sizes, 2 variants) |\n| `CalcIcons` | 8 calculator-mode SVG glyphs |\n\n### Molecules (27)\n\nComposed from atoms.\n\n| Component | Description |\n|---|---|\n| `FormField` | Label + input + helper + error wrapper |\n| `SearchInput` | Search input with leading icon and clear button |\n| `CTAStrip` | Multi-CTA banner (3 layouts, 3 surfaces) |\n| `Breadcrumb` | Hierarchical page path |\n| `AlertBanner` | Severity alert banner (info / success / warning / error) |\n| `Card` | Generic content card (4 elevations) |\n| `FeatureWithIcon` | Icon + heading + description block |\n| `IconCard` | Icon-anchored card variant |\n| `StatBlock` | Big-number stat block |\n| `HowItWorksStep` | Numbered/iconed step (horizontal/vertical) |\n| `VideoContainer`, `VideoCard` | Video poster + play button |\n| `LoanProductCard`, `LoanOfficerCard` | Product / LO summary cards |\n| `NavTab`, `NavTabGroup` | Tabbed navigation primitives |\n| `NavDropdown` | Click-to-open dropdown menu |\n| `ReviewSummary` | Stars + count + caption |\n| `TestimonialQuote` | Quoted testimonial block |\n| `AccordionItem` | Single accordion row |\n| `Tooltip` | Hover tooltip (4 placements) |\n| `CalcRow`, `CalcResultPanel`, `DonutChart` | Calculator primitives |\n| `StateMap`, `Map` | US state SVG and Google-Map embed |\n| `ImageCopyBlock` | Image + copy two-column block |\n\n### Organisms (17)\n\nPage-level sections composed from molecules and atoms.\n\n| Component | Description |\n|---|---|\n| `HeroWithCTA` | Marketing hero with optional CTAs and overlay |\n| `HeroWithVideo` | Hero with video background or side-by-side video |\n| `HeroSlim` | Compact one-line hero |\n| `MortgageCalculator` | Basic + advanced mortgage calculator |\n| `HowItWorksSection` | Multi-step process section |\n| `FeatureListSection` | Feature-icon grid (2/3/4 columns) |\n| `ImageCopyBlockSection` | Image + copy section wrapper |\n| `FAQAccordion` | FAQ list with single or multi-open mode |\n| `LoanProductGrid` | Loan-product card grid |\n| `LoanProductTabPanel` | Tabbed loan-product panel |\n| `ReviewsWidget` | Aggregated reviews summary band |\n| `TestimonialsCarousel` | Auto-rotating testimonial slider |\n| `FindLoanOfficerSearch` | Search form for loan officers |\n| `LoanOfficerResults` | LO search-results grid |\n| `LoanOfficerBar` | Sticky LO contact bar |\n| `CtaSection` | Full-bleed CTA section (5 surfaces) |\n| `HomeAppPromo` | iOS/Android app-store promo block |\n\n### Navigation (4)\n\nSite chrome.\n\n| Component | Description |\n|---|---|\n| `SiteHeader` | Desktop utility band (phone + social + language + login) |\n| `SiteNavigator` | Desktop primary nav bar (logo + items + utility actions + CTA) |\n| `SiteNavigatorMobile` | Mobile drawer (slide-out left, expandable rows) |\n| `SiteFooter` | Site-wide footer with link columns, social, and legal |\n\n---\n\n## Design tokens\n\nAll design tokens are CSS custom properties defined in `dist/tokens/tokens.css`. The full reference lives under the [**Tokens**](https://home-loans-ds.cmgfinancial.ai/?path=/docs/tokens-colors--docs) section of Storybook.\n\n| Category | Examples |\n|---|---|\n| **Color (palette)** | `--color-green-50` → `--color-green-900` (primary); `--color-teal-*` (secondary); `--color-aqua-*` (tertiary base); `--color-gray-*` (neutrals) |\n| **Color (semantic)** | `--color-text`, `--color-text-secondary`, `--color-background`, `--color-surface`, `--color-border`, `--color-focus-ring`, `--color-primary`, `--color-secondary`, `--color-tertiary` |\n| **Spacing** | `--spacing-02` → `--spacing-40` (numeric); `--spacing-xxxs` → `--spacing-xxl` (named aliases) |\n| **Typography** | `--font-family-body` (Open Sans); `--font-family-heading` (Kadwa); `.text-h1` → `.text-h6`; `.text-[xl\\|large\\|normal\\|small]-[bold\\|semibold\\|regular]` |\n| **Elevation** | 4 shadow depth levels + 1 scrim overlay |\n| **Iconography** | `--icon-size-sm` / `--icon-size-md` / `--icon-size-lg` / `--icon-size-xl` |\n\n### Brand-theme delta\n\nPer source-code audit of [`cmg.website-new`](https://dev.azure.com/cmgfidev/Marketing%20Experience/_git/cmg.website-new), CMGHL re-aliases only the tertiary semantic tokens:\n\n| Token | CMG base | CMGHL override |\n|---|---|---|\n| `--color-tertiary` | Aqua 500 `#32A4AC` | Green 500 `#92C13B` |\n| `--color-tertiary-hover` | Aqua 600 `#2D949B` | Green 600 `#82AD34` |\n| `--color-tertiary-active` | Aqua 700 `#25787E` | Green 700 `#6A8D2A` |\n\nThe aqua palette (`--color-aqua-*`) remains available under both themes — only the semantic alias shifts.\n\n---\n\n## Source-of-truth model\n\nThis design system is extracted from two complementary sources — neither alone is sufficient:\n\n1. **Live cmgfi.com** is the visual ground truth. Production rendering = what users actually see.\n2. **`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.\n\nWhen a component renders incorrectly, the visual diff against cmgfi.com is the authoritative check.\n\n---\n\n## Development\n\n```bash\n# Clone the repo\ngit clone https://github.com/cmg-pilot-program/home-loans-ds.git\ncd home-loans-ds\n\n# Install dependencies\nnpm install\n\n# Start Storybook dev server (http://localhost:6006)\nnpm run dev\n\n# Build the library\nnpm run build\n\n# Build Storybook static site\nnpm run build-storybook\n```\n\nReleases are CI-driven — see [`RELEASING.md`](./RELEASING.md).\n\n---\n\n## Contributing\n\n1. Read `CLAUDE.md` at the project root before contributing — it defines the invariant component pattern and the read-only rule for `cmg.website-new/`\n2. Every component requires `React.forwardRef`, a `displayName`, and `...props` spread\n3. CSS Modules only — no hardcoded hex values or pixel spacing; token vars exclusively\n4. Use semantic color aliases (`--color-text`, `--color-focus-ring`) — never raw palette steps (`--color-green-400`)\n5. Never derive a color via `opacity` or `rgba(…, <alpha>)` — use an explicit named color value\n6. Update `project-docs/PROGRESS.md` before moving on from any task — stub entries count\n7. Stories: `tags: ['autodocs']` on every meta; `AllStates` always the last export; organisms need a `Mobile` story\n\n---\n\n## License\n\nProprietary — CMG Financial. All rights reserved.\n","readmeFilename":"README.md"}