@pega/sdk 0.0.4 → 0.0.6

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/Pulse.md

@@ -0,0 +1,97 @@
+# Skill: Pulse
+
+Placeholder activity feed / comments stream card. Currently a stub implementation that renders a card titled "Pulse".
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a card container intended to display an activity feed or comments stream for a Pega case. The current reference implementation is a **stub** — it renders only a Card with the title "Pulse" and placeholder body text. A production implementation would render a real activity feed stream inside the card using the `children` slot.
+
+## Pega Metadata
+
+- **Pega Name:** `Pulse`
+- **Registration key:** `Pulse` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives children via the framework's content projection mechanism
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name       | Type               | Required | Description                                                               |
+| ---------- | ------------------ | -------- | ------------------------------------------------------------------------- |
+| `children` | renderable content | No       | Child components (activity stream content) — currently unused in the stub |
+
+## Implementation Structure
+
+Stub implementation — placeholder only.
+
+### Module Setup
+
+The component accepts children via the framework's content projection mechanism. It does NOT import any Pega SDK modules.
+
+The component is named `Pulse` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Component Logic
+
+The component receives `children` as input (though the current stub does not render them), then:
+
+1. **Render a Card container** — a card-style element with a distinct 6px left border accent using the primary light color from the design system's palette (or CSS variable `--app-primary-light-color`). Apply top and bottom margin of 1 spacing unit (≈ 8px).
+2. **Render a CardHeader** — containing a heading (heading-6 text, ≈1.25rem, weight 500) with the text `"Pulse"`.
+3. **Render CardContent** — containing placeholder text `"Pulse"`.
+
+> **Note:** The current reference implementation ignores `children` and renders placeholder content. A production implementation would render the children (the activity stream) inside the card body.
+
+## Behavioral Contract
+
+1. Render a `Card` (or equivalent container) with a distinct left border accent.
+2. Render a card header with the title text `"Pulse"` using a heading style (heading-6, ≈1.25rem, weight 500).
+3. Render card content body with placeholder text `"Pulse"`.
+4. The left border accent uses the **primary light** color from the design system's theme.
+5. The card has top and bottom margin (1 spacing unit each).
+
+> **Stub note:** Steps 2–3 are placeholder content. In a real implementation, the card header would show a section label and the card body would render the `children` activity stream.
+
+## Visual Specifications
+
+Derived from the component's companion styles:
+
+### Card Container
+
+| Property          | Value                                                |
+| ----------------- | ---------------------------------------------------- |
+| Margin top        | 1 spacing unit (≈ 8px)                               |
+| Margin bottom     | 1 spacing unit (≈ 8px)                               |
+| Border left       | `6px solid`                                          |
+| Border left color | Primary light color from the design system's palette |
+
+**CSS-only implementation notes:**
+
+- Card wrapper: `margin-top: 8px; margin-bottom: 8px; border-left: 6px solid var(--app-primary-light-color); border-radius: 4px; box-shadow: 0 1px 3px rgba(0,0,0,0.12)`.
+- Card header: `padding: 16px; font-size: 1.25rem; font-weight: 500`.
+- Card body: `padding: 0 16px 16px`.
+- Use a CSS variable `--app-primary-light-color` for the accent border color.
+
+## Edge Cases & Special Logic
+
+- The `children` input is received but not currently rendered — it is intentional in the stub.
+- The component renders unconditionally (no conditional logic based on inputs).
+
+## Dependencies
+
+- No Pega SDK imports required (no `getPConnect`)
+- No helper utilities required
+
+## Design System Mapping
+
+**UI control type:** Card with left accent border and header/body sections.
+
+When implementing in a specific design system, map the following:
+
+- **Card container** → use the DS's card component (or a bordered container element)
+- **Left border accent** → apply `border-left: 6px solid` with the DS's primary-light color
+- **Card header** → use the DS's card header/title slot with heading-6 text
+- **Card body** → use the DS's card content/body slot
+- Card header title typography → design system's heading variant (h6 or equivalent)

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension-skills/RichTextEditor.md

@@ -0,0 +1,226 @@
+# Skill: RichTextEditor
+
+WYSIWYG rich text editor field backed by TinyMCE. Supports editable and read-only modes, optional label, helper text, error/required states, and a file picker for image uploads.
+
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
+
+---
+
+## Component Purpose
+
+Renders a rich text editing area (WYSIWYG) for Pega case properties that store HTML content. In **edit mode**, uses a rich text editor library with a bottom toolbar. In **read-only mode**, renders the HTML content as a read-only `<div>`. Wraps the editor in a form field wrapper with an optional label and helper text, consistent with other field components.
+
+The editor supports exposing its instance to parent components — use the framework's standard instance-sharing mechanism.
+
+> **Note:** TinyMCE is the reference editor library. In other implementations, this component can be replaced with an alternative rich text library (Quill, ProseMirror, Slate.js, Tiptap, etc.). The behavioral contract below remains the same regardless of library.
+
+## Pega Metadata
+
+- **Pega Name:** `RichTextEditor`
+- **Registration key:** `RichTextEditor` (in the project's component map)
+- **Does NOT extend the base PConnect interface** — receives all data as explicit field-like inputs
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name           | Type       | Required | Description                                                       |
+| -------------- | ---------- | -------- | ----------------------------------------------------------------- |
+| `id`           | `string`   | No       | DOM id for the editor element. Defaults to a generated UID        |
+| `defaultValue` | `string`   | Yes      | Initial HTML content of the editor                                |
+| `label`        | `string`   | Yes      | Field label displayed above the editor                            |
+| `labelHidden`  | `boolean`  | Yes      | If `true`, hide the label                                         |
+| `info`         | `string`   | No       | Helper text displayed below the editor                            |
+| `testId`       | `string`   | No       | Value for the test id attribute on the form wrapper               |
+| `placeholder`  | `string`   | No       | Placeholder text shown in empty editor                            |
+| `disabled`     | `boolean`  | Yes      | If `true`, editor is in read-only/disabled mode with no toolbar   |
+| `required`     | `boolean`  | Yes      | If `true`, marks the field as required                            |
+| `readOnly`     | `boolean`  | Yes      | If `true`, render as static HTML display (not interactive editor) |
+| `error`        | `boolean`  | Yes      | If `true`, applies error styling to the form wrapper              |
+| `onBlur`       | `function` | Yes      | Called when the editor loses focus                                |
+| `onChange`     | `function` | Yes      | Called when the editor content changes                            |
+
+## Implementation Structure
+
+### Module Setup
+
+The component imports:
+
+- The framework's mechanism for exposing the editor instance to parent components (e.g., ref forwarding in React, `@ViewChild` in Angular)
+- Lifecycle and utility helpers from the SDK bridge package: a post-initial-mount change watcher, a consolidated instance reference utility, and a unique ID generator
+- A rich text editor library (TinyMCE in the reference implementation — can be swapped for Quill, ProseMirror, Tiptap, etc.)
+- Form wrapper components from the design system (form control, helper text, label)
+- Theme/token access from the design system for palette and typography values
+
+The component is named `RichTextEditor`, accepts the inputs listed above, and supports exposing the editor instance to parent components. Define the input contract and export the component following the project's framework conventions.
+
+### Editor Instance and ID Management
+
+- Use the SDK bridge package's consolidated reference utility to create a reference to the editor instance — the rich text editor instance is stored here after initialization via `onInit`.
+- If `id` is not provided in the inputs, generate one using the SDK bridge package's unique ID generator.
+
+### Mode Transition Effect
+
+After initial mount, use the SDK bridge package's post-initial-mount change watcher, observing `[readOnly, disabled]`. When either changes, switch the editor's mode to read-only if either `readOnly` or `disabled` is true, otherwise switch to edit/design mode. This transitions the editor mode without re-mounting it.
+
+### Render Paths
+
+The component has two mutually exclusive render paths, both wrapped in a common form wrapper:
+
+**Read-only path** (when `readOnly === true`):
+
+- Render a `<div>` with the resolved `id`, class `readonly-richtext-editor`, and raw HTML content containing `defaultValue` (or `'--'` if defaultValue is falsy) via the framework's trusted HTML injection mechanism.
+- Skip the TinyMCE Editor entirely.
+
+**Edit path** (when `readOnly === false`):
+
+- Render the TinyMCE editor instance with the configuration described in the Behavioral Contract sections below.
+- On init, store the editor instance in the component's editor reference.
+
+### Wrapper Structure
+
+Both paths are wrapped in a form field wrapper (the DS's form control component) with:
+
+- The test id attribute set to the `testId` input
+- `error` and `required` states passed through
+- If `labelHidden` is false: render a label element with class `fieldLabel` containing the `label` text (non-floating — positioned relative with no transform)
+- The rich text component (either read-only div or interactive editor)
+- If `info` is provided: render a helper text element containing the info text
+
+## Behavioral Contract
+
+### 1. Exposing the Editor Instance
+
+The component exposes the editor instance to parent components. Internally, use the SDK bridge package's consolidated reference utility to store the editor instance after initialization.
+
+### 2. UID for id
+
+If `id` is not provided, generate one using the SDK bridge package's unique ID generator.
+
+### 3. Read-Only Mode
+
+If `readOnly` is `true`, render a `<div>` with `key` and `id` set to the resolved id, class `readonly-richtext-editor`, and the raw HTML content set to `defaultValue` (or `'--'` as fallback if defaultValue is falsy). Skip the interactive editor entirely in this case.
+
+### 4. Edit Mode (TinyMCE)
+
+When `readOnly` is `false`, render the TinyMCE editor component from the project's framework-specific TinyMCE integration package with:
+
+| Config             | Value                                            |
+| ------------------ | ------------------------------------------------ |
+| `tinymceScriptSrc` | `'tinymce/tinymce.min.js'` (local script)        |
+| `id`               | The resolved `id`                                |
+| `initialValue`     | `defaultValue`                                   |
+| `disabled`         | `disabled` input                                 |
+| `onBlur`           | `onBlur` input                                   |
+| `onEditorChange`   | `onChange` input                                 |
+| `onInit`           | Store editor in the component's editor reference |
+
+### 5. TinyMCE `init` Configuration
+
+| Option                     | Value                                                                                                                |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `skin`                     | `'oxide-dark'` (dark mode) / `'oxide'` (light mode) — detect from theme                                              |
+| `menubar`                  | `false`                                                                                                              |
+| `statusbar`                | `false`                                                                                                              |
+| `branding`                 | `false`                                                                                                              |
+| `min_height`               | `130`                                                                                                                |
+| `toolbar_location`         | `'bottom'`                                                                                                           |
+| `plugins`                  | `['lists', 'advlist', 'autolink', 'image', 'link', 'autoresize']`                                                    |
+| `autoresize_bottom_margin` | `0`                                                                                                                  |
+| `toolbar`                  | `'blocks \| bold italic strikethrough \| bullist numlist outdent indent \| link image'` (or `false` when `disabled`) |
+| `paste_data_images`        | `true`                                                                                                               |
+| `file_picker_types`        | `'image'`                                                                                                            |
+| `file_picker_callback`     | See file picker section below                                                                                        |
+| `content_style`            | Theme-aware CSS string (see below)                                                                                   |
+| `placeholder`              | `placeholder` input                                                                                                  |
+
+### 6. Theme-Aware Content Style
+
+Inject a `content_style` string into the TinyMCE init config that uses theme values. The style string should set properties for the following selectors:
+
+| CSS Selector                                                             | Properties                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `body`                                                                   | `font-family` from theme typography; `font-size` from theme typography (in px); `color` from theme's primary text color; `background` from theme's paper/surface background                                                       |
+| `a`                                                                      | `color` from theme's primary/link color                                                                                                                                                                                           |
+| `h1` through `h6`                                                        | `color` from theme's primary text color; `font-family` from theme typography                                                                                                                                                      |
+| `blockquote`                                                             | `color` from theme's secondary text color; `border-left: 4px solid` using theme's primary-light color; `padding-left: 8px`                                                                                                        |
+| `ul, ol`                                                                 | `color` from theme's primary text color                                                                                                                                                                                           |
+| `input, textarea, select`                                                | `background` from theme's paper/surface background; `color` from theme's primary text color; `border: 1px solid` using theme's divider color; `border-radius: 4px`; `padding: 6px 10px`; `font-size: 1em`; `font-family: inherit` |
+| `.mce-content-body[data-mce-placeholder]:not(.mce-visualblocks)::before` | `color` from theme's secondary text color; `opacity: 0.7`                                                                                                                                                                         |
+
+### 7. File Picker Callback
+
+When a user clicks the image upload in the toolbar:
+
+1. Create a hidden `<input type='file' accept='image/*'>`.
+2. On file selected: read as DataURL using `FileReader`.
+3. On `FileReader.load`: create a blob in TinyMCE's blob cache (accessed via the stored editor instance's `editorUpload.blobCache`), then call `cb(blobInfo.blobUri(), { title: file.name })`.
+4. Programmatically click the input to open the file dialog.
+
+### 8. readOnly/disabled Transition (after initial mount)
+
+Use the SDK bridge package's post-initial-mount change watcher, observing `[readOnly, disabled]`. When either value changes after the initial render, switch the editor mode to read-only (if readOnly or disabled is true) or to editable/design mode (otherwise). This transitions the editor mode without re-mounting it.
+
+### 9. Wrapper Structure
+
+The component nests elements in this order:
+
+1. **Form field wrapper** (the DS's form control) with the test id attribute, `error`, and `required` states
+2. Inside the wrapper, conditionally: **Label element** with class `fieldLabel` containing `{label}` (only if `labelHidden` is false)
+3. The rich text component — either the read-only div or the interactive editor
+4. Conditionally: **Helper text element** containing `{info}` (only if `info` is provided)
+
+## Visual Specifications
+
+Derived from the component's companion styles:
+
+### Label
+
+| Property      | Value                                                      |
+| ------------- | ---------------------------------------------------------- |
+| Position      | relative                                                   |
+| Transform     | `translate(0, 0px) scale(1)` (non-floating — stays at top) |
+| Margin bottom | 5px                                                        |
+| Color         | secondary text color                                       |
+
+**CSS-only implementation notes:**
+
+- Label: `display: block; font-size: 0.875rem; color: var(--text-secondary); margin-bottom: 5px`.
+- Editor container: `min-height: 130px; border: 1px solid var(--divider); border-radius: 4px`.
+- Toolbar (if CSS-only): render buttons at bottom of the editor area.
+- Read-only display: `div.readonly-richtext-editor { padding: 8px; min-height: 130px; background: var(--bg-paper); color: var(--text-primary) }`.
+- Error state: `border-color: var(--error-color)`.
+- Helper text: `font-size: 0.75rem; color: var(--text-secondary); margin-top: 4px`.
+- Error helper text: `color: var(--error-color)`.
+
+## Edge Cases & Special Logic
+
+- `defaultValue` in read-only mode falls back to `'--'` if empty.
+- `readOnly` and `disabled` are both handled — `readOnly` suppresses the editor entirely; `disabled` keeps the editor mounted but in TinyMCE's `readonly` mode with no toolbar.
+- Mode transitions (readOnly/disabled changing after mount) use the SDK bridge package's post-initial-mount change watcher — it fires on subsequent changes but NOT on the initial mount, preventing a double-set.
+- The file picker creates a transient `<input type='file'>` element that is never appended to the DOM — it is clicked programmatically.
+- `id` must be stable across renders — use the SDK's unique ID generator only as a fallback when `id` input is absent.
+
+## Dependencies
+
+- A rich text editor library (TinyMCE in the reference — can be swapped for Quill, ProseMirror, Slate.js, Tiptap, etc.)
+- Lifecycle and utility helpers from the SDK bridge package: a post-initial-mount change watcher, a consolidated instance reference utility, and a unique ID generator
+- The design system's theme/token mechanism — for theme-aware content styles
+- The design system's form field wrapper components (form control, helper text, label)
+
+## Design System Mapping
+
+**UI control type:** Rich text / WYSIWYG editor field with label, helper text, and error state.
+
+When implementing in a specific design system, map the following:
+
+- **Rich text editor** → use TinyMCE, Quill, ProseMirror, Tiptap, or any WYSIWYG library appropriate for the project
+- **Form wrapper** → use the DS's form field wrapper (form control, form group, or field container) with error/required states
+- **Label** → use the DS's field label component (non-floating, positioned above the editor)
+- **Helper text** → use the DS's helper/description text below the editor, with error color when `error` is true
+- **`defaultValue`** → initial HTML content
+- **`readOnly` = true** → always render as static HTML display (no editor instance)
+- **`disabled` = true** → editor mounted but in read-only mode with toolbar hidden
+- **`onBlur` / `onChange`** → editor's blur and content-change callbacks
+- **File picker** → `<input type='file' accept='image/*'>` triggered programmatically when the image toolbar button is clicked
+- **Theme-aware styles** → inject the DS's typography and palette values into the editor's content styles so content inside the editor matches the app's theme

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/design-system-extension-skills/WssQuickCreate.md

@@ -2,7 +2,7 @@
 
 Quick-launch action grid that displays a heading and a set of labeled buttons, each optionally with an icon, for creating WSS cases.
 
-> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, props interface, styling patterns, and registration patterns common to ALL DSE components.
+> **Prerequisite skill:** [`design-system-extension.md`](../design-system-extension.md) — covers architecture, input contracts, styling patterns, and registration patterns common to ALL DSE components.
 
 ---
 
@@ -13,16 +13,40 @@ Renders a titled section of clickable action cards arranged in a responsive CSS
 ## Pega Metadata
 
 - **Pega Name:** `WssQuickCreate`
-- **Registration key:** `WssQuickCreate` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
+- **Registration key:** `WssQuickCreate` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
 
-## Props
+## Component Inputs
 
-| Prop      | Type                                                           | Required | Description                                                                  |
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name      | Type                                                           | Required | Description                                                                  |
 | --------- | -------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------- |
 | `heading` | `string`                                                       | Yes      | Section title rendered as an `<h1>`                                          |
 | `actions` | `Array<{ label: string; onClick: () => void; icon?: string }>` | No       | List of action items; each has a label, click handler, and optional icon URL |
 
+## Implementation Structure
+
+### Module Setup
+
+The component requires companion styles (for action list and button styling) co-located following the project's styling convention. It does NOT import any Pega SDK modules — all data arrives via direct inputs.
+
+The component is named `WssQuickCreate` and accepts the inputs listed in the table above. Define the input contract and export the component following the project's framework conventions.
+
+### Component Logic
+
+The component receives `heading` and `actions` as inputs, then renders:
+
+1. **Heading** — an `<h1>` element with `id="quick-links-heading"` and class `quick-links-heading`, containing the `heading` text.
+2. **Action list** — a `<ul>` with `id="quick-links"` and class `quick-link-ul-list`.
+3. **Action items** — if `actions` is provided, iterate over the array rendering one `<li>` per action:
+   - The `<li>` has the `quickLinkList` style class (styled card appearance with border, rounded corners, and themed background color).
+   - Inside each `<li>`, render a `<button>` with `type="button"`, class `quick-link-button`, and the action's `onClick` handler.
+   - Button content is a `<span>` with class `quick-link-button-span` (flex column layout) containing:
+     - If `action.icon` is provided: an `<img>` with class `quick-link-icon` and `src` set to the icon URL.
+     - A `<span>` containing `action.label`.
+4. If `actions` is not provided or is empty, render only the heading with an empty list.
+
 ## Behavioral Contract
 
 1. Render the `heading` in an `<h1>` element with `id='quick-links-heading'` and class `quick-links-heading`.
@@ -37,7 +61,7 @@ Renders a titled section of clickable action cards arranged in a responsive CSS
 
 ## Visual Specifications
 
-Derived from `WssQuickCreate.css` and component makeStyles:
+Derived from the component's companion styles:
 
 ### Section Heading
 
@@ -119,19 +143,10 @@ Derived from `WssQuickCreate.css` and component makeStyles:
 
 **UI control type:** Responsive grid of action cards / quick-launch buttons.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                   |
-| ------------------ | ----------------------------------------------------------------------- |
-| Default (CSS only) | CSS grid `<ul>` + `<button>` cards with flex icon/label layout          |
-| MUI                | `<Button>` inside Grid items; use `makeStyles` or `sx` for card styling |
-| Ant Design         | `<List>` with `<Card>` items or `<Button>` blocks inside a CSS grid     |
-| Chakra UI          | `<SimpleGrid>` with `<Button>` children; `flexDir='column'`             |
-| Shadcn/ui          | Grid of custom `<Button variant='outline'>` cards                       |
-
 When implementing in a specific design system, map the following:
 
-- Card border/background → design system's card or outlined button variant
-- Button `onClick` → standard click handler prop
-- Icon + label stacked layout → `flexDirection: 'column'` button content
-- Responsive grid → design system's grid or `SimpleGrid` equivalent
+- **Card border/background** → use the DS's card or outlined button variant with the themed background and border colors
+- **Button click** → standard click handler wired to `action.onClick`
+- **Icon + label stacked layout** → use a flex column layout inside the button content area
+- **Responsive grid** → use the DS's responsive grid component or CSS grid with `repeat(auto-fit, minmax(min(20ch, 100%), 1fr))`
+- **Dark/light mode background** → use `var(--app-background-color)` in dark mode or `var(--link-button-color)` in light mode (or detect from the DS's theme mode)

package/templates/react-sdk-reference/.ai-common/skills/design-system-extension.md

@@ -0,0 +1,169 @@
+# Skill: Design System Extension (DSE) Components
+
+Create or replace Design System Extension components in the project. DSE components are display-focused presentational components that render structured data without direct PConnect binding. Some receive `getPConnect`, others receive only display inputs.
+
+---
+
+## Architecture Overview
+
+Each DSE component lives in its own folder under the project's design-system-extension components directory, named after the component. The folder contains:
+
+| File                          | Purpose                                                 |
+| ----------------------------- | ------------------------------------------------------- |
+| Component implementation file | The component's logic and markup                        |
+| Re-export module (if present) | Re-exports the component as the folder's default export |
+| Companion styles (optional)   | Styles scoped to the component                          |
+| Metadata (optional)           | Registration metadata (name, label, description, type)  |
+
+---
+
+## Input Contract
+
+DSE components have varying input patterns:
+
+### Pattern A: With PConnect (data-aware display)
+
+The component's input contract extends the project's base component interface, which provides `getPConnect()` — a function returning the PConnect API object — in addition to its own custom inputs. Example: a field-value display component extending the base interface with additional fields like `name`, `value`, and `variant`.
+
+### Pattern B: Without PConnect (pure presentation)
+
+The component's input contract is standalone — it does NOT extend the base component interface. All rendering data arrives via direct inputs. Example: an alert-banner component with fields like `variant`, `heading`, `messages`, and `onClose`.
+
+### Pattern C: Extended field input contract (display-only fields)
+
+The component's input contract extends the project's field input contract, which provides standard field-level inputs (`label`, `value`, `displayMode`, `required`, `disabled`, `readOnly`, `status`, `validatemessage`, `helperText`, `hideLabel`, `placeholder`, `testId`) plus `getPConnect()`. The component adds its own domain-specific inputs on top. Example: a rich-text-editor component extending the field input contract with an additional `content` field.
+
+---
+
+## Implementation Patterns
+
+### Pure Display Component (no PConnect)
+
+Used for: AlertBanner, Banner, Operator
+
+This pattern is design-system agnostic. The variant-mapping logic and message normalisation are always the same — only the final rendered output changes based on the chosen design system (see "Design System Adaptation" below).
+
+**Structure:**
+
+1. **Use** the design system's alert/notification primitive as the visual foundation.
+2. **Define the input contract** (Pattern B — no PConnect). Include the Pega-facing inputs: `variant`, `heading`/`messages`, and an optional close/dismiss handler.
+3. **Define a variant map** at module level — a plain lookup mapping Pega variant strings (`urgent`, `warning`, `info`, `success`) to the design system's equivalent severity/type value. Unknown variants fall back to `info`.
+4. **Define a message normaliser** — a helper function that accepts either a plain string or an object (`{ label?, description? }`) and returns formatted content. Pega may send either format.
+5. **Render** using the design system's alert primitive. Pass the mapped severity as the type/severity/status input. Wire the dismiss handler to the design system's close input only if provided. Render message content inside the alert body.
+
+### Field Value Display Component
+
+Used for: FieldValueList, CaseSummaryFields, DetailsFields
+
+**Structure:**
+
+1. **Define the input contract** (Pattern A — extends the project's base component interface) with fields for `name` (optional string), `value` (any), and `variant` (optional — `'stacked'` or `'inline'`, defaulting to `'inline'`).
+2. **Stacked variant** — when `variant` is `'stacked'`, render the label on its own line above the value. The value should use a larger/emphasized typography style.
+3. **Inline variant** (default) — render the label and value side by side. The label occupies roughly 1/3 width, value occupies 2/3. If `name` is not provided, render only the value at full width.
+4. **Empty value handling** — if `value` is undefined or an empty string, display a placeholder (`'---'`).
+
+### Complex Display Component (with PConnect for data)
+
+Used for: FieldGroup, FieldGroupList, Pulse
+
+**Structure:**
+
+1. **Define the input contract** (Pattern A — extends the project's base component interface) with component-specific fields (e.g., `label`, `showLabel`).
+2. **Obtain the PConnect instance** by calling `getPConnect()` from the component's inputs.
+3. **Retrieve children** via `pConn.getChildren()` — this returns an array of child component configurations from the Pega engine.
+4. **Render children dynamically** — iterate over the children array and render each child configuration using the project's PConnect bridge utility, keyed uniquely. This bridges the Pega component tree into the chosen framework's rendering model.
+5. **Wrap in semantic HTML** — use appropriate semantic elements (e.g., `<fieldset>` with `<legend>` for grouped fields). Conditionally show labels based on the `showLabel` input.
+
+---
+
+## Styling Patterns
+
+DSE components use one of three approaches depending on the component and design system:
+
+### CSS File Pattern (DS-agnostic, preferred for Field Value components)
+
+Create a co-located `.css` file named after the component. Typical CSS conventions for DSE components:
+
+- **Inline layout** — use `display: flex` with a small gap (`0.5rem`) and `align-items: baseline` for label/value pairs.
+- **Labels** — `font-weight: 600` with a secondary text color (use a CSS custom property like `var(--text-secondary)`).
+- **Large values (stacked variant)** — `font-size: 1.25rem`, `font-weight: 500`.
+- Use CSS custom properties (design tokens) for colors and spacing — never hardcode pixel values for spacing.
+- Class names follow the pattern `.component-name-element` (e.g., `.field-value-inline`, `.field-label`).
+
+### Design System Style Inputs (use if your DS provides them)
+
+If the chosen design system provides built-in spacing, typography, or layout inputs, prefer them over plain CSS:
+
+- Use the DS's layout primitives (e.g., a stack, flex, or grid wrapper component) instead of manual flex CSS
+- Use the DS's typography primitives (e.g., a text or heading component) instead of raw `<span>`/`<div>`
+- Use DS CSS custom properties or tokens for spacing — never hardcode `px` values
+- Discover which style inputs are available from the design system's type declarations before using them
+
+---
+
+## Design System Adaptation
+
+DSE components fall into three patterns with different DS dependencies:
+
+| Pattern                                   | Examples                                         | DS needed?                                         |
+| ----------------------------------------- | ------------------------------------------------ | -------------------------------------------------- |
+| **B — Pure display** (no PConnect)        | AlertBanner, Banner, Operator, WssQuickCreate    | Yes — DS provides alert/card/avatar primitives     |
+| **A — PConnect display**                  | CaseSummaryFields, DetailsFields, FieldValueList | Minimal — CSS-based layout; DS typography optional |
+| **C — Complex display** (PConnect bridge) | FieldGroup, FieldGroupList, Pulse                | No — PConnect bridge is DS-agnostic; semantic HTML |
+
+The component-specific skill file specifies which pattern applies.
+
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` contains a **Design System Mapping** table where available.
+
+**2. If the chosen design system is not listed** — use the component purpose and pattern category above to pick the closest DS primitive.
+
+**3. Discover the API from installed packages** — confirm component names and inputs from the design system's type declarations before writing the component's markup. Search the design system package's type declarations for relevant component interfaces (e.g., look for files mentioning `Alert`, `Badge`, or `Avatar` and read the exported input interface to confirm available input names and types).
+
+**4. Variant mapping** — always map Pega's variant names to your DS equivalent before passing to DS components:
+
+| Pega variant | Meaning          | Typical DS equivalent         |
+| ------------ | ---------------- | ----------------------------- |
+| `urgent`     | Critical / error | `error`, `danger`, `critical` |
+| `warning`    | Warning          | `warning`                     |
+| `info`       | Informational    | `info`                        |
+| `success`    | Success          | `success`                     |
+
+---
+
+## Registration
+
+Register DSE components in the project's component map:
+
+1. **Import** the component's default export from its folder under the design-system-extension components directory.
+2. **Add the component** to the object returned by the project's component registration function, using the component name as the key (must match the Pega registration key exactly). The component is spread alongside the base component map.
+
+---
+
+## Existing DSE Components
+
+| Component         | PConnect? | Description                             |
+| ----------------- | --------- | --------------------------------------- |
+| AlertBanner       | No        | Alert/notification banner with variants |
+| Banner            | No        | Promotional/informational banner        |
+| CaseSummaryFields | Yes       | Summary fields for case header          |
+| DetailsFields     | Yes       | Key-value fields in a details region    |
+| FieldGroup        | Yes       | Grouped fields with label/legend        |
+| FieldGroupList    | Yes       | List of field groups (repeating)        |
+| FieldValueList    | Yes       | Single field-value pair display         |
+| Operator          | No        | Operator avatar + name display          |
+| Pulse             | Yes       | Activity feed/comments stream           |
+| RichTextEditor    | Yes       | Rich text editor (TinyMCE-based)        |
+| WssQuickCreate    | No        | WSS quick case creation component       |
+
+---
+
+## Key Conventions
+
+1. **Default export** — export the component as the module's default export.
+2. **Flexible messages** — Always handle both `string` and `object` formats for text inputs (Pega may send either).
+3. **No side effects** — DSE components should be pure renderers. No data fetching or mutations.
+4. **Variant mapping** — Map Pega variant names (urgent, warning, etc.) to the design system's equivalents.
+5. **Display modes** — If a DSE component is also used as a display mode by field components (e.g., FieldValueList), it should be simple and fast to render.
+6. **Graceful fallbacks** — Handle missing/undefined inputs gracefully with defaults.
+7. **Prefer plain CSS or the design system's built-in styling mechanism** over CSS-in-JS libraries, unless the project's conventions dictate otherwise.
+8. **Accessible markup** — Use semantic HTML (fieldset/legend for groups, proper heading levels, ARIA labels).