⚠️ Important
Frames is available in Beta from September 28, 2026. For more information, see the 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 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:
Start a new Chat with the Modeler and set it to Build or Plan mode. For more information, see Run the Modeler Agent.
(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.(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.Describe the Frame you want to create.
Create a new Frame: [your instructions]
Frames can generate:Sparklines, leaderboards, heatmaps
Gamified presentations
Interactive tools
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.
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:
Ask your Customer Success Manager to activate the Frames MCP tools in your Workspace.
Sync with the latest version of Pigment AI plugins (https://github.com/gopigment/ai-plugins) and confirm the building-pigment-frames skill is in your skill repository.
Confirm the Frames tools are enabled by checking the connector settings in your external AI.
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.
ℹ️ 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.
Manage 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.
Review resources. The resource count at the bottom right shows how many resources the Frame uses. Hover over it to open a pop-up showing which Blocks are used, along with your
Read/Writeaccess to them.
Debug a Frame
Use the log recorder at the bottom left of the editor to see how the Frame interacts with the Pigment model.
Select Start recording.
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.
Select Stop recording.
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.
Select Publish.
Review any warnings on the Frame.
Check the connected resources plugged to the Frame.
Confirm to publish. A Published label then appears next to the Frame's name.
Close the editor to return to the main panel.
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:
Select the Frames drop-down above Blocks in the left sidebar, opening the list of Frames.
Hover over the Frame you want to edit and select its three-dot menu.
Select Edit configuration.
Make your changes to the toggle labeled Data input:
Ask for confirmation. Members see the consent dialog
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.
The Test & Deploy workflow is not available for Frames. Instead, duplicate your Frame while iterating, and then Publish once you’re satisfied with the result.
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. 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 above.
Known issue: Frame authentication error
Some Members may see the following error when loading a Frame:
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. For security reasons, Frames run in a sandboxed environment hosted on this separate domain, distinct from the main application (pigment.app).
To solve this, ask your IT team to allowlist pigment-frames.app with the same rules applied to pigment.app (HTTPS, port 443).
Domain | Purpose |
|---|---|
| Main application |
| Frames (sandboxed execution) |
Once allowlisted, reload the page and open the Frame again. If the error persists, submit a Support ticket.