@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,227 @@
+---
+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; column-ratio 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 using a higher-order state-subscription pattern; a companion utilities module; no DS involved
+- **Page template pattern** — region extraction and PConnect bridge; complex API interactions with the underlying engine; 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)
+
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed.
+
+**Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
+
+> You only need layout-related DS components. Form and page templates do not use the DS.
+
+You MUST also thoroughly inspect the installed design system package, focusing on layout primitives (Grid, Columns, Flex, SimpleGrid, Row, Col):
+
+1. **Discover all available layout primitives** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every layout primitive the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map the layout templates to the best available DS layout primitive** — identify which DS component best serves grid/column layout needs. If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every layout primitive you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Pay special attention to **responsive breakpoint APIs** and **column sizing conventions** (e.g., 12-column grid, fractional units, span props). Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
+
+Build a **DS layout API reference** from this discovery. Reuse it for every layout template — do not repeat this discovery per component.
+
+### 2.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 against the README you already read):
+
+| Design System | Styles Package (example) | CSS Import (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>`          |
+
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted from the README — they take precedence over this table.
+
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder in `node_modules` for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
+
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
+
+Report what was installed/configured (or "already configured").
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether the component's file or directory already exists at the output path.
+
+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 the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
+
+Follow the implementation structure described in `template-components.md` (loaded in Step 1) for the component's template category, as identified in Step 4a:
+
+- **Layout**: column-ratio parsing (split on whitespace, strip units, compute ratios) + the DS grid/flex primitive from Step 2, rendering children in computed column ratios. On mobile: columns must stack to full width.
+- **Form**: use the higher-order state-subscription pattern described in the skill file so that each child field is properly wired into the project's state management. Also create the companion utilities module described in the skill file.
+- **Page**: the generated component MUST include ALL props, side effects, API calls, lifecycle hooks, and state management from the skill file's Component Skeleton. Page templates are complex — they interact with the underlying engine's 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 state variable, lifecycle hook, registry lookup, engine API 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).
+
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern.
+
+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:** the higher-order state-subscription pattern is imported and used; the companion utilities module contains the helpers described in the skill file; each child field is wired through those helpers.
+2. **Page templates:** all props listed in the skill file's Props table are destructured; all registry lookups from the skeleton are present; all lifecycle hooks from the skeleton are present; all engine API calls 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-variants to create                                  |
+| ------------- | ------------------------------------------------------- |
+| TwoColumn     | `TwoColumnPage`, `TwoColumnTab`                         |
+| OneColumn     | `OneColumnPage`, `OneColumnTab`                         |
+| NarrowWide    | `NarrowWideForm`, `NarrowWidePage`                      |
+| WideNarrow    | `WideNarrowDetails`, `WideNarrowForm`, `WideNarrowPage` |
+
+Each sub-variant is a passthrough component (using the file naming convention established for this project) that delegates to the base component via the project's component registry — follow the passthrough pattern described in `template-components.md` (loaded in Step 1), substituting the appropriate base component and sub-variant name each time.
+
+### 4c — Register the component
+
+Open the project's component map file (the file that maps component names to their implementations) and:
+
+1. Add an import at the top of the file in the **Templates** section
+2. Add an entry in the component map object under the templates comment
+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 the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.

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

@@ -0,0 +1,172 @@
+---
+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
+- The Design System Adaptation guide (primitive mapping table, icon discovery rules)
+- All common engine APIs used in widgets for data pages, mashup interactions, attachments, case info, etc.
+- Registration conventions
+
+> The data-fetching logic is always identical regardless of design system. Only the presentation layer 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)
+
+Check the project's dependency manifest to determine whether the design system package is already installed. If it is **not** listed in the project's dependencies, install it using the project's package manager. Report what was installed.
+
+**Immediately after installation**, read `node_modules/<designSystem>/README.md` in full. From it, note the correct import paths, usage patterns, version-specific guidance, global CSS/styles import path, provider wrapper component name, and any peer dependency requirements. Store this information in your memory and use it for all subsequent steps — do not re-read the README later. If the README lists peer dependencies that are not already installed in the project, install them now — the design system will not function correctly without them.
+
+You MUST also thoroughly inspect the installed design system package, focusing on presentation primitives (Card, List, Table, Button, Badge, Spinner):
+
+1. **Discover all available components** — browse the installed package's directory tree under `node_modules/<designSystem>/` to find every component it exports. Do not assume a specific folder structure (e.g. `dist/`) — packages vary widely in how they organize source, types, and entry points. Navigate through the package's folders, read its entry-point files and type definitions, and build a complete list of every component the package actually provides. Store all discovered component names and their import paths in your memory for reference during code generation.
+2. **Map each widget to the best available DS primitive** — using the complete list you just discovered, identify which DS component best serves each widget's presentation needs. If no single DS component is a close match, compose the requested behavior from multiple available DS primitives. Never fabricate a component import that does not exist in the installed package.
+3. **Read the props interface of every primitive you plan to use** — for each component you intend to use, locate and read its TypeScript type definitions (`.d.ts` files or inline types) to understand the exact prop names, types, required vs. optional status, and any relevant enums or union types. Store this information in your memory alongside the component names.
+4. **Use ONLY confirmed component names and prop names** — when generating code, you must exclusively use the component names and prop names you discovered from the installed package. Do not rely on training knowledge of the design system's API, as it may be outdated, inaccurate, or refer to components/props that do not exist in the installed version.
+
+Also check:
+
+- Whether the design system has a **companion icon package** — read its exports before using any icon name; never guess icon names
+- Whether it has **size/variant conventions** — use built-in props rather than custom padding
+- Whether it has **CSS tokens** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+Build a **DS UI primitive reference map** from this discovery. Reuse it for every widget — do not repeat this discovery per component.
+
+### 2.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 against the README you already read):
+
+| Design System | Styles Package (example) | CSS Import (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>`          |
+
+Above mentioned are **examples** based on common versions. Use the import path and provider name you noted from the README — they take precedence over this table.
+
+If in table and not already configured: install styles package (if separate), add the global CSS import as the **first import** in the application's entry file, and add the Provider wrapper in the application's providers file.
+If not in table: browse the installed design system's folder in `node_modules` for a `styles/` or `dist/` directory containing CSS files, and use what you find there.
+
+Before implementing any component, verify whether design-system-specific styles are already configured in the existing codebase — check the application's entry file for a matching CSS import. If the styles are already imported and configured, skip this step and report "already configured".
+
+Report what was installed/configured (or "already configured").
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether the component's file or directory already exists at the output path.
+
+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 component props
+
+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 the component's main implementation file using the file naming convention and extension appropriate to the project's framework (determine this by examining existing components in the project).
+
+Follow the implementation structure described in `widget-components.md` (loaded in Step 1). That file specifies the exact imports, interface, data-fetching lifecycle, and render approach for this project's framework. Use the DS primitives you identified in Step 2 for presentation. The data-fetching logic comes from the skill file's Behavioral Contract — do NOT invent API calls.
+
+If the project uses barrel/re-export files (check existing component directories for the convention), create one in the same directory following the same pattern.
+
+Create any CSS or utility files required by the skill file.
+
+### 4c — Register the component
+
+Open the project's component map file (the file that maps component names to their implementations) and:
+
+1. Add an import at the top of the file in the **Widgets** section
+2. Add an entry in the component map object under the widgets comment
+
+⚠️ **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 the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.

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

@@ -2,7 +2,7 @@
 
 Alert/notification banner that displays one or more messages with a severity variant and an optional dismiss button.
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -13,18 +13,62 @@ Renders a visually-styled alert box tied to a Pega `variant` value (urgent, warn
 ## Pega Metadata
 
 - **Pega Name:** `AlertBanner`
-- **Registration key:** `AlertBanner` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
+- **Registration key:** `AlertBanner` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
 
-## Props
+## Component Inputs
 
-| Prop        | Type                                                        | Required | Description                                                   |
+The component accepts the following inputs. Define the input contract using the project's framework conventions for your target stack.
+
+| Name        | Type                                                        | Required | Description                                                   |
 | ----------- | ----------------------------------------------------------- | -------- | ------------------------------------------------------------- |
 | `id`        | `string`                                                    | Yes      | DOM id for the root wrapper element                           |
 | `variant`   | `string`                                                    | Yes      | Alert variant: `'urgent'`, `'warning'`, `'success'`, `'info'` |
 | `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       |
 
+## Implementation Structure
+
+### Module Setup
+
+The component requires companion styles (for badge and list styling) that should be co-located with the component following the project's styling convention. It does NOT import any Pega SDK modules — all data arrives via direct inputs.
+
+The component is named `AlertBanner` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Variant Map (module-level constant)
+
+Define a module-level lookup object that maps Pega variant strings to a UI severity value and a human-readable display label:
+
+| Pega Variant | Severity Value | Display Label |
+| ------------ | -------------- | ------------- |
+| `urgent`     | `error`        | `Error`       |
+| `warning`    | `warning`      | `Warning`     |
+| `success`    | `success`      | `Success`     |
+| `info`       | `info`         | `Info`        |
+
+The map is typed as `Record<string, { severity: string; label: string }>`.
+
+### Helper: `renderMessage`
+
+Define a private helper function `renderMessage` that accepts a single message (either a string or an object with optional `label` and `description` fields) and returns formatted markup. The function follows this decision tree:
+
+1. **Object with truthy `label`** — render the label in a bold/strong element followed by a space and the `description` text.
+2. **Object without `label`** (label is falsy/empty) — render only the `description` text.
+3. **String containing a colon (`:`)** — find the index of the **first** colon only. Render everything from the start up to and including the colon in a bold/strong element, then render the remainder as plain text.
+4. **String with no colon** — render the entire string as plain text with no formatting.
+
+### Component Logic
+
+The component receives `id`, `variant`, `messages`, and `onDismiss` as inputs, then:
+
+1. **Resolve variant** — look up `variant` in the variant map. If the variant is not found (unknown/missing), fall back to the `info` entry.
+2. **Determine plurality** — check whether `messages.length > 1` to decide between single-message and multi-message rendering.
+3. **Render tree:**
+   - Outer wrapper: a plain `<div>` with the `id` input as its DOM id.
+   - Inside the wrapper: a design-system alert component displayed in **outlined** style, with the resolved `severity` passed as the severity/type attribute. If `onDismiss` is provided, wire it as the alert's close handler; otherwise omit the close button entirely.
+   - **Multiple messages path:** display an alert title row containing the display label text and a circular count badge (showing `messages.length`). Below the title, display messages as an unordered list (`<ul>` with class `alert-banner-list`), with each message processed via `renderMessage` inside a `<li>`.
+   - **Single message path:** display `renderMessage(messages[0])` directly as the alert's content (no title, no list).
+
 ## Behavioral Contract
 
 1. **Variant mapping:** Map the Pega `variant` string to a UI severity level and display label:
@@ -47,7 +91,7 @@ Renders a visually-styled alert box tied to a Pega `variant` value (urgent, warn
 
 ## Visual Specifications
 
-Derived from `AlertBanner.css` and MUI Alert usage:
+Derived from the component's companion styles and the reference implementation's alert usage:
 
 ### Alert Container
 
@@ -116,22 +160,14 @@ Derived from `AlertBanner.css` and MUI Alert usage:
 
 **UI control type:** Alert / Notification banner with severity levels.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                                   |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| Default (CSS only) | `<div role="alert">` with severity border + inline close button                         |
-| MUI                | `<Alert variant='outlined' severity={severity} onClose={onDismiss}><AlertTitle>`        |
-| Ant Design         | `<Alert type={type} message={title} description={…} closable banner />`                 |
-| Chakra UI          | `<Alert status={status}><AlertIcon /><AlertTitle /><AlertDescription /><CloseButton />` |
-| Shadcn/ui          | Custom `<Alert>` with `variant` prop                                                    |
-
-When implementing in a specific design system, map the following:
-
-- `variant='urgent'` → `severity/type/status='error'` or `'danger'`
-- `variant='warning'` → `severity/type/status='warning'`
-- `variant='success'` → `severity/type/status='success'`
-- `variant='info'` → `severity/type/status='info'`
-- `onDismiss` → `onClose` / `closable` / close button prop
-- Multiple messages → render as a list inside the alert description area
-- Badge count → render as a tag/badge chip next to the title
+When implementing in a specific design system, use the DS's alert/notification component and map the following:
+
+- `variant='urgent'` → the DS's error/danger severity level
+- `variant='warning'` → the DS's warning severity level
+- `variant='success'` → the DS's success severity level
+- `variant='info'` → the DS's info/informational severity level
+- `onDismiss` → the DS alert's close/dismiss handler (e.g., `onClose`, `closable`, or a close button slot)
+- The alert should render in an **outlined** style (visible border, no filled background) if the DS supports that variant; otherwise use the closest equivalent that shows a colored border indicating severity
+- Multiple messages → render as a list inside the alert's description/content area
+- Badge count → render as a small circular tag/badge element next to the title text
+- If the DS has no built-in alert component, use a `<div role="alert">` with a severity-colored left border or outline, and render a custom close button if `onDismiss` is provided