# Pega Dx Component Builder

> Create or extend a Pega Constellation DX component in this UI gallery. Use for new custom components, config.json authoring, Storybook docs, Jest tests, component registration, and safe PCore or PConnect API integration that works on both Pega Platform and Launchpad (getMappedKey, CASE_INFO constants, capability checks).

- Skill: `pegasystems/pega-dx-component-builder` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add pegasystems/pega-dx-component-builder`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pegasystems/pega-dx-component-builder/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: pegasystems (https://skillmd.com/u/pegasystems)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pegasystems/pega-dx-component-builder

---


# Pega DX Component Builder

Use this skill when you need to create a new component in this repository or bring an incomplete component up to the repo's shipping standard.

Default operating mode:

- fully implement the component, not just scaffold it
- validate the result with practical checks
- update source files only, unless the user explicitly asks for generated artifacts
- rely on bundled guidance first and fetch live Pega docs only when deeper API confirmation is needed

## Load These References First

- [Repository guidance](./references/repository-guidance.md)
- [Official Pega guidance](./references/official-pega-guidance.md)
- [Component delivery checklist](./assets/component-delivery-checklist.md)
- Repo root: `LAUNCHPAD_VS_PLATFORM.md` (required when touching data, actions, case IDs, or rule names)
- Repo root: `Component_Build_Guide.md`, `best practices.md`, `AGENTS.md`

## When To Use

- Creating a new `Pega_Extensions_<Name>` component under `src/components/`
- Extending a component that needs new `config.json` properties, Storybook docs, or tests
- Implementing PConnect or PCore interactions such as actions, value updates, case context access, or container behavior
- Verifying that a DX component follows Constellation styling, accessibility, and repository conventions
- Making a component Launchpad-safe (key mapping, namespaced rule names, optional API fallbacks)

## Inputs To Capture

- Component name and whether it is a `Field`, `Template`, or another supported DX component type
- Intended end-user behavior and any required data binding or actions
- Designer properties that must appear in `config.json`
- Similar existing components in this gallery that can serve as the closest template
- Whether the component must support **Launchpad** as well as Pega Platform (default: yes, unless the gallery marks it unsupported)
- Whether the task requires documentation-only scaffolding, working behavior, or publish-ready validation

## Procedure

1. Review the repository references and inspect the closest existing component implementation before creating files. If the work involves data pages, case IDs, property keys, local actions, or navigation, read `LAUNCHPAD_VS_PLATFORM.md` first.
2. Use bundled guidance first. Fetch live Pega docs only if the task depends on API details or platform behavior that are not clear from repo examples and bundled summaries.
3. Define the component contract:
   - Folder name: `src/components/Pega_Extensions_<Name>`
   - exported component name
   - `config.json` `name` and `componentKey`
   - required runtime props, default config, and any localizations or helper files
4. Implement the component with repository-aligned structure:
   - `index.tsx` for the component
   - `config.json` for Designer metadata
   - `Docs.mdx` for documentation
   - `demo.stories.tsx` for Storybook
   - `demo.test.tsx` for unit coverage
   - optional `styles.ts`, `localizations.json`, and helper modules only when justified
   - when a Storybook prop has a constrained set of supported values, expose it with a `select` control and human-readable labels rather than a free-text control
   - place important custom props near the top of Storybook `argTypes` and set explicit defaults for common DX props such as `testId: ''` and `hideLabel: false` when relevant
   - for field-style components, keep `hideLabel` as the public component prop and pass `labelHidden={hideLabel}` only to the underlying Cosmos control when that control uses the Cosmos prop name
   - for field-style components, type `disabled`, `readOnly`, and `required` as boolean props, but preserve runtime compatibility by coercing `true` and string `'true'` values with the shared `[readOnly, required, disabled].map(...)` pattern used by `MaskedInput` and `DateInput`
   - prefer `getPConnect: () => typeof PConnect` for repo-aligned field component props (types from `@pega/pcore-pconnect-typedefs` via `src/pega-globals.d.ts`) and call `getActionsApi()`, `getStateProps()`, and `ignoreSuggestion()` from the returned object instead of introducing duplicate local `PegaConnect`, `PegaActionsApi`, or `PegaStateProps` interfaces
   - prefer bare `PCore.*` over `(window as any).PCore`; cast incomplete Storybook/test mocks with `as unknown as typeof PCore` / `as unknown as typeof PConnect`
   - if you add non-default stories, add them to a `## Example` or `## Examples` section in `Docs.mdx` using `Story` blocks
5. Prefer `@pega/cosmos-react-core`, existing repo dependencies, and functional React patterns. Use `withConfiguration`, `getPConnect`, and `PCore` only where needed and only after confirming the usage pattern.
6. For any PCore/PConnect integration that touches identifiers, rule names, or data:
   - Use `getMappedKey` from `src/components/shared/utils.ts` for property names, data-page names, and local-action / flow-type names (`pyID`, `pzInsKey`, `pxObjClass`, `pyStartCase`, configured data pages, etc.).
   - Read the current case id via `PCore.getConstants().CASE_INFO.CASE_INFO_ID`, not hard-coded `pyID` or `caseInfo.businessID`.
   - Navigate with `getActionsApi()` and `PCore.getSemanticUrlUtils()` — never hand-build Platform or Launchpad URLs.
   - Gate Platform-only REST DX APIs with `PCore.getRestClient().doesRestApiExist('…')` and provide a fallback, or document the component as not Launchpad-supported.
   - Do **not** use `if (isLaunchpad)` feature switches when key mapping or capability detection can solve the difference.
   - Stub `getNameSpaceUtils`, `getEnvironmentInfo().getKeyMapping`, and related helpers in Storybook/tests.
7. Keep styling theme-aware. Prefer tokens, `styled-components`, and `rem` units. Avoid direct DOM manipulation unless a dependency or browser API makes it unavoidable.
8. Update source-of-truth registration or discovery files when the new component must appear in the gallery. Inspect `src/component-list.json` first. Treat generated outputs such as `src/component-list.js`, `Pega_Extensions/`, and `store/` as build artifacts unless the task explicitly requires them.
9. Validate the implementation with the strongest practical checks for the task:
   - `npm run lint`
   - targeted or full `npm run test`
   - additional build or gallery validation if the change affects registration or packaging
10. Report assumptions, especially around unavailable runtime data, mocked PConnect behavior in Storybook, Launchpad API gaps, or APIs that were inferred from repo examples rather than live platform verification.

## Guardrails

- Do not invent DX component metadata. Mirror the shape and naming patterns from this repository.
- Do not hand-edit generated bundles or release artifacts unless explicitly requested.
- Do not add a package dependency for convenience if the repository already has an adequate option.
- Do not leave the component half-finished if the request implies a usable gallery component.
- Do not hard-code Platform property names (`pyID`, `pzInsKey`, `pxObjClass`, …) as object keys in runtime logic — use `getMappedKey`.
- Do not call Platform-only APIs (for example unconditional `getDataObjectView` / `readDataObject`) without a Launchpad-safe path or an explicit “not supported on Launchpad” decision.

## Success Criteria

- The component folder matches repository naming and file conventions.
- `config.json`, implementation, docs, story, and tests are consistent with each other.
- PConnect or PCore usage is justified by repo patterns or official guidance and is Launchpad-safe when the component is marked Launchpad-supported.
- Validation results and unresolved assumptions are clearly reported.