@pega/sdk 0.0.5 → 0.0.6

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

@@ -2,7 +2,7 @@
 
 Collapsible or static container that groups related fields under an optional section header and instructions text.
 
-> **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.
 
 ---
 
@@ -19,61 +19,45 @@ Children are rendered inside a full-width inner container.
 ## Pega Metadata
 
 - **Pega Name:** `FieldGroup`
-- **Registration key:** `FieldGroup` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives children via `PropsWithChildren`
-
-## Props
-
-| Prop           | Type        | Required | Description                                                             |
-| -------------- | ----------- | -------- | ----------------------------------------------------------------------- |
-| `children`     | `ReactNode` | No       | Field components to render inside the group                             |
-| `name`         | `string`    | No       | Section heading displayed above the fields                              |
-| `collapsible`  | `boolean`   | No       | If `true`, the header acts as a collapse/expand toggle. Default `false` |
-| `instructions` | `string`    | No       | HTML string of instruction text shown between header and fields         |
-
-## Component Skeleton
-
-```typescript
-import { type PropsWithChildren, useState } from 'react';
-
-interface FieldGroupProps {
-  name?: string;
-  collapsible?: boolean;
-  instructions?: string;
-}
-
-export default function FieldGroup(props: PropsWithChildren<FieldGroupProps>) {
-  const { children, name, collapsible = false, instructions } = props;
-  const [collapsed, setCollapsed] = useState(false);
-
-  return (
-    <OuterContainer spacing={4}>
-      <InnerFullWidth>
-        {/* Header */}
-        {name && (
-          <div className="field-margin">
-            {collapsible ? (
-              <span id="field-group-header" className="header-clickable"
-                style={{ cursor: 'pointer' }} onClick={() => setCollapsed(c => !c)}>
-                {collapsed ? <ArrowRightIcon /> : <ArrowDownIcon />}
-                <b>{name}</b>
-              </span>
-            ) : (
-              <b>{name}</b>
-            )}
-          </div>
-        )}
-        {/* Instructions (skip if === 'none') */}
-        {instructions && instructions !== 'none' && (
-          <div className="instruction-text" dangerouslySetInnerHTML={{ __html: instructions }} />
-        )}
-        {/* Children (hidden when collapsed) */}
-        {!collapsed && <div style={{ width: '100%' }}>{children}</div>}
-      </InnerFullWidth>
-    </OuterContainer>
-  );
-}
-```
+- **Registration key:** `FieldGroup` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives children via 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       | Field components to render inside the group                             |
+| `name`         | `string`           | No       | Section heading displayed above the fields                              |
+| `collapsible`  | `boolean`          | No       | If `true`, the header acts as a collapse/expand toggle. Default `false` |
+| `instructions` | `string`           | No       | HTML string of instruction text shown between header and fields         |
+
+## Implementation Structure
+
+### Module Setup
+
+The component accepts children via the framework's content projection mechanism. It maintains local state for the collapsed/expanded toggle. It does NOT import any Pega SDK modules.
+
+The component is named `FieldGroup` 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`, `name`, `collapsible` (defaults to `false`), and `instructions` as inputs. It maintains a `collapsed` boolean state initialized to `false` (expanded). The render tree is:
+
+1. **Outer container** — a Grid container with `spacing={4}` and `justifyContent: 'space-between'`.
+2. **Inner full-width wrapper** — a single Grid item at full width containing all content.
+3. **Header section** (conditional — only if `name` is provided):
+   - Wrapped in a div with margin/padding styling (top/bottom padding of 1 spacing unit, top margin of 1 spacing unit).
+   - **Non-collapsible** (`collapsible === false`): render `<b>{name}</b>` as static bold text.
+   - **Collapsible** (`collapsible === true`): render a clickable `<span>` with `id="field-group-header"`, flex layout (`display: flex; align-items: center; gap: 5px`), and `cursor: pointer`. Inside the span:
+     - A directional arrow icon: **right-pointing arrow** when `collapsed === true`, **down-pointing arrow** when `collapsed === false`.
+     - Bold name text: `<b>{name}</b>`.
+     - Clicking the span toggles `collapsed` state.
+4. **Instructions section** (conditional — only if `instructions` is provided AND is not the literal string `'none'`):
+   - Render a div with class `instruction-text` (padding: `5px 0`) using the framework's trusted HTML injection mechanism.
+5. **Children section** (conditional — only if `collapsed === false`):
+   - Render children inside a full-width container div (`width: 100%`) wrapped in a Grid container.
 
 ## Behavioral Contract
 
@@ -86,37 +70,37 @@ export default function FieldGroup(props: PropsWithChildren<FieldGroupProps>) {
      - A directional arrow icon: **right arrow** when `collapsed === true`, **down arrow** when `collapsed === false`.
      - The bold name text beside the arrow.
      - Clicking the span toggles `collapsed`.
-3. **Instructions:** If `instructions` is provided AND is not the string `'none'`, render it with `dangerouslySetInnerHTML={{ __html: instructions }}`.
+3. **Instructions:** If `instructions` is provided AND is not the string `'none'`, render it using the framework's trusted HTML injection mechanism.
 4. **Children:** Render children inside a full-width div. If `collapsed` is `true`, do NOT render children (or instructions).
 5. **Header cursor:** When `collapsible` is `true`, the header span uses `cursor: pointer`. When `collapsible` is `false`, cursor is `auto`.
 6. **Layout:** All content is wrapped in a `Grid container` with `spacing={4}` and `justifyContent='space-between'`. The name row and children are inside a single inner `Grid` at full width.
 
 ## Visual Specifications
 
-Derived from `FieldGroup.tsx` makeStyles:
+Derived from the component's companion styles:
 
 ### Outer Container
 
-| Property | Value                           |
-| -------- | ------------------------------- |
-| Spacing  | 4 units (≈ 32px in MUI default) |
+| Property | Value            |
+| -------- | ---------------- |
+| Spacing  | 4 units (≈ 32px) |
 
 ### Component Root Margins
 
-| Property      | Value                      |
-| ------------- | -------------------------- |
-| Margin right  | `theme.spacing(1)` (≈ 8px) |
-| Margin left   | `theme.spacing(1)`         |
-| Margin top    | `theme.spacing(1)`         |
-| Margin bottom | `theme.spacing(1)`         |
+| Property      | Value                  |
+| ------------- | ---------------------- |
+| Margin right  | 1 spacing unit (≈ 8px) |
+| Margin left   | 1 spacing unit         |
+| Margin top    | 1 spacing unit         |
+| Margin bottom | 1 spacing unit         |
 
 ### Field Margin (name row)
 
-| Property       | Value              |
-| -------------- | ------------------ |
-| Padding top    | `theme.spacing(1)` |
-| Padding bottom | `theme.spacing(1)` |
-| Margin top     | `theme.spacing(1)` |
+| Property       | Value          |
+| -------------- | -------------- |
+| Padding top    | 1 spacing unit |
+| Padding bottom | 1 spacing unit |
+| Margin top     | 1 spacing unit |
 
 ### Header Row (collapsible)
 
@@ -154,25 +138,16 @@ Derived from `FieldGroup.tsx` makeStyles:
 ## Dependencies
 
 - No Pega SDK imports required (no `getPConnect`)
-- Arrow icons: `KeyboardArrowRightIcon` / `KeyboardArrowDownIcon` from `@mui/icons-material` (MUI only) — use equivalent icons or Unicode characters in non-MUI implementations
+- Arrow icons: use a right-pointing arrow icon (collapsed) and a down-pointing arrow icon (expanded) from the chosen design system's icon set, or use Unicode characters (`▶`/`▼` or `›`/`⌄`)
 
 ## Design System Mapping
 
 **UI control type:** Collapsible section container with label, instructions, and children.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                   |
-| ------------------ | ----------------------------------------------------------------------- |
-| Default (CSS only) | `<div>` with toggled `display: none` on children, `<b>` header          |
-| MUI                | Grid container with `KeyboardArrowRight/Down` icons for collapse toggle |
-| Ant Design         | `<Collapse>` or `<Card>` with collapsible panels                        |
-| Chakra UI          | `<Accordion>` or manual `<Box>` with toggle state                       |
-| Shadcn/ui          | `<Collapsible>` + `<CollapsibleTrigger>` + `<CollapsibleContent>`       |
-
 When implementing in a specific design system, map the following:
 
-- `collapsed` toggle → design system's collapse/expand state or controlled component
-- Arrow direction → visual indicator of expand/collapse state (chevron or arrow icon)
-- `instructions` HTML → design system's `dangerouslySetInnerHTML` or rich content slot
-- Full-width children → ensure children container spans the full group width
+- **Collapse toggle** → use the DS's collapse/accordion component if available, or implement manually with local state toggling visibility of the children section
+- **Arrow direction icon** → use the DS's chevron/arrow icon that points right when collapsed and down when expanded
+- **`instructions` HTML** → render as raw/trusted HTML content using the framework's mechanism for injecting HTML strings
+- **Full-width children** → ensure the children container spans the full group width
+- **Header click** → when `collapsible` is `true`, the entire header row (icon + name) is clickable and toggles the collapsed state

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

@@ -2,7 +2,7 @@
 
 Repeating list of named field groups, each with its own children. Supports per-item delete and a global "+Add" link at the bottom.
 
-> **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,66 +13,56 @@ Renders a vertical list of field group items. Each item has a bold name header,
 ## Pega Metadata
 
 - **Pega Name:** `FieldGroupList`
-- **Registration key:** `FieldGroupList` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
-
-## Props
-
-| Prop       | Type                                                       | Required | Description                                                                                               |
-| ---------- | ---------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
-| `items`    | `Array<{ name: string; id: string; children: ReactNode }>` | Yes      | List of field group items to render                                                                       |
-| `onDelete` | `(id: string) => void`                                     | No       | Called with the item's `id` when the delete button is clicked. If not provided, no delete button is shown |
-| `onAdd`    | `() => void`                                               | No       | Called when the "+Add" link is clicked. If not provided, no add link or dividers are shown                |
-
-## Component Skeleton
-
-```typescript
-import { Utils } from '../../helpers/utils';
-
-interface FieldGroupListProps {
-  items: Array<{ name: string; id: string; children: any }>;
-  onDelete?: (id: string) => void;
-  onAdd?: () => void;
-}
-
-export default function FieldGroupList(props: FieldGroupListProps) {
-  const trashIcon = Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl());
-
-  return (
-    <OuterContainer spacing={4}>
-      <InnerFullWidth>
-        <InnerGrid spacing={1}>
-          {props.items.map(item => (
-            <FullWidthItem key={item.name}>
-              <b>{item.name}</b>
-              {props.onDelete && (
-                <button type="button" style={{ float: 'right' }} className="psdk-utility-button"
-                  id={`delete-row-${item.id}`} aria-label="Delete Row"
-                  onClick={() => props.onDelete(item.id)}>
-                  <img className="psdk-utility-card-action-svg-icon" src={trashIcon} />
-                </button>
-              )}
-              {item.children}
-              <br />
-              {props.onAdd && <><Divider /><br /></>}
-            </FullWidthItem>
-          ))}
-          {props.onAdd && (
-            <LinkButton onClick={props.onAdd} style={{ cursor: 'pointer' }}>+Add</LinkButton>
-          )}
-        </InnerGrid>
-      </InnerFullWidth>
-    </OuterContainer>
-  );
-}
-```
+- **Registration key:** `FieldGroupList` (in the project's component map)
+- **Does NOT use `getPConnect`** — receives all data as direct inputs
+
+## Component Inputs
+
+The component accepts the following inputs. Define the input contract using the project's framework conventions.
+
+| Name       | Type                                                                | Required | Description                                                                                               |
+| ---------- | ------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
+| `items`    | `Array<{ name: string; id: string; children: renderable content }>` | Yes      | List of field group items to render                                                                       |
+| `onDelete` | `(id: string) => void`                                              | No       | Called with the item's `id` when the delete button is clicked. If not provided, no delete button is shown |
+| `onAdd`    | `() => void`                                                        | No       | Called when the "+Add" link is clicked. If not provided, no add link or dividers are shown                |
+
+## Implementation Structure
+
+### Module Setup
+
+The component uses the project's utility helper to resolve the trash icon path. It does NOT import any Pega SDK modules.
+
+The component is named `FieldGroupList` 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 `items`, `onDelete`, and `onAdd` as inputs. At the top of the logic, resolve the trash icon source: call `Utils.getImageSrc('trash', Utils.getSDKStaticConentUrl())` and store the result.
+
+The render tree is:
+
+1. **Outer container** — a grid container with spacing of 4 units (≈32px) and `justifyContent: 'space-between'`.
+2. **Inner full-width wrapper** — a single grid cell at full width.
+3. **Inner grid** — a grid container with spacing of 1 unit (≈8px), containing the iterated items.
+4. **Item iteration** — for each item in `items`, render a full-width grid cell keyed by `item.name`:
+   - Render `<b>{item.name}</b>` as the item header.
+   - **Delete button** (conditional — only if `onDelete` is provided):
+     - Floated right (`float: right`).
+     - `type="button"`, `id` set to `"delete-row-{item.id}"`, `aria-label="Delete Row"`.
+     - Class: `psdk-utility-button`.
+     - On click: call `onDelete(item.id)`.
+     - Contains an `<img>` with class `psdk-utility-card-action-svg-icon` and `src` set to the resolved trash icon path.
+   - Render `{item.children}` (the field group content).
+   - Render a `<br />` for spacing.
+   - **Divider** (conditional — only if `onAdd` is provided): render a horizontal divider element followed by another `<br />`.
+5. **Add link** (conditional — only if `onAdd` is provided):
+   - After all items, render a clickable link with text `"+Add"`, `cursor: pointer`, underline on hover, and click handler wired to `onAdd`.
 
 ## Behavioral Contract
 
-1. Render a `Grid container` with `spacing={4}` and `justifyContent='space-between'` as the outer wrapper.
-2. Inside, render a full-width inner Grid with `spacing={1}`.
-3. For **each item** in `props.items`:
-   - Render a full-width `Grid` keyed by `item.name`.
+1. Render a grid container with spacing of 4 units (≈32px) and `justifyContent='space-between'` as the outer wrapper.
+2. Inside, render a full-width inner grid with spacing of 1 unit (≈8px).
+3. For **each item** in `items`:
+   - Render a full-width grid cell keyed by `item.name`.
    - Render `<b>{item.name}</b>` as the item header.
    - If `onDelete` is provided, render a delete button:
      - Floated right.
@@ -83,12 +73,12 @@ export default function FieldGroupList(props: FieldGroupListProps) {
      - Image class: `psdk-utility-card-action-svg-icon`.
    - Render `{item.children}`.
    - Render `<br />`.
-   - If `onAdd` is provided: render `<Divider />`, then `<br />`.
-4. After all items, if `onAdd` is provided, render a `<Link>` (or `<a>`) with text `'+Add'`, `cursor: pointer`, and `onClick={onAdd}`.
+   - If `onAdd` is provided: render a horizontal divider, then `<br />`.
+4. After all items, if `onAdd` is provided, render a clickable link element with text `'+Add'`, `cursor: pointer`, and click handler calling `onAdd`.
 
 ## Visual Specifications
 
-Derived from `FieldGroupList.tsx`:
+Derived from the component source:
 
 ### Outer Layout
 
@@ -131,26 +121,16 @@ Derived from `FieldGroupList.tsx`:
 
 ## Dependencies
 
-- `Utils` from `../../helpers/utils` — for `getImageSrc` and `getSDKStaticConentUrl` (used only for the trash icon)
+- The project's `Utils` helper — for `getImageSrc` and `getSDKStaticConentUrl` (used only for the trash icon)
 - No Pega SDK `getPConnect` imports required
 
 ## Design System Mapping
 
 **UI control type:** Repeating list of named groups with optional delete and add actions.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                 |
-| ------------------ | --------------------------------------------------------------------- |
-| Default (CSS only) | Flex column layout with `<hr>` divider and `<button>` delete          |
-| MUI                | `<Grid container>` items with `<Divider>` and `<Link>` for "+Add"     |
-| Ant Design         | `<List>` items with `<Divider>` and `<Button type='link'>` for "+Add" |
-| Chakra UI          | `<VStack>` with `<Divider>` and `<Button variant='link'>`             |
-| Shadcn/ui          | `<div>` flex column with `<Separator>` and a link button              |
-
 When implementing in a specific design system, map the following:
 
-- Delete button → icon button or `danger` variant button placed at the item top-right
-- Divider between items → `<Divider>` / `<hr>` (only when `onAdd` is present)
-- "+Add" link → a text link / `Button variant='link'` that calls `onAdd`
-- Trash icon → design system's delete icon or an SVG
+- **Delete button** → use the DS's icon button or danger-variant button placed at the item top-right. Use a trash/delete icon from the DS's icon set.
+- **Divider between items** → use the DS's horizontal divider/separator component (only when `onAdd` is present)
+- **"+Add" link** → use the DS's link button or text-variant button that calls `onAdd`
+- **Trash icon** → use the DS's delete/trash icon, or fall back to the SDK's `Utils.getImageSrc('trash', ...)` path

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

@@ -2,7 +2,7 @@
 
 Single field-value pair display component. Renders a label and value in either an inline (side-by-side) or stacked layout. Also used as a display mode renderer by field components (e.g., `TextInput`, `Dropdown`, etc.).
 
-> **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.
 
 ---
 
@@ -18,63 +18,48 @@ When no name is provided, only the value is rendered at full width. Used directl
 ## Pega Metadata
 
 - **Pega Name:** `FieldValueList`
-- **Registration key:** `FieldValueList` (in `component-map.ts`)
-- **Does NOT use `getPConnect`** — receives all data as direct props
+- **Registration key:** `FieldValueList` (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                                           |
 | --------- | --------- | -------- | ----------------------------------------------------- |
 | `name`    | `string`  | No       | Field label. If omitted, only the value is rendered   |
 | `value`   | `any`     | Yes      | Field value to display                                |
 | `variant` | `string`  | No       | Layout: `'inline'` (default) or `'stacked'`           |
 | `isHtml`  | `boolean` | No       | If `true`, render value as raw HTML (default `false`) |
 
-## Component Skeleton
-
-```typescript
-interface FieldValueListProps {
-  name?: string;
-  value: any;
-  variant?: string;
-  isHtml?: boolean;
-}
-
-export default function FieldValueList({ name, value, variant, isHtml = false }: FieldValueListProps) {
-  // 1. Fallback for empty value
-  const formattedValue = (value === undefined || value === '') ? '---' : value;
-
-  // 2. No-name case: render value only at full width
-  if (!name) {
-    const typography = variant === 'stacked' ? 'h6' : 'body2';
-    return isHtml
-      ? <ValueContainer typography={typography} dangerouslySetInnerHTML={{ __html: formattedValue }} />
-      : <ValueContainer typography={typography}>{formattedValue}</ValueContainer>;
-  }
-
-  // 3. Stacked variant: label on top, larger value below
-  if (variant === 'stacked') {
-    return (
-      <Row direction="column">
-        <Label style={{ paddingBottom: 0 }}>{name}</Label>
-        {isHtml
-          ? <Value typography="h6" style={{ paddingTop: 0 }} dangerouslySetInnerHTML={{ __html: formattedValue }} />
-          : <Value typography="h6" style={{ paddingTop: 0 }}>{formattedValue}</Value>}
-      </Row>
-    );
-  }
-
-  // 4. Inline variant (default): label 4 cols, value 8 cols
-  return (
-    <Row>
-      <Label xs={4}>{name}</Label>
-      {isHtml
-        ? <Value xs={8} dangerouslySetInnerHTML={{ __html: formattedValue }} />
-        : <Value xs={8}>{formattedValue}</Value>}
-    </Row>
-  );
-}
-```
+## Implementation Structure
+
+### Module Setup
+
+The component does NOT import any Pega SDK modules — all data arrives via direct inputs. It uses a grid layout and text elements from the chosen design system.
+
+The component is named `FieldValueList` 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 `name`, `value`, `variant` (defaults to `'inline'`), and `isHtml` (defaults to `false`) as inputs, then follows this rendering logic:
+
+1. **Empty value fallback** — if `value` is `undefined` or an empty string (`''`), substitute with the placeholder string `'---'`.
+
+2. **No-name path** — if `name` is not provided (falsy), render only the value at full width (12 columns):
+   - Use heading-6 text (≈1.25rem, weight 500) if `variant === 'stacked'`, otherwise use body-small text (≈0.875rem).
+   - If `isHtml` is true, render value as raw HTML.
+   - Return early (do not render a label).
+
+3. **Stacked variant path** — if `variant === 'stacked'`, render a column-direction layout:
+   - **Label row:** full-width (12 columns), with `paddingBottom: 0` to sit tight above the value. Text style: body-small (≈0.875rem), secondary text color, `fontWeight: 400`.
+   - **Value row:** full-width (12 columns), with `paddingTop: 0` to sit tight below the label. Text style: heading-6 (≈1.25rem, weight 500, larger/more prominent). If `isHtml`, render as raw HTML.
+
+4. **Inline variant path** (default) — render a side-by-side row layout:
+   - **Label cell:** occupies 4 of 12 columns. Text style: body-small (≈0.875rem), secondary text color, `fontWeight: 400`. Contains `name`.
+   - **Value cell:** occupies 8 of 12 columns (or 12 if no name). Text style: body-small (≈0.875rem), primary text color. If `isHtml`, render as raw HTML.
+
+5. **Layout wrapper** — all variants render inside a container row (Grid container) with `spacing={4}` and `justifyContent: 'space-between'`.
 
 ## Behavioral Contract
 
@@ -83,35 +68,35 @@ export default function FieldValueList({ name, value, variant, isHtml = false }:
 3. **Inline variant** (default — `variant !== 'stacked'`):
    - Label column: 4 of 12 columns.
    - Value column: 8 of 12 columns (or 12 if no name).
-   - Label: secondary text color, `body2` typography, `fontWeight: 400`.
-   - Value: primary text color, `body2` typography.
+   - Label: secondary text color, body-small text (≈0.875rem), `fontWeight: 400`.
+   - Value: primary text color, body-small text (≈0.875rem).
 4. **Stacked variant** (`variant === 'stacked'`):
    - Label column: 12 of 12, `paddingBottom: 0` (label sits tight above value).
    - Value column: 12 of 12, `paddingTop: 0` (value sits tight below label).
-   - Label: secondary text color, `body2` typography, `fontWeight: 400`.
-   - Value: primary text color, **`h6` typography** (larger / more prominent than inline).
-5. **HTML rendering:** If `isHtml` is `true`, wrap value in a `<div dangerouslySetInnerHTML={{ __html: formattedValue }}>`. The formatted value (with `'---'` fallback) is passed to `__html`.
+   - Label: secondary text color, body-small text (≈0.875rem), `fontWeight: 400`.
+   - Value: primary text color, **heading-6 text** (≈1.25rem, weight 500 — larger / more prominent than inline).
+5. **HTML rendering:** If `isHtml` is `true`, render the formatted value as raw HTML content using the framework's mechanism for injecting HTML strings. The formatted value (with `'---'` fallback) is passed as the HTML content.
 6. **Layout wrapper:** Render everything inside a container row with space-between justification and consistent spacing.
 
 ## Visual Specifications
 
-Derived from `FieldValueList.tsx` makeStyles:
+Derived from the component's companion styles:
 
 ### Label
 
-| Property    | Value                                                 |
-| ----------- | ----------------------------------------------------- |
-| Font weight | 400                                                   |
-| Color       | `theme.palette.text.secondary` (muted/secondary text) |
-| Typography  | `body2` (≈ 0.875rem / 14px)                           |
+| Property    | Value                          |
+| ----------- | ------------------------------ |
+| Font weight | 400                            |
+| Color       | secondary text color (muted)   |
+| Text size   | body-small (≈ 0.875rem / 14px) |
 
 ### Value
 
-| Property             | Value                                       |
-| -------------------- | ------------------------------------------- |
-| Color                | `theme.palette.text.primary` (default text) |
-| Typography (inline)  | `body2` (≈ 0.875rem / 14px)                 |
-| Typography (stacked) | `h6` (≈ 1.25rem / 20px, weight 500)         |
+| Property            | Value                                    |
+| ------------------- | ---------------------------------------- |
+| Color               | primary text color (default)             |
+| Text size (inline)  | body-small (≈ 0.875rem / 14px)           |
+| Text size (stacked) | heading-6 (≈ 1.25rem / 20px, weight 500) |
 
 ### Padding Adjustments (stacked only)
 
@@ -131,10 +116,10 @@ Derived from `FieldValueList.tsx` makeStyles:
 
 ## Edge Cases & Special Logic
 
-- `value` can be any type (string, number, boolean, React element). Render it as-is unless it's empty/undefined.
-- When `isHtml` is `true`, set the raw HTML from the formatted value — do NOT sanitize (the caller is responsible). Ensure value is a string before passing to `dangerouslySetInnerHTML`.
-- When `variant` is `'stacked'` and `name` is absent, render value at 12 cols with `h6` typography.
-- When `variant` is `'inline'` and `name` is absent, render value at 12 cols with `body2` typography.
+- `value` can be any type (string, number, boolean, rendered element). Render it as-is unless it's empty/undefined.
+- When `isHtml` is `true`, render the raw HTML from the formatted value using the framework's HTML injection mechanism — do NOT sanitize (the caller is responsible). Ensure value is a string before injecting.
+- When `variant` is `'stacked'` and `name` is absent, render value at 12 cols with heading-6 text.
+- When `variant` is `'inline'` and `name` is absent, render value at 12 cols with body-small text.
 
 ## Dependencies
 
@@ -145,20 +130,11 @@ Derived from `FieldValueList.tsx` makeStyles:
 
 **UI control type:** Read-only field label/value display pair.
 
-Listed design systems are examples only.
-
-| Design System      | Recommended Component                                                                |
-| ------------------ | ------------------------------------------------------------------------------------ |
-| Default (CSS only) | `<div class='field-value-inline'>` or `<div class='field-value-stacked'>` with CSS   |
-| MUI                | `<Grid container>` with `<Typography>` for label and value                           |
-| Ant Design         | `<Descriptions>` item, or `<Typography.Text type='secondary'>` + `<Typography.Text>` |
-| Chakra UI          | `<Stack direction='row'>` (inline) or `<Stack spacing={0}>` (stacked)                |
-| Shadcn/ui          | Custom label/value pair with Tailwind flex utilities                                 |
-
 When implementing in a specific design system, map the following:
 
-- Label → secondary/muted text style
-- Value inline → same size as label
-- Value stacked → larger typography (h6 equivalent)
-- Empty value → always display `'---'` (never show blank)
-- `isHtml={true}` → design system's `dangerouslySetInnerHTML` or `innerHTML` equivalent
+- **Label** → secondary/muted text style (body-small size)
+- **Value inline** → same size as label (body-small), primary text color
+- **Value stacked** → larger text (heading-6 equivalent, ≈1.25rem, weight 500)
+- **Empty value** → always display `'---'` (never show blank)
+- **`isHtml` = true** → use the framework's mechanism for rendering raw HTML content
+- **Grid layout** → use the DS's grid system with 4/8 column split (inline) or 12/12 stacked columns