@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/.ai-common/agents/implementation-expert.md

@@ -0,0 +1,132 @@
+---
+ai-name: Implementation Expert
+ai-description: "Use when the user wants to generate, create, add, replace, migrate, or identify UI components (field, template, widget, design system extension, or infra) in this Pega SDK reference app — a single component, a batch, or the entire app — with any design system (Ant Design, Chakra UI, Radix, Shadcn, Carbon, MUI, etc.). Handles trigger phrases like 'generate a component', 'add a component', 'replace all field components with...', 'migrate the design system to...', 'replace everything with...', 'what components are in this screenshot'. Executes the repo's existing {{PROMPT_DIR}} workflows end-to-end — generation, batch generation, full-app generation, screenshot-based identification, and full/targeted design-system migration — including component-map.ts registration, provider setup, and build verification."
+---
+
+You are the **Implementation Expert** for this Pega Infinity SDK React reference application. You are not limited
+to generating new components — you implement the **entire component lifecycle flow** defined in `{{PROMPT_DIR}}/`:
+creating components, batch-generating them, generating the whole app, identifying components from screenshots, and
+migrating the design system of components that already exist. You execute these workflows end-to-end exactly as
+written, rather than improvising your own approach.
+
+This repo is a reference implementation customers clone and re-skin: the UI components under
+`src/components/{field,template,widget,designSystemExtension}/` are meant to be replaced with any design system,
+while the SDK wiring (`src/components/component-map.ts` registry mechanics, `src/components/infra/`,
+`src/components/helpers/event-utils.ts`, `@pega/sdk-react`, and `MashupApp.tsx`/`PortalApp.tsx`'s auth/bootstrap
+logic) is reusable infrastructure you must never break.
+
+## Startup behavior
+
+The **first time you respond in a conversation**, before doing any routing or file work:
+
+- **If the user's message already states a clear, actionable task** (e.g. "generate a TextInput field with Chakra
+  UI", "replace all widgets with Ant Design"), skip the menu below and go straight to Step 0 / Routing logic.
+- **If the user's message is vague, empty, a greeting, or just says something like "help" / "what can you do"**,
+  respond with:
+  1. A one-paragraph summary of what you do (implement the full component lifecycle: generate, batch-generate,
+     generate everything, identify components from a screenshot, migrate design systems).
+  2. A short bulleted menu of the flows you support, each with a one-line example trigger phrase, e.g.:
+     - **Add/replace a single component** — "add a Dropdown field using Chakra UI"
+     - **Batch-generate one type** — "generate all widget components with Ant Design"
+     - **Generate everything** — "generate all components using Radix"
+     - **Identify components from a screenshot** — attach an image and ask "what components are in this screenshot"
+     - **Migrate the design system** — "replace all field components with Carbon" or "migrate the whole app to Chakra UI"
+  3. Then immediately call the `vscode_askQuestions` tool (not inline text questions) to let the user pick from
+     concrete options rather than typing free text. At minimum ask:
+     - **Flow**: options = Add/replace a single component | Batch-generate one type | Generate everything |
+       Identify components from a screenshot | Migrate the design system.
+     - **Component type** (skip only if "Identify from screenshot" chosen): options = Field | Template | Widget |
+       Design System Extension | **All** (`All` = Field + Template + Widget + Design System Extension together).
+       Enable multi-select so the user can combine individual types into a custom subset (e.g. Field + Widget),
+       but treat **All** as its own exclusive/standalone choice — if the flow is "Generate everything", default
+       the selection to **All** and don't present it as something to combine with the individual type options.
+     - **Design system**: options = Ant Design | Chakra UI | Radix | Shadcn | Carbon | MUI | Other (freeform allowed).
+       Every question should list selectable options (`allowFreeformInput: true` so the user can still type something
+       not listed) instead of asking open-ended questions in plain chat text.
+
+Do not start reading prompt files or editing anything until the user's intent and the required inputs (from
+Step 0 below) are confirmed.
+
+## Routing logic
+
+Determine which prompt file governs the request, then **read that prompt file's full contents with the read tool
+before writing any code**. Never paraphrase or execute steps from memory — always re-read the prompt (and every
+skill file it tells you to read) at the start of the task, and follow every numbered step in order without
+skipping or shortcutting any of them.
+
+| Request shape                                                                                                                                       | Prompt file to read and follow                                                                                                                                                                              |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI")                                                           | `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}`                                                                                                                                                                |
+| Multiple/all field components, one design system                                                                                                    | `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}`                                                                                                                                                    |
+| Multiple/all template components, one design system                                                                                                 | `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}`                                                                                                                                                 |
+| Multiple/all widget components, one design system                                                                                                   | `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}`                                                                                                                                                   |
+| Multiple/all design system extension components, one design system                                                                                  | `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}`                                                                                                                                                      |
+| Multiple component types at once, or "generate all components"                                                                                      | `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` (wave-based orchestration — launch subagents via `runSubagent`, respecting the ≤10-subagents-per-wave limit defined in that prompt)                  |
+| A screenshot/image is attached and the user wants to know what components are in it (no migration requested)                                        | `{{PROMPT_DIR}}/identify-components{{PROMPT_EXT}}` — output only the single `components="..."` line it specifies                                                                                            |
+| Migrating/replacing the design system of components that **already exist** — full app, or scoped by folder/named-shorthand/explicit list/screenshot | `{{PROMPT_DIR}}/replace-design-system{{PROMPT_EXT}}` (reads `{{PROMPT_DIR}}/component-manifest.json` for scope resolution; targeted migration for ≤10 resolved components, full 9-wave migration otherwise) |
+
+If a request mixes generation and migration ambiguously, use `vscode_askQuestions` to ask which they mean (options:
+"Generate/replace" vs "Migrate existing") before picking a prompt — generation prompts assume the component
+doesn't exist yet (or is being fully rewritten), migration assumes it exists and only its design-system primitives
+change.
+
+### Migration-specific notes (`replace-design-system{{PROMPT_EXT}}`)
+
+- That prompt tells you to launch per-component subagents using prompts named `replace-field` (fields) and
+  `replace-component` (everything else). **These files do not exist in `{{PROMPT_DIR}}/`.** When launching those
+  subagents yourself via `runSubagent`, give each one the equivalent instructions inline instead: the relevant
+  general skill (`{{SKILL_DIR}}/field-components.md`, `template-components.md`, `widget-components.md`, or
+  `design-system-extension.md`), the component-specific skill file
+  (`{{SKILL_DIR}}/{type}-skills/<Name>.md`), the target design system, and the same "preserve visual intent /
+  keep default export name / update in place" constraints that `add-component{{PROMPT_EXT}}` uses for a single
+  component.
+- Root provider setup (Step T1.3 / 1.3) and `FieldValueList` replacement (Step T1.4 / 1.4) are blocking
+  prerequisites — complete them before launching any migration subagent wave.
+
+## Step 0 — resolve missing inputs
+
+Every generation prompt requires: component name(s), component type, target design system, and output path.
+`replace-design-system{{PROMPT_EXT}}` requires a target design system plus at least one way to resolve scope
+(screenshot, `components=` list, or `scope=` folder/shorthand) — if none are given, it defaults to a full 9-wave
+migration, so confirm that's really what the user wants before proceeding. If any required input is missing or
+ambiguous, use the `vscode_askQuestions` tool to ask — present concrete, selectable options (e.g. the known
+design systems, the four component types, folder/named-shorthand scopes from `component-manifest.json`) rather
+than a plain open-ended question, while still allowing freeform input for anything not listed. Do not guess a
+design system or silently default to MUI.
+
+## Guardrails
+
+- **One folder per component — never a shared/monolithic file.** Every component (field, template, widget, or
+  designSystemExtension) must be created at `<outputPath>/<ComponentName>/<ComponentName>.tsx` plus a sibling
+  `<outputPath>/<ComponentName>/index.tsx` that does `export { default } from './<ComponentName>';` — exactly as
+  Step 5/6 of `add-component{{PROMPT_EXT}}` specifies. Never write multiple components into one `.tsx` file, never
+  create a catch-all file like `generated/<designSystem>Components.tsx`, and never export a single bundled object
+  (e.g. `generatedComponents`) that `component-map.ts` spreads in one line. This applies identically whether you
+  generate one component, a batch of one type, or "all components" via `generate-all-components{{PROMPT_EXT}}` — the
+  wave/subagent orchestration in that flow does not change the per-component file-and-folder contract.
+- `component-map.ts` must get one **named import + one map entry per component**, added under the matching
+  category comment (Fields / Templates / Widgets / Design System Extension), never a single spread of a bundled
+  object.
+- Never modify the auth/bootstrap logic in `src/MashupApp.tsx`/`src/PortalApp.tsx`, `src/components/infra/`
+  (beyond what a migration prompt explicitly directs), `src/components/helpers/event-utils.ts`, or anything under
+  `@pega/sdk-react`. The one exception: `replace-design-system{{PROMPT_EXT}}` explicitly requires wrapping the
+  existing provider tree in `MashupApp.tsx`/`PortalApp.tsx` with a new design-system provider — that specific,
+  additive change is allowed only during a migration flow.
+- Never remove the `...sdkComponents` spread in `src/components/component-map.ts` — only add or replace entries.
+- Field components must handle `displayMode` (`DISPLAY_ONLY` / `STACKED_LARGE_VAL`) via `FieldValueList`, obtained
+  through `getComponentFromRegistry`, never a hardcoded import.
+- `FieldValueList`'s prop interface (`name`, `value`, `variant: 'stacked' | 'inline'`) must never change — every
+  field component depends on it.
+- Preserve the original visual intent (spacing, padding, sizing) when mapping old styles to the new design
+  system's primitives — don't silently drop them.
+- Keep the same default export name for every generated/replaced component so `component-map.ts` references and
+  imports stay valid.
+
+## Verification
+
+After generation or migration, run the build (`npm run build`, or the steps in `{{SKILL_DIR}}/run-and-verify{{SKILL_EXT}}`
+if the prompt references it) and report the result. Before declaring success, confirm the folder-per-component
+contract held: every generated/replaced component has its own `<ComponentName>/<ComponentName>.tsx` +
+`<ComponentName>/index.tsx`, and no monolithic/shared/"generated" bundle file was created. Summarize: which
+components were generated/replaced/migrated, which files were touched, the `component-map.ts` diff, provider
+changes (if any), and the build outcome (pass/fail, with errors if any).

package/templates/react-sdk-reference/{.github/copilot-instructions.md → .ai-common/global/ai-agent-instructions.md}

@@ -1,4 +1,4 @@
-# Copilot Instructions — React SDK Reference
+# Pega SDK — React Reference App
 
 You are assisting developers in a React reference application that demonstrates the Pega Infinity SDK. Customers clone this repo and **replace the sample UI components with their own design system** (MUI, Chakra, Radix, Shadcn, Ant Design, or any other).
 
@@ -189,7 +189,7 @@ import handleEvent from '../../helpers/event-utils';
 ## 9. Component Generation Workflow — Single Component
 
 When the user asks to generate, create, add, or replace **a single UI component** (e.g., "generate an AutoComplete component", "add a Dropdown using Chakra UI"),
-read the full contents of `.github/prompts/add-component.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 
@@ -200,7 +200,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 10. Batch Field Component Generation
 
 When the user asks to generate, create, or replace **multiple field components** or **all field components** with a design system (e.g., "generate field components with Ant Design", "replace all fields with Chakra UI", "generate all field components using Radix"),
-read the full contents of `.github/prompts/generate-field-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 
@@ -209,7 +209,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 11. Batch Template Component Generation
 
 When the user asks to generate, create, or replace **multiple template components** or **all template components** with a design system (e.g., "generate template components with Ant Design", "replace all templates with Chakra UI", "generate layout templates using Radix"),
-read the full contents of `.github/prompts/generate-template-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 
@@ -218,7 +218,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 12. Batch Widget Component Generation
 
 When the user asks to generate, create, or replace **multiple widget components** or **all widget components** with a design system (e.g., "generate widget components with Ant Design", "replace all widgets with Chakra UI", "generate widgets using Carbon"),
-read the full contents of `.github/prompts/generate-widget-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 
@@ -227,7 +227,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 13. Batch Design System Extension Component Generation
 
 When the user asks to generate, create, or replace **multiple design system extension components** or **all DSE components** with a design system (e.g., "generate DSE components with Ant Design", "replace design system extension components with Chakra UI", "generate designSystemExtension components using Carbon"),
-read the full contents of `.github/prompts/generate-dse-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 
@@ -236,7 +236,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 14. Generate All Components (Multi-Type)
 
 When the user asks to generate, create, or replace components across **multiple types** or **all component types** at once (e.g., "generate all components with Ant Design", "replace everything with Chakra UI", "generate field and widget components using Carbon", "regenerate all components"),
-read the full contents of `.github/prompts/generate-all-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 

package/templates/react-sdk-reference/{.github/instructions/component-map.instructions.md → .ai-common/instructions/component-map.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: "**/component-map.ts"
+ai-globs: **/component-map.ts
 ---
 
 # Component Map Rules
@@ -13,7 +13,7 @@ import { sdkComponents } from '@pega/sdk-react';
 
 function getSampleComponentMap() {
   return {
-    ...sdkComponents,   // NEVER remove this — provides infrastructure
+    ...sdkComponents, // NEVER remove this — provides infrastructure
     // Your components below:
     TextInput,
     Dropdown,
@@ -38,3 +38,10 @@ function getSampleComponentMap() {
    - `Todo: ToDo` (casing difference)
 
 6. **Keep the `registerSampleComponents` function** — it registers all entries into the `ComponentRegistry` instance used by the PConnect bridge.
+
+7. **Sub-component registration** — Some template/widget components internally render sub-components via `getComponentFromRegistry()`. These sub-components MUST also be registered in the component map or they will be `undefined` at runtime. Known sub-components:
+   - `SearchForm` — used by `DataReference` and `AdvancedSearch`
+   - `SearchGroups` — used by `AdvancedSearch`
+   - `ActionButtonsForFileUtil` — used by `FileUtility`
+
+8. **`Todo` vs `ToDo` key** — The Pega engine sends `Todo` (capital T, lowercase odo). The component variable may be named `ToDo`, but the map key MUST be `Todo: ToDo`.

package/templates/react-sdk-reference/{.github/instructions/dse-component.instructions.md → .ai-common/instructions/dse-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/designSystemExtension/**/*.tsx"
+ai-globs: src/components/designSystemExtension/**/*.tsx
 ---
 
 # Design System Extension Component Rules

package/templates/react-sdk-reference/{.cursor/rules/field-component.mdrules → .ai-common/instructions/field-component.md}

@@ -1,6 +1,5 @@
 ---
-globs: ["src/components/field/**/*.tsx"]
-alwaysApply: false
+ai-globs: src/components/field/**/*.tsx
 ---
 
 # Field Component Rules
@@ -10,11 +9,13 @@ When creating or modifying field components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnFieldProps } from '@pega/sdk-react';
    ```
 
 2. **Define a props interface extending `PConnFieldProps`**:
+
    ```typescript
    interface MyFieldProps extends PConnFieldProps {
      // additional props specific to this field
@@ -31,6 +32,7 @@ When creating or modifying field components, follow these rules:
 1. **Extract standard props**: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
 
 2. **Get PConnect APIs**:
+
    ```typescript
    const pConn = getPConnect();
    const actions = pConn.getActionsApi();
@@ -38,6 +40,7 @@ When creating or modifying field components, follow these rules:
    ```
 
 3. **Handle displayMode** (MUST be before the main return):
+
    ```typescript
    if (displayMode === 'DISPLAY_ONLY') {
      return <FieldValueList name={hideLabel ? '' : label} value={value} />;
@@ -72,3 +75,4 @@ The replacement must look the same as the original component:
 - Hardcode component imports for components that exist in the registry
 - Remove the `handleEvent` import from `../../helpers/event-utils`
 - Drop visual styles when removing `makeStyles` — always map them to an equivalent
+- **Import the same symbol twice from `field-utils`** — if you import `DynamicFieldProps` (or any other export) in one import statement, do NOT add a separate `import type { DynamicFieldProps }` line. This causes `"DynamicFieldProps is already defined"` errors. Use a single import: `import { commitField, DynamicFieldProps, FieldValue, getFieldContext } from '../field-utils';`

package/templates/react-sdk-reference/{.github/instructions/template-component.instructions.md → .ai-common/instructions/template-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/template/**/*.tsx"
+ai-globs: src/components/template/**/*.tsx
 ---
 
 # Template Component Rules
@@ -9,6 +9,7 @@ When creating or modifying template/layout components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnProps } from '@pega/sdk-react';
    ```
@@ -28,7 +29,7 @@ Receive React `children` directly:
 import type { PropsWithChildren, ReactElement } from 'react';
 
 interface TwoColumnProps extends PConnProps {
-  templateCol?: string;  // e.g. "1fr 1fr", "2fr 1fr"
+  templateCol?: string; // e.g. "1fr 1fr", "2fr 1fr"
 }
 
 export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {

package/templates/react-sdk-reference/{.github/instructions/widget-component.instructions.md → .ai-common/instructions/widget-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: "src/components/widget/**/*.tsx"
+ai-globs: src/components/widget/**/*.tsx
 ---
 
 # Widget Component Rules
@@ -9,6 +9,7 @@ When creating or modifying widget components, follow these rules:
 ## Required Structure
 
 1. **Import types from `@pega/sdk-react`**:
+
    ```typescript
    import type { PConnProps } from '@pega/sdk-react';
    // or PConnFieldProps if the widget behaves like a field (e.g., Attachment)

package/templates/react-sdk-reference/.ai-common/prompts/add-component.md

@@ -0,0 +1,219 @@
+---
+ai-description: Add a new component type to the registry
+---
+
+## Step 0 — Resolve missing information
+
+Read the user's message carefully. Extract:
+
+- **Component name** — the exact name (e.g. `AutoComplete`, `DatePicker`)
+- **Component type** — one of: `field` | `template` | `widget` | `designSystemExtension`
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output path** — the exact or relative path where the component should be generated (e.g. `src/components/field/AutoComplete`)
+
+All four values above are required. If any are 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 provide ALL of: component name, component type, design system, and 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 to ask (only ask the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is the exact component name?
+3. What type of component is this? (field / template / widget / designSystemExtension)
+4. What is the exact or relative path where the component should be generated? (e.g. `src/components/field/AutoComplete`)
+
+### Case-insensitive component name matching
+
+The user may enter the component name in any casing (e.g. `autocomplete`, `Autocomplete`, `autoComplete`). It is your responsibility to match it to the correct canonical name by checking the skill files in `{{SKILL_DIR}}/field-skills/`, `{{SKILL_DIR}}/template-skills/`, `{{SKILL_DIR}}/widget-skills/`, and `{{SKILL_DIR}}/design-system-extension-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
+
+Once all four are known, continue to Step 1.
+
+---
+
+## Step 1 — Check for existing component (overwrite check)
+
+Before generating, check if a component already exists at the resolved output path:
+
+1. Check if `<outputPath>/<ComponentName>.tsx` (or the directory) already exists.
+2. If it **does exist**, ask the user: _"A component named `<ComponentName>` already exists at `<outputPath>`. Do you want to overwrite it with the new implementation?"_
+   - If the user says **yes**, proceed to overwrite.
+   - If the user says **no**, stop and skip generation.
+3. If it **does not exist**, continue to Step 2.
+
+---
+
+## Step 2 — Check for skill files
+
+Always read the **general type skill** for the component type:
+
+| Component Type          | General Skill File                         |
+| ----------------------- | ------------------------------------------ |
+| `field`                 | `{{SKILL_DIR}}/field-components.md`        |
+| `template`              | `{{SKILL_DIR}}/template-components.md`     |
+| `widget`                | `{{SKILL_DIR}}/widget-components.md`       |
+| `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension.md` |
+
+Then look for a **component-specific skill** based on the component type:
+
+| Component Type          | Specific Skill Location                                           |
+| ----------------------- | ----------------------------------------------------------------- |
+| `field`                 | `{{SKILL_DIR}}/field-skills/<ComponentName>.md`                   |
+| `template`              | `{{SKILL_DIR}}/template-skills/<ComponentName>.md`                |
+| `widget`                | `{{SKILL_DIR}}/widget-skills/<ComponentName>.md`                  |
+| `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` |
+
+If the component-specific skill file exists, read it fully. Pay special attention to:
+
+- **Behavioral Contract** — state management, event handling, option loading, edge cases
+- **Design System Mapping** table — the recommended component for the chosen design system
+
+You must read **both** the general type skill and the component-specific skill (if it exists) before proceeding.
+
+Examples:
+
+- `AutoComplete` (field) → read `field-components.md` + `field-skills/AutoComplete.md`
+- `AdvancedSearch` (template) → read `template-components.md` + `template-skills/AdvancedSearch.md`
+- `AppAnnouncement` (widget) → read `widget-components.md` + `widget-skills/AppAnnouncement.md`
+- `AlertBanner` (designSystemExtension) → read `design-system-extension.md` + `design-system-extension-skills/AlertBanner.md`
+
+If no component-specific skill file exists, continue using the general pattern from the type skill.
+
+---
+
+## Step 3 — Check and install dependencies
+
+Run:
+
+```
+cat package.json | grep "<design-system-package>"
+```
+
+If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+
+```
+npm install <design-system-package>
+```
+
+Also install any peer dependencies documented in the package's README. Report what was installed.
+
+### 3.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 and not already configured: 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` — if already present, report "already configured" and continue.
+
+Report what was installed/configured (or "already configured").
+
+Before writing any code, inspect the installed package:
+
+1. `cat node_modules/<designSystem>/README.md` — note the correct import path and usage patterns for the installed version.
+2. `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"` — lists every component actually exported by the installed version.
+3. For every component you plan to use, read its TypeScript prop interface from the installed `.d.ts`:
+   `find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3`, then `grep -A 40 "interface.*Props"` on the result.
+4. Only use component names and prop names confirmed in those files. Do not rely on training knowledge of the API.
+
+Also check:
+
+- Whether the design system has a **form layout wrapper** (label + input + helper text) — use it instead of manual margins
+- Whether it has **size/density/variant conventions** — use built-in props rather than custom padding
+- Whether it has a **companion icons package** — read its exports before using any icon name; never guess icon names
+- Whether it has a **tokens or CSS directory** — use design system CSS custom properties for spacing; never hardcode `px` values
+
+---
+
+## Step 5 — Generate the component
+
+Create the component directory at the resolved output path (from Step 0).
+
+Create `<ComponentName>.tsx` using the pattern for the component type:
+
+### field
+
+Use this structure from `field-components.md` (read in Step 2):
+
+1. Imports: React hooks + `handleEvent` from `../../helpers/event-utils` + `getComponentFromRegistry` from `@pega/sdk-react` + `PConnFieldProps` + DS input from Step 4
+2. Interface extending `PConnFieldProps` with any extra props from the component skill file
+3. Destructure: `getPConnect`, `label`, `required`, `disabled`, `value`, `validatemessage`, `status`, `readOnly`, `testId`, `helperText`, `displayMode`, `hideLabel`, `placeholder`
+4. Display mode guards: if `DISPLAY_ONLY` or `STACKED_LARGE_VAL` → return `FieldValueList` (via `getComponentFromRegistry('FieldValueList')`)
+5. Return → DS form input from Step 4, with `onBlur` calling `handleEvent(actions, 'changeNblur', propName, inputValue)`. Show `validatemessage` when `status === 'error'`. Pass `data-test-id={testId}` on the interactive element.
+
+### template
+
+Use this structure from `template-components.md` (read in Step 2):
+
+- **Layout**: `PropsWithChildren` + `templateCol` parsing + DS grid from Step 4 rendering children in column ratios. Mobile: 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.
+
+### widget
+
+Use this structure from `widget-components.md` (read in Step 2):
+
+1. Imports: React hooks + DS components from Step 4 + `PConnProps` from `@pega/sdk-react`
+2. Interface extending `PConnProps` with props from the component skill file
+3. Component function: destructure `getPConnect`, call `getPConnect()` to get `pConn`
+4. `useEffect` → data fetch using exact PCore API from skill file's Behavioral Contract
+5. Return → DS Card/List/Table from Step 4, rendering fetched data
+
+### designSystemExtension
+
+Use this structure from `design-system-extension.md` (read in Step 2):
+
+- **Pattern B** (Pure display): variant mapping (urgent→error, etc.) + DS Alert/Card/Avatar from Step 4. No `getPConnect`.
+- **Pattern A** (PConnect display): CSS classes + optional DS typography. No DS primitives.
+- **Pattern C** (Complex display): `createElement(createPConnectComponent(), ...)` for PConnect children. No DS primitives.
+
+---
+
+Create `index.tsx`:
+
+```typescript
+export { default } from './<ComponentName>';
+```
+
+---
+
+## Step 6 — Register in component-map.ts
+
+Edit `src/components/component-map.ts`:
+
+1. Add the import at the top of the file, in the correct section (Fields / Templates / Widgets / Design System Extension)
+2. Add an entry in `getSampleComponentMap()` under the matching category comment
+
+⚠️ **Key name exceptions** — verify after registration:
+
+- `Date: DateField` (not `DateField,`) — `Date` is a reserved JS global
+- `URL: URLComponent` (not `URLComponent,`) — `URL` is a reserved JS global
+- `Todo: ToDo` (not `ToDo,`) — Pega sends `Todo`, not `ToDo`
+
+If the component being added matches any of the above, use the explicit `key: value` mapping instead of shorthand.
+
+Do not restructure or reorder any existing entries.
+
+---
+
+## Step 7 — Verify the build
+
+Run:
+
+```
+npm run build
+```
+
+If build errors occur, fix them before reporting completion. Report what files were created and what was added to `component-map.ts`.