@pega/sdk 0.0.2 → 0.0.4

package/templates/react-sdk-reference/.claude/prompts/component-manifest.json

@@ -0,0 +1,193 @@
+{
+  "folderScopes": {
+    "field": "src/components/field",
+    "template": "src/components/template",
+    "widget": "src/components/widget",
+    "infra": "src/components/infra",
+    "designSystemExtension": "src/components/designSystemExtension"
+  },
+  "namedScopes": {
+    "workflow-form": {
+      "folders": ["field"],
+      "components": [
+        {
+          "name": "Stages",
+          "category": "infra",
+          "path": "src/components/infra/Stages"
+        }
+      ]
+    }
+  },
+  "components": {
+    "field": [
+      { "name": "AutoComplete", "path": "src/components/field/AutoComplete" },
+      { "name": "CancelAlert", "path": "src/components/field/CancelAlert" },
+      { "name": "Checkbox", "path": "src/components/field/Checkbox" },
+      { "name": "Currency", "path": "src/components/field/Currency" },
+      { "name": "Date", "path": "src/components/field/Date" },
+      { "name": "DateTime", "path": "src/components/field/DateTime" },
+      { "name": "Decimal", "path": "src/components/field/Decimal" },
+      { "name": "Dropdown", "path": "src/components/field/Dropdown" },
+      { "name": "Email", "path": "src/components/field/Email" },
+      { "name": "Group", "path": "src/components/field/Group" },
+      { "name": "Integer", "path": "src/components/field/Integer" },
+      { "name": "Location", "path": "src/components/field/Location" },
+      { "name": "Multiselect", "path": "src/components/field/Multiselect" },
+      {
+        "name": "ObjectReference",
+        "path": "src/components/field/ObjectReference"
+      },
+      { "name": "Percentage", "path": "src/components/field/Percentage" },
+      { "name": "Phone", "path": "src/components/field/Phone" },
+      { "name": "RadioButtons", "path": "src/components/field/RadioButtons" },
+      { "name": "RichText", "path": "src/components/field/RichText" },
+      { "name": "ScalarList", "path": "src/components/field/ScalarList" },
+      {
+        "name": "SelectableCard",
+        "path": "src/components/field/SelectableCard"
+      },
+      { "name": "SemanticLink", "path": "src/components/field/SemanticLink" },
+      { "name": "TextArea", "path": "src/components/field/TextArea" },
+      { "name": "TextContent", "path": "src/components/field/TextContent" },
+      { "name": "TextInput", "path": "src/components/field/TextInput" },
+      { "name": "Time", "path": "src/components/field/Time" },
+      { "name": "URL", "path": "src/components/field/URL" },
+      { "name": "UserReference", "path": "src/components/field/UserReference" }
+    ],
+    "template": [
+      {
+        "name": "AdvancedSearch",
+        "path": "src/components/template/AdvancedSearch"
+      },
+      { "name": "AppShell", "path": "src/components/template/AppShell" },
+      { "name": "BannerPage", "path": "src/components/template/BannerPage" },
+      { "name": "CaseSummary", "path": "src/components/template/CaseSummary" },
+      { "name": "CaseView", "path": "src/components/template/CaseView" },
+      {
+        "name": "CaseViewActionsMenu",
+        "path": "src/components/template/CaseViewActionsMenu"
+      },
+      {
+        "name": "Confirmation",
+        "path": "src/components/template/Confirmation"
+      },
+      {
+        "name": "DataReference",
+        "path": "src/components/template/DataReference"
+      },
+      { "name": "DefaultForm", "path": "src/components/template/DefaultForm" },
+      { "name": "DefaultPage", "path": "src/components/template/DefaultPage" },
+      { "name": "Details", "path": "src/components/template/Details" },
+      {
+        "name": "FieldGroupTemplate",
+        "path": "src/components/template/FieldGroupTemplate"
+      },
+      {
+        "name": "HierarchicalForm",
+        "path": "src/components/template/HierarchicalForm"
+      },
+      {
+        "name": "InlineDashboard",
+        "path": "src/components/template/InlineDashboard"
+      },
+      {
+        "name": "InlineDashboardPage",
+        "path": "src/components/template/InlineDashboardPage"
+      },
+      { "name": "ListPage", "path": "src/components/template/ListPage" },
+      { "name": "ListView", "path": "src/components/template/ListView" },
+      {
+        "name": "MultiReferenceReadOnly",
+        "path": "src/components/template/MultiReferenceReadOnly"
+      },
+      { "name": "NarrowWide", "path": "src/components/template/NarrowWide" },
+      { "name": "ObjectPage", "path": "src/components/template/ObjectPage" },
+      { "name": "OneColumn", "path": "src/components/template/OneColumn" },
+      {
+        "name": "PromotedFilters",
+        "path": "src/components/template/PromotedFilters"
+      },
+      {
+        "name": "SelfServiceCaseView",
+        "path": "src/components/template/SelfServiceCaseView"
+      },
+      { "name": "SimpleTable", "path": "src/components/template/SimpleTable" },
+      {
+        "name": "SingleReferenceReadOnly",
+        "path": "src/components/template/SingleReferenceReadOnly"
+      },
+      { "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" }
+    ],
+    "widget": [
+      {
+        "name": "AppAnnouncement",
+        "path": "src/components/widget/AppAnnouncement"
+      },
+      { "name": "Attachment", "path": "src/components/widget/Attachment" },
+      { "name": "CaseHistory", "path": "src/components/widget/CaseHistory" },
+      { "name": "FileUtility", "path": "src/components/widget/FileUtility" },
+      { "name": "Followers", "path": "src/components/widget/Followers" },
+      { "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" }
+    ],
+    "infra": [
+      { "name": "ActionButtons", "path": "src/components/infra/ActionButtons" },
+      {
+        "name": "DashboardFilter",
+        "path": "src/components/infra/DashboardFilter"
+      },
+      { "name": "DeferLoad", "path": "src/components/infra/DeferLoad" },
+      { "name": "NavBar", "path": "src/components/infra/NavBar" },
+      { "name": "Stages", "path": "src/components/infra/Stages" },
+      { "name": "VerticalTabs", "path": "src/components/infra/VerticalTabs" }
+    ],
+    "designSystemExtension": [
+      {
+        "name": "AlertBanner",
+        "path": "src/components/designSystemExtension/AlertBanner"
+      },
+      {
+        "name": "Banner",
+        "path": "src/components/designSystemExtension/Banner"
+      },
+      {
+        "name": "CaseSummaryFields",
+        "path": "src/components/designSystemExtension/CaseSummaryFields"
+      },
+      {
+        "name": "DetailsFields",
+        "path": "src/components/designSystemExtension/DetailsFields"
+      },
+      {
+        "name": "FieldGroup",
+        "path": "src/components/designSystemExtension/FieldGroup"
+      },
+      {
+        "name": "FieldGroupList",
+        "path": "src/components/designSystemExtension/FieldGroupList"
+      },
+      {
+        "name": "FieldValueList",
+        "path": "src/components/designSystemExtension/FieldValueList"
+      },
+      {
+        "name": "Operator",
+        "path": "src/components/designSystemExtension/Operator"
+      },
+      { "name": "Pulse", "path": "src/components/designSystemExtension/Pulse" },
+      {
+        "name": "RichTextEditor",
+        "path": "src/components/designSystemExtension/RichTextEditor"
+      },
+      {
+        "name": "WssQuickCreate",
+        "path": "src/components/designSystemExtension/WssQuickCreate"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,158 @@
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **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, ask both unresolved items in one numbered list. Do not assume or default the base folder — the client's folder structure may differ.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. What is your base components folder? (e.g. `src/components/`) — subfolders `field/`, `template/`, `widget/`, and `designSystemExtension/` will be used under it.
+
+### Component type scope
+
+Extract which types the user wants from the message:
+
+| User says                                  | Types in scope                                    |
+| ------------------------------------------ | ------------------------------------------------- |
+| "generate all components"                  | field + template + widget + designSystemExtension |
+| "generate field and widget components"     | field + widget                                    |
+| "generate widget, template components"     | widget + template                                 |
+| "generate all components except templates" | field + widget + designSystemExtension            |
+| "replace everything"                       | field + template + widget + designSystemExtension |
+
+Default to **all four types** if the message does not restrict the scope.
+
+### Derived output paths
+
+Once the base folder is known, derive the output path for each type in scope:
+
+| Type                  | Derived path                    |
+| --------------------- | ------------------------------- |
+| field                 | `<base>/field/`                 |
+| template              | `<base>/template/`              |
+| widget                | `<base>/widget/`                |
+| designSystemExtension | `<base>/designSystemExtension/` |
+
+Once design system, base folder, and type scope are resolved, continue to Step 1.
+
+---
+
+## Step 1 — Read general skill files (once, for each type in scope)
+
+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                 | `.claude/skills/field-components.md`        |
+| template              | `.claude/skills/template-components.md`     |
+| widget                | `.claude/skills/widget-components.md`       |
+| designSystemExtension | `.claude/skills/design-system-extension.md` |
+
+Keep all loaded skill files active throughout the entire session.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.claude/prompts/add-component.md` exactly as written:
+
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.claude/prompts/add-component.md` exactly as written:
+
+- Read the DS README from `node_modules`
+- Discover all exported components from `dist/index.d.ts`
+- Read prop interfaces for 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
+- Note form layout wrappers, size/variant conventions, icon packages, and design tokens
+
+Build a unified **DS API reference map** covering all types in scope. Reuse it throughout — do not repeat discovery commands 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.
+
+Collect all existing components across all types and report them in one consolidated list:
+
+> "The following N components already exist across [types]: [list grouped by type]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate field components (skip if field not in scope)
+
+If `field` is in scope, execute **Step 4** from `.claude/prompts/generate-field-components.md` in full:
+
+- Use the derived field output path: `<base>/field/`
+- The general skill (`field-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS API reference map is already built from Step 2 — do not repeat discovery commands
+- For each of the 27 field components: read skill file → generate → register in `component-map.ts`
+- Report progress after each component
+
+---
+
+## Step 5 — Generate template components (skip if template not in scope)
+
+If `template` is in scope, execute **Step 4** from `.claude/prompts/generate-template-components.md` in full:
+
+- Use the derived template output path: `<base>/template/`
+- The general skill (`template-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS layout API is already discovered from Step 2 — do not repeat discovery commands
+- For each of the 32 template components: read skill file → generate → register in `component-map.ts`
+- Report progress after each component
+
+---
+
+## Step 6 — Generate widget components (skip if widget not in scope)
+
+If `widget` is in scope, execute **Step 4** from `.claude/prompts/generate-widget-components.md` in full:
+
+- Use the derived widget output path: `<base>/widget/`
+- The general skill (`widget-components.md`) is already loaded from Step 1 — do not re-read it
+- The DS UI primitive map is already built from Step 2 — do not repeat discovery commands
+- For each of the 9 widget components: read skill file → generate → register in `component-map.ts`
+- If no skill file exists for a component (e.g., `SummaryList`), use the general pattern from `widget-components.md`
+- Report progress after each component
+
+---
+
+## Step 7 — Generate design system extension components (skip if DSE not in scope)
+
+If `designSystemExtension` is in scope, execute **Step 4** from `.claude/prompts/generate-dse-components.md` in full:
+
+- Use the derived DSE output path: `<base>/designSystemExtension/`
+- The general skill (`design-system-extension.md`) is already loaded from Step 1 — do not re-read it
+- The DS display primitive map is already built from Step 2 — do not repeat discovery commands
+- For each of the 11 DSE components: read skill file → generate → register in `component-map.ts`
+- Apply the Pattern B/A/C branching as specified in the skill file and `design-system-extension.md`
+- Report progress after each component
+
+---
+
+## Step 8 — Verify the build
+
+Execute **Step 7** from `.claude/prompts/add-component.md` exactly as written:
+
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a final summary:
+  - Total components generated, grouped by type
+  - All entries added to `component-map.ts`
+  - Any components skipped (if "skip existing" was chosen in Step 3)

package/templates/react-sdk-reference/.claude/prompts/generate-dse-components.md

@@ -0,0 +1,140 @@
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where 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, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the DSE components be generated? (e.g. `src/components/designSystemExtension/`)
+
+If the user specified a subset (e.g., "just AlertBanner and FieldValueList"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 11 DSE components)
+
+| Component         | Pattern              | DS needed?    |
+| ----------------- | -------------------- | ------------- |
+| AlertBanner       | B — Pure display     | Yes           |
+| Banner            | B — Pure display     | Yes           |
+| CaseSummaryFields | A — PConnect display | Minimal       |
+| DetailsFields     | A — PConnect display | Minimal       |
+| FieldGroup        | C — Complex display  | No            |
+| FieldGroupList    | C — Complex display  | No            |
+| FieldValueList    | A — PConnect display | No (CSS only) |
+| Operator          | B — Pure display     | Yes           |
+| Pulse             | C — Complex display  | No            |
+| RichTextEditor    | C — Complex display  | No            |
+| WssQuickCreate    | B — Pure display     | Yes           |
+
+---
+
+## Step 1 — Read `design-system-extension.md` (once, for the entire session)
+
+Read the full contents of `.claude/skills/design-system-extension.md`.
+
+This gives you:
+
+- All three implementation patterns (Pure display, Field value display, Complex display with PConnect)
+- The `// [DS RENDER]` placeholder approach for Pattern B components
+- The Design System Adaptation section — pattern categorisation, variant mapping table, DS discovery guidance
+- Styling patterns — when to use CSS files vs DS style props
+- Registration conventions
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.claude/prompts/add-component.md` exactly as written:
+
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.claude/prompts/add-component.md` exactly as written:
+
+- Read the DS README from `node_modules`
+- Discover exported components from `dist/index.d.ts`
+- Focus on display primitives used by Pattern B components: Alert, Card, Avatar, Badge, Tag, Notification
+- Read prop interfaces for these components from `.d.ts` files
+
+> 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.
+
+Build a **DS display primitive reference map** from this discovery. Reuse it for every Pattern B component — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+
+> "The following N components already exist: [list]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file
+
+Execute **Step 2** from `.claude/prompts/add-component.md` for this component:
+
+- Read `.claude/skills/design-system-extension-skills/<ComponentName>.md` fully
+- Identify the component's pattern (B / A / C) from the skill file
+- Pay attention to:
+  - **Behavioral Contract** — prop handling, variant mapping, rendering logic, edge cases
+  - **Design System Mapping** table — the recommended DS primitive for Pattern B components
+
+### 4b — Generate the component files
+
+Execute **Step 5** from `.claude/prompts/add-component.md` for this component:
+
+- Create `<outputPath>/<ComponentName>/` directory
+- Create `<ComponentName>.tsx` using:
+  - **Pattern B** (Pure display — AlertBanner, Banner, Operator, WssQuickCreate): use DS alert/card/avatar primitive from Step 2 API map in the `// [DS RENDER]` section; apply variant mapping from the skill file
+  - **Pattern A** (PConnect display — CaseSummaryFields, DetailsFields, FieldValueList): use CSS classes or DS typography props; no DS component primitives
+  - **Pattern C** (Complex display — FieldGroup, FieldGroupList, Pulse, RichTextEditor): use PConnect bridge (`createElement(createPConnectComponent(), ...)`); no DS primitives
+- Create `index.tsx` if required by the skill file:
+  ```typescript
+  export { default } from './<ComponentName>';
+  ```
+- Create any CSS file required by the skill file
+
+### 4c — Register the component
+
+Execute **Step 6** from `.claude/prompts/add-component.md` for this component:
+
+- Add the import to `src/components/component-map.ts` in the Design System Extension section
+- Add the entry to `getSampleComponentMap()` under the DSE comment
+- Do not reorder or restructure any existing entries
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`<`, using <DS primitive>` if Pattern B>"
+
+---
+
+## Step 5 — Verify the build
+
+Execute **Step 7** from `.claude/prompts/add-component.md` exactly as written:
+
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a summary: list of all files created and all entries added to `component-map.ts`

package/templates/react-sdk-reference/.claude/prompts/generate-field-components.md

@@ -0,0 +1,153 @@
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where field components should be generated (e.g. `src/components/field/`, `app/ui/fields/`)
+- **Component list** — which components to generate (default: all 27 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+
+Example questions (ask only the ones that are actually missing):
+
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the field components be generated? (e.g. `src/components/field/`)
+
+If the user specified a subset (e.g., "just TextInput and Dropdown"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default)
+
+| Component       | Pega Name       |
+| --------------- | --------------- |
+| AutoComplete    | AutoComplete    |
+| CancelAlert     | CancelAlert     |
+| Checkbox        | Checkbox        |
+| Currency        | Currency        |
+| Date            | Date            |
+| DateTime        | DateTime        |
+| Decimal         | Decimal         |
+| Dropdown        | Dropdown        |
+| Email           | Email           |
+| Group           | Group           |
+| Integer         | Integer         |
+| Location        | Location        |
+| Multiselect     | Multiselect     |
+| ObjectReference | ObjectReference |
+| Percentage      | Percentage      |
+| Phone           | Phone           |
+| RadioButtons    | RadioButtons    |
+| RichText        | RichText        |
+| ScalarList      | ScalarList      |
+| SelectableCard  | SelectableCard  |
+| SemanticLink    | SemanticLink    |
+| TextArea        | TextArea        |
+| TextContent     | TextContent     |
+| TextInput       | TextInput       |
+| Time            | Time            |
+| URL             | URL             |
+| UserReference   | UserReference   |
+
+---
+
+## Step 1 — Read `field-components.md` (once, for the entire session)
+
+Read the full contents of `.claude/skills/field-components.md`.
+
+This gives you:
+
+- The behavioral skeleton every field component must follow (state, effects, event handling, display modes)
+- The Design System Adaptation guide (prop mapping conventions, form layout wrappers)
+- The abstract template to use as a base for all components
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.claude/prompts/add-component.md` exactly as written:
+
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.claude/prompts/add-component.md` exactly as written:
+
+- Read the DS README from `node_modules`
+- Discover all exported components from `dist/index.d.ts`
+- Read prop interfaces for the control types needed across the component list
+- Note form layout wrappers, size/variant conventions, icon packages, and design tokens
+
+Build a **DS API reference map** from this discovery. You will reuse it for every component — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+
+> "The following N components already exist: [list]. How should I proceed?
+>
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file
+
+Execute **Step 2** from `.claude/prompts/add-component.md` for this component:
+
+- Read `.claude/skills/field-skills/<ComponentName>.md` fully
+- Pay attention to:
+  - **Behavioral Contract** — state management, option loading, edge cases specific to this component
+  - **Design System Mapping** table — the recommended DS component for the chosen design system
+  - **UI control type** — use this to select the closest DS primitive if the chosen DS is not in the mapping table
+
+### 4b — Generate the component files
+
+Execute **Step 5** from `.claude/prompts/add-component.md` for this component:
+
+- Create `<outputPath>/<ComponentName>/` directory
+- Create `<ComponentName>.tsx` using:
+  - The abstract behavioral skeleton from `field-components.md` (read in Step 1)
+  - The Behavioral Contract from the component skill file
+  - The DS API confirmed in Step 2 (from the DS API reference map — no new terminal commands needed)
+  - Display mode guards (`DISPLAY_ONLY`, `STACKED_LARGE_VAL`) via `getComponentFromRegistry('FieldValueList')`
+  - `data-test-id={testId}` on the underlying interactive element
+- Create `index.tsx`:
+  ```typescript
+  export { default } from './<ComponentName>';
+  ```
+
+### 4c — Register the component
+
+Execute **Step 6** from `.claude/prompts/add-component.md` for this component:
+
+- Add the import to `src/components/component-map.ts` in the Fields section
+- Add the entry to `getSampleComponentMap()` under the fields comment
+- Do not reorder or restructure any existing entries
+
+### 4d — Report progress
+
+After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
+
+---
+
+## Step 5 — Verify the build
+
+Execute **Step 7** from `.claude/prompts/add-component.md` exactly as written:
+
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a summary: list of all files created and all entries added to `component-map.ts`