@cmgfi/clear-ds 1.0.1 → 1.1.1

package/dist/llms.txt

@@ -0,0 +1,1642 @@
+# @cmgfi/clear-ds — Clear Design System
+
+> CMG Financial's official React component library. The UI foundation for CMG's internal loan origination platform. 55+ fully-typed components, a complete CSS custom property token system, and Storybook documentation. Built with React, TypeScript, Vite, and CSS Modules.
+
+## Install
+
+```bash
+# With PrimeIcons (recommended — required for icon-bearing components)
+npm install @cmgfi/clear-ds primeicons
+
+# Without PrimeIcons
+npm install @cmgfi/clear-ds
+```
+
+## Setup (app root, once)
+
+```tsx
+import '@cmgfi/clear-ds/tokens';       // CSS custom property definitions (:root)
+import '@cmgfi/clear-ds/styles';       // compiled component styles
+import 'primeicons/primeicons.css';    // omit if PrimeIcons not installed
+```
+
+```css
+/* Required: token scale is built on 1rem = 12px */
+html { font-size: 12px; }
+```
+
+## Basic usage
+
+```tsx
+import { Button, InputText, Modal, DataTable } from '@cmgfi/clear-ds';
+
+<Button variant="primary" size="md" onClick={handleSave}>Save application</Button>
+<InputText label="First name" value={value} onChange={e => setValue(e.target.value)} />
+```
+
+---
+
+## Tokens
+
+The token system has two layers: **primitive tokens** (the raw scale) and **semantic tokens** (purpose-named aliases). Always reach for a semantic token first. Use a primitive only when no semantic alias covers your use case.
+
+### How to use tokens
+
+```css
+/* In component CSS or consumer stylesheets */
+.my-heading { color: var(--color-text-heading); }
+.my-card    { background: var(--color-surface-default); border: 1px solid var(--color-border-primary); }
+.my-button  { background: var(--color-brand-primary); border-radius: var(--radius-md); transition: background var(--transition-normal); }
+.my-input:focus { box-shadow: var(--focus-ring); }
+```
+
+### Semantic tokens — Text Colors
+
+| Token | Value | Use when |
+|---|---|---|
+| `--color-text-heading` | `--navy-800` | Page headings, section titles, panel headers |
+| `--color-text-body` | `--navy-800` | Body copy, descriptions, content paragraphs |
+| `--color-text-label` | `--navy-800` | Form field labels, data column headers |
+| `--color-text-helper` | `--navy-400` | Helper text, subtitles, field descriptions |
+| `--color-text-placeholder` | `--navy-300` | Input placeholder text |
+| `--color-text-disabled` | `--navy-300` | Disabled input and control text |
+| `--color-text-error` | `--red-600` | Validation error messages |
+| `--color-text-link` | `--teal-700` | Hyperlinks, inline interactive text |
+| `--color-text-link-hover` | `--teal-900` | Hovered hyperlinks |
+| `--color-text-inverse` | `--surface-50` | Text on dark or brand-colored surfaces |
+
+### Semantic tokens — Text Sizes
+
+Base: `1rem = 12px` (consumer app sets `html { font-size: 12px }`).
+
+| Token | Value | Use when |
+|---|---|---|
+| `--font-size-hero` | `48px` | Hero banners, display text |
+| `--font-size-title` | `38px` | Major page titles |
+| `--font-size-section` | `32px` | Section headings |
+| `--font-size-panel` | `20px` | Panel and card headings |
+| `--font-size-subheading` | `18px` | Subheadings, intro paragraphs |
+| `--font-size-label` | `14px` | Form labels, prominent body text |
+| `--font-size-body` | `12px` | Standard body text (= 1rem) |
+| `--font-size-caption` | `10px` | Captions, helper text, badge labels |
+| `--font-weight-bold` | `700` | Headings, strong emphasis |
+| `--font-weight-semibold` | `600` | Labels, medium emphasis |
+| `--font-weight-regular` | `400` | Body copy, field values |
+| `--line-height-heading` | `1.2` | Headings and titles — tight |
+| `--line-height-body` | `1.4` | Body copy and labels — comfortable |
+
+Typography utility classes (`.text-h1`–`.text-h6`, `.text-large-bold`, `.text-normal-regular`, etc.) also exist and apply a full set of `font-size`, `font-weight`, and `color` in one class. Use the CSS vars above when you need the value itself; use the classes when you want to apply the full style at once.
+
+### Semantic tokens — Surfaces
+
+| Token | Value | Use when |
+|---|---|---|
+| `--color-surface-default` | `--surface-50` | White — base page/card/input background |
+| `--color-surface-secondary` | `--surface-200` | Secondary panels, alternate rows |
+| `--color-surface-elevated` | `--surface-100` | Popovers, dropdowns, cards that float |
+| `--color-surface-hover` | `--surface-200` | Hover background on list/menu items |
+| `--color-surface-disabled` | `--surface-300` | Disabled input/field background |
+| `--color-surface-selected` | `--teal-50` | Selected row or active item background |
+| `--color-surface-overlay` | `--scrim` | Modal and drawer backdrop |
+
+### Semantic tokens — Borders
+
+| Token | Value | Use when |
+|---|---|---|
+| `--color-border-primary` | `--navy-100` | Default input, card, and container borders |
+| `--color-border-secondary` | `--navy-200` | Stronger dividers, tab borders |
+| `--color-border-tertiary` | `--surface-500` | Very light internal dividers |
+| `--color-border-brand` | `--teal-100` | Soft brand-colored border |
+| `--color-border-brand-strong` | `--teal-200` | Stronger brand border — hover of soft elements |
+| `--color-border-focus` | `--teal-500` | Focused input border ring |
+| `--color-border-error` | `--red-600` | Error/invalid state border |
+
+### Semantic tokens — Brand
+
+Use `--color-brand-*` for any element whose color comes from the CMG brand (teal). This replaces raw `--teal-*` usage in component code.
+
+| Token | Value | Use when |
+|---|---|---|
+| `--color-brand-primary` | `--teal-700` | Primary brand color — buttons, links, toggles |
+| `--color-brand-primary-hover` | `--teal-800` | Hover over primary brand elements |
+| `--color-brand-primary-active` | `--teal-900` | Pressed/active primary brand elements |
+| `--color-brand-primary-bg` | `--teal-50` | Tinted background for brand-highlighted areas |
+| `--color-brand-secondary` | `--teal-500` | Secondary brand — focus indicators, data markers |
+| `--color-brand-secondary-hover` | `--teal-600` | Hover over secondary brand elements |
+
+### Semantic tokens — Status
+
+Grouped under `--color-status-*` so all status colors are discoverable together.
+
+| Token | Value | Use when |
+|---|---|---|
+| `--color-status-error` | `--red-600` | Error text, icons |
+| `--color-status-error-hover` | `--red-700` | Hovered error elements |
+| `--color-status-error-bg` | `--red-50` | Error background tint |
+| `--color-status-error-border` | `--red-600` | Error borders |
+| `--color-status-warning` | `--yellow-600` | Warning text, icons |
+| `--color-status-warning-bg` | `--yellow-50` | Warning background tint |
+| `--color-status-warning-border` | `--yellow-200` | Warning borders |
+| `--color-status-success` | `--green-500` | Success text, icons |
+| `--color-status-success-bg` | `--green-50` | Success background tint |
+| `--color-status-success-border` | `--green-200` | Success borders |
+| `--color-status-info` | `--blue-500` | Info text, icons |
+| `--color-status-info-bg` | `--blue-50` | Info background tint |
+| `--color-status-info-border` | `--blue-200` | Info borders |
+
+### Semantic tokens — Focus, Radius, Motion, Z-Index
+
+```css
+/* Focus rings — use on :focus-visible */
+--focus-ring:        0 0 0 2px var(--surface-50), 0 0 0 6px var(--teal-700)
+--focus-ring-inset:  inset 0 0 0 2px var(--teal-700)
+
+/* Border radius */
+--radius-sm:    4px     /* chips, tags, badges */
+--radius-md:    6px     /* inputs, cards, buttons */
+--radius-lg:    8px     /* modals, drawers */
+--radius-full:  9999px  /* pill buttons, circular avatars */
+
+/* Transitions */
+--transition-fast:    80ms ease   /* hover color changes */
+--transition-normal:  120ms ease  /* standard state changes */
+--transition-slow:    200ms ease  /* expand/collapse, panel slides */
+
+/* Z-index scale */
+--z-sticky:       100   /* sticky headers */
+--z-dropdown:     200   /* dropdowns, menus */
+--z-overlay:      300   /* modals, drawers */
+--z-notification: 400   /* toasts */
+--z-tooltip:      500   /* tooltips */
+```
+
+### Primitive tokens (reference)
+
+Raw color primitives remain available but should only be used when no semantic alias fits. Color families: `--teal-50`–`--teal-900`, `--navy-50`–`--navy-900`, `--surface-50`–`--surface-900`, `--red-50`–`--red-900`, `--yellow-50`–`--yellow-900`, `--green-50`–`--green-900`, `--blue-50`–`--blue-900`. Spacing: `--spacing-02` through `--spacing-40` (numeric) and `--spacing-xxxs` through `--spacing-xxl` (named). Elevation: `--shadow-depth-1` through `--shadow-depth-4`.
+
+---
+
+## Components
+
+### Button
+
+```tsx
+import { Button } from '@cmgfi/clear-ds';
+import type { ButtonProps, ButtonVariant, ButtonSize } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `variant`: `'primary' | 'secondary' | 'ghost' | 'danger' | 'link'` — default `'primary'`
+- `size`: `'md' | 'sm'` — `md` = 40px height (default), `sm` = 24px height
+- `leadingIcon`: ReactNode — rendered before the label
+- `trailingIcon`: ReactNode — rendered after the label
+- `badge`: `string | number` — red notification badge rendered after the label
+- `disabled`: boolean
+- Extends `React.ButtonHTMLAttributes<HTMLButtonElement>`
+
+```tsx
+<Button variant="primary" size="md">Save application</Button>
+<Button variant="secondary" leadingIcon={<i className="pi pi-plus" />}>Add co-borrower</Button>
+<Button variant="danger">Delete record</Button>
+<Button variant="link">View details</Button>
+<Button variant="primary" disabled leadingIcon={<i className="pi pi-spin pi-spinner" />}>Saving…</Button>
+<Button badge={3} trailingIcon={<i className="pi pi-chevron-down" />}>Actions</Button>
+```
+
+---
+
+### IconButton
+
+```tsx
+import { IconButton } from '@cmgfi/clear-ds';
+import type { IconButtonProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `icon`: ReactNode — the icon to display (e.g. `<i className="pi pi-search" />`)
+- `variant`: `ButtonVariant` — same variants as Button, default `'primary'`
+- `size`: `'md' | 'sm'` — `md` = 40×40px (default), `sm` = 24×24px
+- `aria-label`: string — **required** (no visible text)
+- `disabled`: boolean
+- Extends `React.ButtonHTMLAttributes<HTMLButtonElement>`
+
+```tsx
+<IconButton icon={<i className="pi pi-search" />} aria-label="Search" />
+<IconButton icon={<i className="pi pi-trash" />} aria-label="Delete" variant="danger" />
+<IconButton icon={<i className="pi pi-plus" />} aria-label="Add" size="sm" />
+```
+
+---
+
+### DropdownButton
+
+```tsx
+import { DropdownButton } from '@cmgfi/clear-ds';
+import type { DropdownButtonProps, DropdownButtonItem } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: string — button label
+- `items`: `DropdownButtonItem[]` — `{ label: string; value: string; icon?: ReactNode; disabled?: boolean; divider?: boolean }`
+- `onSelect`: `(value: string) => void`
+- `variant`: `ButtonVariant` — default `'primary'`
+- `size`: `'md' | 'sm'` — default `'md'`
+- `leadingIcon`: ReactNode — optional icon before the label
+- `disabled`: boolean
+
+```tsx
+const items: DropdownButtonItem[] = [
+  { label: 'Edit', value: 'edit', icon: <i className="pi pi-pencil" /> },
+  { label: 'Delete', value: 'delete', icon: <i className="pi pi-trash" /> },
+];
+<DropdownButton label="Actions" items={items} variant="secondary" onSelect={handleSelect} />
+```
+
+---
+
+### SplitButton
+
+```tsx
+import { SplitButton } from '@cmgfi/clear-ds';
+import type { SplitButtonProps, SplitButtonItem } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: string — main action label
+- `onAction`: `() => void` — main button (left side) click handler
+- `items`: `SplitButtonItem[]` — `{ label: string; value: string; icon?: ReactNode; disabled?: boolean }`
+- `onSelect`: `(value: string) => void` — dropdown item selection handler
+- `variant`: `'primary' | 'secondary'` — default `'primary'`
+- `size`: `'md' | 'sm'` — `md` = 36px height (default), `sm` = 24px
+- `leadingIcon`: ReactNode — optional icon in the main action area
+- `disabled`: boolean
+- `triggerAriaLabel`: string — accessible label for the chevron trigger, default `"More options"`
+
+---
+
+### CloseButton
+
+```tsx
+import { CloseButton } from '@cmgfi/clear-ds';
+import type { CloseButtonProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `size`: `'sm' | 'md'` — `sm` = 24×24px (default), `md` = 40×40px
+- `aria-label`: string — defaults to `"Close"`
+- Extends `React.ButtonHTMLAttributes<HTMLButtonElement>`
+
+```tsx
+<CloseButton onClick={onDismiss} />
+<CloseButton aria-label="Close dialog" size="md" onClick={onClose} />
+```
+
+---
+
+### LightningButton
+
+```tsx
+import { LightningButton } from '@cmgfi/clear-ds';
+import type { LightningButtonProps, LightningButtonItem } from '@cmgfi/clear-ds';
+```
+
+Pill-shaped bolt icon + chevron dropdown. Used as a quick-actions trigger in nav bars and toolbars.
+
+Props:
+- `variant`: `'basic' | 'filled'` — `basic` = no container, teal icon (default); `filled` = teal-50 bg / teal border
+- `size`: `'md' | 'sm'` — `md` = 36px tall (default), `sm` = 24px (only meaningful for `filled`)
+- `items`: `LightningButtonItem[]` — `{ label: string; value: string; icon?: ReactNode; disabled?: boolean; divider?: boolean }`
+- `onSelect`: `(value: string) => void` — **required**
+- `disabled`: boolean
+- `aria-label`: string — accessible label (no visible text)
+
+```tsx
+<LightningButton
+  variant="filled"
+  size="sm"
+  items={[{ label: 'Copy loan', value: 'copy' }, { label: 'Export PDF', value: 'export' }]}
+  onSelect={handleSelect}
+  aria-label="Quick actions"
+/>
+```
+
+---
+
+### InputText
+
+```tsx
+import { InputText } from '@cmgfi/clear-ds';
+import type { InputTextProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: string — visible label above the input
+- `required`: boolean — appends a red asterisk to the label
+- `helperText`: string — helper or error text below the input
+- `invalid`: boolean — triggers error/red styling
+- `size`: `'sm' | 'md' | 'lg'` — default `'md'`
+- `prefixIcon`: ReactNode — rendered to the left of the input text
+- `suffixIcon`: ReactNode — rendered to the right of the input text
+- `disabled`: boolean
+- Extends `React.InputHTMLAttributes<HTMLInputElement>` (minus native `size`)
+
+```tsx
+<InputText label="Social Security Number" placeholder="000-00-0000" style={{ width: 240 }} />
+<InputText label="Annual income" required invalid helperText="Must be greater than zero." />
+<InputText label="First name" disabled value="Maria Johnson" />
+<InputText label="Search" prefixIcon={<i className="pi pi-search" />} />
+```
+
+---
+
+### TextArea
+
+```tsx
+import { TextArea } from '@cmgfi/clear-ds';
+import type { TextAreaProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: string
+- `required`: boolean — appends a red asterisk
+- `helperText`: string — turns red when `invalid` is true
+- `invalid`: boolean
+- `rows`: number — default `3`
+- `autoGrow`: boolean — height grows with content instead of scrolling
+- `maxLength`: number (via `TextareaHTMLAttributes`) — shows a live `X/N` character counter
+- `disabled`: boolean
+- Extends `React.TextareaHTMLAttributes<HTMLTextAreaElement>`
+
+```tsx
+<TextArea label="Loan notes" placeholder="Enter notes…" rows={4} />
+<TextArea label="Comments" maxLength={500} />
+<TextArea label="Description" autoGrow />
+<TextArea label="Notes" invalid helperText="This field is required." />
+```
+
+---
+
+### Checkbox
+
+```tsx
+import { Checkbox } from '@cmgfi/clear-ds';
+import type { CheckboxProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: ReactNode — visible label
+- `indeterminate`: boolean — dash state for "select all" patterns
+- `invalid`: boolean — red border and label
+- `helperText`: string — turns red when `invalid`
+- `size`: `'sm' | 'md' | 'lg'` — `sm`=14px, `md`=18px (default), `lg`=22px
+- `checked`, `onChange`, `disabled` — standard input props
+- Extends `React.InputHTMLAttributes<HTMLInputElement>`
+
+```tsx
+<Checkbox label="I agree to the terms" checked={agreed} onChange={e => setAgreed(e.target.checked)} />
+<Checkbox label="Select all" indeterminate />
+<Checkbox label="Accept terms" invalid helperText="You must accept the terms to continue." />
+<Checkbox label="Dense option" size="sm" />
+```
+
+---
+
+### RadioButton
+
+```tsx
+import { RadioButton } from '@cmgfi/clear-ds';
+import type { RadioButtonProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: ReactNode — visible label
+- `invalid`: boolean — red border and label
+- `helperText`: string — turns red when `invalid`
+- `size`: `'sm' | 'md' | 'lg'` — `sm`=14px, `md`=18px (default), `lg`=22px
+- `name`, `value`, `checked`, `onChange`, `disabled` — standard input props
+- Extends `React.InputHTMLAttributes<HTMLInputElement>`
+
+```tsx
+{['Conventional', 'FHA', 'VA'].map(type => (
+  <RadioButton key={type} name="loanType" label={type} value={type} checked={loanType === type} onChange={e => setLoanType(e.target.value)} />
+))}
+```
+
+---
+
+### Select
+
+```tsx
+import { Select } from '@cmgfi/clear-ds';
+import type { SelectProps, SelectOption } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `options`: `SelectOption[]` — `{ label: string; value: string; disabled?: boolean }`
+- `value`: `string | null` — controlled selected value
+- `onChange`: `(value: string | null) => void`
+- `placeholder`: string
+- `label`: string
+- `required`: boolean
+- `helperText`: string
+- `invalid`: boolean
+- `disabled`: boolean
+- `filter`: boolean — shows a live-search input in the dropdown
+- `filterPlaceholder`: string — default `"Search…"`
+- `size`: `'sm' | 'md' | 'lg'` — default `'md'`
+
+```tsx
+const options: SelectOption[] = [
+  { label: 'Conventional', value: 'conventional' },
+  { label: 'FHA', value: 'fha' },
+  { label: 'VA', value: 'va' },
+];
+<Select label="Loan type" options={options} value={loanType} onChange={setLoanType} />
+<Select label="Product" options={options} value={val} onChange={setVal} filter required invalid helperText="Required." />
+```
+
+---
+
+### MultiSelect
+
+```tsx
+import { MultiSelect } from '@cmgfi/clear-ds';
+import type { MultiSelectProps, MultiSelectOption } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `options`: `MultiSelectOption[]` — `{ label: string; value: string; disabled?: boolean }`
+- `value`: `string[]` — controlled selected values
+- `onChange`: `(value: string[]) => void`
+- `placeholder`: string
+- `label`: string
+- `required`: boolean
+- `helperText`: string
+- `invalid`: boolean
+- `disabled`: boolean
+- `filter`: boolean — shows a live-search input (default `true`)
+- `filterPlaceholder`: string — default `"Search…"`
+- `showSelectAll`: boolean — "Select all" checkbox in dropdown header (default `true`)
+- `size`: `'sm' | 'md' | 'lg'` — default `'md'`
+
+```tsx
+<MultiSelect label="Loan types" options={options} value={selected} onChange={setSelected} />
+```
+
+---
+
+### ListBox
+
+```tsx
+import { ListBox } from '@cmgfi/clear-ds';
+import type { ListBoxProps, ListBoxOption, ListBoxOptionGroup } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `options`: `ListBoxOption[] | ListBoxOptionGroup[]` — flat list or grouped; groups auto-detected when entries contain an `items` array
+  - `ListBoxOption`: `{ label: string; value: string; disabled?: boolean }`
+  - `ListBoxOptionGroup`: `{ label: string; items: ListBoxOption[] }`
+- `value`: `string | string[] | null` — single or multi-select
+- `onChange`: `(value: string | string[] | null) => void`
+- `multiple`: boolean — enables checkbox multi-select
+- `filter`: boolean — shows a search input above the list
+- `filterPlaceholder`: string — default `"Search…"`
+- `label`: string
+- `required`: boolean
+- `helperText`: string
+- `invalid`: boolean
+- `disabled`: boolean
+
+---
+
+### SelectButton
+
+```tsx
+import { SelectButton } from '@cmgfi/clear-ds';
+import type { SelectButtonProps, SelectButtonOption, SelectButtonBadge } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `options`: `SelectButtonOption[]` — `{ label: string; value: string; count?: number; badge?: SelectButtonBadge; disabled?: boolean }`
+  - `SelectButtonBadge`: `{ value: string | number; color: string }`
+- `value`: `string | null` — controlled selected value
+- `onChange`: `(value: string) => void`
+- `variant`: `'group' | 'options'` — `group` = joined toggle row (default); `options` = split button + dropdown
+- `label`: string — optional field label above the button
+- `required`: boolean
+- `disabled`: boolean
+- `placeholder`: string — for the `options` variant when nothing is selected
+
+```tsx
+<SelectButton
+  options={[{ label: 'Purchase', value: 'purchase' }, { label: 'Refinance', value: 'refi' }]}
+  value={loanPurpose}
+  onChange={setLoanPurpose}
+/>
+```
+
+---
+
+### DatePicker
+
+```tsx
+import { DatePicker } from '@cmgfi/clear-ds';
+import type { DatePickerProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `value`: `Date | null` — controlled selected date
+- `onChange`: `(date: Date | null) => void`
+- `label`: string
+- `required`: boolean
+- `helperText`: string
+- `invalid`: boolean
+- `disabled`: boolean
+- `placeholder`: string — default `"MM/DD/YYYY"`
+- `minDate`: Date — dates before this are disabled
+- `maxDate`: Date — dates after this are disabled
+- `showWeekNumbers`: boolean — shows ISO week numbers in the calendar
+
+---
+
+### ToggleSwitch
+
+```tsx
+import { ToggleSwitch } from '@cmgfi/clear-ds';
+import type { ToggleSwitchProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: ReactNode — label to the right of the switch
+- `helperText`: string — shown below the switch row
+- `checked`, `onChange`, `disabled`, `defaultChecked` — standard input props
+- Extends `React.InputHTMLAttributes<HTMLInputElement>`
+
+```tsx
+<ToggleSwitch label="Enable notifications" checked={on} onChange={e => setOn(e.target.checked)} />
+<ToggleSwitch label="Auto-lock" defaultChecked />
+<ToggleSwitch label="Feature locked" disabled />
+```
+
+---
+
+### FileUpload
+
+```tsx
+import { FileUpload, DEFAULT_DOC_TYPES } from '@cmgfi/clear-ds';
+import type { FileUploadProps, FileUploadResult } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `onUpload`: `(files: FileUploadResult[]) => void` — **required**; called when the Upload button is clicked with all classified files; `FileUploadResult`: `{ file: File; docType: string }`
+- `onFilesAdded`: `(files: File[]) => void` — called immediately after files are dropped/selected (before classification)
+- `docTypes`: `string[]` — document type options in the per-file dropdown; defaults to `DEFAULT_DOC_TYPES` (8 standard mortgage doc types)
+- `accept`: string — accepted file extensions; defaults to common image, PDF, and Office formats
+- `initialFiles`: `File[]` — pre-populate the staged file queue on mount (for testing/Storybook)
+
+```tsx
+<FileUpload
+  accept=".pdf,image/*"
+  onFilesAdded={files => console.log('Added:', files)}
+  onUpload={results => results.forEach(r => upload(r.file, r.docType))}
+/>
+```
+
+---
+
+### DataTable
+
+```tsx
+import { DataTable } from '@cmgfi/clear-ds';
+import type {
+  DataTableProps, DataTableColumn, DataTableGroup, DataTableExpansion,
+  SortOrder, SortMeta, SelectionMode, EditMode,
+  ColumnFilter, FilterOption, FilterGroup, FilterType, RuleFilterValue
+} from '@cmgfi/clear-ds';
+```
+
+Feature-rich data grid. Props:
+- `data`: `T[] | DataTableGroup<T>[]` — flat rows or pre-grouped data
+  - `DataTableGroup<T>`: `{ label: string; data: T[]; defaultExpanded?: boolean }`
+- `columns`: `DataTableColumn<T>[]`
+  - `field`: string
+  - `header`: ReactNode
+  - `sortable`: boolean
+  - `filter`: `ColumnFilter` — attach a filter popover
+  - `body`: `(row: T, index: number) => ReactNode` — custom cell renderer
+  - `editor`: `(row: T, field: string, onChange: (val: unknown) => void) => ReactNode`
+  - `footer`: ReactNode or `(data: T[]) => ReactNode`
+  - `width`: number | string
+  - `align`: `'left' | 'center' | 'right'`
+- `dataKey`: string — unique row identifier field, default `'id'`
+- `selectionMode`: `'none' | 'single' | 'multiple'`
+- `selection`: `T | T[] | null` — controlled selection
+- `onSelectionChange`: `(sel: T | T[] | null) => void`
+- `sortMode`: `'single' | 'multiple'`
+- `sortField`: string
+- `sortOrder`: `SortOrder` (`1 | -1`)
+- `multiSortMeta`: `SortMeta[]`
+- `onSort`: `(e: { field: string; order: SortOrder; multiSortMeta?: SortMeta[] }) => void`
+- `expansion`: `DataTableExpansion<T>` — `{ dataKey: string; childKey?: string; template?: (row: T) => ReactNode; columns?: DataTableColumn<T>[] }`
+- `editMode`: `'row' | 'cell'`
+- `onRowEditSave`: `(updated: T, original: T) => void`
+- `onCellEdit`: `(row: T, field: string, value: unknown) => void`
+- `stripedRows`: boolean
+- `size`: `'sm' | 'md'` — `sm` = compact (6px padding)
+- `showFooter`: boolean
+- `loading`: boolean — shows a skeleton placeholder
+- `emptyMessage`: ReactNode
+- `scrollable`: boolean
+- `scrollHeight`: string
+
+```tsx
+const columns: DataTableColumn<Loan>[] = [
+  { field: 'borrowerName', header: 'Borrower', sortable: true },
+  { field: 'loanAmount', header: 'Amount', align: 'right', body: row => `$${row.loanAmount.toLocaleString()}` },
+  { field: 'status', header: 'Status', body: row => <SeverityChip severity={row.statusSeverity} label={row.status} /> },
+];
+<DataTable data={loans} columns={columns} selectionMode="multiple" selection={selected} onSelectionChange={setSelected} />
+```
+
+---
+
+### Paginator
+
+```tsx
+import { Paginator } from '@cmgfi/clear-ds';
+import type { PaginatorProps, PageChangeEvent } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `totalRecords`: number
+- `first`: number — 0-based index of the first record on the current page
+- `rows`: number — records per page
+- `onPageChange`: `(e: PageChangeEvent) => void` — `PageChangeEvent`: `{ first: number; rows: number; page: number }`
+- `template`: `'pages' | 'report' | 'full'` — layout variant (default `'pages'`)
+- `rowsPerPageOptions`: `number[]` — default `[10, 25, 50, 100]`
+- `pageLinkSize`: number — max visible page buttons (default `5`)
+
+```tsx
+<Paginator totalRecords={1240} first={first} rows={25} onPageChange={e => setFirst(e.first)} />
+```
+
+---
+
+### Picklist
+
+```tsx
+import { Picklist } from '@cmgfi/clear-ds';
+import type { PicklistProps, PicklistItem, PicklistChangeEvent } from '@cmgfi/clear-ds';
+```
+
+Dual-panel transfer control. Props:
+- `sourceItems`: `PicklistItem[]` — `{ id: string | number; label?: string; icon?: string; disabled?: boolean; [key: string]: unknown }`
+- `targetItems`: `PicklistItem[]`
+- `onChange`: `(e: PicklistChangeEvent) => void` — `PicklistChangeEvent`: `{ source: PicklistItem[]; target: PicklistItem[] }`
+- `sourceHeader`: ReactNode
+- `targetHeader`: ReactNode
+- `itemTemplate`: `(item: PicklistItem) => ReactNode` — custom row renderer (after the checkbox)
+- `filter`: boolean — shows a search input in each panel
+- `sourceFilterPlaceholder`: string
+- `targetFilterPlaceholder`: string
+- `showMoveAll`: boolean — show `>>` / `<<` buttons (default `true`)
+- `showCheckbox`: boolean — show per-row checkboxes (default `true`)
+
+---
+
+### Card
+
+```tsx
+import { Card } from '@cmgfi/clear-ds';
+import type { CardProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `title`: ReactNode — bold primary title
+- `subTitle`: ReactNode — muted subtitle below the title
+- `footer`: ReactNode — action area at the bottom (typically buttons)
+- `children`: ReactNode — card body
+- `onClick`: `React.MouseEventHandler<HTMLDivElement>` — makes the card interactive with hover shadow lift
+
+```tsx
+<Card title="Loan Summary" subTitle="Application #12345" footer={<Button>View</Button>}>
+  <p>Body content goes here.</p>
+</Card>
+
+<Card title="Open Application" onClick={() => navigate('/app/123')}>
+  <p>Click anywhere to open.</p>
+</Card>
+```
+
+---
+
+### Accordion
+
+```tsx
+import { Accordion } from '@cmgfi/clear-ds';
+import type { AccordionProps, AccordionItem, AccordionVariant } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `items`: `AccordionItem[]` — `{ id: string; title: string; content: ReactNode; badge?: number; headerAction?: ReactNode; disabled?: boolean }`
+- `openIds`: `string[]` — controlled open panel IDs
+- `onChange`: `(ids: string[]) => void`
+- `variant`: `'simple' | 'page' | 'panel' | 'flyout'` — default `'page'`
+  - `simple` — teal-700 bottom border on title
+  - `page` — full-width gray `#e4e4e4` header
+  - `panel` — compact gray `#f4f4f5` header, 32px, optional badge
+  - `flyout` — gray `#f4f4f5` header, 44px, optional badge
+- `multiple`: boolean — allow multiple panels open simultaneously (default `false`)
+
+```tsx
+const [open, setOpen] = useState(['item1']);
+<Accordion
+  variant="page"
+  items={[
+    { id: 'item1', title: 'Borrower Information', content: <BorrowerForm /> },
+    { id: 'item2', title: 'Property Details', content: <PropertyForm />, badge: 3 },
+  ]}
+  openIds={open}
+  onChange={setOpen}
+/>
+```
+
+---
+
+### Tabs
+
+```tsx
+import { Tabs } from '@cmgfi/clear-ds';
+import type { TabsProps, TabItem } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `tabs`: `TabItem[]` — `{ id: string; label: string; icon?: ReactNode; count?: number; icon2?: ReactNode; content?: ReactNode; disabled?: boolean }`
+- `activeTab`: string — controlled active tab ID
+- `onChange`: `(id: string) => void`
+
+```tsx
+const [active, setActive] = useState('tab1');
+<Tabs
+  tabs={[
+    { id: 'tab1', label: 'Overview', content: <p>Overview content</p> },
+    { id: 'tab2', label: 'Details',  content: <p>Details content</p>, count: 5 },
+    { id: 'tab3', label: 'History',  content: <p>History</p>, disabled: true },
+  ]}
+  activeTab={active}
+  onChange={setActive}
+/>
+```
+
+---
+
+### BannerTabs
+
+```tsx
+import { BannerTabs } from '@cmgfi/clear-ds';
+import type {
+  BannerTabsProps, BannerTabItem, BannerTabStatus,
+  BannerTabBadge, BannerTabBadgeGroup, StatusShape, StatusColor, BadgeShape
+} from '@cmgfi/clear-ds';
+```
+
+Scrollable card-shaped loan-workflow tab bar with status indicators. Handles overflow with arrow buttons automatically.
+
+Props:
+- `items`: `BannerTabItem[]`
+  - `id`: string
+  - `label`: string — primary label ("DU", "Loan Summary")
+  - `subLabel`: string — secondary label after "/" ("LPA" in "DU / LPA")
+  - `subtitle`: string — muted status line ("Not Complete", "Rep. Score 732")
+  - `status`: `BannerTabStatus` — `{ shape: 'dot' | 'diamond' | 'square' | 'none'; color: 'green' | 'yellow' | 'red' | 'gray' }`
+  - `subStatus`: `BannerTabStatus` — used alongside `subLabel`
+  - `locked`: boolean — shows a lock icon, non-interactive
+  - `badgeGroups`: `BannerTabBadgeGroup[]` — count badges with `{ badges: BannerTabBadge[] }`; each badge: `{ count: number; tooltip: string; shape?: BadgeShape; color?: string }`
+  - `docs`: ReactNode — custom content at the bottom of the card
+  - `disabled`: boolean
+- `activeId`: `string | null`
+- `onChange`: `(id: string) => void`
+
+---
+
+### Modal
+
+```tsx
+import { Modal } from '@cmgfi/clear-ds';
+import type { ModalProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `isOpen`: boolean
+- `onClose`: `() => void` — called on ✕ click, scrim click, or Escape
+- `title`: string — modal header text
+- `children`: ReactNode — modal body
+- `footer`: ReactNode — typically right-aligned action buttons
+- `scrim`: boolean — dark overlay behind the modal (default `true`)
+- `width`: number — modal width in px (default `510`)
+
+```tsx
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title='Delete "July 2024 Purchase Loan"?'
+  footer={
+    <>
+      <Button variant="secondary" onClick={() => setIsOpen(false)} autoFocus>Cancel</Button>
+      <Button variant="danger" onClick={handleDelete}>Delete permanently</Button>
+    </>
+  }
+>
+  <p>This action cannot be undone.</p>
+</Modal>
+```
+
+---
+
+### Drawer
+
+```tsx
+import { Drawer } from '@cmgfi/clear-ds';
+import type { DrawerProps, DrawerAction } from '@cmgfi/clear-ds';
+```
+
+Full-height sliding panel. Props:
+- `isOpen`: boolean
+- `onClose`: `() => void` — called on ✕ click, scrim click, or Escape
+- `title`: string
+- `subtitle`: ReactNode
+- `children`: ReactNode — scrollable body
+- `primaryAction`: `DrawerAction` — **required**; `{ label: string; onClick: () => void; disabled?: boolean }`
+- `secondaryAction`: `DrawerAction` — optional; rendered left of primary
+- `tertiaryActions`: `DrawerAction[]` — optional; left-aligned ghost buttons
+- `side`: `'left' | 'right'` — default `'right'`
+- `width`: number — default `800`
+
+---
+
+### SidePanel / SidePanelLayout
+
+```tsx
+import { SidePanel, SidePanelLayout } from '@cmgfi/clear-ds';
+import type { SidePanelProps, SidePanelLayoutProps } from '@cmgfi/clear-ds';
+```
+
+`SidePanel` props:
+- `isOpen`: boolean
+- `onClose`: `() => void`
+- `title`: string
+- `subtitle`: ReactNode — below the title (e.g. phone + loan number link)
+- `onSave`: `() => void` — renders a Save button in the header when provided
+- `headerContent`: ReactNode — slot below the title row
+- `width`: number — default `470`
+- `children`: ReactNode — scrollable body
+
+`SidePanelLayout` props (layout wrapper that pushes main content left):
+- `open`: boolean — should match `SidePanel`'s `isOpen`
+- `panelWidth`: number — should match `SidePanel`'s `width`, default `470`
+- `children`: ReactNode — the main page content to be shifted
+
+```tsx
+<SidePanelLayout open={panelOpen} panelWidth={470}>
+  <main>…page content…</main>
+</SidePanelLayout>
+<SidePanel isOpen={panelOpen} onClose={() => setPanelOpen(false)} title="Ryan Smith">
+  …panel body…
+</SidePanel>
+```
+
+---
+
+### Popup
+
+```tsx
+import { Popup } from '@cmgfi/clear-ds';
+import type { PopupProps } from '@cmgfi/clear-ds';
+```
+
+Positioned overlay anchored to a trigger element, with a CSS arrow pointing at the trigger. Props:
+- `isOpen`: boolean
+- `onClose`: `() => void` — called on ✕ click or scrim click
+- `trigger`: ReactNode — the element the popup is anchored to
+- `title`: string — optional header
+- `children`: ReactNode — popup body
+- `footer`: ReactNode — optional action area
+- `placement`: `'top' | 'bottom'` — which side of the trigger (default `'bottom'`)
+- `align`: `'left' | 'right'` — horizontal alignment relative to the trigger (default `'right'`)
+- `width`: number — default `360`
+
+---
+
+### Tooltip
+
+```tsx
+import { Tooltip } from '@cmgfi/clear-ds';
+import type { TooltipProps, TooltipPlacement } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `content`: ReactNode — tooltip bubble content
+- `children`: ReactNode — the element the tooltip is anchored to
+- `placement`: `'top' | 'bottom' | 'left' | 'right'` — default `'top'`
+- `delay`: number — hover delay in ms (default `200`)
+- `disabled`: boolean — suppresses the tooltip
+- `maxWidth`: number — bubble max-width in px (default `140`)
+
+```tsx
+<Tooltip content="This rate is locked until March 15." placement="top">
+  <IconButton icon={<i className="pi pi-info-circle" />} aria-label="Rate lock info" />
+</Tooltip>
+```
+
+---
+
+### BannerAlert
+
+```tsx
+import { BannerAlert } from '@cmgfi/clear-ds';
+import type { BannerAlertProps, BannerAlertSeverity } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `severity`: `'success' | 'info' | 'warn' | 'error' | 'neutral'`
+- `title`: string — **required**
+- `detail`: string — optional supporting text after the title
+- `closable`: boolean — shows a dismiss ✕ button (default `true`)
+- `onClose`: `() => void`
+
+```tsx
+<BannerAlert severity="error" title="Missing required fields" detail="First name, last name, and SSN are required to continue." />
+<BannerAlert severity="success" title="Application submitted" detail="Assigned to underwriter." closable onClose={handleDismiss} />
+<BannerAlert severity="neutral" title="Rate lock expires in 3 days." closable={false} />
+```
+
+---
+
+### InlineContainedAlert
+
+```tsx
+import { InlineContainedAlert } from '@cmgfi/clear-ds';
+import type { InlineContainedAlertProps, AlertSeverity } from '@cmgfi/clear-ds';
+```
+
+Bordered inline alert for use inside panels or cards.
+
+Props:
+- `severity`: `AlertSeverity` — `'success' | 'info' | 'warn' | 'error'`
+- `message`: string — **required**
+- `closable`: boolean — default `true`
+- `onClose`: `() => void`
+
+---
+
+### InlineAlert
+
+```tsx
+import { InlineAlert } from '@cmgfi/clear-ds';
+import type { InlineAlertProps } from '@cmgfi/clear-ds';
+```
+
+Minimal icon + colored text; no background or border.
+
+Props:
+- `severity`: `AlertSeverity` — `'success' | 'info' | 'warn' | 'error'`
+- `message`: string — **required**
+
+---
+
+### Toast / Toaster / toast
+
+```tsx
+import { Toast, Toaster, toast } from '@cmgfi/clear-ds';
+import type { ToastSeverity, ToastLayout, ToastOptions, StaticToastProps } from '@cmgfi/clear-ds';
+```
+
+Mount `<Toaster />` once at the app root. Call `toast.*()` anywhere.
+
+```tsx
+// App root
+<Toaster />
+
+// Anywhere in the app — imperative API
+toast.success('Application saved');
+toast.error('Upload failed', 'Check your connection.', { duration: 0 }); // 0 = no auto-dismiss
+toast.warn('Session expiring', 'You will be logged out in 5 minutes.');
+toast.info('3 items updated');
+```
+
+`toast.success / .info / .warn / .error` signature: `(title: string, detail?: string, opts?: ToastOptions) => void`
+
+`ToastOptions`:
+- `duration`: number (ms) — default `5000`; `0` = no auto-dismiss (use for errors)
+- `layout`: `'horizontal' | 'vertical'` — `horizontal` = title and detail inline (default); `vertical` = stacked
+
+---
+
+### ProgressBar
+
+```tsx
+import { ProgressBar } from '@cmgfi/clear-ds';
+import type { ProgressBarProps } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `value`: number — current progress, clamped to `[0, max]`
+- `max`: number — default `100`
+- `error`: boolean — hides the fill and shows `errorMessage` in red
+- `errorMessage`: string — shown below the track when `error` is true
+- `aria-label`: string — accessible label describing what is being measured
+
+```tsx
+<ProgressBar value={65} aria-label="Underwriting review" />
+<ProgressBar value={100} max={100} aria-label="Upload complete" />
+<ProgressBar value={0} error errorMessage="Upload failed. Please try again." />
+```
+
+---
+
+### ProgressSpinner
+
+```tsx
+import { ProgressSpinner } from '@cmgfi/clear-ds';
+import type { ProgressSpinnerProps } from '@cmgfi/clear-ds';
+```
+
+SVG gradient loading spinner.
+
+Props:
+- `size`: `'sm' | 'md' | 'lg'` — `sm`=20px, `md`=32px (default), `lg`=36px with Clear logo inside
+- `label`: string — text displayed below the spinner (designed for `lg`)
+- `theme`: `'light' | 'dark'` — adjusts label text color (default `'light'`)
+- `aria-label`: string — accessible label (default `"Loading"`)
+
+```tsx
+<ProgressSpinner size="md" aria-label="Loading loan pipeline…" />
+<ProgressSpinner size="lg" label="Loading…" theme="dark" />
+```
+
+---
+
+### SeverityChip
+
+```tsx
+import { SeverityChip } from '@cmgfi/clear-ds';
+import type { SeverityChipProps, SeverityChipVariant } from '@cmgfi/clear-ds';
+```
+
+Props:
+- `label`: string — **required**
+- `severity`: `'plain' | 'contrast' | 'error' | 'warning' | 'informative' | 'success'`
+- `dismissible`: boolean — shows a ✕ button (default `true`)
+- `onDismiss`: `() => void`
+
+```tsx
+<SeverityChip severity="success" label="Approved" />
+<SeverityChip severity="warning" label="Conditions pending" />
+<SeverityChip severity="error" label="Denied" dismissible={false} />
+<SeverityChip severity="plain" label="Draft" onDismiss={handleDismiss} />
+```
+
+---
+
+### MiscChip
+
+```tsx
+import { MiscChip } from '@cmgfi/clear-ds';
+import type { MiscChipProps, MiscChipColor } from '@cmgfi/clear-ds';
+```
+
+General-purpose color-coded label chip. 12 named colors, all mapping to existing token vars.
+
+Props:
+- `label`: string — **required**
+- `color`: `'red-darkest' | 'red-light' | 'yellow-darkest' | 'yellow-dark' | 'yellow-light' | 'green-darkest' | 'green-dark' | 'green-light' | 'blue-darkest' | 'blue-dark' | 'blue-light' | 'navy'`
+- `dismissible`: boolean — default `true`
+- `onDismiss`: `() => void`
+
+---
+
+### ProfileChip
+
+```tsx
+import { ProfileChip } from '@cmgfi/clear-ds';
+import type { ProfileChipProps } from '@cmgfi/clear-ds';
+```
+
+Person/user identifier pill.
+
+Props:
+- `label`: string — **required**
+- `leading`: ReactNode — rendered before the label in a 18×18px circular clip (avatar, initials, etc.)
+- `trailing`: ReactNode — rendered after the label in a 18×18px circular clip
+- `dismissible`: boolean — default `true`
+- `onDismiss`: `() => void`
+
+```tsx
+<ProfileChip label="Maria Johnson" />
+<ProfileChip label="Robert Chen" leading={<img src="/avatars/rchen.jpg" alt="" />} />
+```
+
+---
+
+### AUSChip
+
+```tsx
+import { AUSChip } from '@cmgfi/clear-ds';
+import type { AUSChipProps, AUSChipColor } from '@cmgfi/clear-ds';
+```
+
+Automated Underwriting System result chip. Non-dismissible.
+
+Props:
+- `label`: string — e.g. `'Approve/Eligible'`, `'Refer/Eligible'`
+- `color`: `'green' | 'red' | 'yellow' | 'grey'`
+
+```tsx
+<AUSChip label="Approve/Eligible" color="green" />
+<AUSChip label="Refer/Eligible" color="yellow" />
+```
+
+---
+
+### TopBar
+
+```tsx
+import { TopBar } from '@cmgfi/clear-ds';
+import type { TopBarProps, TopBarNavItem, TopBarMenuItem, TopBarUserProfile } from '@cmgfi/clear-ds';
+```
+
+Desktop application top bar with logo, nav items, search, and profile menu.
+
+Props:
+- `navItems`: `TopBarNavItem[]` — `{ id: string; label: string; items?: TopBarMenuItem[]; onSelect?: (value: string) => void; isPrimary?: boolean }`
+  - `isPrimary`: renders the item in teal with a `+` circle icon (for the Create CTA)
+  - `TopBarMenuItem`: `{ label: string; value: string; icon?: ReactNode; disabled?: boolean; divider?: boolean }`
+- `profile`: `TopBarUserProfile` — `{ name: string; role?: string; initials?: string; menuItems?: TopBarMenuItem[]; onMenuSelect?: (value: string) => void }`
+- `version`: string — e.g. `"v.1.88.3459"`, shown next to the logo
+- `onSearch`: `(query: string) => void`
+- `searchPlaceholder`: string — default `"Search Leads and Loans"`
+
+---
+
+### TopBarMobile
+
+```tsx
+import { TopBarMobile } from '@cmgfi/clear-ds';
+import type { TopBarMobileProps, TopBarMobileBorrower } from '@cmgfi/clear-ds';
+```
+
+Mobile top bar. Two modes: standard (Clear logo centered) and URLA (small C logo + borrower name).
+
+Props:
+- `profile`: `TopBarUserProfile` — **required**
+- `borrower`: `TopBarMobileBorrower` — `{ name: string; onInfoClick?: () => void }`; when provided, activates URLA mode
+- `onMenuOpen`: `() => void`
+- `onSearchOpen`: `() => void`
+
+---
+
+### URLATabsNav
+
+```tsx
+import { URLATabsNav } from '@cmgfi/clear-ds';
+import type {
+  URLATabsNavProps, URLATabsNavApplicantOption, URLATabsNavTab, URLATabsNavMenuItem
+} from '@cmgfi/clear-ds';
+```
+
+Single-row desktop sub-navigation for the URLA section. Left: applicant selector + optional sort. Right: optional AUS buttons + scrollable tab strip.
+
+Props:
+- `applicants`: `URLATabsNavApplicantOption[]` — `{ id: string; label: string }`
+- `selectedApplicantId`: string
+- `onApplicantChange`: `(id: string) => void`
+- `onAddApplicant`: `() => void`
+- `sortItems`: `URLATabsNavMenuItem[]` — `{ label: string; value: string }`
+- `onSortSelect`: `(value: string) => void`
+- `tabs`: `URLATabsNavTab[]` — `{ id: string; label: string; disabled?: boolean }`
+- `activeTabId`: string
+- `onTabChange`: `(id: string) => void`
+- `onNextValidation`: `() => void` — renders a red "Next Validation" button
+- `nextValidationBadge`: number — count badge on the validation button
+- `onBackToAUS`: `() => void` — renders a secondary "Back to AUS" button
+
+---
+
+### URLATabsNavTablet
+
+```tsx
+import { URLATabsNavTablet } from '@cmgfi/clear-ds';
+import type { URLATabsNavTabletProps } from '@cmgfi/clear-ds';
+```
+
+Two-row tablet variant (~992px). Row 1: borrower name + "Loan Details" | applicant selector + sort | AUS buttons. Row 2: scrollable tab strip.
+
+Props (extends URLATabsNav props with):
+- `borrowerName`: string — **required**
+- `onLoanDetailsClick`: `() => void`
+- `tabStripBadge`: number — optional red count badge at the far right of the tab strip
+
+---
+
+### URLATabsNavMobile
+
+```tsx
+import { URLATabsNavMobile } from '@cmgfi/clear-ds';
+import type { URLATabsNavMobileProps } from '@cmgfi/clear-ds';
+```
+
+Two-row touch-optimized mobile variant (~768px). Row 1: borrower name + section dropdown + sort + Actions + Save. Row 2: AUS pills + applicant selector (44px) + sort button + tab dropdown.
+
+Props (extends URLATabsNav props with):
+- `borrowerName`: string — **required**
+- `onLoanDetailsClick`: `() => void`
+- `sectionLabel`: string — **required** (current section, e.g. `"URLA"`)
+- `sectionItems`: `URLATabsNavMenuItem[]`
+- `onSectionSelect`: `(value: string) => void`
+- `onSectionSort`: `() => void`
+- `actionItems`: `URLATabsNavMenuItem[]`
+- `onActionSelect`: `(value: string) => void`
+- `onSave`: `() => void`
+
+---
+
+### LoanBannerNav
+
+```tsx
+import { LoanBannerNav } from '@cmgfi/clear-ds';
+import type {
+  LoanBannerNavProps, LoanBannerNavAction, LoanBannerNavCondition,
+  LoanBannerNavToolbar, LoanBannerNavBanner, LoanBannerNavCollapsedSection
+} from '@cmgfi/clear-ds';
+```
+
+Primary loan-file navigation bar (83px tall). Renders BannerTabs in the center and a configurable action zone on the right.
+
+Props:
+- `tabs`: `BannerTabItem[]` — **required**
+- `activeTabId`: string — **required**
+- `onTabChange`: `(id: string) => void` — **required**
+- `onMenuToggle`: `() => void` — hamburger button handler
+- `secondaryActions`: `LoanBannerNavAction[]` — action buttons before the primary
+  - `LoanBannerNavAction`: `{ value: string; label?: string; onClick?: () => void; variant?: ButtonVariant; icon?: ReactNode; badge?: string | number; items?: DropdownButtonItem[]; onSelect?: (value: string) => void; dividerBefore?: boolean; ariaLabel?: string; lightning?: boolean; lightningVariant?: 'basic' | 'filled' }`
+- `onRefresh`: `() => void` — dedicated refresh icon button
+- `primaryLabel`: string — primary button label, default `'Save Loan'`
+- `onPrimary`: `() => void`
+- `primaryItems`: `SplitButtonItem[]` — when provided, primary renders as a SplitButton
+- `onPrimarySelect`: `(value: string) => void`
+- `condition`: `LoanBannerNavCondition` — `{ label: string; onDismiss?: () => void }`
+- `toolbar`: `LoanBannerNavToolbar` — `{ left?: ReactNode; center?: ReactNode; right?: ReactNode }` — adds a secondary row below
+- `banner`: `LoanBannerNavBanner` — `{ title: string; detail?: string; severity?: BannerAlertSeverity; closable?: boolean; onClose?: () => void }` — adds a BannerAlert strip below
+- `collapsed`: boolean — compact single-row mode (hides BannerTabs, shows breadcrumbs)
+- `collapsedSection`: `LoanBannerNavCollapsedSection` — `{ label: string; subLabel?: string; status?: StatusColor }`
+- `onCollapsedBack`: `() => void`
+- `onExpandTabs`: `() => void`
+- `collapsedQuickItems`: `DropdownButtonItem[]`
+- `onCollapsedQuickAction`: `(value: string) => void`
+
+---
+
+### FullNav
+
+```tsx
+import { FullNav } from '@cmgfi/clear-ds';
+import type { FullNavProps } from '@cmgfi/clear-ds';
+```
+
+Full desktop navigation shell. Stacks TopBar → optional LoanBannerNav → optional URLATabsNav.
+
+Props:
+- `topBar`: `TopBarProps` — **required**
+- `loanBannerNav`: `LoanBannerNavProps` — renders the loan banner below the top bar
+- `urlATabsNav`: `URLATabsNavProps` — renders the URLA tab nav below the loan banner (requires `loanBannerNav`)
+
+```tsx
+<FullNav
+  topBar={{ version: 'v.1.88.3459', navItems: NAV_ITEMS, profile: PROFILE, onSearch: () => {} }}
+  loanBannerNav={{ tabs: BANNER_TABS, activeTabId: activeTab, onTabChange: setActiveTab, primaryLabel: 'Save Loan', onPrimary: handleSave }}
+  urlATabsNav={{ applicants: APPLICANTS, selectedApplicantId: applicant, onApplicantChange: setApplicant, tabs: URLA_TABS, activeTabId: urlaTab, onTabChange: setUrlaTab }}
+/>
+```
+
+---
+
+### FullNavMobile
+
+```tsx
+import { FullNavMobile } from '@cmgfi/clear-ds';
+import type { FullNavMobileProps } from '@cmgfi/clear-ds';
+```
+
+Mobile navigation shell. Stacks TopBarMobile → optional URLATabsNavMobile (only when `topBar.borrower` is set).
+
+Props:
+- `topBar`: `TopBarMobileProps` — **required**
+- `urlATabsNavMobile`: `URLATabsNavMobileProps` — renders when `topBar.borrower` is also set
+
+---
+
+## Token Reference
+
+All tokens are CSS custom properties. Import `@cmgfi/clear-ds/tokens` in your app root.
+
+**Base scale: 1rem = 12px** — set `html { font-size: 12px }` in your app.
+
+### Colors
+
+7 families × 10 shades (-50 to -900):
+
+```css
+/* Teal — brand, primary actions, focus rings */
+--teal-50 through --teal-900
+/* key: --teal-500: #32A4AC  --teal-600: #138890  --teal-700: #047880 */
+
+/* Surface — backgrounds */
+--surface-50: #FFFFFF   --surface-100: #FCFCFC  --surface-200: #F7F7F7
+--surface-300: #F4F4F5  --surface-400: #EDEDED  --surface-500: #E4E4E4
+--surface-600: #CFCFCF  --surface-700: #A2A2A2  --surface-800: #7D7D7D
+--surface-900: #606060
+
+/* Navy — text, borders */
+--navy-50 through --navy-900
+/* key: --navy-800: #171D22  --navy-900: #12161A */
+
+/* Semantic */
+--color-text: #202020
+--color-text-secondary: #70777D
+
+/* Severity */
+--yellow-* (warning)   --blue-* (info)   --green-* (success)   --red-* (error)
+```
+
+### Spacing
+
+```css
+/* Numeric scale */
+--spacing-02: 2px    --spacing-04: 4px    --spacing-06: 6px
+--spacing-08: 8px    --spacing-12: 12px   --spacing-16: 16px
+--spacing-20: 20px   --spacing-24: 24px   --spacing-32: 32px   --spacing-40: 40px
+
+/* Named aliases */
+--spacing-xxxs: 2px   --spacing-xxs: 4px   --spacing-xs: 6px   --spacing-sm: 8px
+--spacing-md: 12px    --spacing-lg: 16px   --spacing-xl: 24px   --spacing-xxl: 32px
+```
+
+### Typography
+
+```css
+--font-family: 'Open Sans', sans-serif
+
+/* Utility classes */
+.text-h1 .text-h2 .text-h3 .text-h4 .text-h5 .text-h6
+.text-xl-bold      .text-xl-semibold      .text-xl-regular
+.text-large-bold   .text-large-semibold   .text-large-regular
+.text-normal-bold  .text-normal-semibold  .text-normal-regular
+.text-small-bold   .text-small-semibold   .text-small-regular
+```
+
+### Elevation
+
+```css
+--shadow-depth-1: 0 1px 4px rgba(0,0,0,0.12)
+--shadow-depth-2: 0 2px 8px rgba(0,0,0,0.16)
+--shadow-depth-3: 0 4px 16px rgba(0,0,0,0.20)
+--shadow-depth-4: 0 8px 32px rgba(0,0,0,0.24)
+```
+
+### Icons
+
+```css
+--icon-size-sm: 12px   --icon-size-md: 14px   --icon-size-lg: 18px   --icon-size-xl: 24px
+```
+
+```tsx
+<i className="pi pi-check" style={{ fontSize: 'var(--icon-size-lg)' }} />
+```
+
+### Grid
+
+```css
+--grid-columns-mobile: 4     --grid-gutter-mobile: 16px    --grid-margin-mobile: 24px
+--grid-columns-tablet: 6     --grid-gutter-tablet: 16px    --grid-margin-tablet: 48px
+--grid-columns-desktop: 12   --grid-gutter-desktop: 18px   --grid-margin-desktop: 128px
+--breakpoint-sm: 576px   --breakpoint-md: 768px   --breakpoint-lg: 1200px
+```
+
+---
+
+## Best Practices
+
+The full interactive best practices reference is in Storybook under **Best Practices/**. Summary:
+
+### Accessibility
+- Every image needs alt text — `alt=""` for decorative images
+- All form inputs must have a visible `<label>` — never use placeholder as label
+- Use `:focus-visible` styles, not `:focus` — keyboard-only focus rings
+- `aria-live` regions for dynamic content updates
+- Minimum color contrast 4.5:1 for normal text, 3:1 for large text (WCAG AA)
+- Icon-only buttons must have `aria-label`
+- Use semantic HTML — `<button>` for actions, `<a>` for navigation
+
+### Color
+- Color is never the only indicator of state — always pair with text, icon, or shape
+- Red is for destructive actions and errors only
+- Teal (`--teal-500/600`) for primary interactive elements; never invent new interactive colors
+- Never use color tokens outside the system — always reference `var(--token-name)`
+
+### Forms
+- Labels go above fields — never use placeholder text as a label
+- Group related fields; separate groups with 32px + a section heading
+- Validate inline, adjacent to the field — not in a distant summary list
+- Always use a single primary submit action per form section
+
+### Error Handling
+- Display error messages adjacent to the field or action that caused them
+- Be specific: "SSN must be 9 digits" not "Invalid input"
+- Page-level `BannerAlert` for system errors; field-level `helperText` + `invalid` for validation
+- Never auto-dismiss error toasts — users need time to read them
+
+### Feedback & Notifications
+- Always acknowledge completed async actions with a success message
+- Success toasts: auto-dismiss after 5s (`duration: 5000`)
+- Error toasts: no auto-dismiss (`duration: 0`)
+- Use `ProgressBar` for operations with known progress; `ProgressSpinner` for indeterminate
+
+### Loading & Async
+- 0–100ms: no loading indicator needed
+- 100ms–1s: loading state on the triggering button (disabled + spinner)
+- 1s+: `ProgressSpinner` or `ProgressBar` in the content area
+- Skeleton screens feel faster than spinners for predictable-shape content
+- Optimistic UI: update immediately, roll back on error with a Toast
+
+### Destructive Actions
+- Always confirm before irreversible operations — use Modal with explicit "Cancel" + "Delete permanently"
+- `autoFocus` the Cancel button in destructive confirmation modals
+- Label the destructive action specifically: "Delete application" not "Delete"
+- Use `Button variant="danger"` for destructive primary actions
+
+### Microcopy
+- Button labels: Verb + Noun — "Save application" not "Submit"
+- Sentence case for all labels — not Title Case, not ALL CAPS
+- Avoid "Click here" — write descriptive link text
+- Error messages: what went wrong + how to fix it
+
+### Mobile & Responsive
+- Design for 375px (iPhone SE) as the smallest mobile viewport
+- Minimum touch target: 44×44px (use `Button md` = 40px for mobile; supplement with padding)
+- Test at 375px, 768px, 1024px, 1440px
+- Stack form fields vertically on mobile; never use multi-column form layouts below 768px
+
+### Navigation
+- Users must always know: where they are, where else they can go, and how they got here
+- Active nav item must be visually obvious — not color alone (add bold/underline/background)
+- Deep links must work — always reflect navigation state in the URL
+- Keep navigation consistent across all pages
+
+### Performance Perception
+- Any action >100ms: immediate visual feedback on the triggering element
+- Any operation >1s: `ProgressSpinner` or `ProgressBar`
+- Debounce search/filter inputs at 300ms
+- Lazy-load images below the fold; preload critical above-fold images
+
+### Spacing & Layout
+- Use spacing token scale — never invent arbitrary pixel values
+- Card padding: `--spacing-16` (compact) or `--spacing-24` (content-heavy)
+- Form section gaps: `--spacing-32` with a section heading
+- Group related items within 8px; separate groups by at least 24px
+
+### Tables & Data
+- Right-align numbers; left-align text; center-align icons and status badges
+- Always show context: "Showing 25 of 1,240 results"
+- Sticky column headers on tables taller than the viewport
+- Empty/filtered states must explain what's filtered and offer "Clear filters"
+
+### Typography
+- Body text minimum 14px. Labels and helper text minimum 12px. Never below 12px
+- Line length: 60–80 characters per line
+- Line height: 1.4–1.6× for body text; 1.1–1.2× for headings
+- Never more than 2 typefaces or 4 distinct sizes on one screen
+
+### Visual Hierarchy
+- Every screen has exactly one primary action (one `Button variant="primary"`)
+- Use maximum 3 levels of visual weight per screen
+- Primary button is always the rightmost in a button row
+- Destructive actions are always leftmost (so users encounter Cancel before Delete)
+
+---
+
+## Common Patterns
+
+### Form with validation
+
+```tsx
+const [name, setName] = useState('');
+const [nameError, setNameError] = useState('');
+
+function validate() {
+  if (!name) { setNameError('First name is required.'); return false; }
+  return true;
+}
+
+<InputText
+  label="First name"
+  required
+  value={name}
+  onChange={e => { setName(e.target.value); setNameError(''); }}
+  invalid={!!nameError}
+  helperText={nameError}
+/>
+<Button variant="primary" onClick={() => validate() && handleSubmit()}>Save application</Button>
+```
+
+### Loading button state
+
+```tsx
+const [saving, setSaving] = useState(false);
+
+async function handleSave() {
+  setSaving(true);
+  try { await saveApplication(); toast.success('Application saved'); }
+  catch { toast.error('Save failed', 'Check your connection.', { duration: 0 }); }
+  finally { setSaving(false); }
+}
+
+<Button
+  variant="primary"
+  disabled={saving}
+  leadingIcon={saving ? <i className="pi pi-spin pi-spinner" /> : undefined}
+  onClick={handleSave}
+>
+  {saving ? 'Saving…' : 'Save application'}
+</Button>
+```
+
+### Confirmation modal for destructive action
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<Button variant="danger" size="sm" onClick={() => setIsOpen(true)}>Delete application</Button>
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title='Delete "July 2024 Purchase Loan"?'
+  footer={
+    <>
+      <Button variant="secondary" onClick={() => setIsOpen(false)} autoFocus>Cancel</Button>
+      <Button variant="danger" onClick={() => { handleDelete(); setIsOpen(false); }}>Delete permanently</Button>
+    </>
+  }
+>
+  <p style={{ margin: 0, fontSize: 14, color: 'var(--color-text)', lineHeight: 1.6 }}>
+    This action cannot be undone. The loan file and all associated documents will be permanently removed.
+  </p>
+</Modal>
+```
+
+### Data table with server-side sort and pagination
+
+```tsx
+const [first, setFirst] = useState(0);
+const [sortField, setSortField] = useState('borrowerName');
+const [sortOrder, setSortOrder] = useState<SortOrder>(1);
+
+<DataTable
+  data={loans}
+  columns={columns}
+  sortField={sortField}
+  sortOrder={sortOrder}
+  onSort={({ field, order }) => { setSortField(field); setSortOrder(order); }}
+  loading={isLoading}
+  emptyMessage="No loans match the current filters."
+/>
+<Paginator
+  totalRecords={totalCount}
+  first={first}
+  rows={25}
+  onPageChange={e => setFirst(e.first)}
+/>
+```
+
+### Toast notifications
+
+```tsx
+// App root — mount once
+<Toaster />
+
+// After async operations
+toast.success('Document uploaded', 'Income verification added to file.');
+toast.error('Upload failed', 'The file exceeds the 25 MB limit.', { duration: 0 });
+toast.warn('Session expiring', 'You will be logged out in 5 minutes.');
+```
+
+---
+
+## Architecture Notes
+
+- **CSS Modules** — all component styles are scoped; no class name collisions with your app
+- **Zero runtime CSS** — no CSS-in-JS; styles are pre-compiled at build time
+- **Tree-shakeable** — import only the components you use; unused components are dropped by your bundler
+- **`React.forwardRef` on every component** — all refs forward to the underlying DOM element
+- **Token vars only in styles** — no hardcoded colors or spacing anywhere in component CSS
+- **Consumer `className` is always merged**, never replaced — pass any class to any component safely
+- **Dual output** — `index.mjs` (ESM) and `index.cjs` (CJS); works in Vite, Webpack, Next.js, Create React App