--- title: "Create experiences with Frames" slug: "create-frames" description: "Create interactive applications with Frames on Pigment data, using AI tools for real-time data presentation and seamless user experiences." tags: ["AI Applications", "Frames", "Pigment Data"] updated: 2026-11-11T11:50:18Z published: 2026-11-11T11:50:18Z canonical: "kb.pigment.com/create-frames" --- > ## Documentation Index > Fetch the complete documentation index at: https://kb.pigment.com/llms.txt > Use this file to discover all available pages before exploring further. # Create experiences with Frames > [!WARNING] > ⚠️ Important > > Frames is available in Beta from September 28, 2026. For more information, see the [Beta Features Policy](/v1/docs/beta-features-policy) article. This article provides practical guidance on building Frames, including design optimization, best practice and troubleshooting. ## Before you begin To learn more about how Frames work, when you would use Frames compared to other tools like Boards, who can build Frames and what access conditions apply, see the [Frames](/v1/docs/frames) article. ## How to build a Frame There are two ways to build a Frame: using the Modeler Agent inside Pigment, or using an external AI tool (such as Claude, ChatGPT or Cursor) connected through the Pigment MCP tools. Both follow the same conversational build process. ### 1. Use the Modeler Agent Open a chat and discuss what you want to build: 1. Start a new Chat with the Modeler and set it to Build or Plan mode. For more information, see [Run the Modeler Agent](/v1/docs/configure-and-run-the-modeler-agent#how-to-work-with-the-modeler-agent). 2. (*Optional*) Ask it to analyze your Application and suggest thematic areas and capabilities achievable with Frames. It loads the Frames skill and analyzes your Application. 3. (*Recommended*) Navigate to the Block you want to visualize **before** you start. When you are on a Block, it is automatically added to the chat context, so the Modeler Agent knows exactly which Block to use. You can also reference Blocks using the Object picker: type `@` to open a drop-down menu of eligible Blocks. 4. Describe the Frame you want to create. `Create a new Frame: [your instructions]` Frames can generate: 1. Sparklines, leaderboards, heatmaps 2. Gamified presentations 3. Interactive tools 5. Specify your design intent. You can share a specific design for the Agent to match, or ask it to use the Pigment design already registered in the platform. 6. *(Optional)* Specify the Scenario the Frame should use. The Frame will read from and, if applicable, write to the Scenario you designate. This includes [Shared Scenarios](/v1/docs/get-started-scenarios#what-are-the-types-of-scenarios). 7. The Agent creates the Frame and applies successive updates to build the content you asked for. This produces a first version that you can then iterate on. ### 2. Use external AI tools via MCP You can build the same way from an external AI tool such as Claude and ChatGPT. Before you start, complete the set-up below: 1. In your Pigment Workspace, select **Settings** from the left sidebar. 2. Under **Account settings** select **Advanced features**. 3. Select **Enable advanced tools on MCP Server.** 4. Confirm the **building-pigment-frames** skill is in your skill repository. In Claude Code or Cursor, you may need to sync with the latest version of Pigment AI plugins at [https://github.com/gopigment/ai-plugins](https://github.com/gopigment/ai-plugins). If possible, activate auto-sync on the Pigment AI plugin to ensure you always have the latest version available. 5. Confirm the **Create Frame** and **Update Frame** tools are included in your Connector’s tool list. If necessary, refresh the tool list. Confirm they are enabled. Once set up, the build process is exactly the same as with the Modeler Agent. See steps 4 to 6 in [Use the Modeler Agent](/v1/docs/create-frames#use-the-modeler-agent). > [!NOTE] > ℹ️ Note > > Frames follow a simple publication lifecycle: > > - A newly created or updated Frame is visible only to its author until it is explicitly published. > - Once published, the Frame becomes accessible to other Members. > - Any update to a Frame's code returns it to unpublished status. It must be re-published to become visible to others again. ### Improve Frame design The AI Agent produces strong visuals from a plain description, but if you have a specific look in mind, you can guide it further. Consider the following for your prompts: - **Describe your design intent.** Directly mention colors, layout preferences, typography or the overall feel you're going for. - **Share a screenshot.** If you have a visual reference, paste it into the conversation and ask the Agent to match it. - **Use a template.** Copy and paste an existing template into your prompt to give the Agent a concrete starting point. For inspiration and ready-to-use design templates, publicly available slides design libraries are a great place to start. ## Edit Frames You can iterate on a Frame in natural language with the Modeler Agent or an external AI tool, or edit it manually in the Frame editor. Changes remain in draft and are invisible to Members until you publish. #### Open the Frame editor At the top center of a Frame, a pop-up shows whether you are viewing the **Published** version or a **Draft**, and lets you open the Frame editor. Open it to work on the Frame: - If a draft exists, the editor displays the draft. - If no draft exists, the editor displays the published version with a **Published** label. The editor only ever displays one version at a time: the published version or the draft. #### What you can do in the editor - **View the underlying code.** Select the source code symbol to see the Frame's code and resources. This is for advanced users. - **Edit the name.** Open the three-dot menu, then **Edit details**, to rename the Frame. - **Manage access.** Select the person symbol to apply a permission Metric to the Frame, as you would for Boards. For more information, see [Use Board Permissions to Grant Board Access](/v1/docs/board-permissions-grant-board-access#how-to-create-and-apply-a-board-permission-metric). - **Review resources.** The count at the bottom right shows how many objects from your Application the Frame is allowed to access. Hover over it to open a pop-up showing the following information: - **Data source.** The Data source symbol by a resource denotes that the Frame can read from this resource and display its data. Hover over it to see the resource’s name and type information. For more information, see the [When Frames read from Pigment](/v1/docs/frames#when-frames-read-from-pigment) section of [Frames](/v1/docs/frames). - **List.** The List symbol denotes that the Frame can read List Items from this resource and use them for Page Selectors and other purposes. - **Metrics with** `Write` **access.** Metrics with the `Write` label receive the data that Members submit through the Frame. These are called Data sinks. For more information, see the [When Frames write to Pigment](/v1/docs/frames#frames-write-to-pigment) section of [Frames](/v1/docs/frames). #### Debug a Frame Use the log recorder at the bottom left of the editor to see how the Frame interacts with the Pigment model. 1. Select **Start recording**. 2. Reload the Frame to capture page-load behavior or interact with it (for example, select a button that reads or writes data) to capture runtime behavior. You can view the subscriptions to data sources and Lists and the data your Frame reads or writes in real time. 3. Select **Stop recording**. 4. Ask the Modeler Agent to look at the logs and debug. The Agent has automatic access to the recorded logs, there’s no need to share them. If you use an external AI tool via MCP, download the logs as a JSON file and share it with your tool. #### Publish or discard When you are done, publish the Frame to make it available to other Members, or discard your draft to return to the current published version. 1. Select **Publish**. 2. Review any warnings on the Frame. 3. Check the connected resources plugged to the Frame. 4. Confirm to publish. A **Published** label then appears next to the Frame's name. 5. Close the editor to return to the main panel. ### Manage Frames To manage Frames, including editing their configuration, duplicating or deleting them: 1. Select the **Frames** drop-down above **Blocks** in the left sidebar, opening the list of Frames. 2. Hover over the Frame you want to edit and select its three-dot menu. The menu gives you the below options. #### Edit configuration This opens the Frame editor. For more information, see [Open the Frame editor](/v1/docs/create-frames#open-the-frame-editor). #### Duplicate This creates a copy of your Frame inside the Frame folder. This allows you to keep a development version of your Frame while the original is in prod. #### Set data input behavior If you have the **Define Application Security** permission, you can define whether Members see a consent dialog when using a Frame to input data into a Block. This dialog ensures the Member understands that by proceeding they are writing data to a Block. The dialog summarizes what data is going to be input and the name of the Block receiving the Member's input. It also lets Members choose between two future behavior types: - **Just once**. Consent is requested each time you try to input data. - **For this session**. You are not asked for consent again until your next Frames session. If a Member decides that they do not want to write data to the Block, they can select **Deny** at the bottom of the dialog. This returns them to the Frame with no data written to the Block. To set whether this consent dialog appears: 1. Select the **Frames** drop-down above **Blocks** in the left sidebar, opening the list of Frames. 2. Hover over the Frame you want to edit and select its three-dot menu. 3. Select **Edit configuration**. 4. Make your changes to the toggle labeled **Data input**: 1. **Ask for confirmation**. Members see the consent dialog 2. **Do not ask**. Members do not see the dialog. ## Best practice - Business logic such as calculations and aggregations belongs in the Pigment Application, rather than in Frames. In the Application, it is auditable and produces better performance. Frames is designed as a presentation and interaction layer. - While our Support team is not able to provide custom code modifications, many questions or enhancements can be addressed by accessing the generated code, then sharing it with a large language model (LLM) such as Claude. For information on accessing the code, see the section [What you can do in the editor](/v1/docs/create-frames#open-the-frame-editor2). You can ask Claude to explain how the code works, help diagnose unexpected behavior or suggest changes to achieve the outcome you're looking for. ## Troubleshooting If your Frame does not load or if you run into an issue: - **Ask the Modeler Agent or your AI tool first.** Describe what's wrong or what you'd like to change, and the Agent will update the Frame for you. - **Add a debugger panel.** Ask the Agent to add a debugger panel at the bottom of your Frame. It can surface useful information that you can share directly with the Agent to help solve the issue your Frame is facing. - **Record a log**. For more information, see [Debug a Frame](/v1/docs/create-frames#what-you-can-do-in-the-editor1) above. #### Known issue: Frame authentication error Some Members may see the following error when loading a Frame: > [!CAUTION] > **An error occurred (Frame authentication). Please try again later or contact us.** This is caused by a firewall or proxy blocking access to [pigment-frames.app](http://pigment-frames.app). For security reasons, Frames run in a sandboxed environment hosted on this separate domain, distinct from the main application ([pigment.app](http://pigment.app)). To solve this, ask your IT team to allowlist [pigment-frames.app](http://pigment-frames.app) with the same rules applied to [pigment.app](http://pigment.app) (HTTPS, port 443). | Domain | Purpose | | --- | --- | | `pigment.app` | Main application | | `pigment-frames.app` | Frames (sandboxed execution) | Once allowlisted, reload the page and open the Frame again. If the error persists, submit a [Support ticket](https://support.pigment.com/en/support/tickets/new?ticket_form=ai_feature_request).