@pega/sdk 0.0.5 → 0.0.7

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

@@ -0,0 +1,155 @@
+---
+ai-description: 'Design Profile template — defines the structure and schema for the customer codebase analysis output consumed by generate-embedded-components'
+---
+
+# Design Profile Schema
+
+This document defines the required structure for a Design Profile produced by the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo.md` skill. The profile is consumed by the `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}` prompt to generate Pega components matching the customer's application.
+
+---
+
+## Required Sections
+
+Every Design Profile **must** contain the following sections. If a section cannot be populated (e.g., the project has no explicit theme tokens), note "Not detected — infer from component source" rather than omitting the section.
+
+---
+
+### 1. Project Fundamentals
+
+| Field         | Description                                                                                                    | Example values                                               |
+| ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Framework     | Application framework and version                                                                              | Any frontend framework + version                             |
+| Language      | Primary programming language and configuration                                                                 | Any typed or untyped language                                |
+| UI Library    | Component library name and version, or "Custom"                                                                | Any component library or "Custom"                            |
+| Styling       | Styling approach identifier                                                                                    | Utility classes, CSS modules, CSS-in-JS, scoped styles, etc. |
+| Form Handling | Form library or pattern used by the customer's own forms — **context only**, generated components never use it | Any form library or "Native"                                 |
+| Module System | Module format used                                                                                             | ESM, CommonJS, etc.                                          |
+
+---
+
+### 2. Design Tokens
+
+Organize by category. Use semantic names where the customer defines them; otherwise use descriptive labels.
+
+**Colors:**
+
+- Primary, secondary, accent
+- Error/danger, warning, success, info
+- Background (surface, page, card)
+- Text (primary, secondary, disabled, inverse)
+- Border (default, focus, error)
+
+**Spacing:**
+
+- The scale used (e.g., 4px base, or named sizes)
+
+**Typography:**
+
+- Font families (heading, body, mono)
+- Size scale
+- Weight scale
+- Line heights
+
+**Borders & Radii:**
+
+- Border widths
+- Radius values (small, medium, large, full)
+
+**Shadows:**
+
+- Elevation levels (if defined)
+
+**Breakpoints:**
+
+- Responsive boundaries (if defined)
+
+---
+
+### 3. Component Patterns
+
+Document how the customer's existing components work. **This section is context, not instructions.** Only the Validation Display and Styling conventions below are replicated in generated Pega components, because they affect appearance. The Input Interface, State Management, and Event Handling conventions are recorded so the reader understands the codebase — generated components follow the Pega contract for all three regardless of what is written here.
+
+**Input Interface Convention:**
+
+- How components define what they accept (typed interfaces, attribute schemas, parameter decorators, etc.)
+- Whether inputs are flat or nested/grouped
+- Common optional vs required patterns
+
+**State Management Convention:**
+
+- How components manage transient/local state
+- Controlled vs uncontrolled patterns
+- How derived/computed values are handled
+
+**Event Handling Convention:**
+
+- How components report value changes to parents
+- Whether changes are immediate, debounced, or committed on blur
+- Event naming conventions
+
+**Validation Display Convention:**
+
+Record the visual treatment only. Generated components read validation messages from PConnect, never from the customer's form state — so capture what an error _looks_ like, not where the customer's error value comes from.
+
+- Where error messages appear (below field, in tooltip, as banner)
+- How error styling is applied (border color, background, icon)
+- Whether validation is inline or form-level
+
+**Styling Convention:**
+
+- How styles are applied to elements
+- How conditional/dynamic styles are _expressed_ (e.g., error, disabled, focus states) — record the visual mechanism only; Pega supplies the state itself
+- How responsive behavior is implemented
+
+---
+
+### 4. File Conventions
+
+**Context only.** Generated components use Pega-owned paths and names (`pega-components/{type}/{ComponentName}/`), so Structure and Naming below do not apply to them. Re-exports, test location, and style location still inform co-located files.
+
+| Field          | Description                                             |
+| -------------- | ------------------------------------------------------- |
+| Structure      | Folder-per-component, flat, grouped by feature, etc.    |
+| Naming         | File and folder naming convention (casing, separators)  |
+| Re-exports     | Barrel/index file pattern (if any)                      |
+| Test location  | Co-located with component or in separate test directory |
+| Style location | Co-located, in shared styles directory, or inline       |
+
+---
+
+### 5. Import Conventions
+
+| Field                    | Description                                                      |
+| ------------------------ | ---------------------------------------------------------------- |
+| Path resolution          | Aliases used, or relative paths                                  |
+| Grouping order           | How imports are organized (external → internal → relative, etc.) |
+| Default/named preference | Which import style dominates                                     |
+| Style imports            | How stylesheets or style modules are imported                    |
+
+Generated components import the customer's UI primitives through their path aliases. Relative paths are used only _within_ `pega-components/` — for shared helpers, barrel files, and the registry file's component imports. One Pega component is never imported into another to render it; that always goes through the component registry.
+
+---
+
+### 6. Representative Component Examples
+
+List 3–5 components that were analyzed, with their file paths. These serve as reference points that the generation workflow can re-read for detailed implementation guidance.
+
+| Component | Path   | Why selected                 |
+| --------- | ------ | ---------------------------- |
+| [Name]    | [path] | Text input with validation   |
+| [Name]    | [path] | Select/dropdown with options |
+| [Name]    | [path] | Layout/container component   |
+| ...       | ...    | ...                          |
+
+---
+
+## Usage
+
+The generation prompt reads this profile once at the start of component generation. It uses:
+
+- **Project Fundamentals** → to determine which SDK adapter to reference and what language to generate
+- **Design Tokens** → to apply correct colors, spacing, typography without hardcoding values
+- **Component Patterns** → to replicate the customer's validation display and styling conventions; the rest of the section is context only
+- **File Conventions** → to inform co-located files (barrels, tests, styles); generated components' paths and names come from Pega, not from here
+- **Import Conventions** → to write imports that match the project's style
+- **Representative Examples** → as reference sources to re-read for detailed pattern matching

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

@@ -65,175 +65,57 @@ Keep all loaded skill files active throughout the entire session.
 
 ## Step 2 — Install and discover the design system (once)
 
-### 2a — Check and install the DS package
+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.
 
-Run this command in your terminal:
+**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.
 
-```bash
-cat package.json | grep "<design-system-package>"
-```
+You MUST also thoroughly inspect the installed design system package:
 
-If the design system package is **not** listed in `dependencies` or `devDependencies`, install it:
+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 requested component to the best available DS component** — component names from the skill files may not have an exact name match in the installed design system. Using the complete component list you just discovered, identify which DS component best serves the same purpose. For example, `@carbon/react` does not export an `AutoComplete` component — but it does export `ComboBox`, which provides equivalent autocomplete/typeahead functionality. 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 component 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.
 
-```bash
-npm install <design-system-package>
-```
+Also check:
 
-Also install any peer dependencies documented in the package's README. Report what was installed.
+- 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
 
-### 2a.1 — Install the DS styles package and configure global CSS (MANDATORY)
+### 2.1 — Install the DS styles package and configure global CSS (MANDATORY)
 
-Design systems require their global stylesheet to be loaded — without it, components render as unstyled browser-native HTML. This step is **not optional**.
+Design systems require their global stylesheet — without it, components render unstyled.
 
-#### Known DS style requirements (examples — verify from README for exact paths):
+#### Known DS style requirements (examples — verify against the README you already read):
 
-| 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` |
+| 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>`          |
 
-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.
+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 the DS is in the table above:
+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.
 
-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`
+Since you have already read the design system's README, install the styles package it specifies (if any). If you have already installed it, skip this step. If the README did not provide enough detail about design-system-specific styles, browse the `styles/` folder within the installed design system package to locate the correct stylesheet and understand how it should be applied. Ensure these design system styles are applied globally so that all generated components render correctly.
 
-#### If the DS is NOT in the table:
+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".
 
-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 "*.css" -path "*/dist/*" | head -5
-   ```
-3. Install and import whatever is found
-4. Check if a Provider/ThemeProvider is documented in the README
+Report what was installed/configured (or "already configured").
 
-#### 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.
-
-#### Step 2b.4 — Check supporting features
-
-- **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`).
-
-#### Step 2b.5 — Build the DS API reference map
-
-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.
+Keep all DS discovery information active throughout the entire session. Reference it whenever generating a component — do NOT re-run discovery per component.
 
 ---
 
 ## Step 3 — Overwrite check (all types, all at once)
 
-For every type in scope, check whether each component's `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+For every type in scope, check whether each component's file or directory already exists at the derived output path.
 
 Collect all existing components across all types and report them in one consolidated list:
 
@@ -273,28 +155,20 @@ If no skill file exists at that path, use the general behavioral skeleton from `
 
 Create the directory `<base>/field/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using this structure from `field-components.md` (loaded in Step 1):
+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).
 
-1. Imports: React hooks + `handleEvent` from `../../helpers/event-utils` + `getComponentFromRegistry` from `@pega/sdk-react` + `PConnFieldProps` + DS input from Step 2
-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`
-5. Return → DS form input from Step 2, with `onBlur` calling `handleEvent(actions, 'changeNblur', propName, inputValue)`
+Follow the implementation structure described in `field-components.md` (loaded in Step 1). That file specifies the exact imports, interface, props destructuring, display mode guards, event handling, and render approach for this project's framework. Use the DS component you identified in Step 2 as the primary input element.
 
-Pass `data-test-id={testId}` on the underlying interactive element.
+If the component-specific skill file exists, also incorporate its Behavioral Contract (validation rules, option loading, event sequences, edge cases).
 
-Create `index.tsx`:
-
-```typescript
-export { default } from './<ComponentName>';
-```
+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.
 
 ### 4.3 — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file (the file that maps component names to their implementations) and:
 
 1. Add an import at the top in the **Fields** section
-2. Add an entry in `getSampleComponentMap()` under the fields comment
+2. Add an entry in the component map object under the fields comment
 
 ⚠️ **Key name exceptions for fields** — these MUST use explicit key mapping (Pega sends a name that differs from the JS variable):
 
@@ -332,21 +206,13 @@ If no skill file exists at that path, use the general pattern from `template-com
 
 Create the directory `<base>/template/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using the structure matching the template category from `template-components.md` (loaded in Step 1):
-
-- **Layout**: `PropsWithChildren` + `templateCol` parsing (split on whitespace, strip units, compute ratios) + DS grid/flex from Step 2 rendering children in computed column ratios. On mobile: columns must stack to full width.
-- **Form**: `createElement(createPConnectComponent(), ...)` for each child from `getPConnect().getChildren()[0].getPConnect().getChildren()`. No DS primitives.
-- **Page**: `createElement(createPConnectComponent(), ...)` for each region from `getPConnect().getChildren()`. No DS primitives.
-
-Apply the Behavioral Contract from the component skill file.
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework.
 
-Create `index.tsx` if required by the skill file:
+Follow the implementation structure described in `template-components.md` (loaded in Step 1). That file specifies the layout, form, and page patterns — including how to render child components — for this project's framework.
 
-```typescript
-export { default } from './<ComponentName>';
-```
+Apply the Behavioral Contract from the component skill file (sub-variants, region handling, slot rendering logic).
 
-Create any CSS file required by the skill file.
+If the project uses barrel/re-export files, create one in the same directory. Also create any CSS file required by the skill file.
 
 ### 5.2.1 — Create sub-variant files (MANDATORY for Layout templates)
 
@@ -354,33 +220,21 @@ Create any CSS file required by the skill file.
 
 After generating **TwoColumn**, **OneColumn**, **NarrowWide**, or **WideNarrow**, you MUST immediately create these additional files in the same directory:
 
-| Base template | Sub-variant files to create                                         |
-| ------------- | ------------------------------------------------------------------- |
-| TwoColumn     | `TwoColumnPage.tsx`, `TwoColumnTab.tsx`                             |
-| OneColumn     | `OneColumnPage.tsx`, `OneColumnTab.tsx`                             |
-| NarrowWide    | `NarrowWideForm.tsx`, `NarrowWidePage.tsx`                          |
-| WideNarrow    | `WideNarrowDetails.tsx`, `WideNarrowForm.tsx`, `WideNarrowPage.tsx` |
-
-Each sub-variant is a one-line passthrough that delegates to the base component via the registry:
-
-```typescript
-import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnProps } from '@pega/sdk-react';
-
-export default function TwoColumnPage(props: PConnProps & Record<string, any>) {
-  const TwoColumn = getComponentFromRegistry('TwoColumn');
-  return <TwoColumn {...props} />;
-}
-```
+| Base template | Sub-variant files to create                             |
+| ------------- | ------------------------------------------------------- |
+| TwoColumn     | `TwoColumnPage`, `TwoColumnTab`                         |
+| OneColumn     | `OneColumnPage`, `OneColumnTab`                         |
+| NarrowWide    | `NarrowWideForm`, `NarrowWidePage`                      |
+| WideNarrow    | `WideNarrowDetails`, `WideNarrowForm`, `WideNarrowPage` |
 
-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`).
+Each sub-variant is a one-line passthrough that delegates to the base component via the project's component registry. It retrieves the base component (e.g. `TwoColumn`) from the registry and renders it with all props forwarded. Follow the same file extension and module pattern used by the rest of the project.
 
 ### 5.3 — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file and:
 
 1. Add an import at the top in the **Templates** section
-2. Add an entry in `getSampleComponentMap()` under the templates comment
+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 5.2.1. Each sub-variant gets its own import and its own entry in the map.
 
 ### 5.4 — Report progress
@@ -403,7 +257,7 @@ After reading, extract and keep active:
 
 - **Behavioral Contract** — the exact PCore API calls, state variables, event handlers, and edge cases specific to this widget
 - **Design System Mapping** table — the recommended DS primitive for this component's presentation layer
-- **Props interface** — any required/optional props beyond the base `PConnProps`
+- **Props interface** — any required/optional props beyond the base props type
 
 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.
 
@@ -413,30 +267,20 @@ If no skill file exists at that path (e.g., `SummaryList`), use the general data
 
 Create the directory `<base>/widget/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using this structure from `widget-components.md` (loaded in Step 1):
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework.
 
-1. Imports (React hooks + DS components from Step 2 + `PConnProps` from `@pega/sdk-react`)
-2. Interface extending PConnProps with props from the component skill file's Props table
-3. Component function: destructure `getPConnect`, call `getPConnect()` to get `pConn`
-4. `useEffect` → data fetch using the exact PCore API call from the skill file's Behavioral Contract
-5. Return → DS Card/List/Table primitive from Step 2 API map, rendering the fetched data
+Follow the implementation structure described in `widget-components.md` (loaded in Step 1). That file specifies the imports, interface, data-fetching lifecycle, and render approach for this project's framework. Use the DS components you identified in Step 2 for presentation.
 
-Fill in the `// [DS RENDER]` section with DS primitives confirmed in Step 2. The data-fetching logic comes from the skill file's Behavioral Contract — do NOT invent API calls.
+The data-fetching logic comes from the skill file's Behavioral Contract — do NOT invent API calls. Fill in the presentation layer with DS primitives confirmed in Step 2.
 
-Create `index.tsx`:
-
-```typescript
-export { default } from './<ComponentName>';
-```
-
-Create any CSS or utility files required by the skill file.
+If the project uses barrel/re-export files, create one in the same directory. Also create any CSS or utility files required by the skill file.
 
 ### 6.3 — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file and:
 
 1. Add an import at the top in the **Widgets** section
-2. Add an entry in `getSampleComponentMap()` under the widgets comment
+2. Add an entry in the component map object under the widgets comment
 
 ⚠️ **Key name exception for widgets** — this MUST use explicit key mapping:
 
@@ -472,28 +316,20 @@ If no skill file exists at that path, use the general pattern from `design-syste
 
 Create the directory `<base>/designSystemExtension/<ComponentName>/`.
 
-Create `<ComponentName>.tsx` using the structure matching the pattern from `design-system-extension.md` (loaded in Step 1):
-
-- **Pattern B** (Pure display — AlertBanner, Banner, Operator, WssQuickCreate): variant mapping (urgent→error, warning→warning, info→info, success→success) + DS Alert/Card/Avatar primitive from Step 2. No `getPConnect`.
-- **Pattern A** (PConnect display — CaseSummaryFields, DetailsFields, FieldValueList): CSS classes + optional DS typography, no DS component primitives. May use `getPConnect`.
-- **Pattern C** (Complex display — FieldGroup, FieldGroupList, Pulse, RichTextEditor): `createElement(createPConnectComponent(), ...)` for PConnect children, semantic HTML. No DS primitives.
+Create the component's main implementation file using the file naming convention and extension appropriate to the project's framework.
 
-Apply the Behavioral Contract from the component skill file.
+Follow the implementation structure described in `design-system-extension.md` (loaded in Step 1). That file specifies the pattern variants (pure display, PConnect display, complex display) for this project's framework.
 
-Create `index.tsx` if required by the skill file:
+Apply the Behavioral Contract from the component skill file (prop handling, variant mapping, rendering logic, edge cases).
 
-```typescript
-export { default } from './<ComponentName>';
-```
-
-Create any CSS file required by the skill file.
+If the project uses barrel/re-export files, create one in the same directory. Also create any CSS file required by the skill file.
 
 ### 7.3 — Register the component
 
-Edit `src/components/component-map.ts`:
+Open the project's component map file and:
 
 1. Add an import at the top in the **Design System Extension** section
-2. Add an entry in `getSampleComponentMap()` under the DSE comment
+2. Add an entry in the component map object under the DSE comment
 
 ### 7.4 — Report progress
 
@@ -503,17 +339,11 @@ After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`"
 
 ## Step 8 — Verify the build
 
-Run:
-
-```bash
-npm run build
-```
-
-Fix any TypeScript or build errors before reporting completion.
+Run the project's build process to confirm everything compiles without errors. Fix any TypeScript or build errors before reporting completion.
 
-### 8.1 — Validate component-map key names
+### 8.1 — Validate component map key names
 
-After a clean build, verify these key name exceptions in `component-map.ts`:
+After a clean build, verify these key name exceptions in the component map:
 
 - [ ] `Date: DateField` (not `DateField,`)
 - [ ] `URL: URLComponent` (not `URLComponent,`)
@@ -524,5 +354,5 @@ These are cases where the Pega engine sends a component name that differs from t
 Report a final summary:
 
 - Total components generated, grouped by type
-- All entries added to `component-map.ts`
+- All entries added to the component map
 - Any components skipped (if "skip existing" was chosen in Step 3)