Generate experiences with Puck AI
Read docs
CloudAIDesign Mode

Design Mode

In design mode, Puck AI creates new component types on the fly, incorporating components from your config where possible.

Using design mode

Design mode is opt-in across both the plugin and server APIs.

In the plugin

To enable it in the plugin, set ai.mode in the puckHandler:

import { puckHandler } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  return puckHandler(request, {
    ai: {
      mode: "design",
    },
  });
}

With server APIs

ai.generate() accepts mode and designMode directly:

const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config,
  mode: "design",
});

See generate with design mode.

Wire up the config

Designed components persist in page data. To render them, pass your config through withDynamicConfig when rendering <Puck> or <Render>:

import { withDynamicConfig } from "@puckeditor/plugin-ai";
 
export function Editor({ data }) {
  const dynamicConfig = withDynamicConfig(config, data);
 
  return <Puck plugins={[aiPlugin]} config={dynamicConfig} data={data} />;
  // return <Render config={dynamicConfig} data={data} />;
}

Enabling the design mode toggle

To let users toggle between design and assembly mode via the chat interface, first allow it on your server with ai.designMode.allowed:

import { puckHandler } from "@puckeditor/cloud-client";
 
export async function POST(request) {
  return puckHandler(request, {
    ai: {
      designMode: {
        allowed: true,
      },
    },
  });
}

Then enable the design mode toggle in the client with designMode.visible, optionally making it the defaultMode:

const aiPlugin = createAiPlugin({
  designMode: {
    visible: true,
  },
  // defaultMode: "design",
});

Customizing design behavior

You can configure design behavior using ai.designMode.

Custom instructions

Use instructions to give the agent instructions to follow when designing, such as brand colors or layout conventions.

In the plugin

Configure ai.designMode.instructions on the puckHandler:

return puckHandler(request, {
  ai: {
    designMode: {
      instructions:
        "Use our brand colors: #4285F4 for primary, #DB4437 for accents.",
    },
  },
});

With server APIs

Pass designMode.instructions to ai.generate:

const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config,
  mode: "design",
  designMode: {
    instructions:
      "Use our brand colors: #4285F4 for primary, #DB4437 for accents.",
  },
});

Allowing scripts

By default, the agent can’t add scripts to designed components or the page.

In the plugin

Set scripts in the puckHandler to true to allow them in the plugin:

return puckHandler(request, {
  ai: {
    designMode: {
      scripts: true,
    },
  },
});

With server APIs

Set designMode.scripts in ai.generate to true to allow scripts in generated pages:

const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config,
  mode: "design",
  designMode: {
    scripts: true,
  },
});

Choosing a model

Design mode uses the same model as assembly mode: openai/gpt-5.6-luna by default, or the top-level model if you set one. Set a design-mode model to use a different one.

In the plugin

Set model in the puckHandler to use a different one for design-mode requests:

return puckHandler(request, {
  ai: {
    designMode: {
      model: "openai/gpt-6-sol",
    },
  },
});

Optionally set providerOptions to fine-tune the design-mode model:

return puckHandler(request, {
  ai: {
    designMode: {
      model: "openai/gpt-6-sol",
      providerOptions: {
        openai: { reasoningEffort: "high" },
      },
    },
  },
});

With server APIs

Provide designMode.model and designMode.providerOptions to ai.generate to use a different model for this generation:

const { data } = await puck.ai.generate({
  prompt: "Create a pricing section with three tiers",
  config,
  mode: "design",
  designMode: {
    model: "openai/gpt-6-sol",
    // providerOptions: {}
  },
});

Global styles and scripts

Alongside the per-component CSS, the agent may create a page-wide stylesheet (for shared styles and CSS properties) and script tag (if enabled by your configuration).

Design mode data

Designed components and the page-wide globals are stored on the root of Puck’s Data. You can access them under the _dynamicConfig prop:

{
  "root": {
    "props": {
      "_dynamicConfig": {
        "components": {
          "MyComponent": {
            "html": "<div>Hello, world</div>",
            "fields": {}
          }
        },
        "styles": ":root { --brand: #4285f4; }",
        "script": "document.documentElement.dataset.ready = 'true';"
      }
    }
  }
}

Further reading