@pega/sdk 0.0.3 → 0.0.5

package/templates/react-sdk-reference/{.cursor/rules/skills/template-skills/TwoColumn.mdrules → .ai-common/skills/template-skills/TwoColumn.md}

@@ -1,8 +1,3 @@
----
-description: Template component skill: TwoColumn
-alwaysApply: false
----
-
 # Skill: TwoColumn
 
 Two-column layout template that splits children into two responsive grid columns with configurable width ratios.
@@ -21,20 +16,69 @@ Renders two child components side by side in a responsive grid. Column widths ar
 
 ## Pega Metadata
 
-| Variant | Registration Key |
-|---------|-----------------|
-| TwoColumn | `TwoColumn` |
-| TwoColumnPage | `TwoColumnPage` |
-| TwoColumnTab | `TwoColumnTab` |
+| Variant       | Registration Key |
+| ------------- | ---------------- |
+| TwoColumn     | `TwoColumn`      |
+| TwoColumnPage | `TwoColumnPage`  |
+| TwoColumnTab  | `TwoColumnTab`   |
 
 All three extend `PConnProps`. Children are received as React `children` (not via `getPConnect().getChildren()`).
 
+## Component Skeletons
+
+### TwoColumn (core)
+
+```typescript
+import type { PropsWithChildren, ReactElement } from 'react';
+import type { GridSize } from '@mui/material/Grid';
+import type { PConnProps } from '@pega/sdk-react';
+
+interface TwoColumnProps extends PConnProps {
+  templateCol?: string;
+}
+
+export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
+  const { children, templateCol = '1fr 1fr' } = props;
+  const childrenToRender = children as ReactElement[];
+
+  if (childrenToRender.length !== 2) {
+    console.error(`TwoColumn sees ${childrenToRender.length} children (expected 2)`);
+  }
+
+  // Parse templateCol to compute column sizes (12-grid)
+  const colAArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
+  const totalCols = colAArray.reduce((v, itm) => itm + v, 0);
+  const ratio = 12 / totalCols;
+  const aSize = (ratio * colAArray[0]) as GridSize;
+  const bSize = (ratio * colAArray[1]) as GridSize;
+
+  return (
+    <GridContainer spacing={1}>
+      <GridItem xs={12} md={aSize} className="col-styles">{childrenToRender[0]}</GridItem>
+      <GridItem xs={12} md={bSize} className="col-styles">{childrenToRender[1]}</GridItem>
+    </GridContainer>
+  );
+}
+// CSS: .col-styles { display: grid; gap: 1rem; align-content: baseline; }
+```
+
+### TwoColumnPage
+
+```typescript
+const TwoColumn = getComponentFromRegistry('TwoColumn');
+return <TwoColumn {...props} />;
+```
+
+### TwoColumnTab
+
+Identical implementation to `TwoColumn` — same `templateCol` parsing, same grid output.
+
 ## Props
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | Yes | Exactly 2 children (left column, right column) |
-| `templateCol` | `string` | No | Column width ratio string, e.g., `'1fr 1fr'`, `'2fr 1fr'`. Default `'1fr 1fr'` |
+| Prop          | Type          | Required | Description                                                                    |
+| ------------- | ------------- | -------- | ------------------------------------------------------------------------------ |
+| `children`    | `ReactNode[]` | Yes      | Exactly 2 children (left column, right column)                                 |
+| `templateCol` | `string`      | No       | Column width ratio string, e.g., `'1fr 1fr'`, `'2fr 1fr'`. Default `'1fr 1fr'` |
 
 ## Sub-Variants
 
@@ -71,35 +115,36 @@ Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
 
 ### Column Style
 
-| Property | Value |
-|----------|-------|
-| Display | grid |
-| Gap | 1rem |
+| Property      | Value                                 |
+| ------------- | ------------------------------------- |
+| Display       | grid                                  |
+| Gap           | 1rem                                  |
 | Align content | baseline (children stack top-aligned) |
 
 ### Grid Spacing
 
-| Property | Value |
-|----------|-------|
+| Property          | Value                     |
+| ----------------- | ------------------------- |
 | Container spacing | 1 (≈ 8px between columns) |
 
 ### Responsive Behavior
 
-| Breakpoint | Column A | Column B |
-|-----------|----------|----------|
-| xs (mobile) | 12/12 (full width) | 12/12 (full width, stacks below) |
-| md+ (desktop) | `aSize`/12 | `bSize`/12 |
+| Breakpoint    | Column A           | Column B                         |
+| ------------- | ------------------ | -------------------------------- |
+| xs (mobile)   | 12/12 (full width) | 12/12 (full width, stacks below) |
+| md+ (desktop) | `aSize`/12         | `bSize`/12                       |
 
 **Column ratio examples:**
 
-| `templateCol` | Column A | Column B |
-|--------------|----------|----------|
-| `'1fr 1fr'` | 6/12 (50%) | 6/12 (50%) |
-| `'2fr 1fr'` | 8/12 (67%) | 4/12 (33%) |
-| `'1fr 2fr'` | 4/12 (33%) | 8/12 (67%) |
-| `'3fr 1fr'` | 9/12 (75%) | 3/12 (25%) |
+| `templateCol` | Column A   | Column B   |
+| ------------- | ---------- | ---------- |
+| `'1fr 1fr'`   | 6/12 (50%) | 6/12 (50%) |
+| `'2fr 1fr'`   | 8/12 (67%) | 4/12 (33%) |
+| `'1fr 2fr'`   | 4/12 (33%) | 8/12 (67%) |
+| `'3fr 1fr'`   | 9/12 (75%) | 3/12 (25%) |
 
 **CSS-only implementation notes:**
+
 - Column container: `display: grid; gap: 1rem; align-content: start`.
 - Outer grid: `display: grid; grid-template-columns: <aFraction>fr <bFraction>fr; gap: 8px`.
 - Mobile: `grid-template-columns: 1fr` (single column stack).
@@ -122,15 +167,16 @@ Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
 
 Listed design systems are examples only.
 
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | CSS Grid with `grid-template-columns: <a>fr <b>fr; gap: 8px` |
-| MUI | `<Grid container spacing={1}><Grid size={{ xs: 12, md: N }}>` |
-| Ant Design | `<Row gutter={8}><Col xs={24} md={N * 2}>` (Ant uses 24-column grid) |
-| Chakra UI | `<SimpleGrid columns={{ base: 1, md: 2 }} spacing={2}>` |
-| Shadcn/ui | Tailwind `grid grid-cols-1 md:grid-cols-[<a>fr_<b>fr] gap-2` |
+| Design System      | Recommended Component                                                |
+| ------------------ | -------------------------------------------------------------------- |
+| Default (CSS only) | CSS Grid with `grid-template-columns: <a>fr <b>fr; gap: 8px`         |
+| MUI                | `<Grid container spacing={1}><Grid size={{ xs: 12, md: N }}>`        |
+| Ant Design         | `<Row gutter={8}><Col xs={24} md={N * 2}>` (Ant uses 24-column grid) |
+| Chakra UI          | `<SimpleGrid columns={{ base: 1, md: 2 }} spacing={2}>`              |
+| Shadcn/ui          | Tailwind `grid grid-cols-1 md:grid-cols-[<a>fr_<b>fr] gap-2`         |
 
 When implementing in a specific design system:
+
 - Parse `templateCol` using the same ratio algorithm (strip units, divide 12 by total)
 - Apply `align-content: baseline` so children within each column stack top-aligned
 - Collapse to single column on mobile breakpoint

package/templates/react-sdk-reference/{.claude → .ai-common}/skills/template-skills/WideNarrow.md

@@ -19,11 +19,11 @@ Renders two children side by side with the left column wider than the right. Typ
 
 ## Pega Metadata
 
-| Variant | Registration Key |
-|---------|-----------------|
-| WideNarrow | `WideNarrow` |
-| WideNarrowPage | `WideNarrowPage` |
-| WideNarrowForm | `WideNarrowForm` |
+| Variant           | Registration Key    |
+| ----------------- | ------------------- |
+| WideNarrow        | `WideNarrow`        |
+| WideNarrowPage    | `WideNarrowPage`    |
+| WideNarrowForm    | `WideNarrowForm`    |
 | WideNarrowDetails | `WideNarrowDetails` |
 
 All extend `PConnProps`.
@@ -32,38 +32,38 @@ All extend `PConnProps`.
 
 ### WideNarrow
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | No | Two children — `[0]` → wide (left), `[1]` → narrow (right) |
-| `a` | `any` | No | Wide (left) column content |
-| `b` | `any` | No | Narrow (right) column content |
-| `title` | `string` | No | Optional title (not rendered) |
-| `cols` | `string` | No | Column template (not rendered) |
-| `icon` | `string` | No | Icon name (not rendered) |
+| Prop       | Type          | Required | Description                                                |
+| ---------- | ------------- | -------- | ---------------------------------------------------------- |
+| `children` | `ReactNode[]` | No       | Two children — `[0]` → wide (left), `[1]` → narrow (right) |
+| `a`        | `any`         | No       | Wide (left) column content                                 |
+| `b`        | `any`         | No       | Narrow (right) column content                              |
+| `title`    | `string`      | No       | Optional title (not rendered)                              |
+| `cols`     | `string`      | No       | Column template (not rendered)                             |
+| `icon`     | `string`      | No       | Icon name (not rendered)                                   |
 
 ### WideNarrowPage
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | Yes | Two children — `[0]` → wide slot, `[1]` → narrow slot |
-| `title` | `string` | Yes | Page title (passed to WideNarrow) |
-| `templateCol` | `string` | No | Column ratio (default `'1fr 1fr'`) |
-| `icon` | `string` | No | Icon name (strips `'pi pi-'` prefix) |
+| Prop          | Type          | Required | Description                                           |
+| ------------- | ------------- | -------- | ----------------------------------------------------- |
+| `children`    | `ReactNode[]` | Yes      | Two children — `[0]` → wide slot, `[1]` → narrow slot |
+| `title`       | `string`      | Yes      | Page title (passed to WideNarrow)                     |
+| `templateCol` | `string`      | No       | Column ratio (default `'1fr 1fr'`)                    |
+| `icon`        | `string`      | No       | Icon name (strips `'pi pi-'` prefix)                  |
 
 ### WideNarrowForm
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `children` | `ReactNode[]` | Yes | Two children rendered in wide/narrow slots |
+| Prop       | Type          | Required | Description                                |
+| ---------- | ------------- | -------- | ------------------------------------------ |
+| `children` | `ReactNode[]` | Yes      | Two children rendered in wide/narrow slots |
 
 ### WideNarrowDetails
 
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `label` | `string` | No | Section label for FieldGroup |
-| `showLabel` | `boolean` | No | Whether to show the label. Default `true` |
-| `showHighlightedData` | `boolean` | No | Whether to render highlighted data fields. Default `false` |
-| `getPConnect` | `function` | Yes | PConnect getter |
+| Prop                  | Type       | Required | Description                                                |
+| --------------------- | ---------- | -------- | ---------------------------------------------------------- |
+| `label`               | `string`   | No       | Section label for FieldGroup                               |
+| `showLabel`           | `boolean`  | No       | Whether to show the label. Default `true`                  |
+| `showHighlightedData` | `boolean`  | No       | Whether to render highlighted data fields. Default `false` |
+| `getPConnect`         | `function` | Yes      | PConnect getter                                            |
 
 ## Behavioral Contract
 
@@ -98,13 +98,14 @@ Derived from `WideNarrow.css`:
 
 ### Container
 
-| CSS Class | Property | Value |
-|-----------|----------|-------|
-| `.psdk-wide-narrow-column` | Display | two-column row layout |
-| `.psdk-wide-column-column` | Width | ~67% (2 of 3 parts) — LEFT column |
-| `.psdk-narrow-column-column` | Width | ~33% (1 of 3 parts) — RIGHT column |
+| CSS Class                    | Property | Value                              |
+| ---------------------------- | -------- | ---------------------------------- |
+| `.psdk-wide-narrow-column`   | Display  | two-column row layout              |
+| `.psdk-wide-column-column`   | Width    | ~67% (2 of 3 parts) — LEFT column  |
+| `.psdk-narrow-column-column` | Width    | ~33% (1 of 3 parts) — RIGHT column |
 
 **CSS-only implementation notes:**
+
 - `.psdk-wide-narrow-column`: `display: grid; grid-template-columns: 2fr 1fr; gap: 1rem`.
 - Wide column (left): `2fr` — takes the first grid column.
 - Narrow column (right): `1fr` — takes the second grid column.
@@ -112,12 +113,12 @@ Derived from `WideNarrow.css`:
 
 ### Key Difference from NarrowWide
 
-| | NarrowWide | WideNarrow |
-|---|---|---|
-| Left column | Narrow (~33%) | Wide (~67%) |
-| Right column | Wide (~67%) | Narrow (~33%) |
-| CSS container class | `.psdk-narrow-wide-column` | `.psdk-wide-narrow-column` |
-| `COLUMN_WIDTHS` (Details) | `[4, 8]` | `[8, 4]` |
+|                           | NarrowWide                 | WideNarrow                 |
+| ------------------------- | -------------------------- | -------------------------- |
+| Left column               | Narrow (~33%)              | Wide (~67%)                |
+| Right column              | Wide (~67%)                | Narrow (~33%)              |
+| CSS container class       | `.psdk-narrow-wide-column` | `.psdk-wide-narrow-column` |
+| `COLUMN_WIDTHS` (Details) | `[4, 8]`                   | `[8, 4]`                   |
 
 ## Edge Cases & Special Logic
 
@@ -136,15 +137,16 @@ Derived from `WideNarrow.css`:
 
 Listed design systems are examples only.
 
-| Design System | Recommended Component |
-|---|---|
-| Default (CSS only) | CSS Grid `grid-template-columns: 2fr 1fr; gap: 1rem` |
-| MUI | `<Grid container><Grid size={{ xs: 12, md: 8 }}><Grid size={{ xs: 12, md: 4 }}>` |
-| Ant Design | `<Row gutter={16}><Col xs={24} md={16}><Col xs={24} md={8}>` |
-| Chakra UI | `<Grid templateColumns={{ base: '1fr', md: '2fr 1fr' }} gap={4}>` |
-| Shadcn/ui | Tailwind `grid grid-cols-1 md:grid-cols-[2fr_1fr] gap-4` |
+| Design System      | Recommended Component                                                            |
+| ------------------ | -------------------------------------------------------------------------------- |
+| Default (CSS only) | CSS Grid `grid-template-columns: 2fr 1fr; gap: 1rem`                             |
+| MUI                | `<Grid container><Grid size={{ xs: 12, md: 8 }}><Grid size={{ xs: 12, md: 4 }}>` |
+| Ant Design         | `<Row gutter={16}><Col xs={24} md={16}><Col xs={24} md={8}>`                     |
+| Chakra UI          | `<Grid templateColumns={{ base: '1fr', md: '2fr 1fr' }} gap={4}>`                |
+| Shadcn/ui          | Tailwind `grid grid-cols-1 md:grid-cols-[2fr_1fr] gap-4`                         |
 
 When implementing in a specific design system:
+
 - Wide column ≈ 67% width (left side)
 - Narrow column ≈ 33% width (right side)
 - `WideNarrowDetails` forces DISPLAY_ONLY + readOnly on all children

package/templates/react-sdk-reference/.ai-common/skills/template-skills/WssNavBar.md

@@ -0,0 +1,210 @@
+# Skill: WssNavBar
+
+WSS (Web Self-Service) navigation bar template. Renders the app bar for WSS portal with responsive hamburger menu, navigation links, operator avatar, and logout.
+
+> **Prerequisite skill:** [`template-components.md`](../template-components.md) — covers architecture, child rendering patterns, and registration conventions common to ALL template components.
+
+---
+
+## Component Purpose
+
+Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive: shows a hamburger menu on mobile, full nav links on desktop. Navigation position and alignment are configurable. Includes operator avatar with initials and a logout action.
+
+## Pega Metadata
+
+- **Registration key:** `WssNavBar` (in `component-map.ts`)
+- **Category:** Navigation template — WSS portal
+- **Extends:** `PConnProps`
+
+## Props
+
+| Prop                | Type       | Required | Description                                           |
+| ------------------- | ---------- | -------- | ----------------------------------------------------- |
+| `links`             | `array`    | Yes      | Array of `{ label, url, id }` navigation link objects |
+| `navDisplayOptions` | `object`   | No       | `{ alignment: 'left'                                  | 'right' | 'center', position: 'inline' | 'below' }` |
+| `portalLogoUrl`     | `string`   | No       | URL for the portal logo image                         |
+| `operatorInfo`      | `object`   | No       | `{ displayName: string }` — for avatar initials       |
+| `getPConnect`       | `function` | Yes      | PConnect getter                                       |
+
+## Component Skeleton
+
+```typescript
+import { useState } from 'react';
+import { logout } from '@pega/auth/lib/sdk-auth-manager';
+import type { PConnProps } from '@pega/sdk-react';
+import './WssNavBar.css';
+
+interface WssNavBarProps extends PConnProps {
+  appInfo: any;
+  navLinks: any[];
+  operator: { currentUserInitials: string };
+  navDisplayOptions: { alignment: string; position: string };
+  portalName: string;
+  imageSrc: string;
+  fullImageSrc: string;
+  appName: any;
+}
+
+export default function WssNavBar(props: WssNavBarProps) {
+  const { appInfo, navLinks, operator, navDisplayOptions } = props;
+  const { alignment, position } = navDisplayOptions;
+
+  // 1. Menu state
+  const [anchorElNav, setAnchorElNav] = useState(null);  // hamburger menu
+  const [anchorElUser, setAnchorElUser] = useState(null); // user menu
+  const localizedVal = PCore.getLocaleUtils().getLocaleValue;
+
+  // 2. Nav links content (hidden on mobile, shown on desktop)
+  const navLinksContent = (
+    <Box sx={{ display: { xs: 'none', md: 'flex' }, justifyContent: alignment }}>
+      {navLinks.map(link => <Button key={link.text} onClick={link.onClick}>{link.text}</Button>)}
+    </Box>
+  );
+
+  // 3. Render: AppBar > Toolbar > (logo + hamburger(mobile) + navLinks(desktop) + avatar)
+  return (
+    <AppBar position="static">
+      <Toolbar>
+        {/* App logo + name */}
+        <Button onClick={appInfo.onClick}>
+          <img src={appInfo.imageSrc} />
+          <span>{appInfo.appName}</span>
+        </Button>
+
+        {/* Hamburger (mobile only) */}
+        <HamburgerButton sx={{ display: { xs: 'flex', md: 'none' } }}
+          onClick={e => setAnchorElNav(e.currentTarget)} />
+        <MobileMenu anchorEl={anchorElNav} open={Boolean(anchorElNav)}
+          onClose={() => setAnchorElNav(null)}>
+          {navLinks.map(link => <MenuItem key={link.text} onClick={link.onClick}>{link.text}</MenuItem>)}
+        </MobileMenu>
+
+        {/* Nav links inline (position === 'inline') */}
+        {position === 'inline' && navLinksContent}
+
+        {/* Operator avatar + logout menu */}
+        <Avatar onClick={e => setAnchorElUser(e.currentTarget)}>{operator.currentUserInitials}</Avatar>
+        <UserMenu anchorEl={anchorElUser} open={Boolean(anchorElUser)}
+          onClose={() => setAnchorElUser(null)}>
+          <MenuItem onClick={logout}>{localizedVal('Log off', 'AppShell')}</MenuItem>
+        </UserMenu>
+      </Toolbar>
+
+      {/* Nav links below (position === 'below') */}
+      {position === 'below' && navLinksContent}
+    </AppBar>
+  );
+}
+```
+
+## Behavioral Contract
+
+### Responsive Layout
+
+- **Mobile (xs breakpoint):** Hamburger menu button (`<MenuIcon>`) shown; nav links hidden.
+  - On click: opens a `<Drawer>` or dropdown menu with nav links.
+  - CSS: `display: { xs: 'flex', md: 'none' }` on hamburger; `display: { xs: 'none', md: 'flex' }` on nav links.
+- **Desktop (md+ breakpoint):** Nav links shown inline; hamburger hidden.
+
+### Navigation Position
+
+From `navDisplayOptions.position`:
+
+- `'inline'` — nav links appear in the same row as the logo.
+- `'below'` — nav links appear in a second row below the logo/title row.
+
+### Navigation Alignment
+
+From `navDisplayOptions.alignment`:
+
+- `'left'` — links flush left.
+- `'right'` — links pushed to the right (flex with `ml: 'auto'`).
+- `'center'` — links centered.
+
+### Operator Avatar
+
+- Extract initials from `operatorInfo.displayName`:
+  - Split by space, take first letter of first and last word.
+  - E.g. `"John Smith"` → `"JS"`.
+- Render as `<Avatar>{initials}</Avatar>`.
+- Clicking avatar opens a menu with a Logout option.
+
+### Logout
+
+- Import `logout` from `@pega/auth/lib/sdk-auth-manager`.
+- Call `logout()` when the Logout menu item is clicked.
+
+### Render Structure
+
+```
+<AppBar position='static'>
+  <Toolbar>
+    {/* Logo */}
+    {portalLogoUrl && <img src={portalLogoUrl} alt='logo' />}
+
+    {/* Hamburger (mobile) */}
+    <IconButton sx={{ display: { xs: 'flex', md: 'none' } }} onClick={openMobileMenu}>
+      <MenuIcon />
+    </IconButton>
+
+    {/* Nav links (desktop) */}
+    <Box sx={{ display: { xs: 'none', md: 'flex' }, ...alignmentStyles }}>
+      {links.map(link => <Button key={link.id} href={link.url}>{link.label}</Button>)}
+    </Box>
+
+    {/* Operator avatar */}
+    <Avatar onClick={openUserMenu}>{initials}</Avatar>
+  </Toolbar>
+</AppBar>
+```
+
+## Visual Specifications
+
+| Element   | Mobile                  | Desktop               |
+| --------- | ----------------------- | --------------------- |
+| Logo      | Shown                   | Shown                 |
+| Nav links | Hidden (hamburger menu) | Shown inline or below |
+| Avatar    | Shown                   | Shown                 |
+| Hamburger | Shown                   | Hidden                |
+
+**CSS-only implementation notes:**
+
+- App bar: `background: var(--app-primary-color); color: white`.
+- Toolbar: `display: flex; align-items: center; gap: 1rem; padding: 0 1rem`.
+- Hamburger: `display: none`. At mobile breakpoint: `display: flex`.
+- Nav links: `display: flex; gap: 0.5rem`. At mobile breakpoint: `display: none`.
+- Avatar: `width: 36px; height: 36px; border-radius: 50%; background: var(--avatar-bg); cursor: pointer`.
+- Logout menu: `position: absolute; top: 100%; right: 0; background: white; box-shadow: 0 2px 8px rgba(0,0,0,0.2)`.
+
+## Edge Cases & Special Logic
+
+- `portalLogoUrl` is async — show fallback text until resolved.
+- `operatorInfo.displayName` may be undefined — guard and show a default avatar (single letter or icon).
+- `navDisplayOptions` may be absent — default to `{ alignment: 'left', position: 'inline' }`.
+- Mobile drawer state must be managed separately from the user menu state.
+
+## Dependencies
+
+- `logout` from `@pega/auth/lib/sdk-auth-manager` — logout handler
+- MUI: `<AppBar>`, `<Toolbar>`, `<IconButton>`, `<Avatar>`, `<Menu>`, `<MenuItem>`, `<Button>`, `<Box>`
+- MUI Icons: `<MenuIcon>`
+
+## Design System Mapping
+
+**UI control type:** Responsive application navigation bar with avatar and logout.
+
+Listed design systems are examples only.
+
+| Design System      | App Bar                  | Avatar                 | Mobile Menu              |
+| ------------------ | ------------------------ | ---------------------- | ------------------------ |
+| Default (CSS only) | `<header>` + CSS         | `<div class='avatar'>` | CSS hamburger + dropdown |
+| MUI                | `<AppBar>` + `<Toolbar>` | `<Avatar>`             | `<Drawer>` or `<Menu>`   |
+| Ant Design         | `<Layout.Header>`        | `<Avatar>`             | `<Drawer>`               |
+| Chakra UI          | `<Box as='header'>`      | `<Avatar>`             | `<Drawer>`               |
+| Shadcn/ui          | Custom `<header>`        | Custom initials avatar | `<Sheet>` (drawer)       |
+
+When implementing in a specific design system:
+
+- `logout` from `@pega/auth/lib/sdk-auth-manager` is mandatory — always call the SDK logout, not a custom one
+- Responsive breakpoints for hamburger/nav visibility must be implemented
+- `navDisplayOptions.alignment` and `.position` must be respected

package/templates/react-sdk-reference/{.cursor/rules/skills/widget-components.mdrules → .ai-common/skills/widget-components.md}

@@ -1,8 +1,3 @@
----
-description: widget-components
-alwaysApply: false
----
-
 # Skill: Widget Components
 
 Create or replace widget components in the react-sdk-reference application. Widgets are self-contained UI blocks that fetch their own data from Pega APIs (data pages, case info) and render interactive features (ToDo lists, attachments, case history, etc.).
@@ -123,11 +118,12 @@ export default function MyWidget(props: MyWidgetProps) {
 
 The PCore data-fetching logic (all `PCore.*` calls) is always identical regardless of design system. Only the `// [DS RENDER]` section changes.
 
-**1. Check the component-specific skill file** — `.cursor/rules/skills/widget-skills/<ComponentName>.mdrules` contains a **Design System Mapping** table where available. Use it as a starting point.
+**1. Check the component-specific skill file** — `{{SKILL_DIR}}/widget-skills/<ComponentName>.md` contains a **Design System Mapping** table where available. Use it as a starting point.
 
 **2. If the chosen design system is not listed** — use the component purpose description to identify the appropriate DS primitives (card, list, table, button, badge, etc.).
 
 **3. Discover the API from installed packages** — confirm component names and props from `.d.ts` before writing JSX:
+
 ```bash
 find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Card\|List\|Table" | head -5
 grep -A 30 "interface.*Props" <path-to-file>
@@ -135,14 +131,14 @@ grep -A 30 "interface.*Props" <path-to-file>
 
 **4. Common widget UI primitive mapping:**
 
-| Widget pattern | Typical DS equivalent |
-|---|---|
-| Container with title | `Card` + header/title prop, or `Panel`, `Box` |
-| Item list | `List`, `UnorderedList`, or `Table` rows |
-| Loading indicator | `Spinner`, `Skeleton`, `Loading` |
-| Action button | `Button` with `onClick` |
-| Status badge | `Badge`, `Tag`, `Chip` |
-| Empty state | DS empty/placeholder component or plain `<div>` |
+| Widget pattern       | Typical DS equivalent                           |
+| -------------------- | ----------------------------------------------- |
+| Container with title | `Card` + header/title prop, or `Panel`, `Box`   |
+| Item list            | `List`, `UnorderedList`, or `Table` rows        |
+| Loading indicator    | `Spinner`, `Skeleton`, `Loading`                |
+| Action button        | `Button` with `onClick`                         |
+| Status badge         | `Badge`, `Tag`, `Chip`                          |
+| Empty state          | DS empty/placeholder component or plain `<div>` |
 
 **5. Icons** — if the DS has a companion icon package, read its exports before using any icon name. Never guess icon names.
 
@@ -172,14 +168,7 @@ function createCase(caseType) {
 
 ```typescript
 // Fetch list data
-PCore.getDataPageUtils().getDataAsync(
-  dataPageName,
-  context,
-  params,
-  paging,
-  query,
-  options,
-);
+PCore.getDataPageUtils().getDataAsync(dataPageName, context, params, paging, query, options);
 
 // Get page data (single record)
 PCore.getDataPageUtils().getPageDataAsync(dataPageName, context, params);
@@ -198,12 +187,7 @@ const caseName = pConn.getCaseInfo().getName();
 
 ```typescript
 PCore.getAttachmentUtils().prepareAttachmentData(value);
-PCore.getAttachmentUtils().uploadAttachment(
-  file,
-  onProgress,
-  errorHandler,
-  context,
-);
+PCore.getAttachmentUtils().uploadAttachment(file, onProgress, errorHandler, context);
 PCore.getAttachmentUtils().downloadAttachment(attachmentID, context);
 ```