@pega/sdk 0.0.5 → 0.0.6

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

@@ -8,10 +8,10 @@ Two-column layout template that splits children into two responsive grid columns
 
 ## Component Purpose
 
-Renders two child components side by side in a responsive grid. Column widths are driven by the `templateCol` prop (e.g., `'1fr 1fr'`, `'2fr 1fr'`). On mobile (`xs`), both columns collapse to full width. Three closely related sub-variants share this same layout logic:
+Renders two child components side by side in a responsive grid. Column widths are driven by the `templateCol` input (e.g., `'1fr 1fr'`, `'2fr 1fr'`). On mobile, both columns collapse to full width. Three closely related sub-variants share this same layout logic:
 
 - **`TwoColumn`** — core layout, used inside forms and views
-- **`TwoColumnPage`** — thin wrapper that delegates to `TwoColumn` via the component registry
+- **`TwoColumnPage`** — thin wrapper that delegates to `TwoColumn` via the project's component registry
 - **`TwoColumnTab`** — identical layout implementation used inside tab contexts
 
 ## Pega Metadata
@@ -22,97 +22,54 @@ Renders two child components side by side in a responsive grid. Column widths ar
 | TwoColumnPage | `TwoColumnPage`  |
 | TwoColumnTab  | `TwoColumnTab`   |
 
-All three extend `PConnProps`. Children are received as React `children` (not via `getPConnect().getChildren()`).
+All three extend the project's base component interface. Children are received via the framework's content projection mechanism (not via `getPConnect().getChildren()`).
 
-## Component Skeletons
+## Implementation Structure
 
 ### 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; }
-```
+**Module Setup:** Define the input contract as an extension of the project's base component interface, adding an optional `templateCol` string field and accepting children.
 
-### TwoColumnPage
-
-```typescript
-const TwoColumn = getComponentFromRegistry('TwoColumn');
-return <TwoColumn {...props} />;
-```
-
-### TwoColumnTab
-
-Identical implementation to `TwoColumn` — same `templateCol` parsing, same grid output.
-
-## Props
+**Main Component Logic** — steps in order:
 
-| 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'` |
+1. Receive `children` and `templateCol` (default `'1fr 1fr'`) from inputs; treat `children` as an array of two child elements.
+2. If the child count isn't exactly 2, log a console error noting the actual count (still continue rendering).
+3. **Parse `templateCol` into 12-grid sizes:** strip unit suffixes (e.g., `'fr'`) via a regex replace (remove all lowercase letters), split on whitespace, and convert each token to a number, producing a column-values array; sum the array into `totalCols`; compute `ratio = 12 / totalCols`; derive `aSize = ratio * colArray[0]` and `bSize = ratio * colArray[1]` (both treated as grid column size values within a 12-column system).
+4. Render a grid container with spacing of 1 unit (≈ 8px) containing two grid items, each with full width at mobile breakpoint and the computed column size at medium+ breakpoint, both with a column-styles class: the first holds `children[0]`, the second holds `children[1]`.
 
-## Sub-Variants
+**Visual-only styling notes:** apply a column-styles class to each column with `display: grid; gap: 1rem; align-content: baseline`.
 
 ### TwoColumnPage
 
-Thin pass-through wrapper. Retrieves `TwoColumn` from the component registry and renders it with all props forwarded:
-
-```typescript
-const TwoColumn = getComponentFromRegistry('TwoColumn');
-return <TwoColumn {...props} />;
-```
+A thin pass-through wrapper: resolve `TwoColumn` from the project's component registry and render it forwarding all inputs.
 
 ### TwoColumnTab
 
-Identical implementation to `TwoColumn` — same grid layout, same `templateCol` parsing, same column styles. Registered separately under `TwoColumnTab` key to support tab context rendering.
+Identical implementation to `TwoColumn` — same `templateCol` parsing, same grid output. Registered separately under `TwoColumnTab` key to support tab context rendering.
+
+## Inputs
+
+| Name          | Type               | Required | Description                                                                    |
+| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------ |
+| `children`    | renderable content | Yes      | Exactly 2 children (left column, right column)                                 |
+| `templateCol` | `string`           | No       | Column width ratio string, e.g., `'1fr 1fr'`, `'2fr 1fr'`. Default `'1fr 1fr'` |
 
 ## Behavioral Contract
 
 1. Accept exactly 2 children. If a different count is received, log an error (console only — still render).
-2. Parse `templateCol` to compute MUI Grid column sizes:
-   - Strip unit suffixes (e.g., `'fr'`) from each token using regex: `.replaceAll(/[a-z]+/g, '')`.
+2. Parse `templateCol` to compute grid column sizes within a 12-column system:
+   - Strip unit suffixes (e.g., `'fr'`) from each token using regex (remove lowercase letters).
    - Split on whitespace and convert to numbers.
    - Compute `totalCols = sum(colArray)`.
    - Compute `ratio = 12 / totalCols`.
-   - `aSize = ratio * colArray[0]`, `bSize = ratio * colArray[1]` (both clamped to MUI's 1–12 GridSize range).
-3. Render a Grid container with `spacing={1}`.
-4. Render `children[0]` in the left column at `size={{ xs: 12, md: aSize }}`.
-5. Render `children[1]` in the right column at `size={{ xs: 12, md: bSize }}`.
-6. Apply `colStyles` class to each column: `display: grid; gap: 1rem; alignContent: baseline`.
+   - `aSize = ratio * colArray[0]`, `bSize = ratio * colArray[1]`.
+3. Render a grid container with spacing of 1 unit (≈ 8px).
+4. Render `children[0]` in the left column at full width on mobile, `aSize` on medium+ breakpoint.
+5. Render `children[1]` in the right column at full width on mobile, `bSize` on medium+ breakpoint.
+6. Apply column-styles to each column: `display: grid; gap: 1rem; align-content: baseline`.
 
 ## Visual Specifications
 
-Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
-
 ### Column Style
 
 | Property      | Value                                 |
@@ -129,10 +86,10 @@ Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
 
 ### 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                  |
+| ---------- | ---------- | ------------------------- |
+| Mobile     | full width | full width (stacks below) |
+| Medium+    | `aSize`/12 | `bSize`/12                |
 
 **Column ratio examples:**
 
@@ -145,7 +102,7 @@ Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
 
 **CSS-only implementation notes:**
 
-- Column container: `display: grid; gap: 1rem; align-content: start`.
+- Column container: `display: grid; gap: 1rem; align-content: baseline`.
 - Outer grid: `display: grid; grid-template-columns: <aFraction>fr <bFraction>fr; gap: 8px`.
 - Mobile: `grid-template-columns: 1fr` (single column stack).
 - Each column has `display: grid; gap: 1rem; align-content: baseline` for internal stacking.
@@ -154,29 +111,23 @@ Derived from `TwoColumn.tsx` and `TwoColumnTab.tsx` makeStyles:
 
 - Default `templateCol` is `'1fr 1fr'` (equal split) when not provided.
 - The `templateCol` parsing is regex-based — any non-numeric suffix is stripped. If only numbers are provided (e.g., `'6 6'`), it still works.
-- `TwoColumnPage` uses `getComponentFromRegistry('TwoColumn')` — if the registry returns an override, that override is used instead of the default `TwoColumn` implementation.
+- `TwoColumnPage` uses the project's component registry to resolve `TwoColumn` — if an override exists, that override is used instead.
 
 ## Dependencies
 
-- `TwoColumnPage`: `getComponentFromRegistry` from `@pega/sdk-react` — to resolve the `TwoColumn` component at runtime
-- `TwoColumn` / `TwoColumnTab`: no special dependencies beyond layout
+- `TwoColumnPage`: the project's component registry — to resolve the `TwoColumn` component at runtime.
+- `TwoColumn` / `TwoColumnTab`: no special dependencies beyond layout.
 
 ## Design System Mapping
 
 **UI control type:** Responsive two-column grid layout.
 
-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`         |
+When implementing in a specific design system, map the following:
 
-When implementing in a specific design system:
+- **Grid container** → use the DS's grid/layout system with configurable column spans
+- **Column sizing** → parse `templateCol` using the ratio algorithm (strip units, divide 12 by total) to compute column sizes
+- **Responsive behavior** → full width on mobile, computed ratio on medium+ breakpoint
+- **Column style** → apply `display: grid; gap: 1rem; align-content: baseline` so children within each column stack top-aligned
+- **TwoColumnPage** → resolve via the project's component registry and delegate
 
-- 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/.ai-common/skills/template-skills/WideNarrow.md

@@ -10,8 +10,8 @@ Asymmetric two-column layout with a wide left column (~67%) and a narrow right c
 
 Renders two children side by side with the left column wider than the right. Typically used when the main content occupies the left and a utility/sidebar panel sits on the right. Four sub-variants:
 
-- **`WideNarrow`** — core CSS-based layout, accepts either `a`/`b` slot props or React `children[0]`/`children[1]`
-- **`WideNarrowPage`** — wrapper that passes React children as `a` and `b` slot props to `WideNarrow`
+- **`WideNarrow`** — core CSS-based layout, accepts either `a`/`b` slot inputs or `children[0]`/`children[1]`
+- **`WideNarrowPage`** — wrapper that passes children as `a` and `b` slot inputs to `WideNarrow`
 - **`WideNarrowForm`** — simplified wrapper using only `children`
 - **`WideNarrowDetails`** — details read-only variant; sets children to DISPLAY_ONLY mode and supports highlighted data
 
@@ -26,39 +26,39 @@ Renders two children side by side with the left column wider than the right. Typ
 | WideNarrowForm    | `WideNarrowForm`    |
 | WideNarrowDetails | `WideNarrowDetails` |
 
-All extend `PConnProps`.
+All extend the project's base component interface.
 
-## Props
+## Inputs
 
 ### 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)                                   |
+| Name       | Type               | Required | Description                                                |
+| ---------- | ------------------ | -------- | ---------------------------------------------------------- |
+| `children` | renderable content | 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)                  |
+| Name          | Type               | Required | Description                                           |
+| ------------- | ------------------ | -------- | ----------------------------------------------------- |
+| `children`    | renderable content | 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 |
+| Name       | Type               | Required | Description                                |
+| ---------- | ------------------ | -------- | ------------------------------------------ |
+| `children` | renderable content | Yes      | Two children rendered in wide/narrow slots |
 
 ### WideNarrowDetails
 
-| Prop                  | Type       | Required | Description                                                |
+| Name                  | Type       | Required | Description                                                |
 | --------------------- | ---------- | -------- | ---------------------------------------------------------- |
 | `label`               | `string`   | No       | Section label for FieldGroup                               |
 | `showLabel`           | `boolean`  | No       | Whether to show the label. Default `true`                  |
@@ -75,9 +75,9 @@ All extend `PConnProps`.
 
 ### WideNarrowPage
 
-1. Extract `childArray = Children.toArray(children)`.
-2. Retrieve `WideNarrow` from the component registry.
-3. Render `<WideNarrow a={childArray[0]} b={childArray[1]} title={title} cols={templateCol} icon={icon?.replace('pi pi-', '')} />`.
+1. Extract the children array from the content projection.
+2. Resolve `WideNarrow` from the project's component registry.
+3. Render `WideNarrow` with `a` set to `children[0]`, `b` set to `children[1]`, `title`, `cols` set to `templateCol`, and `icon` with the `'pi pi-'` prefix stripped.
 
 ### WideNarrowForm
 
@@ -86,7 +86,7 @@ All extend `PConnProps`.
 ### WideNarrowDetails
 
 1. Set `getPConnect().setInheritedProp('displayMode', 'DISPLAY_ONLY')` and `setInheritedProp('readOnly', true)`.
-2. Map `getPConnect().getChildren()` → `createElement(PConnectComponent, { ...configObject, key: index })`.
+2. Map `getPConnect().getChildren()` → render each child using the project's PConnect bridge utility with the config object and a unique key.
 3. If `showHighlightedData` is true, read `getRawMetadata().config.highlightedData`, set each field's `displayMode = 'STACKED_LARGE_VAL'`, mark `pyStatusWork` as `displayAsStatus=true`, and create components via `getPConnect().createComponent(field, '', 0, {})`.
 4. Wrap in `<FieldGroup name={theName}>` using `propsToUse.showLabel && propsToUse.label`.
 5. Layout: highlighted data in `Grid size={{ xs: COLUMN_WIDTHS[i] }}` where **`COLUMN_WIDTHS = [8, 4]`** (wide left, narrow right — reversed vs NarrowWideDetails).
@@ -123,30 +123,23 @@ Derived from `WideNarrow.css`:
 ## Edge Cases & Special Logic
 
 - `WideNarrowDetails` defaults `children` to empty (`= []`) — safe even if no children are provided.
-- Highlighted data guard: check `if (!theConfigObject) theConfigObject = {}` before creating PConnectComponent — prevents crash on null config objects.
+- Highlighted data guard: check `if (!theConfigObject) theConfigObject = {}` before creating the PConnect bridge component — prevents crash on null config objects.
 - Icon cleanup in `WideNarrowPage`: strip `'pi pi-'` from icon string before passing to `WideNarrow`.
 
 ## Dependencies
 
-- `WideNarrowPage`: `getComponentFromRegistry` from `@pega/sdk-react`
-- `WideNarrowDetails`: `getComponentFromRegistry('FieldGroup')`, `PConnectComponent` from `@pega/sdk-react`
+- `WideNarrowPage`: the project's component registry — to resolve `WideNarrow` at runtime.
+- `WideNarrowDetails`: the project's component registry (to resolve `FieldGroup`) and the project's PConnect bridge utility.
 
 ## Design System Mapping
 
 **UI control type:** Asymmetric two-column layout (main content + sidebar).
 
-Listed design systems are examples only.
+When implementing in a specific design system, map the following:
 
-| 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
+- **Two-column grid** → use the DS's grid with `2fr 1fr` column ratio (wide left, narrow right)
+- **Mobile** → collapse to single column (`1fr`), wide content on top
+- **WideNarrowDetails** → forces DISPLAY_ONLY + readOnly on children via inherited inputs
+- **WideNarrowPage** → resolve via the project's component registry and delegate
+- **Wide column** ≈ 67% width (left side)
+- **Narrow column** ≈ 33% width (right side)

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

@@ -12,13 +12,13 @@ Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive:
 
 ## Pega Metadata
 
-- **Registration key:** `WssNavBar` (in `component-map.ts`)
+- **Registration key:** `WssNavBar` (in the project's component map)
 - **Category:** Navigation template — WSS portal
-- **Extends:** `PConnProps`
+- **Extends:** the project's base component interface
 
-## Props
+## Inputs
 
-| Prop                | Type       | Required | Description                                           |
+| Input               | Type       | Required | Description                                           |
 | ------------------- | ---------- | -------- | ----------------------------------------------------- |
 | `links`             | `array`    | Yes      | Array of `{ label, url, id }` navigation link objects |
 | `navDisplayOptions` | `object`   | No       | `{ alignment: 'left'                                  | 'right' | 'center', position: 'inline' | 'below' }` |
@@ -26,85 +26,26 @@ Provides the top navigation bar for WSS (Web Self-Service) portals. Responsive:
 | `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>
-  );
-}
-```
+## Implementation Structure
+
+**Module Setup:** Use the project's base component interface for typing. Import the `logout` function from the SDK auth manager (`@pega/auth/lib/sdk-auth-manager`). Include a companion styles file for layout. Register the component under its key in the project's component map.
+
+**Main Component Logic** — steps in order:
+
+1. Receive inputs: `appInfo`, `navLinks`, `operator`, and `navDisplayOptions`; further destructure `alignment` and `position` from `navDisplayOptions`.
+2. Declare local state for menu anchoring: one for the mobile hamburger menu, one for the user/avatar menu (both initialized to `null`). Bind `localizedVal` to `PCore.getLocaleUtils().getLocaleValue`.
+3. Build a reusable `navLinksContent` element — a container hidden on mobile and shown as a flex row on desktop (justified per `alignment`), containing one button per nav link that invokes the link's `onClick`.
+4. Render an app bar with static position, containing a toolbar with, in order: the app logo/name button (invoking `appInfo.onClick`, showing `appInfo.imageSrc` and `appInfo.appName`); a hamburger icon button shown only on mobile that opens the mobile menu; a mobile dropdown menu (anchored to the hamburger state, open when set, closing by resetting to `null`) listing each nav link as a menu item; the `navLinksContent` block rendered inline when `position === 'inline'`; and an avatar showing `operator.currentUserInitials` that opens a user menu containing a "Log off" menu item (localized via `localizedVal('Log off', 'AppShell')`) wired to the imported `logout` function.
+5. When `position === 'below'`, render the `navLinksContent` block again below the toolbar, still inside the app bar.
 
 ## 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.
+- **Mobile (narrow viewport):** Hamburger menu button shown; nav links hidden.
+  - On click: opens a dropdown or drawer with nav links.
+  - CSS approach: hide nav links at narrow breakpoint, show hamburger; reverse at wide breakpoint.
+- **Desktop (wide viewport):** Nav links shown inline; hamburger hidden.
 
 ### Navigation Position
 
@@ -118,7 +59,7 @@ From `navDisplayOptions.position`:
 From `navDisplayOptions.alignment`:
 
 - `'left'` — links flush left.
-- `'right'` — links pushed to the right (flex with `ml: 'auto'`).
+- `'right'` — links pushed to the right (e.g., flex with auto-margin on left side).
 - `'center'` — links centered.
 
 ### Operator Avatar
@@ -126,7 +67,7 @@ From `navDisplayOptions.alignment`:
 - 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>`.
+- Render as a circular avatar element with initials text.
 - Clicking avatar opens a menu with a Logout option.
 
 ### Logout
@@ -136,27 +77,7 @@ From `navDisplayOptions.alignment`:
 
 ### 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>
-```
+An app bar (static position) containing a toolbar with, in order: the portal logo image (when `portalLogoUrl` is set); a hamburger icon button hidden on desktop that opens the mobile menu; a nav-links container hidden on mobile / shown on desktop applying the alignment styles, with one button per link (using `link.url` as the href and `link.label` as the text); and an avatar showing the operator initials that opens the user menu.
 
 ## Visual Specifications
 
@@ -181,29 +102,18 @@ From `navDisplayOptions.alignment`:
 - `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.
+- Mobile menu 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>`
+- The project's design system components for app bar, toolbar, icon button, avatar, menu, and button elements
 
 ## 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:
+When implementing, choose the design system's app bar, avatar, and mobile menu (drawer or dropdown) components that match the project's chosen library. All design systems must preserve:
 
 - `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