@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/{.github/prompts/generate-field-components.prompt.md → .ai-common/prompts/generate-field-components.md}

@@ -1,6 +1,5 @@
 ---
-agent: agent
-description: Generate all (or a subset of) field components using any design system
+ai-description: Generate all (or a subset of) field components using any design system
 ---
 
 ## Step 0 — Resolve inputs
@@ -11,7 +10,7 @@ Read the user's message carefully. Extract:
 - **Output base path** — the folder where field components should be generated (e.g. `src/components/field/`, `app/ui/fields/`)
 - **Component list** — which components to generate (default: all 27 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, `.instructions.md` files, existing folders, or any other source.
+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.
 
@@ -60,7 +59,7 @@ Once both are known, continue to Step 1.
 
 ## Step 1 — Read `field-components.md` (once, for the entire session)
 
-Read the full contents of `.github/skills/field-components.md`.
+Read the full contents of `{{SKILL_DIR}}/field-components.md`.
 
 This gives you:
 
@@ -90,7 +89,29 @@ npm install <design-system-package>
 
 Also install any peer dependencies documented in the package's README. Report what was installed.
 
-### 2b — Discover the DS API from installed files
+### 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):
 
@@ -149,7 +170,7 @@ 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 `.github/skills/field-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 `field-components.md`.
+Read the file `{{SKILL_DIR}}/field-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 `field-components.md`.
 
 After reading, extract and keep active:
 
@@ -194,19 +215,14 @@ Edit `src/components/component-map.ts`:
    <ComponentName>,
    ```
 
-Do not reorder or restructure any existing entries.
-
-### 4d — Batch checkpoint
+⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping:
 
-After every **5 components**, run:
+- `Date: DateField` (not `DateField,`) — `Date` is a reserved JS global
+- `URL: URLComponent` (not `URLComponent,`) — `URL` is a reserved JS global
 
-```bash
-npm run build
-```
-
-Fix any TypeScript or build errors before continuing to the next component. This prevents error accumulation.
+Do not reorder or restructure any existing entries.
 
-### 4e — Report progress
+### 4d — Report progress
 
 After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
 

package/templates/react-sdk-reference/{.github/prompts/generate-template-components.prompt.md → .ai-common/prompts/generate-template-components.md}

@@ -1,6 +1,5 @@
 ---
-agent: agent
-description: Generate all (or a subset of) template components using any design system
+ai-description: Generate all (or a subset of) template components using any design system
 ---
 
 ## Step 0 — Resolve inputs
@@ -11,7 +10,7 @@ Read the user's message carefully. Extract:
 - **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, `.instructions.md` files, existing folders, or any other source.
+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.
 
@@ -62,19 +61,21 @@ Once both are known, continue to Step 1.
 | 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 `.github/skills/template-components.md`.
+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 `createElement(createPConnectComponent(), ...)` and `connectToState`; no DS involved
-- **Page template pattern** — region extraction via `getRawMetadata()` and PConnect bridge; no DS involved
+- **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.
@@ -99,7 +100,29 @@ npm install <design-system-package>
 
 Also install any peer dependencies documented in the package's README. Report what was installed.
 
-### 2b — Discover the DS layout API from installed files
+### 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.
 
@@ -154,7 +177,7 @@ 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 `.github/skills/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`.
+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:
 
@@ -173,8 +196,10 @@ 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**: `createElement(createPConnectComponent(), ...)` for each child from `getPConnect().getChildren()[0].getPConnect().getChildren()`. No DS primitives.
-- **Page**: `createElement(createPConnectComponent(), ...)` for each region from `getPConnect().getChildren()`. No DS primitives.
+- **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).
 
@@ -186,6 +211,45 @@ 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`:
@@ -198,21 +262,11 @@ Edit `src/components/component-map.ts`:
    ```typescript
    <ComponentName>,
    ```
-3. For sub-variants (e.g., TwoColumnPage, TwoColumnTab), register each key separately pointing to its own file or a shared implementation as specified in the skill file.
+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 — Batch checkpoint
-
-After every **5 components**, run:
-
-```bash
-npm run build
-```
-
-Fix any TypeScript or build errors before continuing to the next component. This prevents error accumulation.
-
-### 4e — Report progress
+### 4d — Report progress
 
 After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template`<, using <DS component name> for grid>` if layout"
 

package/templates/react-sdk-reference/{.github/prompts/generate-widget-components.prompt.md → .ai-common/prompts/generate-widget-components.md}

@@ -1,6 +1,5 @@
 ---
-agent: agent
-description: Generate all (or a subset of) widget components using any design system
+ai-description: Generate all (or a subset of) widget components using any design system
 ---
 
 ## Step 0 — Resolve inputs
@@ -11,7 +10,7 @@ Read the user's message carefully. Extract:
 - **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, `.instructions.md` files, existing folders, or any other source.
+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.
 
@@ -24,25 +23,26 @@ If the user specified a subset (e.g., "just ToDo and Attachment"), restrict the
 
 Once both are known, continue to Step 1.
 
-### Full component list (default — 9 widgets)
-
-| Component       | Description                 |
-| --------------- | --------------------------- |
-| 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         |
+### 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 `.github/skills/widget-components.md`.
+Read the full contents of `{{SKILL_DIR}}/widget-components.md`.
 
 This gives you:
 
@@ -75,7 +75,29 @@ npm install <design-system-package>
 
 Also install any peer dependencies documented in the package's README. Report what was installed.
 
-### 2b — Discover the DS API from installed files
+### 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):
 
@@ -132,7 +154,7 @@ 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 `.github/skills/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`.
+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:
 
@@ -179,19 +201,11 @@ Edit `src/components/component-map.ts`:
    <ComponentName>,
    ```
 
-Do not reorder or restructure any existing entries.
-
-### 4d — Batch checkpoint
-
-After every **5 components**, run:
-
-```bash
-npm run build
-```
+⚠️ **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.
 
-Fix any TypeScript or build errors before continuing to the next component. This prevents error accumulation.
+Do not reorder or restructure any existing entries.
 
-### 4e — Report progress
+### 4d — Report progress
 
 After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
 

package/templates/react-sdk-reference/{.claude → .ai-common}/prompts/identify-components.md

@@ -1,3 +1,7 @@
+---
+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.

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.
 

package/templates/react-sdk-reference/{.github → .ai-common}/skills/design-system-extension-skills/AlertBanner.md

@@ -25,6 +25,56 @@ Renders a visually-styled alert box tied to a Pega `variant` value (urgent, warn
 | `messages`  | `Array<string \| { label?: string; description?: string }>` | Yes      | One or more messages (string or structured object)            |
 | `onDismiss` | `function` (optional)                                       | No       | Dismiss/close handler; if provided, show a close button       |
 
+## Component Skeleton
+
+```typescript
+import './AlertBanner.css';
+
+interface AlertBannerProps {
+  id: string;
+  variant: string;
+  messages: Array<string | { label?: string; description?: string }>;
+  onDismiss?: () => void;
+}
+
+const VARIANT_MAP: Record<string, { severity: string; label: string }> = {
+  urgent: { severity: 'error', label: 'Error' },
+  warning: { severity: 'warning', label: 'Warning' },
+  success: { severity: 'success', label: 'Success' },
+  info: { severity: 'info', label: 'Info' },
+};
+
+function renderMessage(message: string | { label?: string; description?: string }) {
+  if (typeof message === 'object' && message !== null) {
+    const { label = '', description = '' } = message;
+    return label ? <><strong>{label}</strong> {description}</> : <>{description}</>;
+  }
+  const colonIndex = message.indexOf(':');
+  if (colonIndex === -1) return message;
+  return <><strong>{message.slice(0, colonIndex + 1)}</strong>{message.slice(colonIndex + 1)}</>;
+}
+
+export default function AlertBanner({ id, variant, messages, onDismiss }: AlertBannerProps) {
+  const { severity, label } = VARIANT_MAP[variant] ?? VARIANT_MAP.info;
+  const isMultiple = messages.length > 1;
+
+  return (
+    <div id={id}>
+      <AlertWidget variant="outlined" severity={severity} onClose={onDismiss}>
+        {isMultiple && (
+          <AlertTitle>
+            {label} <CountBadge variant={variant}>{messages.length}</CountBadge>
+          </AlertTitle>
+        )}
+        {isMultiple
+          ? <ul className="alert-banner-list">{messages.map((m, i) => <li key={i}>{renderMessage(m)}</li>)}</ul>
+          : renderMessage(messages[0])}
+      </AlertWidget>
+    </div>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **Variant mapping:** Map the Pega `variant` string to a UI severity level and display label:

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/design-system-extension-skills/Banner.md

@@ -34,6 +34,50 @@ Renders a visually rich banner composed of two parts:
 | `banner.tintImage`       | `any`       | No       | Unused internally                                                  |
 | `variant`                | `string`    | Yes      | Column layout: `'two-column'`, `'narrow-wide'`, or `'wide-narrow'` |
 
+## Component Skeleton
+
+```typescript
+import './Banner.css';
+
+interface BannerProps {
+  a: any; b: any;
+  banner?: { title?: string; message?: string; backgroundImage?: string; variant?: any; backgroundColor?: any; tintImage?: any };
+  variant: string;
+}
+
+export default function Banner(props: BannerProps) {
+  const { a, b, banner = {}, variant } = props;
+  const { title, message, backgroundImage } = banner;
+  const variantMap = {
+    'two-column': [6, 6],
+    'narrow-wide': [4, 8],
+    'wide-narrow': [8, 4],
+  };
+
+  return (
+    <div style={{ marginBottom: '2rem' }}>
+      {/* Hero section */}
+      <div className="background-image-style" style={{ backgroundImage: `url(${backgroundImage})` }}>
+        <div className="background-style content">
+          <h1 className="title">{title}</h1>
+          <p className="message">{message}</p>
+        </div>
+      </div>
+      {/* Content columns */}
+      <GridContainer spacing={1}>
+        <GridItem xs={variantMap[variant][0]}
+          style={{ padding: '1rem', backgroundColor: 'var(--app-form-bg-color)', borderRadius: '16px', height: 'fit-content' }}>
+          {a}
+        </GridItem>
+        <GridItem xs={variantMap[variant][1]} style={{ padding: '0 1rem' }}>
+          {b}
+        </GridItem>
+      </GridContainer>
+    </div>
+  );
+}
+```
+
 ## Behavioral Contract
 
 1. **Hero section:** Render a `<div>` with class `background-image-style` and the inline style `backgroundImage: url(${backgroundImage})`.

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/design-system-extension-skills/CaseSummaryFields.md

@@ -24,6 +24,60 @@ Renders a responsive 2-column read-only grid of field values for a case summary
 | `status`     | `string`                                       | No       | The case status value, injected at position 1 if `showStatus` is true     |
 | `showStatus` | `boolean`                                      | No       | If `true`, splices a status field entry at position 1 in the fields array |
 
+## Component Skeleton
+
+```typescript
+import { useState, useEffect } from 'react';
+import isDeepEqual from 'fast-deep-equal/react';
+import { getDateFormatInfo } from '../../helpers/date-format-utils';
+import { getCurrencyOptions } from '../../field/Currency/currency-utils';
+import { getComponentFromRegistry } from '@pega/sdk-react';
+import { format } from '../../helpers/formatters';
+import './CaseSummaryFields.css';
+
+interface CaseSummaryFieldsProps {
+  status?: string;
+  showStatus?: boolean;
+  theFields: any[];
+}
+
+export default function CaseSummaryFields(props: CaseSummaryFieldsProps) {
+  const Operator = getComponentFromRegistry('Operator');
+  const { status, showStatus, theFields } = props;
+  const [theFieldsToRender, setFieldsToRender] = useState([]);
+  const [theFieldsAsGridItems, setFieldsAsGridItems] = useState<any[]>([]);
+
+  // 1. getFieldValue(field) — type-based rendering switch
+  //    See Behavioral Contract #4 for the full type switch
+
+  // 2. useEffect: recompute grid items when theFieldsToRender changes
+  useEffect(() => {
+    const items = theFieldsToRender?.map(field => {
+      if (field.config.visibility === undefined || field.config.visibility === true)
+        return <GridItem xs={6} key={field.config.label}>{getFieldValue(field)}</GridItem>;
+      return null;
+    });
+    setFieldsAsGridItems(items);
+  }, [theFieldsToRender]);
+
+  // 3. Status injection (mutates theFields)
+  const theFieldsModifiable = theFields;
+  if (showStatus && theFields?.[1]?.type !== 'status') {
+    const oStatus = { type: 'status', config: { value: status, label: 'Status' } };
+    if (theFieldsModifiable.length < 2) theFieldsModifiable.push(oStatus);
+    else theFieldsModifiable.splice(1, 0, oStatus);
+  }
+
+  // 4. Deep equality check before state update (prevents infinite re-render)
+  if (!isDeepEqual(theFieldsToRender, theFieldsModifiable)) {
+    setFieldsToRender(theFieldsModifiable);
+  }
+
+  // 5. Render: 2-column grid
+  return <GridContainer className="psdk-case-summary-fields">{theFieldsAsGridItems}</GridContainer>;
+}
+```
+
 ### FieldConfig shape (within each item in `theFields`)
 
 | Property          | Type                 | Description                               |

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/design-system-extension-skills/DetailsFields.md

@@ -28,6 +28,55 @@ Supports three item layouts:
 | -------- | ------- | -------- | ----------------------------------------------------------------------------- |
 | `fields` | `any[]` | Yes      | Array of PConnect-aware field objects. Each must have `.getPConnect()` method |
 
+## Component Skeleton
+
+```typescript
+import { createElement, isValidElement } from 'react';
+import { PConnectComponent } from '@pega/sdk-react';
+import { format } from '../../helpers/formatters';
+
+interface DetailsFieldsProps { fields: any[]; }
+
+export default function DetailsFields(props: DetailsFieldsProps) {
+  const { fields = [] } = props;
+  const fieldComponents: any[] = [];
+
+  // 1. Build field components array
+  fields?.forEach((field, index) => {
+    const thePConn = field.getPConnect();
+    const theCompType = thePConn.getComponentName().toLowerCase();
+    const { label } = thePConn.getConfigProps();
+    const configObj = thePConn.getReferencedView();
+    configObj.config.readOnly = true;
+    configObj.config.displayMode = 'DISPLAY_ONLY';
+    if (theCompType === 'reference') configObj.config.label = thePConn.getInheritedProps()?.label;
+    fieldComponents.push({
+      type: theCompType, label,
+      value: createElement(PConnectComponent, thePConn.getReferencedViewPConnect()),
+    });
+  });
+
+  // 2. Render grid items per field
+  return (
+    <>
+      {fieldComponents.map((field, index) => {
+        if (field.type === 'reference') return field.value;
+        if (isValidElement(field.value)) {
+          return <GridRow key={index}><GridItem xs={12}>{field.value}</GridItem></GridRow>;
+        }
+        const formattedValue = field.type === 'date' ? format(field.value, 'date') : field.value;
+        return (
+          <GridRow key={index} style={{ padding: '4px 0' }}>
+            <GridItem xs={6}><Label>{field.label}</Label></GridItem>
+            <GridItem xs={6}><Value>{formattedValue || '---'}</Value></GridItem>
+          </GridRow>
+        );
+      })}
+    </>
+  );
+}
+```
+
 ## Behavioral Contract
 
 ### 1. Field Iteration and PConnect Setup