@pega/sdk 0.0.4 → 0.0.5

package/templates/react-sdk-reference/{.github/prompts/add-component.prompt.md → .ai-common/prompts/add-component.md}

@@ -1,6 +1,5 @@
 ---
-agent: agent
-description: Add a new component type to the registry
+ai-description: Add a new component type to the registry
 ---
 
 ## Step 0 — Resolve missing information
@@ -12,7 +11,7 @@ Read the user's message carefully. Extract:
 - **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, `.instructions.md` files, existing folders, or any other source.
+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.
 
@@ -25,7 +24,7 @@ Example questions to ask (only ask the ones that are actually missing):
 
 ### 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 `.github/skills/field-skills/`, `.github/skills/template-skills/`, `.github/skills/widget-skills/`, and `.github/skills/design-system-extension-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
+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.
 
@@ -47,21 +46,21 @@ Before generating, check if a component already exists at the resolved output pa
 
 Always read the **general type skill** for the component type:
 
-| Component Type          | General Skill File                          |
-| ----------------------- | ------------------------------------------- |
-| `field`                 | `.github/skills/field-components.md`        |
-| `template`              | `.github/skills/template-components.md`     |
-| `widget`                | `.github/skills/widget-components.md`       |
-| `designSystemExtension` | `.github/skills/design-system-extension.md` |
+| 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`                 | `.github/skills/field-skills/<ComponentName>.md`                   |
-| `template`              | `.github/skills/template-skills/<ComponentName>.md`                |
-| `widget`                | `.github/skills/widget-skills/<ComponentName>.md`                  |
-| `designSystemExtension` | `.github/skills/design-system-extension-skills/<ComponentName>.md` |
+| 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:
 
@@ -97,9 +96,29 @@ 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`).
 
-## Step 4 — Discover the design system's API
+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:
 
@@ -177,6 +196,14 @@ 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.
 
 ---

package/templates/react-sdk-reference/{.cursor/rules → .ai-common}/prompts/component-manifest.json

@@ -119,7 +119,9 @@
       { "name": "SubTabs", "path": "src/components/template/SubTabs" },
       { "name": "TwoColumn", "path": "src/components/template/TwoColumn" },
       { "name": "WideNarrow", "path": "src/components/template/WideNarrow" },
-      { "name": "WssNavBar", "path": "src/components/template/WssNavBar" }
+      { "name": "WssNavBar", "path": "src/components/template/WssNavBar" },
+      { "name": "SearchForm", "path": "src/components/template/DataReference/SearchForm" },
+      { "name": "SearchGroups", "path": "src/components/template/AdvancedSearch/SearchGroups" }
     ],
     "widget": [
       {
@@ -133,7 +135,11 @@
       { "name": "QuickCreate", "path": "src/components/widget/QuickCreate" },
       { "name": "SummaryItem", "path": "src/components/widget/SummaryItem" },
       { "name": "SummaryList", "path": "src/components/widget/SummaryList" },
-      { "name": "ToDo", "path": "src/components/widget/ToDo" }
+      { "name": "ToDo", "path": "src/components/widget/ToDo" },
+      {
+        "name": "ActionButtonsForFileUtil",
+        "path": "src/components/widget/FileUtility/ActionButtonsForFileUtil"
+      }
     ],
     "infra": [
       { "name": "ActionButtons", "path": "src/components/infra/ActionButtons" },

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

@@ -1,6 +1,5 @@
 ---
-agent: agent
-description: Generate components across multiple types (field, template, widget, designSystemExtension) using any design system
+ai-description: Generate components across multiple types (field, template, widget, designSystemExtension) using any design system
 ---
 
 ## Step 0 — Resolve inputs
@@ -11,7 +10,7 @@ Read the user's message carefully. Extract:
 - **Base components folder** — the root folder that contains (or will contain) the component type subfolders (e.g. `src/components/`)
 - **Component types in scope** — which types to generate (default: all four if not specified)
 
-Both **design system** and **base components folder** 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 **base components folder** 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 base components folder, ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
 
@@ -53,12 +52,12 @@ Once design system, base folder, and type scope are resolved, continue to Step 1
 
 Read the general skill file for every type in scope. Do this upfront — do not re-read per component.
 
-| Type                  | Skill file to read                          |
-| --------------------- | ------------------------------------------- |
-| field                 | `.github/skills/field-components.md`        |
-| template              | `.github/skills/template-components.md`     |
-| widget                | `.github/skills/widget-components.md`       |
-| designSystemExtension | `.github/skills/design-system-extension.md` |
+| Type                  | Skill file to read                         |
+| --------------------- | ------------------------------------------ |
+| 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` |
 
 Keep all loaded skill files active throughout the entire session.
 
@@ -82,44 +81,153 @@ 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)
 
-Run these commands to discover the actual API (do NOT rely on training knowledge):
+Design systems require their global stylesheet to be loaded — without it, components render as unstyled browser-native HTML. This step is **not optional**.
 
-1. Read the README for correct import paths and usage patterns:
+#### Known DS style requirements (examples — verify from README for exact paths):
 
-   ```bash
-   cat node_modules/<designSystem>/README.md
-   ```
+| Design System | Styles Package to Install        | CSS Import to Add in `src/main.tsx` (example) | Provider Wrapper (example)                    |
+| ------------- | -------------------------------- | --------------------------------------------- | --------------------------------------------- |
+| Carbon        | `@carbon/styles`                 | `import '@carbon/react/css/styles.css';`      | `<Theme>` from `@carbon/react`                |
+| Ant Design    | (included in `antd`)             | `import 'antd/dist/reset.css';`               | `<ConfigProvider>` from `antd`                |
+| Radix Themes  | `@radix-ui/themes`               | `import '@radix-ui/themes/styles.css';`       | `<Theme>` from `@radix-ui/themes`             |
+| Chakra UI     | (included in `@chakra-ui/react`) | (no CSS file needed)                          | `<ChakraProvider>` from `@chakra-ui/react`    |
+| Shadcn/ui     | (Tailwind CSS)                   | `import './globals.css';` (Tailwind output)   | None (uses Tailwind classes directly)         |
+| MUI           | (included in `@mui/material`)    | (no CSS file needed — CSS-in-JS)              | `<ThemeProvider>` from `@mui/material/styles` |
 
-2. List every exported component:
+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`) — paths may differ across versions.
 
-   ```bash
-   grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -3 | xargs grep "^export"
-   ```
+#### If the DS is in the table above:
+
+1. Install the styles package (if separate): `npm install <styles-package>`
+2. Add the CSS import as the **first import** in `src/main.tsx` (before any component imports)
+3. Add the Provider wrapper in `src/AppProviders.tsx`
 
-3. For every component you plan to use across all types in scope, read its TypeScript prop interface:
+#### If the DS is NOT in the table:
 
+1. Check `node_modules/<designSystem>/README.md` for CSS/styles setup instructions
+2. Search for a CSS entry point:
    ```bash
-   find node_modules/<designSystem> -name "ComponentName.d.ts" | head -3
-   grep -A 40 "interface.*Props" <path-from-above>
+   find node_modules/<designSystem> -name "*.css" -path "*/dist/*" | head -5
    ```
+3. Install and import whatever is found
+4. Check if a Provider/ThemeProvider is documented in the README
+
+#### Verification (non-visual):
+
+After adding the CSS import, confirm it exists in the entry file:
+
+```bash
+grep -n "import.*css\|import.*styles\|import.*reset" src/main.tsx
+```
+
+If this grep returns nothing, the CSS was NOT added correctly — fix it before proceeding.
+
+⛔ **Do NOT proceed to Step 2b until the CSS import is confirmed present in `src/main.tsx`.** Without it, every generated component will render unstyled.
+
+### 2b — Deep-dive into the installed DS package
+
+After installation, build a comprehensive understanding of the design system by reading its source declarations. Do NOT rely on training knowledge — read the actual installed files.
+
+#### Step 2b.1 — Read the README and understand the DS architecture
+
+```bash
+cat node_modules/<designSystem>/README.md
+```
+
+Extract:
+
+- Correct import paths (named exports from root vs subpath imports like `<ds>/Button`)
+- Whether it uses a **Provider/ThemeProvider** wrapper (if so, note the setup requirements)
+- Whether it has a **CSS reset or global styles** requirement
+
+#### Step 2b.2 — List every exported component
+
+```bash
+grep "^export" node_modules/<designSystem>/dist/index.d.ts 2>/dev/null || grep -rl "^export" node_modules/<designSystem> --include="index.d.ts" | head -5 | xargs grep "^export"
+```
+
+Save this full export list — it is the authoritative source of what components exist. Any component name not in this list does NOT exist and must NOT be used.
+
+#### Step 2b.3 — Read every exported component's prop interface
+
+For EACH exported component from Step 2b.2, read its TypeScript declarations to understand:
+
+- All available props (required and optional)
+- Supported variants, sizes, and states (e.g., `variant: 'outlined' | 'filled'`)
+- Event handler prop names (e.g., `onChange`, `onValueChange`, `onSelect`)
+- Slot/composition patterns (e.g., `renderInput`, `startAdornment`, `prefix`)
+- Whether it accepts `children` or uses named slots
+
+```bash
+# For each component, find and read its type declarations:
+find node_modules/<designSystem> -name "*.d.ts" -path "*ComponentName*" | head -3
+grep -A 60 "interface.*Props" <path-from-above>
+```
+
+Organize your findings into a **DS Component Catalog** grouped by UI category:
+
+**Form inputs:** Input, Select, Checkbox, Radio, DatePicker, TimePicker, Autocomplete/Combobox, NumberInput, Textarea, Switch, etc.
+
+- For each: note the exact prop names for `value`, `onChange`, `error/invalid`, `disabled`, `readOnly`, `placeholder`, `label`, `helperText/description`
+
+**Layout:** Grid, Flex, Stack, SimpleGrid, Columns, Box, Container, etc.
+
+- For each: note how column counts/ratios are specified (e.g., `columns={2}`, `templateColumns`, `span`)
+- Note responsive breakpoint props (e.g., `{{ base: 1, md: 2 }}`)
+
+**Data display:** Table, List, Card, Badge, Tag, Avatar, Typography/Text, etc.
+
+- For each: note sub-components (e.g., `Table.Head`, `Card.Header`)
+
+**Feedback:** Alert, Toast/Snackbar, Dialog/Modal, Popover, Progress, Spinner, etc.
+
+- For each: note severity/status prop names and how to show/dismiss
+
+**Navigation:** Tabs, Menu/Dropdown, Link, Button, IconButton, etc.
 
-   Focus on primitives needed across **all types in scope**:
-   - **field**: form input controls (Input, Select, Checkbox, DatePicker, etc.)
-   - **template**: grid/layout primitives (Grid, Flex, Columns, SimpleGrid, etc.)
-   - **widget**: card/list/table/button/badge primitives
-   - **designSystemExtension**: alert/notification/avatar primitives
+#### Step 2b.4 — Check supporting features
 
-4. Also check:
-   - Whether the DS 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 **CSS tokens** — use design system CSS custom properties for spacing; never hardcode `px` values
+- **Form layout wrapper** — does the DS provide a component that combines label + input + helper text + error message? (e.g., `Form.Item`, `FormControl`, `Field`). If yes, use it for ALL field components instead of composing label/input/helper manually.
+- **Companion icons package** — list the package name and read its exports. Never guess icon names:
+  ```bash
+  ls node_modules/<designSystem>-icons/dist/ 2>/dev/null | head -20
+  ```
+- **CSS tokens / design tokens** — does the DS expose CSS custom properties or a token system? Use them for spacing instead of hardcoded `px` values.
+- **Theme variants** — what `size` values are available? (e.g., `sm`, `md`, `lg`). What `variant` values? (e.g., `outlined`, `filled`, `ghost`).
 
-Only use component names and prop names confirmed in these files.
+#### Step 2b.5 — Build the DS API reference map
 
-Build a unified **DS API reference map** covering all types in scope. Reuse it throughout — do not repeat discovery commands per component.
+Compile all findings into a single reference map structured as:
+
+```
+DS API Reference Map
+====================
+Package: <name>@<version>
+Import pattern: import { Component } from '<path>'
+Provider required: yes/no (ThemeProvider, etc.)
+
+Form Inputs:
+  Input: { value, onChange, onBlur, placeholder, disabled, readOnly, invalid/error, size, variant }
+  Select: { value, onChange, options/children, placeholder, disabled, ... }
+  ...
+
+Layout:
+  Grid: { columns, gap, children }
+  ...
+
+Data Display:
+  Card: { children } → Card.Header, Card.Body, Card.Footer
+  Table: { children } → Table.Head, Table.Body, Table.Row, Table.Cell
+  ...
+
+Feedback:
+  Alert: { status/severity, title, description, closable/onClose }
+  ...
+```
+
+Keep this map active throughout the entire session. Reference it whenever generating a component — do NOT re-run discovery commands per component.
 
 ---
 
@@ -137,6 +245,8 @@ Collect all existing components across all types and report them in one consolid
 
 Wait for the user's answer before proceeding. If none exist, continue immediately.
 
+⚠️ **This decision is final for the entire session.** Do NOT re-check file existence or re-ask this overwrite question during Steps 4–7. When you encounter a component file that already exists during generation, silently apply the decision made here (overwrite it or skip it) without prompting again. This applies even after retries, transport errors, or subagent restarts — the user's answer here governs all subsequent component generation in this conversation.
+
 ---
 
 ## Step 4 — Generate field components (skip if field not in scope)
@@ -147,7 +257,7 @@ If `field` is in scope, generate each of the 27 field components in order:
 
 ### 4.1 — 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:
 
@@ -186,17 +296,13 @@ Edit `src/components/component-map.ts`:
 1. Add an import at the top in the **Fields** section
 2. Add an entry in `getSampleComponentMap()` under the fields comment
 
-### 4.4 — Batch checkpoint
+⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping (Pega sends a name that differs from the JS variable):
 
-After every **5 field components**, run:
+- `Date: DateField` (not `DateField,`)
+- `URL: URLComponent` (not `URLComponent,`)
+- `Checkbox: CheckboxComponent` (if your variable name differs from `Checkbox`)
 
-```bash
-npm run build
-```
-
-Fix any errors before continuing.
-
-### 4.5 — Report progress
+### 4.4 — Report progress
 
 After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
 
@@ -210,7 +316,7 @@ If `template` is in scope, generate each of the 32 template components in order:
 
 ### 5.1 — 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:
 
@@ -242,25 +348,42 @@ export { default } from './<ComponentName>';
 
 Create any CSS file required by the skill file.
 
-### 5.3 — Register the component
+### 5.2.1 — Create sub-variant files (MANDATORY for Layout templates)
 
-Edit `src/components/component-map.ts`:
+⛔ **Do NOT skip this step.** Without sub-variants, portal pages and tabs won't render column layouts.
 
-1. Add an import at the top in the **Templates** section
-2. Add an entry in `getSampleComponentMap()` under the templates comment
-3. For sub-variants (e.g., TwoColumnPage, TwoColumnTab), register each key separately
+After generating **TwoColumn**, **OneColumn**, **NarrowWide**, or **WideNarrow**, you MUST immediately create these additional files in the same directory:
 
-### 5.4 — Batch checkpoint
+| 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` |
 
-After every **5 template components**, run:
+Each sub-variant is a one-line passthrough that delegates to the base component via the registry:
 
-```bash
-npm run build
+```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} />;
+}
 ```
 
-Fix any errors before continuing.
+Replace `TwoColumnPage`/`TwoColumn` with the appropriate names for each sub-variant. These files go in the same directory as the base component (e.g., `template/TwoColumn/TwoColumnPage.tsx`).
 
-### 5.5 — Report progress
+### 5.3 — Register the component
+
+Edit `src/components/component-map.ts`:
+
+1. Add an import at the top in the **Templates** section
+2. Add an entry in `getSampleComponentMap()` under the templates comment
+3. **Also import and register ALL sub-variant files** created in Step 5.2.1. Each sub-variant gets its own import and its own entry in the map.
+
+### 5.4 — Report progress
 
 After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template"
 
@@ -274,7 +397,7 @@ If `widget` is in scope, generate each of the 9 widget components in order:
 
 ### 6.1 — 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:
 
@@ -315,17 +438,11 @@ Edit `src/components/component-map.ts`:
 1. Add an import at the top in the **Widgets** section
 2. Add an entry in `getSampleComponentMap()` under the widgets comment
 
-### 6.4 — Batch checkpoint
-
-After every **5 widget components**, run:
+⚠️ **Key name exception for widgets** — this MUST use explicit key mapping:
 
-```bash
-npm run build
-```
+- `Todo: ToDo` (not `ToDo,`) — Pega engine sends `Todo` (lowercase 'odo'), not `ToDo`
 
-Fix any errors before continuing.
-
-### 6.5 — Report progress
+### 6.4 — Report progress
 
 After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
 
@@ -339,7 +456,7 @@ If `designSystemExtension` is in scope, generate each of the 11 DSE components i
 
 ### 7.1 — Read the component-specific skill file (MANDATORY — do not skip)
 
-Read the file `.github/skills/design-system-extension-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 `design-system-extension.md`.
+Read the file `{{SKILL_DIR}}/design-system-extension-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 `design-system-extension.md`.
 
 After reading, extract and keep active:
 
@@ -378,17 +495,7 @@ Edit `src/components/component-map.ts`:
 1. Add an import at the top in the **Design System Extension** section
 2. Add an entry in `getSampleComponentMap()` under the DSE comment
 
-### 7.4 — Batch checkpoint
-
-After every **5 DSE components**, run:
-
-```bash
-npm run build
-```
-
-Fix any errors before continuing.
-
-### 7.5 — Report progress
+### 7.4 — Report progress
 
 After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`"
 
@@ -404,6 +511,16 @@ npm run build
 
 Fix any TypeScript or build errors before reporting completion.
 
+### 8.1 — Validate component-map key names
+
+After a clean build, verify these key name exceptions in `component-map.ts`:
+
+- [ ] `Date: DateField` (not `DateField,`)
+- [ ] `URL: URLComponent` (not `URLComponent,`)
+- [ ] `Todo: ToDo` (not `ToDo,`)
+
+These are cases where the Pega engine sends a component name that differs from the JavaScript variable name. If any are registered using shorthand (e.g., `ToDo,`), fix them to use explicit key mapping (e.g., `Todo: ToDo,`).
+
 Report a final summary:
 
 - Total components generated, grouped by type

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

@@ -1,6 +1,5 @@
 ---
-agent: agent
-description: Generate all (or a subset of) design system extension components using any design system
+ai-description: Generate all (or a subset of) design system extension 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 DSE components should be generated (e.g. `src/components/designSystemExtension/`)
 - **Component list** — which components to generate (default: all 11 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.
 
@@ -44,7 +43,7 @@ Once both are known, continue to Step 1.
 
 ## Step 1 — Read `design-system-extension.md` (once, for the entire session)
 
-Read the full contents of `.github/skills/design-system-extension.md`.
+Read the full contents of `{{SKILL_DIR}}/design-system-extension.md`.
 
 This gives you:
 
@@ -76,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 display primitives 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.
 
 > Pattern A/C components (FieldValueList, FieldGroup, Pulse, etc.) use PConnect bridge or plain CSS — they do not use the DS API. Only Pattern B components consume DS primitives.
 
@@ -131,7 +152,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/design-system-extension-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 `design-system-extension.md`.
+Read the file `{{SKILL_DIR}}/design-system-extension-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 `design-system-extension.md`.
 
 After reading, extract and keep active:
 
@@ -178,17 +199,7 @@ Edit `src/components/component-map.ts`:
 
 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>` ✓ — Pattern `<B/A/C>`<`, using <DS primitive>` if Pattern B>"