@pega/sdk 0.0.2 → 0.0.3

package/templates/react-sdk-reference/.github/prompts/generate-template-components.prompt.md

@@ -0,0 +1,156 @@
+---
+agent: agent
+description: Generate all (or a subset of) template components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where template components should be generated (e.g. `src/components/template/`)
+- **Component list** — which templates to generate (default: all 32 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+
+Example questions (ask only the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the template components be generated? (e.g. `src/components/template/`)
+
+> **Note:** The design system applies only to **layout templates** (TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants). Form templates and page templates use the PConnect bridge pattern and are design-system agnostic — they will be generated without DS primitives regardless of your choice.
+
+If the user specified a subset (e.g., "just TwoColumn and OneColumn"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 32 templates)
+
+| Component | Category |
+|---|---|
+| AdvancedSearch | Page |
+| AppShell | Page |
+| BannerPage | Page |
+| CaseSummary | Page |
+| CaseView | Page |
+| CaseViewActionsMenu | Widget |
+| Confirmation | Page |
+| DataReference | Form |
+| DefaultForm | Form |
+| DefaultPage | Page |
+| Details | Layout |
+| DetailsSubTabs | Layout |
+| DetailsThreeColumn | Layout |
+| DetailsTwoColumn | Layout |
+| DynamicTabs | Navigation |
+| FieldGroupTemplate | Form |
+| HierarchicalForm | Form |
+| InlineDashboard | Page |
+| InlineDashboardPage | Page |
+| ListPage | Page |
+| ListView | Page |
+| MultiReferenceReadOnly | Display |
+| NarrowWide | Layout |
+| OneColumn | Layout |
+| PromotedFilters | Widget |
+| SelfServiceCaseView | Page |
+| SimpleTable | Table |
+| SingleReferenceReadOnly | Display |
+| SubTabs | Navigation |
+| TwoColumn | Layout |
+| WideNarrow | Layout |
+| WssNavBar | Navigation |
+
+---
+
+## Step 1 — Read `template-components.md` (once, for the entire session)
+
+Read the full contents of `.github/skills/template-components.md`.
+
+This gives you:
+- **Layout template pattern** — DS-agnostic grid skeleton with `// [DS GRID]` placeholder; `templateCol` parsing logic; responsive behavior rules
+- **Design System Adaptation section** — how to map the chosen DS's grid/flex primitive to the computed column ratios
+- **Form template pattern** — PConnect bridge via `createElement(createPConnectComponent(), ...)` and `connectToState`; no DS involved
+- **Page template pattern** — region extraction via `getRawMetadata()` and PConnect bridge; no DS involved
+- Registration conventions and helper utilities
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Read the DS README from `node_modules`
+- Discover exported layout components (Grid, Columns, Flex, SimpleGrid, etc.) from `dist/index.d.ts`
+- Read prop interfaces for the grid/layout components needed by layout templates
+- Note responsive breakpoint APIs and column sizing conventions
+
+> You only need layout-related DS components. Form and page templates do not use the DS.
+
+Build a **DS layout API reference** from this discovery. Reuse it for every layout template — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+> "The following N components already exist: [list]. How should I proceed?
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file
+Execute **Step 2** from `.github/prompts/add-component.prompt.md` for this component:
+- Read `.github/skills/template-skills/<ComponentName>.md` fully
+- Identify the template category from the skill file:
+  - **Layout** — uses DS grid primitives from Step 2's API reference
+  - **Form** — uses PConnect bridge + CSS classes; ignore DS
+  - **Page** — uses region extraction + PConnect bridge; ignore DS
+- Pay attention to Behavioral Contract, sub-variants, and any Design System Mapping table
+
+### 4b — Generate the component files
+Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
+- Create `<outputPath>/<ComponentName>/` directory
+- Create `<ComponentName>.tsx` using:
+  - **Layout templates**: DS-agnostic skeleton from `template-components.md` with the `// [DS GRID]` section filled in using DS layout API confirmed in Step 2
+  - **Form/Page templates**: PConnect bridge pattern from `template-components.md`; no DS primitives
+  - Behavioral Contract from the component skill file
+- Create `index.tsx` if required by the skill file:
+  ```typescript
+  export { default } from './<ComponentName>';
+  ```
+- Create any CSS file required by the skill file (e.g., `DefaultForm.css` with grid classes)
+
+### 4c — Register the component
+Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
+- Add the import to `src/components/component-map.ts` in the Templates section
+- Add the entry to `getSampleComponentMap()` under the templates comment
+- For sub-variants (e.g., TwoColumnPage, TwoColumnTab), register each key separately pointing to its own file or a shared implementation as specified in the skill file
+- Do not reorder or restructure any existing entries
+
+### 4d — Report progress
+After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template`<, using <DS component name> for grid>` if layout"
+
+---
+
+## Step 5 — Verify the build
+
+Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a summary: list of all files created and all entries added to `component-map.ts`

package/templates/react-sdk-reference/.github/prompts/generate-widget-components.prompt.md

@@ -0,0 +1,129 @@
+---
+agent: agent
+description: Generate all (or a subset of) widget components using any design system
+---
+
+## Step 0 — Resolve inputs
+
+Read the user's message carefully. Extract:
+
+- **Design system** — the UI library to use (e.g. `Ant Design`, `Chakra UI`, `Carbon`, `Radix UI`)
+- **Output base path** — the folder where widget components should be generated (e.g. `src/components/widget/`)
+- **Component list** — which widgets to generate (default: all 9 listed below)
+
+Both **design system** and **output base path** are required. If either is missing or ambiguous, ask both unresolved items in one numbered list. Do not assume or default the output path — the client's folder structure may differ from the reference app.
+
+Example questions (ask only the ones that are actually missing):
+1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
+2. Where should the widget components be generated? (e.g. `src/components/widget/`)
+
+If the user specified a subset (e.g., "just ToDo and Attachment"), restrict the list accordingly.
+
+Once both are known, continue to Step 1.
+
+### Full component list (default — 9 widgets)
+
+| Component | Description |
+|---|---|
+| AppAnnouncement | System-wide announcements |
+| Attachment | File upload/download |
+| CaseHistory | Case audit trail |
+| FileUtility | File management utility |
+| Followers | Case followers list |
+| QuickCreate | Quick case creation buttons |
+| SummaryItem | Single summary card |
+| SummaryList | List of summary cards |
+| ToDo | Assignment worklist |
+
+---
+
+## Step 1 — Read `widget-components.md` (once, for the entire session)
+
+Read the full contents of `.github/skills/widget-components.md`.
+
+This gives you:
+- The DS-agnostic data-fetching skeleton with `// [DS RENDER]` placeholder
+- The Design System Adaptation guide (primitive mapping table, icon discovery rules)
+- All common Pega APIs used in widgets: `PCore.getDataPageUtils()`, `PCore.getMashupApi()`, `PCore.getAttachmentUtils()`, `pConn.getCaseInfo()`, etc.
+- Registration conventions
+
+> The PCore data-fetching logic is always identical regardless of design system. Only the `// [DS RENDER]` section changes per DS.
+
+Keep this context active throughout the entire generation session. Do not re-read it per component.
+
+---
+
+## Step 2 — Install and discover the design system (once)
+
+Execute **Step 3** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Check `package.json` for the DS package
+- Install if missing, including any peer dependencies
+- Report what was installed
+
+Then execute **Step 4** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Read the DS README from `node_modules`
+- Discover exported components from `dist/index.d.ts`
+- Focus on presentation primitives used in widgets: Card, List, Table, Button, Badge, Spinner, Skeleton, Empty state
+- Read prop interfaces for these components from `.d.ts` files
+- If the DS has a companion icon package, discover its exports
+
+Build a **DS UI primitive reference map** from this discovery. Reuse it for every widget — do not repeat these commands per component.
+
+---
+
+## Step 3 — Overwrite check (all at once)
+
+For each component in the list, check whether `<outputPath>/<ComponentName>/<ComponentName>.tsx` already exists.
+
+If **any** exist, report them all at once and ask:
+> "The following N components already exist: [list]. How should I proceed?
+> - **Overwrite all** — replace all existing implementations
+> - **Skip existing** — only generate components that don't exist yet
+> - **Cancel** — stop without generating anything"
+
+Wait for the user's answer before proceeding. If none exist, continue immediately.
+
+---
+
+## Step 4 — Generate each component (loop)
+
+For each component in the resolved list (in the order listed in Step 0):
+
+### 4a — Read the component-specific skill file
+Execute **Step 2** from `.github/prompts/add-component.prompt.md` for this component:
+- Read `.github/skills/widget-skills/<ComponentName>.md` fully if it exists
+- Pay attention to:
+  - **Behavioral Contract** — data fetching logic, PCore API calls, state management, action handlers
+  - **Design System Mapping** table — the recommended DS component for presentation
+- If no skill file exists (e.g., `SummaryList`), use the general data-fetching pattern from `widget-components.md`
+
+### 4b — Generate the component files
+Execute **Step 5** from `.github/prompts/add-component.prompt.md` for this component:
+- Create `<outputPath>/<ComponentName>/` directory
+- Create `<ComponentName>.tsx` using:
+  - The DS-agnostic data-fetching skeleton from `widget-components.md` (read in Step 1)
+  - The Behavioral Contract from the component skill file (PCore API calls, state, actions)
+  - The DS UI primitives confirmed in Step 2 (from the DS primitive reference map — no new terminal commands needed) filling in the `// [DS RENDER]` section
+- Create `index.tsx` if required by the skill file:
+  ```typescript
+  export { default } from './<ComponentName>';
+  ```
+- Create any CSS or utility files required by the skill file
+
+### 4c — Register the component
+Execute **Step 6** from `.github/prompts/add-component.prompt.md` for this component:
+- Add the import to `src/components/component-map.ts` in the Widgets section
+- Add the entry to `getSampleComponentMap()` under the widgets comment
+- Do not reorder or restructure any existing entries
+
+### 4d — Report progress
+After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
+
+---
+
+## Step 5 — Verify the build
+
+Execute **Step 7** from `.github/prompts/add-component.prompt.md` exactly as written:
+- Run `npm run build`
+- Fix any TypeScript or build errors before reporting completion
+- Report a summary: list of all files created and all entries added to `component-map.ts`

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

@@ -61,9 +61,12 @@ interface RichTextEditorProps extends PConnFieldProps {
 
 Used for: AlertBanner, Banner, Operator
 
+This pattern is design-system agnostic. The variant-mapping logic and message normalisation are always the same. The `// [DS RENDER]` section must be replaced with your design system's alert/notification primitive — see "Design System Adaptation" below.
+
 ```typescript
-import Alert from '@mui/material/Alert';
-import AlertTitle from '@mui/material/AlertTitle';
+// Import your design system alert/notification component:
+// e.g. import { Alert } from 'antd';
+// e.g. import { Alert } from '@chakra-ui/react';
 
 interface AlertBannerProps {
   variant: 'urgent' | 'warning' | 'info' | 'success';
@@ -75,26 +78,31 @@ interface AlertBannerProps {
 export default function AlertBanner(props: AlertBannerProps) {
   const { variant, heading, messages = [], onClose } = props;
 
-  // Map Pega variant names to MUI severity
-  const severityMap: Record<string, 'error' | 'warning' | 'info' | 'success'> = {
+  // Map Pega variant names to your DS equivalent
+  // e.g. MUI: urgent → 'error' | Ant Design: urgent → 'error' | Chakra: urgent → 'error'
+  const variantMap: Record<string, string> = {
     urgent: 'error',
     warning: 'warning',
     info: 'info',
     success: 'success'
   };
 
+  // Normalise messages — Pega may send a plain string or an object
   function renderMessage(msg: string | { label?: string; description?: string }) {
     if (typeof msg === 'string') return msg;
     return `${msg.label ?? ''} ${msg.description ?? ''}`.trim();
   }
 
+  // [DS RENDER] — replace with your design system's alert/notification primitive
+  // The variantMap value above should be passed as the DS severity/type/status prop
   return (
-    <Alert severity={severityMap[variant] ?? 'info'} onClose={onClose}>
-      {heading && <AlertTitle>{heading}</AlertTitle>}
-      {messages.map((msg, i) => (
-        <div key={i}>{renderMessage(msg)}</div>
-      ))}
-    </Alert>
+    <YourDesignSystemAlert
+      type={variantMap[variant] ?? 'info'}
+      message={heading}
+      description={messages.map(renderMessage).join(' ')}
+      closable={!!onClose}
+      onClose={onClose}
+    />
   );
 }
 ```
@@ -167,9 +175,9 @@ export default function FieldGroup(props: FieldGroupProps) {
 
 ## Styling Patterns
 
-DSE components use either CSS files or MUI's `sx` prop:
+DSE components use one of three approaches depending on the component and design system:
 
-### CSS File Pattern
+### CSS File Pattern (DS-agnostic, preferred for Field Value components)
 
 ```css
 /* FieldValueList.css */
@@ -190,15 +198,47 @@ DSE components use either CSS files or MUI's `sx` prop:
 }
 ```
 
-### MUI sx Prop Pattern
+### Design System Style Props (use if your DS provides them)
 
-```typescript
-<Box sx={{ display: 'flex', gap: 1, alignItems: 'center' }}>
-  <Typography variant='body2' color='text.secondary'>{name}</Typography>
-  <Typography variant='body1'>{value}</Typography>
-</Box>
+If the chosen design system provides built-in spacing, typography, or layout props, prefer them over plain CSS:
+- Use the DS's layout wrapper (e.g., `<Stack>`, `<Flex>`, `<HStack>`) instead of manual flex CSS
+- Use DS typography components (e.g., `<Text>`, `<Heading>`) instead of raw `<span>`/`<div>`
+- Use DS CSS custom properties or tokens for spacing — never hardcode `px` values
+- Discover which style props are available from the installed `.d.ts` files 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** — `.github/skills/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 props from `.d.ts` before writing JSX:
+```bash
+find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Alert\|Badge\|Avatar" | head -5
+grep -A 30 "interface.*Props" <path-to-file>
 ```
 
+**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

package/templates/react-sdk-reference/.github/skills/field-components.md

@@ -59,18 +59,22 @@ interface MyFieldProps extends PConnFieldProps {
 
 ## Implementation Pattern
 
-### Minimal Field Component Template
+### Abstract Field Component Template
+
+This template is design-system agnostic. It defines the **behavioral skeleton** every field component must follow. Replace the `// [DS RENDER]` section with your design system's input primitive — see the "Design System Adaptation" section below for guidance.
 
 ```typescript
 import { useState, useEffect } from 'react';
-import { TextField } from '@mui/material';  // or your design system
+// Import your design system component here:
+// e.g. import { Input } from 'antd';
+// e.g. import { Input } from '@chakra-ui/react';
 
 import handleEvent from '../../helpers/event-utils';
 import { getComponentFromRegistry } from '@pega/sdk-react';
-import type { PConnFieldProps } from '../../../types/PConnProps';
+import type { PConnFieldProps } from '@pega/sdk-react';
 
 interface MyFieldProps extends PConnFieldProps {
-  // Component-specific props
+  // Add component-specific props here
 }
 
 export default function MyField(props: MyFieldProps) {
@@ -97,13 +101,15 @@ export default function MyField(props: MyFieldProps) {
   const propName = (pConn.getStateProps() as any).value;
   const helperTextToDisplay = validatemessage || helperText;
 
+  // 1. Track input value locally — do NOT commit on every keystroke
   const [inputValue, setInputValue] = useState(value);
 
+  // 2. Sync local state when the store value changes
   useEffect(() => {
     setInputValue(value);
   }, [value]);
 
-  // --- Display modes (read-only rendering) ---
+  // 3. Display modes — must short-circuit before any interactive rendering
   if (displayMode === 'DISPLAY_ONLY') {
     return <FieldValueList name={hideLabel ? '' : label} value={value} />;
   }
@@ -112,33 +118,30 @@ export default function MyField(props: MyFieldProps) {
     return <FieldValueList name={hideLabel ? '' : label} value={value} variant='stacked' />;
   }
 
-  // --- Event handlers ---
-  function handleChange(event) {
-    setInputValue(event?.target?.value);
+  // 4. Event handlers
+  function handleChange(newValue: string) {
+    setInputValue(newValue); // update local state only
   }
 
   function handleBlur() {
-    handleEvent(actions, 'changeNblur', propName, inputValue);
+    handleEvent(actions, 'changeNblur', propName, inputValue); // commit to Pega store
   }
 
-  // --- Render ---
+  // 5. [DS RENDER] — replace with your design system's input primitive
+  // Refer to "Design System Adaptation" below for prop mapping guidance
   return (
-    <TextField
-      fullWidth
-      variant={readOnly ? 'standard' : 'outlined'}
-      helperText={helperTextToDisplay}
-      placeholder={placeholder ?? ''}
-      size='small'
-      required={required}
-      disabled={disabled}
+    <YourDesignSystemInput
+      value={inputValue}
       onChange={handleChange}
       onBlur={!readOnly ? handleBlur : undefined}
-      error={status === 'error'}
+      disabled={disabled}
+      readOnly={readOnly}
+      required={required}
+      placeholder={placeholder}
       label={label}
-      value={inputValue}
-      slotProps={{
-        input: { readOnly, inputProps: { 'data-test-id': testId } }
-      }}
+      helperText={helperTextToDisplay}
+      isInvalid={status === 'error'}
+      data-test-id={testId}
     />
   );
 }
@@ -146,6 +149,35 @@ export default function MyField(props: MyFieldProps) {
 
 ---
 
+## Design System Adaptation
+
+When filling in the `// [DS RENDER]` section with a specific design system:
+
+**1. Check the component-specific skill file** — `.github/skills/field-skills/<ComponentName>.md` contains a **Design System Mapping** table that lists the recommended DS component for common design systems. Use it as a starting point.
+
+**2. If the chosen design system is not in the mapping table** — use the **UI control type** field in the same skill file (e.g., `"Combobox / typeahead autocomplete input"`) to identify the closest DS primitive.
+
+**3. Discover the API from installed packages** — before writing any render JSX, confirm all prop names from `.d.ts` files. Never rely on training-knowledge of a DS API:
+```bash
+find node_modules/<ds-package> -name "ComponentName.d.ts" | head -3
+grep -A 40 "interface.*Props" <path-to-file>
+```
+
+**4. Prop mapping conventions** — adapt these Pega/SDK props to whatever your DS component calls them:
+
+| Pega/SDK prop | Meaning | Typical DS equivalent |
+|---|---|---|
+| `status === 'error'` | Validation error state | `error`, `status="error"`, `invalid`, `isInvalid` |
+| `validatemessage \|\| helperText` | Helper/error text below field | `helperText`, `description`, `hint`, `extra` |
+| `readOnly` | Non-editable, still visible | `readOnly`, `isReadOnly`, `variant="borderless"` |
+| `testId` | Automation selector | `data-test-id` on the underlying `<input>` element |
+| `required` | Required field marker | `required`, `isRequired` |
+| `hideLabel` | Suppress label display | Pass empty string `''` as label |
+
+**5. Use a form layout wrapper** — if the DS provides a wrapper that combines label + input + helper text (e.g., `<Form.Item>` in Ant Design, `<FormControl>` in Chakra UI), use it rather than composing them manually.
+
+---
+
 ## Event Handling
 
 Use `src/components/helpers/event-utils.ts` to commit values to the Pega store:

package/templates/react-sdk-reference/.github/skills/template-components.md

@@ -48,35 +48,72 @@ Templates typically receive children through `getPConnect().getChildren()` rathe
 
 Used for: TwoColumn, OneColumn, NarrowWide, WideNarrow
 
+This pattern is design-system agnostic. The `// [DS GRID]` section must be replaced with your design system's grid or flex layout primitive — see the "Design System Adaptation" section below.
+
 ```typescript
 import type { PropsWithChildren, ReactElement } from 'react';
-import Grid, { type GridSize } from '@mui/material/Grid';
-import type { PConnProps } from '../../../types/PConnProps';
+// Import your design system layout primitive here:
+// e.g. import { Grid } from 'antd';
+// e.g. import { SimpleGrid } from '@chakra-ui/react';
+import type { PConnProps } from '@pega/sdk-react';
 
 interface TwoColumnProps extends PConnProps {
-  templateCol?: string;  // e.g. "1fr 1fr", "2fr 1fr"
+  templateCol?: string; // e.g. '1fr 1fr', '2fr 1fr'
 }
 
 export default function TwoColumn(props: PropsWithChildren<TwoColumnProps>) {
   const { children, templateCol = '1fr 1fr' } = props;
   const childrenToRender = children as ReactElement[];
 
-  // Parse templateCol to calculate grid sizes
+  // Parse templateCol into column width ratios
+  // Strip unit suffixes, split on whitespace, convert to numbers
   const colArray = templateCol.replaceAll(/[a-z]+/g, '').split(/\s/).map(Number);
   const totalCols = colArray.reduce((v, itm) => itm + v, 0);
-  const ratio = 12 / totalCols;
-  const aSize = (ratio * colArray[0]) as GridSize;
-  const bSize = (ratio * colArray[1]) as GridSize;
+  // colArray[0] / totalCols = left column fraction
+  // colArray[1] / totalCols = right column fraction
 
+  // [DS GRID] — render two children in a responsive grid using the computed ratios
+  // On mobile (narrow viewport): both columns should stack to full width
+  // On desktop: apply the computed left/right ratio
   return (
-    <Grid container spacing={1}>
-      <Grid size={{ xs: 12, md: aSize }}>{childrenToRender[0]}</Grid>
-      <Grid size={{ xs: 12, md: bSize }}>{childrenToRender[1]}</Grid>
-    </Grid>
+    <YourDesignSystemGrid>
+      <YourDesignSystemColumn ratio={colArray[0] / totalCols}>
+        {childrenToRender[0]}
+      </YourDesignSystemColumn>
+      <YourDesignSystemColumn ratio={colArray[1] / totalCols}>
+        {childrenToRender[1]}
+      </YourDesignSystemColumn>
+    </YourDesignSystemGrid>
   );
 }
 ```
 
+---
+
+## Design System Adaptation (Layout Templates Only)
+
+> Form templates and page templates use the PConnect bridge pattern and do **not** use any design system primitives. This section applies only to layout templates: TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants.
+
+**1. Check the component-specific skill file** — `.github/skills/template-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 layout primitive (grid, flex, columns).
+
+**3. Discover the API from installed packages** — confirm layout component names and props from `.d.ts` before writing JSX:
+```bash
+find node_modules/<ds-package> -name "*.d.ts" | xargs grep -l "Grid\|Columns\|Flex" | head -5
+grep -A 30 "interface.*Props" <path-to-file>
+```
+
+**4. Column ratio mapping** — the `templateCol` prop (e.g., `'2fr 1fr'`) gives you fractional widths. Map to your DS's column system:
+
+| `templateCol` | Fraction | MUI 12-col | CSS `grid-template-columns` |
+|---|---|---|---|
+| `'1fr 1fr'` | 50% / 50% | 6 / 6 | `1fr 1fr` |
+| `'2fr 1fr'` | 67% / 33% | 8 / 4 | `2fr 1fr` |
+| `'1fr 2fr'` | 33% / 67% | 4 / 8 | `1fr 2fr` |
+
+**5. Responsive behavior** — on mobile, both columns must stack to full width. Use your DS's responsive breakpoint props or a CSS media query.
+
 ### Form Template (renders children via PConnect bridge)
 
 Used for: DefaultForm, HierarchicalForm