@pega/sdk 0.0.1 → 0.0.3

package/templates/react-sdk-reference/.claude/prompts/replace-design-system.md

@@ -0,0 +1,519 @@
+# replace-design-system
+
+Replace the current design system in this application with **{{designSystem}}**.
+
+> **Before doing anything else:** if `{{designSystem}}` is empty or not provided, stop immediately and ask the user: _"Which design system should I migrate to? (e.g. Ant Design, Carbon Design System, Chakra UI)"_ — do not proceed with any migration steps until it is provided.
+
+---
+
+## Step 0: Determine target component list
+
+Read `.claude/prompts/component-manifest.json` first.
+
+Collect components from **every applicable source** below, then merge and deduplicate into a single final list.
+
+---
+
+### Source A — Screenshot / image attached
+
+> Applies when: one or more images or screenshots are attached to this prompt invocation.
+
+Analyze **each attached image** using the **[Visual Recognition Guide](#visual-recognition-guide)** below.
+Produce a list of SDK component names visible across **all** screenshots, then union the results into a single list.
+
+---
+
+### Source B — `components` param provided (explicit list)
+
+> Applies when: `{{components}}` is non-empty (e.g. `components="TextInput,Phone,Stages"`)
+
+Resolve each name against the manifest's `components` map to get its path and category.
+
+---
+
+### Source C — `scope` param provided
+
+> Applies when: `{{scope}}` is provided
+
+**If `{{scope}}` is a folder name** (one of `field`, `template`, `widget`, `infra`, `designSystemExtension`):
+Read every entry under `manifest.components["{{scope}}"]` — that is the full component list for this source.
+
+**If `{{scope}}` is a named shorthand** (a key in `manifest.namedScopes`, e.g. `workflow-form`):
+Read `manifest.namedScopes["{{scope}}"]`:
+
+- For each entry in `folders[]`: collect all components in `manifest.components[folder]`
+- For each entry in `components[]`: add that component directly (it includes path + category)
+
+---
+
+### Merge & deduplicate
+
+Take the union of all non-empty source lists (A, B, C).
+Remove duplicates using **case-insensitive component name matching** — the manifest is authoritative for path and category regardless of which source contributed the name.
+
+**If the merged list is non-empty → [Targeted Migration](#targeted-migration)**
+**If ALL sources produced nothing (no image, no params) → [Full Migration (9 waves)](#full-migration)**
+
+---
+
+### Combination examples
+
+| Sources active                      | Behaviour                                              |
+| ----------------------------------- | ------------------------------------------------------ |
+| One image only                      | A only → targeted migration of identified components   |
+| Multiple images only                | A only (union across all images) → targeted migration  |
+| `components=` only                  | B only → targeted migration (same as before)           |
+| `scope=` only                       | C only → all components in that scope (same as before) |
+| Image(s) + `components=`            | A ∪ B, deduplicated → targeted migration               |
+| Image(s) + `scope=`                 | A ∪ C, deduplicated → targeted migration               |
+| `scope=` + `components=`            | B ∪ C, deduplicated → targeted migration               |
+| Image(s) + `scope=` + `components=` | A ∪ B ∪ C, deduplicated → targeted migration           |
+| No image, no params                 | Full 9-wave migration                                  |
+
+---
+
+## Visual Recognition Guide
+
+Use the tables below to map what you see in an attached image to SDK component names.
+
+### Structural / layout components
+
+| What you see                                                                                                                                                                      | SDK component name                        | Category |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------- |
+| Chevron/arrow step bar at the top of a form (e.g. "Step 1 → Step 2 → Step 3")                                                                                                     | `Stages`                                  | infra    |
+| Full case shell: step bar + case title + **action menu (⋮ or kebab)** + tabbed content area                                                                                       | `CaseView`                                | template |
+| Avatar + assignment/step name at the top **and** form fields in the body **and** action buttons (e.g. Cancel / Save for later / Submit) at the bottom — all three must be present | `FlowContainer`                           | template |
+| Row of action buttons at the bottom (Cancel / Save / Submit)                                                                                                                      | `ActionButtons`                           | infra    |
+| White/card area wrapping form fields                                                                                                                                              | `DefaultForm`                             | template |
+| Full-page layout with header + sidebar + content area                                                                                                                             | `AppShell`                                | template |
+| Left-side vertical tab navigation                                                                                                                                                 | `VerticalTabs`                            | infra    |
+| Top navigation bar with logo + user menu                                                                                                                                          | `NavBar`                                  | infra    |
+| Top navigation bar (WSS / self-service variant)                                                                                                                                   | `WssNavBar`                               | template |
+| Two-column layout (equal or narrow/wide split)                                                                                                                                    | `TwoColumn` / `NarrowWide` / `WideNarrow` | template |
+| Single-column stacked layout                                                                                                                                                      | `OneColumn`                               | template |
+| Tabbed panel inside a form or page                                                                                                                                                | `SubTabs` / `Details`                     | template |
+
+### Field components
+
+| What you see                                               | SDK component name | Category |
+| ---------------------------------------------------------- | ------------------ | -------- |
+| Single-line text input box                                 | `TextInput`        | field    |
+| Multi-line text input / textarea                           | `TextArea`         | field    |
+| Dropdown / select menu (chevron on right)                  | `Dropdown`         | field    |
+| Phone input with country code prefix (e.g. "+1 ▼")         | `Phone`            | field    |
+| Date picker input (calendar icon)                          | `Date`             | field    |
+| Date + time picker input                                   | `DateTime`         | field    |
+| Time-only picker                                           | `Time`             | field    |
+| Currency input ($ prefix or formatted number)              | `Currency`         | field    |
+| Percentage input (% suffix)                                | `Percentage`       | field    |
+| Decimal / float number input                               | `Decimal`          | field    |
+| Integer-only number input                                  | `Integer`          | field    |
+| Email input (envelope icon or @-hint)                      | `Email`            | field    |
+| URL input (link icon or http-hint)                         | `URL`              | field    |
+| Checkbox with label                                        | `Checkbox`         | field    |
+| Radio button group                                         | `RadioButtons`     | field    |
+| Multi-select / tag-style select with chips                 | `Multiselect`      | field    |
+| Type-ahead / autocomplete input with suggestions           | `AutoComplete`     | field    |
+| Rich text editor (toolbar with Bold/Italic/etc.)           | `RichText`         | field    |
+| Read-only comma-separated list of values                   | `ScalarList`       | field    |
+| Selectable card / tile (click to select, like a plan card) | `SelectableCard`   | field    |
+| Map / location picker with pin icon                        | `Location`         | field    |
+| Link to another object/record                              | `ObjectReference`  | field    |
+| Hyperlink displayed inline                                 | `SemanticLink`     | field    |
+| User avatar + name displayed inline                        | `UserReference`    | field    |
+| Inline alert / warning inside a form                       | `CancelAlert`      | field    |
+| Static text block / paragraph inside a form                | `TextContent`      | field    |
+| Grouping box around related fields                         | `Group`            | field    |
+
+### Widget components
+
+| What you see                                      | SDK component name | Category |
+| ------------------------------------------------- | ------------------ | -------- |
+| To-do / task list card with assignments           | `ToDo`             | widget   |
+| File attachment area with upload button           | `Attachment`       | widget   |
+| Case history / audit trail table                  | `CaseHistory`      | widget   |
+| File list with download actions                   | `FileUtility`      | widget   |
+| List of follower avatars + "Follow" button        | `Followers`        | widget   |
+| "+" quick-create button with dropdown menu        | `QuickCreate`      | widget   |
+| Summary card for a single record with action menu | `SummaryItem`      | widget   |
+| List of SummaryItem cards                         | `SummaryList`      | widget   |
+| Announcement / news card                          | `AppAnnouncement`  | widget   |
+
+### DSE / design system extension components
+
+| What you see                                                 | SDK component name  | Category              |
+| ------------------------------------------------------------ | ------------------- | --------------------- |
+| Coloured banner alert bar (info / warning / error / success) | `AlertBanner`       | designSystemExtension |
+| Hero-style banner with title + CTA button                    | `Banner`            | designSystemExtension |
+| Read-only field+value pairs in a case summary                | `CaseSummaryFields` | designSystemExtension |
+| Read-only label+value pairs in a details view                | `DetailsFields`     | designSystemExtension |
+| Collapsible section with header (accordion-style)            | `FieldGroup`        | designSystemExtension |
+| List of field groups with "Add" link                         | `FieldGroupList`    | designSystemExtension |
+| User operator info popover (name + contact)                  | `Operator`          | designSystemExtension |
+| Comment/pulse card with avatar + timestamp                   | `Pulse`             | designSystemExtension |
+| Rich text editor with theme-aware toolbar                    | `RichTextEditor`    | designSystemExtension |
+| Quick-create shortcut links list (WSS sidebar)               | `WssQuickCreate`    | designSystemExtension |
+
+### Recognition rules
+
+1. **An avatar + form title alone is NOT `CaseView`** — `CaseView` requires the full case shell: step bar + action/kebab menu (⋮) + tabbed content area. A simple form with a header is `DefaultForm`.
+2. **`FlowContainer` requires ALL THREE signals together** — avatar + assignment name at the top, form fields in the body, AND action buttons (Cancel / Save for later / Submit) at the bottom. If any one of the three is absent, do not identify it as `FlowContainer`.
+3. Match the most specific pattern first — a form with both a step bar AND action buttons means both `Stages` AND `ActionButtons` are present.
+4. If a field is read-only (label + value, no input box), it may be rendered by `DetailsFields` or `CaseSummaryFields` rather than the individual field component.
+5. Include only components you can confidently identify — do not guess.
+
+---
+
+## Targeted Migration
+
+> Used when the merged component list from Step 0 is non-empty. Replaces only those components.
+
+### T1 — Setup
+
+**T1.1 — Install {{designSystem}}** if not already in `package.json`.
+
+**T1.2 — Confirm installed version and provider API**
+Run `npm ls {{designSystem}}` to confirm the exact installed major version.
+Then read the installed package directly — do NOT rely on training knowledge, which may reflect a different version:
+
+1. Read the README: `cat node_modules/{{designSystem}}/README.md`  
+   Captures correct import paths, provider setup, and quick-start usage examples.
+2. Find the provider's type signature:  
+   `grep -rl "Provider" node_modules/{{designSystem}} --include="*.d.ts" | head -5`  
+   Then read the matched `.d.ts` file(s) to extract the exact provider name and every required prop.
+3. Check for peer dependencies: `cat node_modules/{{designSystem}}/package.json | grep -A 20 peerDep`
+
+**Verification gate — do not proceed to T1.3 until you have written out:**
+
+- The exact `import` statement for the provider (confirmed against the `.d.ts` above)
+- The complete provider JSX including all required props with their values (confirmed against the README/types above)
+
+**T1.3 — Add root provider to both entry points (always required)**
+Most design systems require a root provider/context wrapper for any component in the tree to work (e.g. `ThemeProvider`, `Provider`, `ConfigProvider`, `ChakraProvider`, etc.).
+
+Check whether `{{designSystem}}` requires one. If yes:
+
+- Add it to **both** `src/MashupApp.tsx` **and** `src/PortalApp.tsx` — wrapping the existing provider tree
+- Do this **before** launching any subagents, regardless of how few components are being migrated
+- Do **not** remove any existing providers (MUI providers may still be needed by unmigrated components)
+
+**T1.4 — FieldValueList (if `field` scope or any field component is in the list)**
+If any field component is being migrated, replace `src/components/designSystemExtension/FieldValueList/` with a {{designSystem}} implementation **first** — all field components depend on it for `displayMode` rendering.
+
+Required interface (must not change):
+
+```typescript
+interface FieldValueListProps {
+  name?: string;
+  value?: string;
+  variant?: 'stacked' | 'inline';
+}
+```
+
+**T1.5 — Update providers for full-app scopes (if `template` or `infra` components are in the list)**
+If `CaseView`, `AppShell`, `MashupApp`, or `PortalApp` are in the list, replace the old design system's `ThemeProvider` in `src/MashupApp.tsx` and `src/PortalApp.tsx` with {{designSystem}}'s provider.
+
+### T2 — Migrate components (parallel subagents, ≤10 at a time)
+
+For each component in the resolved list, launch a subagent:
+
+- If `category` = `field` → use prompt **`replace-field`** with `fieldName` + `designSystem`
+- Otherwise → use prompt **`replace-component`** with `componentName`, `componentCategory`, `componentPath`, `designSystem`
+
+If the list has ≤10 components, launch all at once.
+If the list has >10 components, batch into waves of ≤10 and wait for each wave before starting the next.
+
+### T3 — Cleanup
+
+After all subagents complete:
+
+1. Search for any remaining imports of the old design system in the migrated files — fix stragglers
+2. Run `npm run build` — fix ALL TypeScript errors until clean
+3. If providers were updated, run `npm run dev` and verify the app loads
+
+---
+
+## Full Migration
+
+> Used by Rule 4 only. Migrates all 81 components across 9 waves.
+
+> **Why 9 waves of 10?** Launching more than ~10 subagents simultaneously triggers rate-limit errors. Waves of 10 stay safely within the limit while still being ~10× faster than fully sequential execution. **Never launch the next wave until every subagent in the current wave has finished.**
+
+### Phase 1: Setup (sequential — blocks everything else)
+
+### 1.1 Install {{designSystem}}
+
+Install the {{designSystem}} package and any required peer dependencies. Do NOT remove MUI yet — it's needed until all replacements finish.
+
+### 1.2 Confirm installed version and provider API
+
+Run `npm ls {{designSystem}}` to confirm the exact installed major version.
+Then read the installed package directly — do NOT rely on training knowledge, which may reflect a different version:
+
+1. Read the README: `cat node_modules/{{designSystem}}/README.md`  
+   Captures correct import paths, provider setup, and quick-start usage examples.
+2. Find the provider's type signature:  
+   `grep -rl "Provider" node_modules/{{designSystem}} --include="*.d.ts" | head -5`  
+   Then read the matched `.d.ts` file(s) to extract the exact provider name and every required prop.
+3. Check for peer dependencies: `cat node_modules/{{designSystem}}/package.json | grep -A 20 peerDep`
+
+**Verification gate — do not proceed to 1.3 until you have written out:**
+
+- The exact `import` statement for the provider (confirmed against the `.d.ts` above)
+- The complete provider JSX including all required props with their values (confirmed against the README/types above)
+
+### 1.3 Add root provider to both entry points
+
+Most design systems require a root provider/context wrapper for any component in the tree to work.
+
+Check whether `{{designSystem}}` requires one. If yes:
+
+- Add it to **both** `src/MashupApp.tsx` **and** `src/PortalApp.tsx` — wrapping the existing provider tree
+- Do **not** remove any existing providers (MUI providers are still needed by unmigrated components)
+
+### 1.4 Replace FieldValueList (blocking dependency for all fields)
+
+Replace `src/components/designSystemExtension/FieldValueList/` with a {{designSystem}} implementation **before** starting any wave. Every field component depends on this for `displayMode` rendering.
+
+Required interface (must not change — all 27 field components depend on it):
+
+```typescript
+interface FieldValueListProps {
+  name?: string;
+  value?: string;
+  variant?: 'stacked' | 'inline';
+}
+```
+
+### 1.5 Update provider files for full migration
+
+Replace MUI's `ThemeProvider` / `LegacyThemeProvider` in `src/MashupApp.tsx` and `src/PortalApp.tsx` with {{designSystem}}'s provider. Remove `LocalizationProvider` from `@mui/x-date-pickers` only if {{designSystem}} provides its own date picker.
+
+---
+
+## Phase 2: Replacement — 9 waves (one wave at a time, ≤10 subagents per wave)
+
+For field components → prompt: **`replace-field`** with `fieldName` + `designSystem`.
+For all others → prompt: **`replace-component`** with `componentName`, `componentCategory`, `componentPath`, and `designSystem`.
+
+---
+
+### Wave 1 — Fields batch 1 (10 subagents — wait for all before Wave 2)
+
+Each uses prompt: **`replace-field`** with `designSystem` = **{{designSystem}}**
+
+| #   | `fieldName`  |
+| --- | ------------ |
+| 1   | TextInput    |
+| 2   | TextArea     |
+| 3   | Dropdown     |
+| 4   | Checkbox     |
+| 5   | RadioButtons |
+| 6   | Date         |
+| 7   | DateTime     |
+| 8   | Time         |
+| 9   | Currency     |
+| 10  | Decimal      |
+
+---
+
+### Wave 2 — Fields batch 2 (9 subagents — wait for all before Wave 3)
+
+Each uses prompt: **`replace-field`** with `designSystem` = **{{designSystem}}**
+
+| #   | `fieldName`  |
+| --- | ------------ |
+| 11  | Integer      |
+| 12  | Percentage   |
+| 13  | Email        |
+| 14  | Phone        |
+| 15  | URL          |
+| 16  | AutoComplete |
+| 17  | Multiselect  |
+| 18  | RichText     |
+| 19  | ScalarList   |
+
+---
+
+### Wave 3 — Fields batch 3 + DSE batch 1 (9 subagents — wait for all before Wave 4)
+
+Fields use prompt: **`replace-field`** | DSE use prompt: **`replace-component`** with `componentCategory` = `designSystemExtension`
+
+| #   | prompt            | `fieldName` / `componentName` | `componentPath`                      | MUI to replace                    |
+| --- | ----------------- | ----------------------------- | ------------------------------------ | --------------------------------- |
+| 20  | replace-field     | SelectableCard                | —                                    | —                                 |
+| 21  | replace-field     | Group                         | —                                    | —                                 |
+| 22  | replace-field     | Location                      | —                                    | —                                 |
+| 23  | replace-field     | ObjectReference               | —                                    | —                                 |
+| 24  | replace-field     | SemanticLink                  | —                                    | —                                 |
+| 25  | replace-field     | UserReference                 | —                                    | —                                 |
+| 26  | replace-field     | CancelAlert                   | —                                    | —                                 |
+| 27  | replace-field     | TextContent                   | —                                    | —                                 |
+| 28  | replace-component | AlertBanner                   | `designSystemExtension/AlertBanner/` | `Alert`, `AlertTitle`, `Collapse` |
+
+---
+
+### Wave 4 — DSE batch 2 + Templates batch 1 (10 subagents — wait for all before Wave 5)
+
+DSE use prompt: **`replace-component`** with `componentCategory` = `designSystemExtension`
+Templates use prompt: **`replace-component`** with `componentCategory` = `template`
+
+| #   | category              | `componentName`   | `componentPath`                            | MUI to replace                              |
+| --- | --------------------- | ----------------- | ------------------------------------------ | ------------------------------------------- |
+| 29  | designSystemExtension | Banner            | `designSystemExtension/Banner/`            | `Box`, `Typography`, `Button`               |
+| 30  | designSystemExtension | CaseSummaryFields | `designSystemExtension/CaseSummaryFields/` | `Grid`, `Typography`                        |
+| 31  | designSystemExtension | DetailsFields     | `designSystemExtension/DetailsFields/`     | `Grid`, `Typography`                        |
+| 32  | designSystemExtension | FieldGroup        | `designSystemExtension/FieldGroup/`        | `Box`, `Divider`, `Typography`              |
+| 33  | designSystemExtension | FieldGroupList    | `designSystemExtension/FieldGroupList/`    | `List`, `ListItem`, `Button`                |
+| 34  | designSystemExtension | Operator          | `designSystemExtension/Operator/`          | `Avatar`, `Typography`, `Box`               |
+| 35  | designSystemExtension | Pulse             | `designSystemExtension/Pulse/`             | `TextField`, `List`, `Avatar`, `Typography` |
+| 36  | designSystemExtension | RichTextEditor    | `designSystemExtension/RichTextEditor/`    | MUI wrappers (keep editor lib)              |
+| 37  | designSystemExtension | WssQuickCreate    | `designSystemExtension/WssQuickCreate/`    | `Button`, `Menu`, `MenuItem`                |
+| 38  | template              | OneColumn         | `template/OneColumn/`                      | `Grid`, `makeStyles`                        |
+
+---
+
+### Wave 5 — Templates batch 2 (10 subagents — wait for all before Wave 6)
+
+Each uses prompt: **`replace-component`** with `componentCategory` = `template`, `designSystem` = **{{designSystem}}**
+
+| #   | `componentName`     | `componentPath`                 | MUI to replace                   |
+| --- | ------------------- | ------------------------------- | -------------------------------- |
+| 39  | TwoColumn           | `template/TwoColumn/`           | `Grid` with column ratios        |
+| 40  | NarrowWide          | `template/NarrowWide/`          | `Grid` (3:9 ratio)               |
+| 41  | WideNarrow          | `template/WideNarrow/`          | `Grid` (9:3 ratio)               |
+| 42  | Details             | `template/Details/`             | `Grid`, `Tabs`, `Tab`            |
+| 43  | CaseView            | `template/CaseView/`            | `Box`, `Grid`, `Typography`      |
+| 44  | CaseSummary         | `template/CaseSummary/`         | `Box`, `Grid`                    |
+| 45  | CaseViewActionsMenu | `template/CaseViewActionsMenu/` | `Menu`, `MenuItem`, `IconButton` |
+| 46  | SelfServiceCaseView | `template/SelfServiceCaseView/` | `Box`, `Grid`                    |
+| 47  | AppShell            | `template/AppShell/`            | `Box`, layout containers         |
+| 48  | DefaultForm         | `template/DefaultForm/`         | `Grid`, `Box`                    |
+
+---
+
+### Wave 6 — Templates batch 3 (10 subagents — wait for all before Wave 7)
+
+Each uses prompt: **`replace-component`** with `componentCategory` = `template`, `designSystem` = **{{designSystem}}**
+
+| #   | `componentName` | `componentPath`            | MUI to replace                   |
+| --- | --------------- | -------------------------- | -------------------------------- |
+| 49  | DefaultPage     | `template/DefaultPage/`    | `Grid`, `Box`                    |
+| 50  | ObjectPage      | `template/ObjectPage/`     | `Grid`, `Box`                    |
+| 51  | SimpleTable     | `template/SimpleTable/`    | `Table`, `TableRow`, `TableCell` |
+| 52  | ListView        | `template/ListView/`       | `Table`, `Pagination`            |
+| 53  | ListPage        | `template/ListPage/`       | `Table`, `Box`                   |
+| 54  | DataReference   | `template/DataReference/`  | `Modal`/`Dialog`, `TextField`    |
+| 55  | AdvancedSearch  | `template/AdvancedSearch/` | `Dialog`, `TextField`, `Button`  |
+| 56  | SubTabs         | `template/SubTabs/`        | `Tabs`, `Tab`                    |
+| 57  | BannerPage      | `template/BannerPage/`     | `Box`, `Typography`              |
+| 58  | Confirmation    | `template/Confirmation/`   | `Box`, `Typography`              |
+
+> **ListView note:** This is the largest file (~1500 lines). If the subagent hits a length limit, retry with a prompt that lists each MUI import by name.
+
+---
+
+### Wave 7 — Templates batch 4 (9 subagents — wait for all before Wave 8)
+
+Each uses prompt: **`replace-component`** with `componentCategory` = `template`, `designSystem` = **{{designSystem}}**
+
+| #   | `componentName`         | `componentPath`                     | MUI to replace                                          |
+| --- | ----------------------- | ----------------------------------- | ------------------------------------------------------- |
+| 59  | HierarchicalForm        | `template/HierarchicalForm/`        | `Box`, `Grid`                                           |
+| 60  | InlineDashboard         | `template/InlineDashboard/`         | `Box`, `Grid`                                           |
+| 61  | InlineDashboardPage     | `template/InlineDashboardPage/`     | `Box`, `Grid`                                           |
+| 62  | PromotedFilters         | `template/PromotedFilters/`         | `Box`, `Grid`                                           |
+| 63  | MultiReferenceReadOnly  | `template/MultiReferenceReadOnly/`  | `List`, `ListItem`                                      |
+| 64  | SingleReferenceReadOnly | `template/SingleReferenceReadOnly/` | `List`, `ListItem`                                      |
+| 65  | FieldGroupTemplate      | `template/FieldGroupTemplate/`      | `Box`, `Divider`                                        |
+| 66  | WssNavBar               | `template/WssNavBar/`               | `AppBar`, `Toolbar`                                     |
+| 67  | ToDo                    | `widget/ToDo/`                      | `Card`, `List`, `Badge`, `Avatar`, `Button`, `Snackbar` |
+
+> Note: #67 (ToDo) uses `componentCategory` = `widget`
+
+---
+
+### Wave 8 — Widgets (8 subagents — wait for all before Wave 9)
+
+Each uses prompt: **`replace-component`** with `componentCategory` = `widget`, `designSystem` = **{{designSystem}}**
+
+| #   | `componentName` | `componentPath`           | MUI to replace                                 |
+| --- | --------------- | ------------------------- | ---------------------------------------------- |
+| 68  | Attachment      | `widget/Attachment/`      | `Button`, `Dialog`, `Table`, `IconButton`      |
+| 69  | CaseHistory     | `widget/CaseHistory/`     | `Table`, `TableRow`, `TableCell`, `Typography` |
+| 70  | FileUtility     | `widget/FileUtility/`     | `Button`, `IconButton`, `List`, `Dialog`       |
+| 71  | Followers       | `widget/Followers/`       | `List`, `ListItem`, `Avatar`, `Button`         |
+| 72  | QuickCreate     | `widget/QuickCreate/`     | `Button`, `Menu`, `MenuItem`                   |
+| 73  | SummaryItem     | `widget/SummaryItem/`     | `Card`, `CardContent`, `Typography`            |
+| 74  | SummaryList     | `widget/SummaryList/`     | `List`, `ListItem`                             |
+| 75  | AppAnnouncement | `widget/AppAnnouncement/` | `Alert`, `Snackbar`                            |
+
+---
+
+### Wave 9 — Infra (6 subagents)
+
+Each uses prompt: **`replace-component`** with `componentCategory` = `infra`, `designSystem` = **{{designSystem}}**
+
+| #   | `componentName` | `componentPath`          | MUI to replace                                  |
+| --- | --------------- | ------------------------ | ----------------------------------------------- |
+| 76  | ActionButtons   | `infra/ActionButtons/`   | `Button`, `Stack`, `Divider`                    |
+| 77  | DashboardFilter | `infra/DashboardFilter/` | `Select`, `MenuItem`, `Box`                     |
+| 78  | DeferLoad       | `infra/DeferLoad/`       | `CircularProgress`, `Box`                       |
+| 79  | NavBar          | `infra/NavBar/`          | `AppBar`, `Toolbar`, `Button`, `Menu`, `Avatar` |
+| 80  | Stages          | `infra/Stages/`          | `Stepper`, `Step`, `StepLabel`, `makeStyles`    |
+| 81  | VerticalTabs    | `infra/VerticalTabs/`    | `Tabs`, `Tab`, `Box`                            |
+
+---
+
+## Phase 3: Cleanup (sequential — after ALL 9 waves complete)
+
+### 3.1 Remove MUI dependencies
+
+```bash
+npm uninstall @mui/material @mui/icons-material @mui/styles @mui/x-date-pickers @emotion/react @emotion/styled
+```
+
+Keep `@mui/x-date-pickers` and `@emotion/*` ONLY if {{designSystem}} doesn't provide a date picker.
+
+### 3.2 Remove remaining MUI imports
+
+Search all files for leftover `@mui/*` imports AND `makeStyles` calls. Fix any stragglers.
+
+### 3.3 Remove MUI theme augmentation
+
+Delete `src/mui-theme-augmentation.d.ts` if it exists.
+
+### 3.4 Verify build
+
+Run `npm run build` — fix ALL TypeScript errors until clean.
+
+> **Note:** A passing build does not catch undefined-component runtime errors. Components removed from JSX imports but still referenced in JSX will only fail at render time.
+
+### 3.5 Verify runtime
+
+Run `npm run dev` and exercise:
+
+- App loads without console errors
+- Open a **ListView** (table with pagination)
+- Open a **ToDo widget**
+- Open a **form with Dropdown and Date fields**
+- Trigger a **Create Case** flow end-to-end
+- Open a record in **read-only / Details view** (exercises FieldValueList)
+- Confirm validation messages appear on required fields
+
+If any `ReferenceError: X is not defined` appears in the console, a component was removed from imports but its JSX usage was not updated. Fix and re-verify.
+
+---
+
+## Critical Rules — NEVER violate these
+
+1. **NEVER modify `@pega/sdk-react` imports or behavior**
+2. **NEVER remove `handleEvent(actions, 'changeNblur', propName, value)` calls**
+3. **NEVER remove `getPConnect()` prop extraction**
+4. **NEVER remove `displayMode` handling in field components**
+5. **NEVER modify `src/components/helpers/event-utils.ts`**
+6. **NEVER change the `...sdkComponents` spread in `component-map.ts`**
+7. **NEVER remove `data-test-id` attributes**
+8. **NEVER modify PCore.\* API calls**
+9. **KEEP the same default export function names** — component-map.ts imports depend on them
+10. **KEEP the same file/directory structure** — only file content changes, not paths

package/templates/react-sdk-reference/.claude/skills/component-contracts.md

@@ -0,0 +1,140 @@
+# Skill: Component Contracts Reference
+
+Quick-reference lookup of all registered component names and their prop contracts. Use this when you need to know what props a specific component receives from the Pega platform.
+
+---
+
+## Field Components
+
+All extend `PConnFieldProps` from `@pega/sdk-react`.
+
+| Registry Name | File | Additional Props |
+|---------------|------|-----------------|
+| `TextInput` | `field/TextInput/TextInput.tsx` | `fieldMetadata?: any` |
+| `TextArea` | `field/TextArea/` | `fieldMetadata?: any` |
+| `Dropdown` | `field/Dropdown/` | `datasource?, listType?` |
+| `Checkbox` | `field/Checkbox/` | `value: boolean` (not string) |
+| `RadioButtons` | `field/RadioButtons/` | `datasource?, listType?` |
+| `Date` | `field/Date/` | — |
+| `DateTime` | `field/DateTime/` | — |
+| `Time` | `field/Time/` | — |
+| `Currency` | `field/Currency/` | `currencyISOCode?, formatterType?` |
+| `Decimal` | `field/Decimal/` | `decimalPrecision?` |
+| `Integer` | `field/Integer/` | — |
+| `Percentage` | `field/Percentage/` | — |
+| `Email` | `field/Email/Email.tsx` | — |
+| `Phone` | `field/Phone/Phone.tsx` | `datasource?` (country codes) |
+| `URL` | `field/URL/` | — |
+| `AutoComplete` | `field/AutoComplete/` | `datasource?, listType?, columns?` |
+| `Multiselect` | `field/Multiselect/Multiselect.tsx` | `datasource?, listType?` |
+| `RichText` | `field/RichText/` | — |
+| `ScalarList` | `field/ScalarList/` | `datasource?` |
+| `SelectableCard` | `field/SelectableCard/` | `datasource?` |
+| `Group` | `field/Group/` | — |
+| `Location` | `field/Location/` | — |
+| `ObjectReference` | `field/ObjectReference/` | `value: object` |
+| `SemanticLink` | `field/SemanticLink/` | `text?, displayAs?` |
+| `UserReference` | `field/UserReference/` | `showAsFormattedText?` |
+| `CancelAlert` | `field/CancelAlert/` | — |
+| `TextContent` | `field/TextContent/` | `content?` |
+
+---
+
+## Template Components
+
+All extend `PConnProps`. Most receive React `children` or use `getPConnect().getChildren()`.
+
+| Registry Name | File | Key Props |
+|---------------|------|-----------|
+| `OneColumn` | `template/OneColumn/OneColumn.tsx` | `children` |
+| `OneColumnPage` | `template/OneColumn/OneColumnPage.tsx` | `children` |
+| `OneColumnTab` | `template/OneColumn/OneColumnTab.tsx` | `children` |
+| `TwoColumn` | `template/TwoColumn/TwoColumn.tsx` | `children, templateCol?` |
+| `TwoColumnPage` | `template/TwoColumn/TwoColumnPage.tsx` | `children` |
+| `TwoColumnTab` | `template/TwoColumn/TwoColumnTab.tsx` | `children` |
+| `NarrowWide` | `template/NarrowWide/NarrowWide.tsx` | `children, templateCol?` |
+| `WideNarrow` | `template/WideNarrow/WideNarrow.tsx` | `children, templateCol?` |
+| `Details` | `template/Details/Details.tsx` | `children` |
+| `DefaultForm` | `template/DefaultForm/` | PConnect children |
+| `DefaultPage` | `template/DefaultPage/` | PConnect children |
+| `CaseView` | `template/CaseView/` | PConnect children, `header?, subheader?` |
+| `CaseSummary` | `template/CaseSummary/` | PConnect children |
+| `Confirmation` | `template/Confirmation/` | `label?` |
+| `SimpleTable` | `template/SimpleTable/SimpleTable.tsx` | `datasource?, fields?, label?` |
+| `ListView` | `template/ListView/` | `datasource?, fields?` |
+| `SubTabs` | `template/SubTabs/` | PConnect children |
+| `AppShell` | `template/AppShell/AppShell.tsx` | PConnect children |
+| `DataReference` | `template/DataReference/` | PConnect children |
+| `ListPage` | `template/ListPage/ListPage.tsx` | PConnect children |
+| `InlineDashboard` | `template/InlineDashboard/` | PConnect children |
+| `FieldGroupTemplate` | `template/FieldGroupTemplate/` | PConnect children |
+
+---
+
+## Widget Components
+
+All extend `PConnProps`. Fetch their own data.
+
+| Registry Name | File | Key Props |
+|---------------|------|-----------|
+| `Todo` | `widget/ToDo/` | `datasource?, headerText?, context?` |
+| `Attachment` | `widget/Attachment/` | `value, allowMultiple?, extensions?` |
+| `CaseHistory` | `widget/CaseHistory/` | `datasource?` |
+| `FileUtility` | `widget/FileUtility/FileUtility.tsx` | `datasource?` |
+| `Followers` | `widget/Followers/` | — |
+| `AppAnnouncement` | `widget/AppAnnouncement/` | `datasource?, headerText?` |
+| `QuickCreate` | `widget/QuickCreate/` | — |
+| `SummaryItem` | `widget/SummaryItem/` | `label?, value?, actions?` |
+| `SummaryList` | `widget/SummaryList/` | `datasource?` |
+
+---
+
+## Design System Extension Components
+
+| Registry Name | File | Key Props |
+|---------------|------|-----------|
+| `FieldValueList` | `designSystemExtension/FieldValueList/` | `name?, value?, variant?` |
+| `AlertBanner` | `designSystemExtension/AlertBanner/` | `variant, heading?, messages, onClose?` |
+| `Banner` | `designSystemExtension/Banner/` | `variant?, text?` |
+| `CaseSummaryFields` | `designSystemExtension/CaseSummaryFields/` | PConnect-based |
+| `DetailsFields` | `designSystemExtension/DetailsFields/` | PConnect-based |
+| `FieldGroup` | `designSystemExtension/FieldGroup/` | PConnect-based |
+| `FieldGroupList` | `designSystemExtension/FieldGroupList/` | PConnect-based |
+| `Operator` | `designSystemExtension/Operator/` | `label?, name?, id?` |
+| `Pulse` | `designSystemExtension/Pulse/` | PConnect-based |
+| `RichTextEditor` | `designSystemExtension/RichTextEditor/` | extends `PConnFieldProps` |
+| `WssQuickCreate` | `designSystemExtension/WssQuickCreate/` | — |
+
+---
+
+## Infrastructure (from `sdkComponents` — do NOT replace)
+
+| Registry Name | Source |
+|---------------|--------|
+| `RootContainer` | `@pega/sdk-react` |
+| `ViewContainer` | `@pega/sdk-react` |
+| `FlowContainer` | `@pega/sdk-react` |
+| `Reference` | `@pega/sdk-react` |
+| `View` | `@pega/sdk-react` |
+| `Region` | `@pega/sdk-react` |
+| `CaseView` (infra) | `@pega/sdk-react` |
+| `Assignment` | `@pega/sdk-react` |
+| `AssignmentCard` | `@pega/sdk-react` |
+| `ActionButtons` | `@pega/sdk-react` |
+| `CaseSummary` (infra) | `@pega/sdk-react` |
+| `ErrorBoundary` | `@pega/sdk-react` |
+| `MultiStep` | `@pega/sdk-react` |
+
+---
+
+## Infra (sample-local, replaceable but exercise caution)
+
+| Registry Name | File |
+|---------------|------|
+| `ActionButtons` | `infra/ActionButtons/` |
+| `DeferLoad` | `infra/DeferLoad/` |
+| `NavBar` | `infra/NavBar/` |
+| `Stages` | `infra/Stages/` |
+| `DashboardFilter` | `infra/DashboardFilter/` |
+| `VerticalTabs` | `infra/VerticalTabs/VerticalTabs.tsx` |
+| `LeftAlignVerticalTabs` | `infra/VerticalTabs/LeftAlignVerticalTabs.tsx` |