@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/.ai-common/prompts/generate-template-components.md

@@ -0,0 +1,283 @@
+---
+ai-description: Generate all (or a subset of) template components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where template components should be generated (e.g. `src/components/template/`)
+- **Component list** — which templates to generate (default: all 32 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the output path, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the template components be generated? (e.g. `src/components/template/`)
+
+> **Note:** The design system applies only to **layout templates** (TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants). Form templates and page templates use the PConnect bridge pattern and are design-system agnostic — they will be generated without DS primitives regardless of your choice.
+
+If the user specified a subset (e.g., "just TwoColumn and OneColumn"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 32 templates)
+
+| Component               | Category   |
+| ----------------------- | ---------- |
+| AdvancedSearch          | Page       |
+| AppShell                | Page       |
+| BannerPage              | Page       |
+| CaseSummary             | Page       |
+| CaseView                | Page       |
+| CaseViewActionsMenu     | Widget     |
+| Confirmation            | Page       |
+| DataReference           | Form       |
+| DefaultForm             | Form       |
+| DefaultPage             | Page       |
+| Details                 | Layout     |
+| DetailsSubTabs          | Layout     |
+| DetailsThreeColumn      | Layout     |
+| DetailsTwoColumn        | Layout     |
+| DynamicTabs             | Navigation |
+| FieldGroupTemplate      | Form       |
+| HierarchicalForm        | Form       |
+| InlineDashboard         | Page       |
+| InlineDashboardPage     | Page       |
+| ListPage                | Page       |
+| ListView                | Page       |
+| MultiReferenceReadOnly  | Display    |
+| NarrowWide              | Layout     |
+| OneColumn               | Layout     |
+| PromotedFilters         | Widget     |
+| SelfServiceCaseView     | Page       |
+| SimpleTable             | Table      |
+| SingleReferenceReadOnly | Display    |
+| SubTabs                 | Navigation |
+| TwoColumn               | Layout     |
+| WideNarrow              | Layout     |
+| WssNavBar               | Navigation |
+| SearchForm              | Form       |
+| SearchGroups            | Form       |
+
+---
+
+## Step 1 — Read `template-components.md` (once, for the entire session)
+
+Read the full contents of `{{SKILL_DIR}}/template-components.md`.
+
+This gives you:
+
+- **Layout template pattern** — DS-agnostic grid skeleton with `// [DS GRID]` placeholder; `templateCol` parsing logic; responsive behavior rules
+- **Design System Adaptation section** — how to map the chosen DS's grid/flex primitive to the computed column ratios
+- **Form template pattern** — PConnect bridge via `connectToState` HOC wrapping `PConnectComponent`; `utils/index.ts` with `mapStateToProps`; no DS involved
+- **Page template pattern** — region extraction via `getRawMetadata()` and PConnect bridge; complex PCore API interactions; no DS involved
+- Registration conventions and helper utilities
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+### 2a — Check and install the DS package
+
+Run this command in your terminal:
+
+```bash
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+
+```bash
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+
+Design systems require their global stylesheet — without it, components render unstyled.
+
+#### Known DS style requirements (examples — verify from README for exact paths):
+
+| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
+| Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
+| Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
+| Radix Themes  | `@radix-ui/themes`       | `import '@radix-ui/themes/styles.css';`  | `<Theme>`                  |
+| Chakra UI     | (included)               | (none — runtime)                         | `<ChakraProvider>`         |
+| Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
+| MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
+
+These are **examples** based on common versions. Always verify the exact import path and provider name from the installed package's README (`node_modules/<ds>/README.md`).
+
+If in table: install styles package (if separate), add CSS import as **first import** in `src/main.tsx`, add Provider in `src/AppProviders.tsx`.
+If not in table: check README and `find node_modules/<ds> -name "*.css" -path "*/dist/*" | head -5`.
+
+Verification: `grep -n "import.*css\|import.*styles" src/main.tsx` must return a result. Do NOT proceed until confirmed.
+
+Report what was installed and configured.
+
+> You only need layout-related DS components. Form and page templates do not use the DS.
+
+Run these commands to discover the actual API (do NOT rely on training knowledge):
+
+1. Read the README for correct import paths and usage patterns:
+
+   ```bash
+   cat node_modules/<designSystem>/README.md
+   ```
+
+2. List every exported component — focus on layout primitives (Grid, Columns, Flex, SimpleGrid, Row, Col):
+
+   ```bash
+   grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"
+   ```
+
+3. For every grid/layout component you plan to use, read its prop interface:
+
+   ```bash
+   find node_modules/<designSystem> -name "Grid.d.ts" -o -name "Col.d.ts" -o -name "Flex.d.ts" | head -5
+   grep -A 40 "interface.*Props" <path-from-above>
+   ```
+
+4. Note **responsive breakpoint APIs** and **column sizing conventions** (e.g., 12-column grid, fractional units, span props).
+
+Only use component names and prop names confirmed in these files.
+
+Build a **DS layout API reference** from this discovery. Reuse it for every layout template — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+
+> "The following N components already exist: [list]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/template-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component — do not rely solely on the general `template-components.md`.
+
+After reading, extract and keep active:
+
+- **Template category** — Layout (uses DS grid from Step 2) | Form (PConnect bridge + CSS) | Page (region extraction + PConnect bridge)
+- **Behavioral Contract** — sub-variants, region handling, slot rendering logic
+- **Design System Mapping** table — the recommended DS layout primitive (for Layout templates only)
+
+If no skill file exists at that path, use the general pattern from `template-components.md` loaded in Step 1.
+
+⚠️ The general skill file (`template-components.md`) provides the pattern skeletons. The component-specific skill file provides the **exact region structure, sub-variant keys, and rendering logic**. Both are needed — generating from only the general skill will produce templates with wrong region counts or missing sub-variant registrations.
+
+### 4b — Generate the component files
+
+Create the directory `<outputPath>/<ComponentName>/`.
+
+Create `<ComponentName>.tsx` using the structure matching the template category from `template-components.md` (loaded in Step 1):
+
+- **Layout**: `PropsWithChildren` + `templateCol` parsing (split on whitespace, strip units, compute ratios) + DS grid/flex from Step 2 rendering children in computed column ratios. On mobile: columns must stack to full width.
+- **Form**: Use the `connectToState` HOC pattern from the skill file. Each child field MUST be wrapped in `connectToState(mapStateToProps)` for Redux store subscription. Plain `createElement(PConnectComponent, ...)` without `connectToState` will cause fields to NOT render. Also create `utils/index.ts` with `mapStateToProps` and `getKeyForMappedField`.
+- **Page**: The generated component MUST include ALL props, side effects, PCore API calls, useEffect hooks, and state management from the skill file's Component Skeleton. Page templates are complex — they interact with PCore APIs and infrastructure components. NEVER simplify a Page template to a single return statement or a pass-through wrapper.
+
+⚠️ **CRITICAL RULE for Form and Page templates:** The component-specific skill file's Component Skeleton is the **minimum implementation**. You must include every `useState`, `useEffect`, `getComponentFromRegistry`, `PCore.*` call, helper function, and utility import shown in that skeleton. If your generated output is significantly shorter than the skeleton, you have over-simplified and MUST add the missing logic.
+
+Apply the Behavioral Contract from the component skill file (sub-variants, region handling, slot logic).
+
+Create `index.tsx` if required by the skill file:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+Create any CSS file required by the skill file (e.g., `DefaultForm.css` with grid classes).
+
+Create any `utils/` or helper files mandated by the skill file (e.g., `utils/index.ts` for DefaultForm).
+
+### 4b.1 — Post-generation verification (MANDATORY for Form and Page templates)
+
+After generating each Form or Page template, verify:
+
+1. **Form templates:** `connectToState` is imported and used; `mapStateToProps` + `getKeyForMappedField` are in `utils/index.ts`; each child field uses the `<Child key={getKeyForMappedField(kid)} {...kid} />` pattern.
+2. **Page templates:** All props listed in the skill file's Props table are destructured; all `getComponentFromRegistry()` lookups from the skeleton are present; all `useEffect` hooks from the skeleton are present; all PCore API calls (`PCore.getEnvironmentInfo()`, `PCore.getPubSubUtils()`, etc.) from the skeleton are present; infrastructure components (NavBar, VerticalTabs, DeferLoad, etc.) receive ALL required props from the skeleton.
+3. **Both:** The generated file is NOT a single-line return. If the skill file skeleton is 50+ lines, your output should be comparable in length.
+
+If any check fails, revise the generated output before proceeding.
+
+### 4b.2 — Create sub-variant files (MANDATORY for Layout templates)
+
+⛔ **Do NOT skip this step.** Without sub-variants, portal pages and tabs won't render column layouts.
+
+After generating **TwoColumn**, **OneColumn**, **NarrowWide**, or **WideNarrow**, you MUST immediately create these additional files in the same directory:
+
+| Base template | Sub-variant files to create                                         |
+| ------------- | ------------------------------------------------------------------- |
+| TwoColumn     | `TwoColumnPage.tsx`, `TwoColumnTab.tsx`                             |
+| OneColumn     | `OneColumnPage.tsx`, `OneColumnTab.tsx`                             |
+| NarrowWide    | `NarrowWideForm.tsx`, `NarrowWidePage.tsx`                          |
+| WideNarrow    | `WideNarrowDetails.tsx`, `WideNarrowForm.tsx`, `WideNarrowPage.tsx` |
+
+Each sub-variant is a one-line passthrough that delegates to the base component via the registry:
+
+```typescript
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import type { PConnProps } from '@pega/sdk-react';
+
+export default function TwoColumnPage(props: PConnProps & Record<string, any>) {
+  const TwoColumn = getComponentFromRegistry('TwoColumn');
+  return <TwoColumn {...props} />;
+}
+```
+
+Replace `TwoColumnPage`/`TwoColumn` with the appropriate names for each sub-variant.
+
+### 4c — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top of the file in the **Templates** section:
+   ```typescript
+   import <ComponentName> from './template/<ComponentName>';
+   ```
+2. Add an entry in the return object of `getSampleComponentMap()` under the templates comment:
+   ```typescript
+   <ComponentName>,
+   ```
+3. **Also import and register ALL sub-variant files** created in Step 4b.2. Each gets its own import and map entry.
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template`<, using <DS component name> for grid>` if layout"
+
+---
+
+## Step 5 — Verify the build
+
+Run:
+
+```bash
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report a summary: list of all files created and all entries added to `component-map.ts`.

package/templates/react-sdk-reference/.ai-common/prompts/generate-widget-components.md

@@ -0,0 +1,222 @@
+---
+ai-description: Generate all (or a subset of) widget components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where widget components should be generated (e.g. `src/components/widget/`)
+- **Component list** — which widgets to generate (default: all 9 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
+
+⛔ **STOP** — If the user's message does not explicitly state BOTH the design system AND the output path, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the widget components be generated? (e.g. `src/components/widget/`)
+
+If the user specified a subset (e.g., "just ToDo and Attachment"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 10 widgets)
+
+| Component                | Description                     |
+| ------------------------ | ------------------------------- |
+| ActionButtonsForFileUtil | Action buttons for file utility |
+| AppAnnouncement          | System-wide announcements       |
+| Attachment               | File upload/download            |
+| CaseHistory              | Case audit trail                |
+| FileUtility              | File management utility         |
+| Followers                | Case followers list             |
+| QuickCreate              | Quick case creation buttons     |
+| SummaryItem              | Single summary card             |
+| SummaryList              | List of summary cards           |
+| ToDo                     | Assignment worklist             |
+
+---
+
+## Step 1 — Read `widget-components.md` (once, for the entire session)
+
+Read the full contents of `{{SKILL_DIR}}/widget-components.md`.
+
+This gives you:
+
+- The DS-agnostic data-fetching skeleton with `// [DS RENDER]` placeholder
+- The Design System Adaptation guide (primitive mapping table, icon discovery rules)
+- All common Pega APIs used in widgets: `PCore.getDataPageUtils()`, `PCore.getMashupApi()`, `PCore.getAttachmentUtils()`, `pConn.getCaseInfo()`, etc.
+- Registration conventions
+
+> The PCore data-fetching logic is always identical regardless of design system. Only the `// [DS RENDER]` section changes per DS.
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+### 2a — Check and install the DS package
+
+Run this command in your terminal:
+
+```bash
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+
+```bash
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+
+Design systems require their global stylesheet — without it, components render unstyled.
+
+#### Known DS style requirements (examples — verify from README for exact paths):
+
+| Design System | Styles Package (example) | CSS Import in `src/main.tsx` (example)   | Provider Wrapper (example) |
+| ------------- | ------------------------ | ---------------------------------------- | -------------------------- |
+| Carbon        | `@carbon/styles`         | `import '@carbon/react/css/styles.css';` | `<Theme>`                  |
+| Ant Design    | (included)               | `import 'antd/dist/reset.css';`          | `<ConfigProvider>`         |
+| Radix Themes  | `@radix-ui/themes`       | `import '@radix-ui/themes/styles.css';`  | `<Theme>`                  |
+| Chakra UI     | (included)               | (none — runtime)                         | `<ChakraProvider>`         |
+| Shadcn/ui     | (Tailwind)               | `import './globals.css';`                | None                       |
+| MUI           | (included)               | (none — CSS-in-JS)                       | `<ThemeProvider>`          |
+
+These are **examples** based on common versions. Always verify the exact import path and provider name from the installed package's README (`node_modules/<ds>/README.md`).
+
+If in table: install styles package (if separate), add CSS import as **first import** in `src/main.tsx`, add Provider in `src/AppProviders.tsx`.
+If not in table: check README and `find node_modules/<ds> -name "*.css" -path "*/dist/*" | head -5`.
+
+Verification: `grep -n "import.*css\|import.*styles" src/main.tsx` must return a result. Do NOT proceed until confirmed.
+
+Report what was installed and configured.
+
+Run these commands to discover the actual API (do NOT rely on training knowledge):
+
+1. Read the README for correct import paths and usage patterns:
+
+   ```bash
+   cat node_modules/<designSystem>/README.md
+   ```
+
+2. List every exported component:
+
+   ```bash
+   grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"
+   ```
+
+3. For every component you plan to use (Card, List, Table, Button, Badge, Spinner), read its prop interface:
+
+   ```bash
+   find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3
+   grep -A 40 "interface.*Props" <path-from-above>
+   ```
+
+4. Check for a **companion icon package** — if it exists, read its exports before using any icon name. Never guess icon names.
+
+5. Check for **size/variant conventions** — use built-in props rather than custom padding.
+
+6. Check for **CSS tokens** — use design system CSS custom properties for spacing; never hardcode `px` values.
+
+Only use component names and prop names confirmed in these files.
+
+Build a **DS UI primitive reference map** from this discovery. Reuse it for every widget — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+
+> "The following N components already exist: [list]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file (MANDATORY — do not skip)
+
+Read the file `{{SKILL_DIR}}/widget-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `widget-components.md`.
+
+After reading, extract and keep active:
+
+- **Behavioral Contract** — the exact PCore API calls, state variables, event handlers, and edge cases specific to this widget
+- **Design System Mapping** table — the recommended DS primitive for this component's presentation layer
+- **Props interface** — any required/optional props beyond the base `PConnProps`
+
+If no skill file exists at that path (e.g., `SummaryList`), use the general data-fetching pattern from `widget-components.md` loaded in Step 1.
+
+⚠️ The general skill file (`widget-components.md`) provides the skeleton. The component-specific skill file provides the **exact data flow and behavioral logic**. Both are needed — generating from only the general skill will produce components that render but don't fetch or display data correctly.
+
+### 4b — Generate the component files
+
+Create the directory `<outputPath>/<ComponentName>/`.
+
+Create `<ComponentName>.tsx` using this structure from `widget-components.md` (loaded in Step 1):
+
+1. Imports (React hooks + DS components from Step 2 + `PConnProps` from `@pega/sdk-react`)
+2. Interface extending PConnProps with props from the component skill file's Props table
+3. Component function: destructure `getPConnect`, call `getPConnect()` to get `pConn`
+4. `useEffect` → data fetch using the exact PCore API call from the skill file's Behavioral Contract
+5. Return → DS Card/List/Table primitive from Step 2 API map, rendering the fetched data
+
+Fill in the `// [DS RENDER]` section with DS primitives confirmed in Step 2. The data-fetching logic comes from the skill file's Behavioral Contract — do NOT invent API calls.
+
+Create `index.tsx`:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+Create any CSS or utility files required by the skill file.
+
+### 4c — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top of the file in the **Widgets** section:
+   ```typescript
+   import <ComponentName> from './widget/<ComponentName>';
+   ```
+2. Add an entry in the return object of `getSampleComponentMap()` under the widgets comment:
+   ```typescript
+   <ComponentName>,
+   ```
+
+⚠️ **Key name exception:** `ToDo` MUST be registered as `Todo: ToDo` (not `ToDo,`). The Pega engine sends `Todo` (capital T, lowercase 'odo'). Using shorthand `ToDo,` creates key `ToDo` which won't match.
+
+Do not reorder or restructure any existing entries.
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
+
+---
+
+## Step 5 — Verify the build
+
+Run:
+
+```bash
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report a summary: list of all files created and all entries added to `component-map.ts`.

package/templates/react-sdk-reference/.ai-common/prompts/identify-components.md

@@ -0,0 +1,109 @@
+---
+ai-description: Analyze an attached screenshot and identify which SDK components are visible — outputs a components list ready to pass to replace-design-system
+---
+
+# identify-components
+
+Analyze the attached screenshot and identify which SDK components from this application are visible in the image.
+
+**Output only a single line** in this exact format — nothing else:
+
+```
+components="ComponentA,ComponentB,ComponentC"
+```
+
+This output can be pasted directly into a `/replace-design-system` invocation.
+
+---
+
+## Visual Recognition Guide
+
+Use the table below to map what you see in the 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 |
+| 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 |
+
+---
+
+## Rules
+
+1. **Only list components you can actually see rendered in the image.** Do not include components that might be present but are not visible (e.g. a NavBar not shown in the screenshot).
+2. **Do not include `FieldValueList`** — it is an internal rendering helper, not a visible component.
+3. **Structural components that frame a form always count** — if you see a step bar, include `Stages`; if you see action buttons, include `ActionButtons`.
+4. **An avatar + form title alone is NOT `CaseView`** — `CaseView` requires a full case shell with an action/kebab menu and tabbed content. A simple avatar + heading above a form is just part of `DefaultForm`.
+5. **When in doubt between two similar components** (e.g. `NarrowWide` vs `WideNarrow`), pick the one whose column ratio best matches the image proportions, or include both separated by a comma.
+6. **Output only the single `components="..."` line.** No explanation, no list, no markdown — just that line.

package/templates/react-sdk-reference/{.cursor/rules/prompts/replace-design-system.mdrules → .ai-common/prompts/replace-design-system.md}

@@ -1,6 +1,5 @@
 ---
-description: replace-design-system.prompt
-alwaysApply: false
+ai-description: Replace design system components — full app, by scope/folder, by named shorthand, or by explicit component list
 ---
 
 # replace-design-system
@@ -13,7 +12,7 @@ Replace the current design system in this application with **{{designSystem}}**.
 
 ## Step 0: Determine target component list
 
-Read `.cursor/rules/prompts/component-manifest.json` first.
+Read `{{PROMPT_DIR}}/component-manifest.json` first.
 
 Collect components from **every applicable source** below, then merge and deduplicate into a single final list.