@cmgfi/clear-ds 1.0.1 → 1.1.0

package/README.md

@@ -0,0 +1,478 @@
+# @cmgfi/clear-ds
+
+**Clear Design System** — CMG Financial's official React component library.
+
+The UI foundation for CMG's internal loan origination platform. Built from scratch for pixel-fidelity control, token ownership, and zero dead code. Every component was designed in Pencil before it was written in code.
+
+- **npm:** [`@cmgfi/clear-ds`](https://www.npmjs.com/package/@cmgfi/clear-ds)
+- **Storybook:** [clear-pimkxt5rp-cmgprojects.vercel.app](https://clear-pimkxt5rp-cmgprojects.vercel.app)
+- **Version:** 1.0.1
+- **License:** UNLICENSED (CMG Financial internal)
+
+---
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Consumer Setup](#consumer-setup)
+3. [Component Catalog](#component-catalog)
+4. [Token System](#token-system)
+5. [Tech Stack](#tech-stack)
+6. [Project Structure](#project-structure)
+7. [Local Development](#local-development)
+8. [Build Output](#build-output)
+9. [Publishing](#publishing)
+10. [Contributing](#contributing)
+11. [Hard-won Rules](#hard-won-rules)
+
+---
+
+## Installation
+
+**Full install — with PrimeIcons (recommended):**
+
+```bash
+npm install @cmgfi/clear-ds primeicons
+```
+
+**Without PrimeIcons** — if your composition does not use any icon-bearing components:
+
+```bash
+npm install @cmgfi/clear-ds
+```
+
+> PrimeIcons is a `peerDependency`. It must be installed in the consumer app — it is not bundled into the library.
+
+---
+
+## Consumer Setup
+
+Add these three imports once, in your application root (e.g. `main.tsx` or `App.tsx`):
+
+```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
+```
+
+Set the base font size. The token system is built on **`1rem = 12px`**:
+
+```css
+/* global.css or index.css */
+html {
+  font-size: 12px;
+}
+```
+
+Then use components anywhere in your app:
+
+```tsx
+import { Button, InputText, Modal, DataTable } from '@cmgfi/clear-ds';
+```
+
+---
+
+## Component Catalog
+
+43 components across 7 sections. All are fully typed with JSDoc-annotated props, `React.forwardRef`-wrapped, and documented in Storybook.
+
+### Buttons
+
+| Component | Description |
+|---|---|
+| `Button` | Primary action button. Variants: `primary`, `secondary`, `ghost`, `danger`. Sizes: `sm`, `md`, `lg`. |
+| `IconButton` | Square button containing a single PrimeIcon. |
+| `DropdownButton` | Button that opens a dropdown action menu. |
+| `SplitButton` | Combined primary action + dropdown trigger in one control. |
+| `LightningButton` | Quick-action button with a lightning icon affordance. |
+| `CloseButton` | Compact `×` dismiss button used inside overlays and alerts. |
+
+### Form Controls
+
+| Component | Description |
+|---|---|
+| `InputText` | Single-line text input with label, helper text, and validation states. |
+| `TextArea` | Multi-line text input. |
+| `Checkbox` | Controlled checkbox with label. Supports indeterminate state. |
+| `RadioButton` | Single radio option. Compose multiples in a group. |
+| `Select` | Single-select dropdown. |
+| `MultiSelect` | Multi-select dropdown with chip display and search. |
+| `ListBox` | Inline scrollable single or multi-select list. |
+| `SelectButton` | Segmented button group for mutually exclusive options. |
+| `DatePicker` | Date input with calendar popover. |
+| `ToggleSwitch` | On/off toggle. |
+| `FileUpload` | Drag-and-drop file upload with type validation. |
+
+### Data
+
+| Component | Description |
+|---|---|
+| `DataTable` | Feature-rich table with sorting, filtering, row selection, grouping, inline editing, column resizing, and row expansion. |
+| `Paginator` | Standalone pagination control for use with any data list. |
+| `Picklist` | Dual-list transfer control for moving items between two sets. |
+
+### Messages
+
+| Component | Description |
+|---|---|
+| `BannerAlert` | Full-width page-level alert. Severities: `info`, `success`, `warning`, `error`. |
+| `InlineAlert` | Compact inline alert for form-level feedback. |
+| `InlineContainedAlert` | Bordered inline alert for use inside panels or cards. |
+| `Toast` / `Toaster` / `toast` | Programmatic toast notifications. Mount `<Toaster />` once; call `toast(options)` anywhere. |
+
+### Overlay
+
+| Component | Description |
+|---|---|
+| `Modal` | Dialog overlay with header, body, and footer action slots. |
+| `Drawer` | Slide-in panel overlay. |
+| `SidePanel` / `SidePanelLayout` | Fixed side panel for persistent secondary content. |
+| `Popup` | Anchored floating popup (e.g. contextual menus, micro-overlays). |
+| `Tooltip` | Hover tooltip. Placements: `top`, `bottom`, `left`, `right`. |
+
+### Panel
+
+| Component | Description |
+|---|---|
+| `Card` | Surface container with optional header and footer. |
+| `Accordion` | Collapsible section list. Variants: `default`, `flush`. |
+| `Tabs` | Horizontal tab navigation with panel content. |
+| `BannerTabs` | Loan-workflow tab bar with status chips and badge groups. |
+
+### Status
+
+| Component | Description |
+|---|---|
+| `SeverityChip` | Color-coded severity label. Variants: `info`, `success`, `warning`, `error`. |
+| `MiscChip` | General-purpose label chip with configurable color. |
+| `ProfileChip` | Avatar-style chip showing a person's initials or image. |
+| `AUSChip` | Automated Underwriting System result chip. |
+| `ProgressBar` | Horizontal progress indicator. |
+| `ProgressSpinner` | Circular loading indicator. Large variant includes the Clear brand logo. |
+
+### Navigation
+
+| Component | Description |
+|---|---|
+| `TopBar` | App-level top navigation bar with logo, nav items, user menu, and notifications. |
+| `TopBarMobile` | Mobile variant of `TopBar` with drawer-based navigation. |
+| `URLATabsNav` | URLA section tab navigation with applicant selector. Responsive: desktop, tablet, mobile variants. |
+| `LoanBannerNav` | Loan detail page banner with action toolbar, condition badges, and collapsible sections. |
+| `FullNav` / `FullNavMobile` | Full application navigation shell with primary and secondary nav areas. |
+
+---
+
+## Token System
+
+All tokens are CSS custom properties defined in `src/tokens/tokens.css` and exported via `@cmgfi/clear-ds/tokens`.
+
+**Base scale:** `1rem = 12px` — the consumer app must set `html { font-size: 12px }`.
+
+### Colors
+
+Seven families, 10 shades each (`-50` lightest → `-900` darkest):
+
+| Family | Prefix | Role |
+|---|---|---|
+| Teal | `--teal-*` | Brand color; primary actions, focus rings, active states |
+| Surface | `--surface-*` | Neutral backgrounds; `50` = white, `900` = near-black |
+| Navy | `--navy-*` | Text and borders |
+| Yellow | `--yellow-*` | Warning severity |
+| Blue | `--blue-*` | Informational severity |
+| Green | `--green-*` | Success severity |
+| Red | `--red-*` | Error severity |
+
+Semantic aliases:
+
+```css
+--color-text:           var(--navy-800);   /* primary body text */
+--color-text-secondary: var(--navy-500);   /* helper / secondary text */
+```
+
+### Spacing
+
+Two complementary scales:
+
+```css
+/* Numeric — direct pixel mapping */
+--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 — semantic */
+--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
+
+Font family: **Open Sans** (`--font-family: 'Open Sans', sans-serif`)
+
+Heading utility classes: `.text-h1` through `.text-h6`
+
+Body utility classes — 4 sizes × 3 weights = 12 combinations:
+```
+.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);
+--scrim: /* navy-500 at 25% opacity */;
+```
+
+### Icons
+
+```css
+--icon-size-sm: 12px;
+--icon-size-md: 14px;
+--icon-size-lg: 18px;
+--icon-size-xl: 24px;
+```
+
+Usage with PrimeIcons:
+```tsx
+<i className="pi pi-check" style={{ fontSize: 'var(--icon-size-lg)' }} />
+```
+
+### Grid
+
+```css
+/* Mobile — 4 column */
+--grid-columns-mobile: 4;   --grid-gutter-mobile: 16px;
+--grid-margin-mobile: 24px; --grid-container-mobile: 576px;
+
+/* Tablet — 6 column */
+--grid-columns-tablet: 6;   --grid-gutter-tablet: 16px;
+--grid-margin-tablet: 48px; --grid-container-tablet: 768px;
+
+/* Desktop — 12 column */
+--grid-columns-desktop: 12; --grid-gutter-desktop: 18px;
+--grid-margin-desktop: 128px; --grid-container-desktop: 1200px;
+
+/* Breakpoints */
+--breakpoint-sm: 576px;   --breakpoint-md: 768px;   --breakpoint-lg: 1200px;
+```
+
+---
+
+## Tech Stack
+
+| Concern | Choice | Notes |
+|---|---|---|
+| Framework | React `>=17` | Peer dep — never bundled; consumer's React is used |
+| Language | TypeScript 5 strict | Exported types are part of the public API |
+| Build | Vite 5 library mode | ESM + CJS dual output; CSS Modules built-in |
+| Type declarations | `vite-plugin-dts` `rollupTypes: true` | Single rolled-up `index.d.ts` |
+| Styles | CSS Modules | Scoped, zero runtime overhead; token vars pass through without JS |
+| Docs / QA | Storybook v8 `@storybook/react-vite` | Shares the same Vite config; no duplicate setup |
+| Icons | PrimeIcons `>=7` | CSS font glyphs; `pi pi-*` class API; must be peer dep |
+| Node / npm | 22 / 11 (LTS) | |
+
+**Not present (intentional):**
+- No CSS-in-JS — runtime overhead is unacceptable in a library
+- No Tailwind — custom token system conflicts with Tailwind's class API
+- No third-party component library — pixel-fidelity requires full control
+
+---
+
+## Project Structure
+
+```
+clear-ds/
+├── src/
+│   ├── index.ts                        ← explicit public API; all component + type exports
+│   ├── tokens/
+│   │   ├── tokens.css                  ← all CSS custom properties (428 lines)
+│   │   ├── TokenDocs.module.css        ← shared layout for token Storybook pages
+│   │   ├── Colors.stories.tsx
+│   │   ├── Typography.stories.tsx
+│   │   ├── Spacing.stories.tsx
+│   │   ├── Elevation.stories.tsx
+│   │   ├── Icons.stories.tsx
+│   │   └── Grid.stories.tsx
+│   └── components/
+│       └── ComponentName/
+│           ├── ComponentName.tsx       ← React.forwardRef; JSDoc props; displayName
+│           ├── ComponentName.module.css← token vars only; no hardcoded values
+│           ├── ComponentName.stories.tsx← autodocs; named states; AllStates last
+│           └── index.ts               ← re-exports component + all types
+├── .storybook/
+│   ├── main.ts                         ← framework, addons, stories glob
+│   └── preview.ts                      ← global CSS imports, backgrounds, storySort
+├── dist/                               ← build output (not committed)
+├── vercel.json                         ← Storybook deployment config
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+---
+
+## Local Development
+
+**Prerequisites:** Node 22, npm 11
+
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook dev server (localhost:6006)
+npm run storybook
+
+# Build the library (outputs to dist/)
+npm run build
+
+# Type-check without emitting
+npm run type-check
+
+# Watch mode for library build
+npm run build:watch
+```
+
+### Adding a new component
+
+Every component follows the same invariant structure — do not deviate:
+
+1. Create `src/components/ComponentName/` with four files:
+   - `ComponentName.tsx` — always `React.forwardRef`; props extend `React.HTMLAttributes<HTMLElement>`; every prop has a JSDoc comment; set `displayName`; spread `...props`; merge `className`
+   - `ComponentName.module.css` — token vars exclusively; no hardcoded hex or pixel values (except sub-pixel precision: `border: 1px`, `outline-offset: 2px`); use `:focus-visible` not `:focus`
+   - `ComponentName.stories.tsx` — `tags: ['autodocs']` on meta; individual state stories; `AllStates` is always the last export
+   - `index.ts` — re-export component and all types
+2. Add exports to `src/index.ts`
+3. Add the component to `storySort.order` in `.storybook/preview.ts`
+
+### Storybook conventions
+
+- **Sidebar order:** `Best Practices → Tokens → Components (Buttons, Data, Form Controls, Messages, Overlay, Panel, Status) → Navigation`
+- `tags: ['autodocs']` is mandatory on every `meta` — without it there is no Docs tab
+- `AllStates` (or `AllSizes` / `AllSeverities`) must always be the last story export — Storybook renders in declaration order
+- When a story `render:` function needs `useState`, define a named inner component and call the hook inside it (hooks cannot be called inside `render` directly)
+
+---
+
+## Build Output
+
+```
+dist/
+├── index.mjs          ← ESM bundle (tree-shakeable), 230 KB
+├── index.cjs          ← CommonJS bundle, 153 KB
+├── index.css          ← all compiled component styles, 126 KB
+├── index.d.ts         ← single rolled-up TypeScript declarations, 81 KB
+├── index.mjs.map      ← ESM source map
+├── index.cjs.map      ← CJS source map
+└── tokens/
+    └── tokens.css     ← design tokens (separate import path), 14 KB
+```
+
+**Vite config highlights:**
+- `cssCodeSplit: false` — all CSS Modules compile into a single `index.css`
+- `external: ['react', 'react/jsx-runtime', 'react-dom']` — React is never bundled
+- `rollupTypes: true` — single `index.d.ts` instead of one file per source file
+- `assetFileNames: 'index.css'` — predictable output filename
+- `postbuild` npm script — copies `src/tokens/tokens.css` → `dist/tokens/tokens.css`
+
+---
+
+## Publishing
+
+### npm
+
+Auth token must be in `~/.npmrc` (never in the project `.npmrc`):
+```
+//registry.npmjs.org/:_authToken=<automation-token>
+```
+
+Use an **automation token** — it bypasses 2FA which is required for unattended publishes.
+
+```bash
+# Bump version in package.json, then:
+npm publish
+# prepublishOnly runs `npm run build` automatically
+```
+
+The package publishes to `@cmgfi/clear-ds` on public npm under the `andyg-cmg-xd` account.
+
+### Storybook (Vercel)
+
+The Storybook is hosted on Vercel under the `cmgprojects` team.
+
+```bash
+# First deploy (no .vercel/ present):
+vercel --prod --yes --scope cmgprojects
+
+# Subsequent deploys:
+vercel --prod --yes
+
+# Disable SSO protection after first deploy (new projects inherit team SSO):
+TOKEN=$(cat ~/Library/Application\ Support/com.vercel.cli/auth.json | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
+curl -s -X PATCH "https://api.vercel.com/v9/projects/clear-ds?teamId=team_fm7yrQmYpugXC0N7tiglM4Bw" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"ssoProtection": null}'
+```
+
+`vercel.json` configures the Storybook build:
+```json
+{
+  "buildCommand": "npm run build-storybook",
+  "outputDirectory": "storybook-static"
+}
+```
+
+---
+
+## Contributing
+
+### Git workflow
+
+- Remote: `https://cmg-financial.ghe.com/andyg/clear-ds.git`
+- Branch from `main`, PR back to `main`
+- Commit messages follow conventional commits (`feat:`, `fix:`, `chore:`, `docs:`)
+
+### Before submitting a PR
+
+- [ ] `npm run type-check` passes with zero errors
+- [ ] `npm run build` completes successfully
+- [ ] New component has all four required files
+- [ ] `tags: ['autodocs']` is on the story meta
+- [ ] `AllStates` is the last story export
+- [ ] No hardcoded colors or spacing values — token vars only
+- [ ] `src/index.ts` exports the new component and all its types
+- [ ] Component added to `storySort.order` in `.storybook/preview.ts`
+
+---
+
+## Hard-won Rules
+
+These are not guidelines — they are invariants derived from real failures during the build of this library:
+
+| Rule | Why |
+|---|---|
+| `tags: ['autodocs']` on every story meta | Without it there is no Docs tab. Retroactively adding it across many files is painful. Add it when the file is created. |
+| `AllStates` always last story export | Storybook renders in declaration order. A misplaced overview story at the top pollutes the component's story list. |
+| `primeicons` in `peerDependencies`, not `devDependencies` | If it is only in `devDeps`, it will not be available in consumer bundles — icon glyphs silently disappear. |
+| `publishConfig: { "access": "public" }` is required | Scoped packages are private by default on npm. Without this field, `npm publish` is rejected even with a valid token. |
+| Never hardcode colors or spacing | Always use token vars. Hardcoded values break theming and make design drift invisible. |
+| `React.forwardRef` on every component | Consumers need ref access for focus management, animations, and third-party integrations. |
+| `:focus-visible` not `:focus` | `:focus` shows focus rings on mouse clicks. `:focus-visible` restricts them to keyboard navigation. |
+| `min-width: 0` on shrinkable flex children | `flex: 1` alone does not allow an item to shrink below its content size. Without `min-width: 0`, the item overflows its container. |
+| Merge consumer `className`, never replace | Spreading `...props` is not enough. Explicitly merge: `className={[styles.root, props.className].filter(Boolean).join(' ')}`. |
+| The `postbuild` script must stay in `package.json` | It copies `src/tokens/tokens.css` → `dist/tokens/tokens.css`. Without it, the `@cmgfi/clear-ds/tokens` import path resolves to a file that does not exist. |
+
+---
+
+## Design Source
+
+All visual decisions originate in **Pencil** — a design tool integrated as an MCP server. The `.pen` source files are in the project experiments directory alongside this package. The code is a direct translation of those designs: same structure, same hierarchy, same property names.
+
+The token master copy lives at `../clear-ds-tokens.css` (one level above this package). When updating tokens, sync that file into `src/tokens/tokens.css`.