Using Merge library with AI

If you use UXPin Merge and have connected your own React component library, Forge can generate and edit UI using those same components.

Instead of generic elements, Forge builds real JSX using your exported React components and their props. This means the generated UI follows the same structure that exists in your codebase.

Enabling AI support for your Merge library

To enable AI support for your component library:

1. Add the following configuration to your library’s "Uxpin.config.js" file under the settings field:

const path = require('path');
const fs = require('fs');

module.exports = {
  components: './src/components/**/*.[jt]sx?(x)',

  settings: {
    useAI: {
      name: "Your Design System Name",
      documentationUrl: "",
      systemPrompt: "",
    },
  },
};

Push the updated "Uxpin.config.js" file.

npx uxpin-merge push --token="YOUR_TOKEN"

After configuration, your library will appear in the Library pill in Forge.

Important notes

• If the component library is private or proprietary, include detailed documentation or usage guidelines in "Systemprompt" so AI can generate correct code.
• If "Documentationurl" is provided, it is included in the AI prompt as a reference.
• "Systemprompt" can be used to define custom rules or override default JSX behavior.

Additional spacing, typography, or visual rules can be defined in Design System Guidelines.

Configuration options

name (string)
Name of the component library for which the prompt should be generated.
Required. Default: empty string.

documentationUrl (string)
URL to the component library's official documentation.
Optional. Default: empty string.

systemPrompt (string)
Structured instructions that define how Forge should generate JSX.
Required. Default: empty string.

How Forge uses your configuration

When AI support is enabled:

• Forge generates JSX using components from your Merge library.
• It follows rules defined in systemPrompt.
• If rules are missing, the output may not match your internal standards.
• Better documentation produces more consistent results.

Creating System Prompt

The "Systemprompt" defines how your components should be used during generation and editing.

For larger libraries, store the instructions in a separate file (SYSTEM_PROMPT.MD) and load it into "Uxpin.config.js" .

Keeping instructions in a separate file makes them easier to maintain and version.

Structuring an effective systemPrompt

The quality of generated JSX depends on how clearly your component rules are defined.

A structured "Systemprompt" should include:

• Library overview and purpose
• Design principles
• Critical usage patterns
• Detailed component documentation (props, required fields, defaults)
• Layout and spacing rules
• Anti-patterns

Define strict prop rules clearly.

Example SYSTEM_PROMPT.MD template

You can use the following structure as a starting point.
Replace the placeholder content with rules specific to your component library.

``
# System Prompt: JSX Code Generation for [Library Name]

This UXPin Merge library is a custom React component library for [purpose].

Based on: [Framework name if applicable, e.g., Material UI, Ant Design]

Philosophy: [For custom libraries, describe design philosophy]

---

## DESIGN PRINCIPLES

### Core Principles

Replace this section with global rules that apply to all components.

---

## CRITICAL USAGE PATTERNS

Document your librarys most important conventions here using WRONG vs CORRECT examples in jsx code.

### Pattern 1: [e.g., Text Props]

WRONG:

<Component wrongProp="value">Text as children</Component>

CORRECT:

<Component textProp="value" />

### Pattern 2: [e.g., Icons]

WRONG:

<Button icon={<HomeIcon />} />


CORRECT:

<Button iconName="Home" />

---

## COMPONENT DOCUMENTATION

### ComponentName

Description: [Brief description of component purpose.]


Props:

- `propName` (type, required/optional, default) - Description

- `anotherProp` (string | number, optional) - Description

---

## LAYOUT GUIDELINES

Document how to structure layouts using your library components.

**Grid System:**

<Row gutter={[16, 16]}>
  <Col xs={24} md={12} lg={8}>
    Content
  </Col>
</Row>


**Spacing:**
- Use 8px base unit for spacing
- Maintain consistent margins: 8, 16, 24, 32, 48px
- Container padding: 16px mobile, 24px tablet, 32px desktop
---

## ANTI-PATTERNS

List patterns that must not be generated.  

❌ DO NOT:

- Use multiple primary buttons in the same view

- Apply fixed widths that break responsiveness

✅ DO:

- Establish clear visual hierarchy

- Use semantic HTML and proper component structure

---

## ICONS

Available Icons: [List available icons]

Usage: 
<Icon iconName="Search" size="medium" />
<Button iconName="Plus" label="Add Item" />

---

## ADDITIONAL NOTES

[Any other important information specific to your library]

```

Best Practices

Define required props clearly

If a prop is mandatory, state it clearly.

Example:

• label is required.
• variant defaults to "Secondary" .
• Only one primary button per view.

Avoid vague instructions such as 'Use buttons consistently.'

Define layout patterns

If your system requires specific wrappers, containers, or grid rules, include them in "Systemprompt" .

If spacing follows a fixed scale (for example, 8px increments), clearly define it.

Document anti-patterns

State what should not be generated.

Example:

• Do not use inline styles.
• Do not use multiple primary buttons.

Constraints improve output predictability.

Keep rules inside systemPrompt for private libraries

If your library is private or proprietary:

• Do not rely only on documentationUrl.
• Include full usage conventions directly in "Systemprompt"

External links are treated as reference.
Rules written inside the prompt have a stronger impact on the generated output.

Maintain and update the prompt

Update "System_prompt.md" when:

• New components are added
• Props change
• Layout rules are updated
• Design tokens are modified

After each update, run uxpin-merge push to apply changes.