Beautiful.ai

View saved version →

---
name: beautiful-ai-presentation-building
description: Build a whole Beautiful.ai presentation from scratch with the Beautiful.ai MCP tools - outline, theme, creating the presentation as a deck of placeholder slides, opening it for the user and filling the placeholders with the generated slides. Use when the user asks for a new deck or presentation; for changes to existing slides use the slide editing skill.
---

# Building a Beautiful.ai presentation

When the user asks for a whole presentation ("make me a deck about X", "a 10-slide pitch for ...", "turn these notes into a presentation"), you create the presentation with a placeholder for every slide of the outline, then build the slides one by one into their placeholders. The slide work itself (model, render, check, save) is the slide editing skill's workflow; this skill is about the deck: what goes in it, in which order, and how to keep the user in the loop while it takes shape.

## The other skills

- **Slide editing** (`beautiful-ai://skills/slide-editing`): the workflow for every slide you build (notes, element reference, build, render and check, save, notes), the tools, and the rules. Each slide of the deck goes through it.
- **Slide templates** (`beautiful-ai://skills/slide-templates`): which template fits which content; pick the template of each slide with it.
- **Slide design** (`beautiful-ai://skills/slide-design`): what makes a slide look good and the checklist to run on every render; the deck is only as good as its slides.
- **Slide elements** (`beautiful-ai://skills/slide-elements`): the model reference for the elements you write.

## Steps

1. **Settle the outline first.** Read the user's notes first (`list_user_notes`, `read_user_note`): their preferences, brand, audience and past decks decide much of what follows (tone, language, theme, how much text, what to avoid), so you ask less and get it right the first time. Then the slides, one idea each, in a sensible order: a title slide, the story (context, problem, solution, evidence, plan, ...), a closing or next-steps slide. Decide the deck's tone and how much text a slide carries, and for each slide its template (the slide templates skill) and what it needs beyond text (a chart, a table, a picture, icons). Pick the templates for the deck as a whole, not one slide at a time: a deck whose slides all look alike (the same template and layout slide after slide) is the most common way a generated deck disappoints, and the user expects variety without asking for it. Two neighboring slides on the same template are fine when their content calls for it; what to avoid is many slides that look identical: a run of three or more on the same template, or a template on more than about a third of the deck. When a template would repeat that much, give one of the slides the alternative the templates skill lists for that content or restructure it; when it repeats at all, plan a different layout for the two so they do not come out identical (see "Varied across the deck" in the slide design skill). Plan the pictures the same way: which slides get one, what each shows, and each its own. Ask only when the request leaves out something you cannot decide well yourself (the audience, the number of slides, must-have content) and for the two things that are the user's call: where the deck's pictures come from (their own images, the workspace's Team Assets, the web, stock photos or AI; see the editing skill's images section), and, when the workspace has shared themes (step 2), which Brand Kit (the user's word for a theme) to use, naming the team's default one as the default and, where the workspace's brand guardrails allow only shared themes, saying so; unless their notes or the request already say. Ask everything in one message, before creating the deck, and decide the rest yourself and tell the user what you assumed. When the user does not say how many slides, make as many as the content needs: typically 6–12, one idea per slide, no filler.
2. **Pick the theme.** To the user a theme is a **Brand Kit** (the app's name for it; "theme" is the tools' internal name for the same thing), so that is the word to use with them. First `list_shared_themes` for the workspace: these are the team's own Shared Brand Kits (the tool answers with an error where the user may not use shared themes). When there are shared themes, the user decides: ask them, in the outline message of step 1, naming the shared themes, the default one first and as the default ("your team's default Brand Kit, X, unless you prefer another"), unless their notes or the request already say. Whether a built-in look is an alternative depends on the workspace's brand guardrails (`list_workspaces`, `permissions.customThemes.use`): where custom themes are not allowed, built-in themes are out and the deck has to use one of the shared themes, so say so in the same question ("your workspace's brand guardrails keep decks on the team's Brand Kits") and do not offer a built-in look; otherwise offer it. A shared theme is the usual choice of a team that has them; a deck on it follows the theme when the team updates it. For a built-in look (the user's choice, or a workspace without shared themes), `list_themes` lists the built-in themes (palette, fonts, style); choose the one the user's notes name, else what the user asked for ("something dark and modern") or one that fits the subject and audience; Classic is the safe default. Either kind comes with its raw theme model (`list_shared_themes`, or `list_themes` with the id), which lets you render a slide with it (`render_slide` with `theme`) when you want to see it before deciding.
3. **Create the presentation as a deck of placeholders.** `create_presentation` takes a name that says what the deck is about, the workspace id from `list_workspaces` (ask which one when the user has several and the request does not say), the theme (`sharedThemeId` for a shared theme, `themeId` for a built-in one) and `slides`: one placeholder model per slide of the outline, in deck order. A placeholder is `{ "template_id": "ai-generation", "states": [{}], "metadata": { "isGenerating": true, "slidePrompt": "<one line: what this slide will say>" } }` plus the version fields of any new slide model (`Slide.md` in the elements reference); it has no content to render or check. In the editor every placeholder shows "Generating slide..." until you replace it. The tool returns the presentation id, `slideIds` in deck order (the n-th id is the n-th slide of your outline) and the editor url: keep the ids, they are the slides you are about to fill.
4. **Open the deck for the user.** Right after creating it, call `open_presentation`: in a client that renders MCP Apps the app appears in the chat with a button that opens the editor fullscreen, showing the whole deck as placeholders that turn into finished slides as you save them. In the same message give the editor link (`editorUrl`, from `create_presentation` or from `open_presentation`'s result) and recommend it: the editor open in its own browser tab next to the chat is the better way to watch the deck being built (it updates live as you save, and the conversation stays visible, which it does not while the in-chat editor is fullscreen); the button in the chat is the alternative. The link is also all a client that does not render apps shows, and the fallback if `open_presentation` fails. Say that the deck is being built and will be ready in a few minutes.
5. **Fill the placeholders** with `update_slide`, in deck order, each slide built, rendered and checked as in the slide editing workflow. The first is the title slide: a `title` template slide, kept simple (the presentation title and, when the request gives them, a subtitle and the presenter or date; no pictures or extras unless the user asked; `PresentationTitle.md` in the elements reference, a `title` example). For every slide, `update_slide` on its id from step 3 with the full model: `template_id`, `states`, `layout`, the version fields, and `metadata` with `isGenerating: false` (it replaces the placeholder's metadata; a slide left with `isGenerating: true` keeps showing as generating in the slide navigator and gets no thumbnail). There is no need to read a placeholder first (`get_slide`): it has nothing to keep. Render with the presentation's theme (`render_slide` with `presentationId`). Never `create_slide` for a slide of the outline: its placeholder already exists. Keep each slide consistent with the ones before it in style (the same title style, wording, number formats, icon style and level of detail, no two slides saying the same thing) and different from them in structure: build it on the template and layout the outline gave it, and when it ends up on the same template as the slide before it, make it look different before saving (the other tray side or none, the other header position; the alternative template when it would be the third in a row). Give slides visuals where the design guidelines call for them, from the source the user chose in step 1, and get every slide its own picture: one `generate_image_asset` call (or one of the user's files) per slide that gets one, for that slide's subject. An asset that is already on a slide of the deck does not go on another; a logo is the one exception.
6. **Finish.** No placeholder may be left: a slide that did not come out well is saved in its best working version, and a placeholder you end up not needing is moved to the trash (`update_presentation` with a `slideRefs` without it, see "Removing and restoring slides" in the editing skill). Tell the user what the deck contains (one line per slide is plenty) and what you assumed, and give the links again (editor and player, `get_presentation_links`); the open editor already shows the finished deck, so do not open it a second time. Leave notes as the editing skill asks: what you learned about the app in the shared knowledge base, what you learned about the user (the deck's subject and audience, where their pictures come from, choices they confirmed or corrected) in their notes.

## Rules

- The user gets to see the deck (the editor link, recommended for its own tab, and the editor in the chat where the client renders apps) right after it is created, as placeholders that fill in one by one, not at the end.
- The presentation is created with a placeholder (`template_id` `ai-generation`, `metadata.isGenerating: true`) for every slide of the outline, and each one is replaced in place with `update_slide` on its id, with `isGenerating` cleared; no placeholder is left behind and none is duplicated with `create_slide`. The first slide is a simple `title` slide, the only title slide of the deck.
- Every slide is rendered and checked before it is saved (the placeholders are the one exception: they carry no content); a slide that does not come out well after the attempts the editing skill allows is saved in its best working version and mentioned to the user, not silently dropped.
- The deck is varied without the user asking for it: no run of three or more slides on the same template, no template on more than about a third of the deck, no two neighboring slides with the same template and the same layout, and every picture on one slide only. This is planned in the outline and checked on every slide before it is saved.
- Build the slides the user asked for and nothing else; when the content is too thin for the number of slides asked, say so and make fewer rather than padding. Settle the count in the outline, before the placeholders are created; a placeholder that turns out unnecessary is removed from the deck, not left as it is.

View saved version →

---
name: beautiful-ai-slide-design
description: Design guidelines for Beautiful.ai slides - what makes a slide look good, how to keep it from being dull or empty, and the checks to run on a rendered slide before saving it. Use whenever you build, change or review a slide in Beautiful.ai.
---

# Beautiful.ai slide design guidelines

A slide is judged on its rendered image. Build for the picture, not for the model: the model is only right when the render looks right. These guidelines say what "looks right" means and how to get there with the templates and elements available.

## Not dull: give every slide something to look at

- Do not be shy with images. A slide made only of text looks dull; a fitting picture makes it look designed. When the content allows it and a suitable image can be obtained from the source the user chose (the editing skill says to ask once per task: their own images uploaded with `create_upload_url` and saved with `save_image_asset`, or `generate_image_asset` for the workspace's Team Assets, the web, stock photos or AI), add one: a side tray (`left_tray` / `right_tray`) next to a list, a process or a table; an image cell in a dashboard next to a chart or statistics; a background photo on a section break (`headline2`, `section`) or on a title slide when the user asks for one (a new deck's title slide stays simple, see the presentation building skill); the photo slots of `team`, `textgrid_photos`, `user_testimonial`. Pick an image that matches the slide's subject and the deck's style (photo vs. illustration, color mood), not a generic stock cliché.
- Use the built-in icons (`list_icons`) when a photo is not available or would be too much: an icon per item on lists (`textgrid_vertical_icons`), steps (`step_chevrons`, `step_circular`), hub-and-spoke nodes, statistics; they follow the theme's icon style and colors, so they always fit. Keep one icon per idea and a consistent level of detail across the set.
- Prefer templates with a visual structure over plain text when the content has one: steps become a process diagram, a comparison becomes compare bars or a stack diagram, numbers become statistics or a chart, a date series a timeline. Reserve `text` / `textlist` for content that really is prose or a list.
- Use the theme's colors: a colored tray or dashboard cell (`cellColor` with an accent or `background_accent`), a colored background on a section break, a highlighted item (`hilited`, `color`) for the one thing the audience should notice. One or two accents per slide; not every cell a different color.
- Exceptions: data-dense slides (a full table, a chart with many series, a dashboard already at 4+ cells) and slides that are mostly a single big visual do not need a decorative image; adding one would crowd them. And never add a picture that is not available: do not invent asset ids, do not leave `__generateImage` objects behind hoping for the best.

## Not empty: fill the canvas

Large empty areas look unfinished. The renderer scales text to the space it has, so a slide with little content gets big text and still large gaps. Fix it by changing the layout, not by padding the content with filler text.

- Few items: pick a template that is built for few items (1 statistic -> `action-number`; 2–3 points -> `textBoxGrid` in one row, `stackDiagram` or `headline2`; 2 values -> `compare_circles`), or give the slide a second element: a side tray with an image or a short takeaway, a second cell in a dashboard, a header with a subtitle line.
- Short text: a `textlist` with three short bullets fills better with an image tray and one column than with two columns; a lone paragraph is a `headline2` or `text` with an image, not a list.
- Dashboards: cells should fill the 12x12 grid with no unused rows or columns; a single small chart in a big cell gets a text cell under it or a statistic beside it. Charts with few categories want a narrower cell, not a full-width one.
- Trays: a tray takes 300–470 px of a 1280 px slide; use it when the main element has fewer than ~4 items or is naturally narrow (a short list, a quote, a single number); drop it when the main element needs the width (a wide table, a long timeline, a chart with many categories).
- Headers: most templates have one; a slide without a header and with little content looks empty. Use the header for the title and, when it helps, a one-line subtitle (a `body` block after the `heading`).

## Not crowded: leave room to breathe

The opposite failure. Crowded slides are the result of too much content for the template, not of the template.

- Every text readable at a glance: no overflow, no clipping, no ellipsis, nothing scaled down to tiny print, labels (axis, data, legend, column headers, step captions) not touching each other.
- Shorten before squeezing: trim wording, drop non-essential labels or secondary text, reduce item count or split the content over two slides (only when the user asks for a split; otherwise say that a split would help). Respect the item counts in the templates skill.
- Keep gutters: a dashboard with `showGutter` and a few cells looks calmer than many edge-to-edge cells; a list with sub-bullets on every item is a wall of text, keep sub-bullets to the items that need them.

## Coherent and consistent

- Balance: elements aligned and evenly spaced; nothing squeezed into a corner, nothing leaving a big gap on one side; an image tray on the side that balances the header position.
- Contrast: text readable against what is behind it (background color or image, cell color, chart bars). Light text on light images and dark text on dark cells are the most common render failures; change the `cellColor`, add a backdrop, or pick a different image.
- Consistency with the deck: same title style, capitalization, number formats, label tone and icon style as the neighboring slides; slides of the same template with their content structured the same way. Look at the neighbors before building. Consistency is in the style, not in the look: the deck should not read as one slide repeated (see "Varied across the deck").
- Titles as takeaways where the deck does it: "Revenue grew 40% in Q3" over "Q3 revenue"; mirror the deck's convention.
- Text style: short, parallel phrasing across items (all nouns, or all verbs), numbers formatted alike, no trailing periods on fragments.

## Varied across the deck

A deck is judged as a whole too, and the most common complaint about a generated one is that its slides all look alike: the same template slide after slide, the same layout, the same picture turning up again. Every slide can pass the checks above and the deck still look like one slide repeated. The user expects variety without asking for it, so build it in from the start rather than waiting to be told.

- Two neighboring slides on the same template are fine when their content calls for it (two lists in a row within one section, two charts of related series); what makes a deck dull is many slides that look identical. Keep a template from running three or more slides in a row or taking more than about a third of the deck: take the alternative the templates skill lists for that content (a bullet list next to an icon list or text boxes, chevrons next to a circular process, a dashboard of statistics next to big numbers, a list next to a two-column comparison) or restructure one of them (two of its points become a statistic, its steps a timeline). And when a template does repeat, make the two slides look different: the other tray side or no tray, the other header position, a colored background on one, a different kind of visual.
- Vary the kind of visual as well: a photo tray on one slide, icons on the next, a chart or a colored cell on the one after. A deck where every slide has the same right-hand photo tray is as monotonous as one with no pictures.
- A picture appears on one slide only. Every slide that gets a picture gets its own, chosen for its subject (a `generate_image_asset` call or another of the user's files per slide); the same photo on two slides looks like a mistake, the title slide's picture included. A logo is the one asset that may repeat.

## Checklist before saving

Run it on the rendered image after your last edit; fix and render again when something fails (at most 3 attempts, then save the best working version and tell the user what remains):

1. Rendered without errors and visibly shows the requested change.
2. Every piece of text readable: nothing overflowing, clipped, truncated, overlapping or too small; good contrast against its background.
3. Not crowded: text blocks and labels have breathing room; the slide does not look dense.
4. Not empty: no large unused area; the content fills the canvas in a balanced way.
5. Not dull: the slide has a visual (image, icon, chart, colored element) unless it is data-dense by nature.
6. Coherent: balanced layout, aligned and evenly spaced elements, theme colors, new content matching the style of the existing content and the deck.
7. Varied: in a deck, not identical to the slide before it (the same template with the same layout), not the third slide in a row on one template, and no picture that is already on another slide of the deck.

View saved version →

---
name: beautiful-ai-slide-editing
description: Edit, add, split, combine and review Beautiful.ai slides with the Beautiful.ai MCP tools - the workflow every slide change goes through. Use whenever the user asks to change a slide or presentation in Beautiful.ai, add slides, or wants advice on a slide; a whole new deck starts with the presentation building skill and comes back here for each slide.
---

# Editing Beautiful.ai slides

You work on the user's Beautiful.ai presentations through the Beautiful.ai MCP tools. A presentation is a deck of slides; a slide is a JSON model: `template_id` (which template renders it), `states[0]` (the element tree: `header`, `primary`, optional `tray`), `layout` and a few version fields. The app renders the model with the presentation's theme (colors, fonts, styles, logo). The user knows a theme as a **Brand Kit**, a shared team theme as a Shared Brand Kit: that is the app's name for it everywhere the user looks, while the tools, fields and models keep the internal name (`theme`, `sharedThemeId`, `list_themes`, `list_shared_themes`), so say "Brand Kit" to the user and "theme" to the tools. You read models, change them, render them to check the result, and save them; every save is visible to the user in the editor right away.

## Tools

- Shared knowledge base: `list_shared_knowledge_notes`, `read_shared_knowledge_note`, `write_shared_knowledge_note`
- The user's notes: `list_user_notes`, `read_user_note`, `write_user_note`
- Workspaces and presentations: `list_workspaces`, `find_presentations`, `get_presentation`, `get_presentation_theme`, `get_presentation_links`, `create_presentation`, `update_presentation`, `export_presentation`, `list_themes`, `list_shared_themes`
- Sharing: `create_public_link`, `create_password_protected_link`, `share_presentation_with_user`
- Slides: `get_slide`, `create_slide`, `update_slide`
- Templates: `list_slide_templates`, `get_slide_examples`
- Images and icons: `generate_image_asset`, `create_upload_url`, `save_image_asset`, `list_icons`
- Rendering: `render_slide`
- Interactive app: `open_presentation`

## Workflow

1. **Understand the request and find the slide.** You need a presentation id: the user gives it (it is in the editor's url), you find it by name (`find_presentations` in a workspace from `list_workspaces`: a loose match on the words of the name, most recent first, editable presentations only; search each workspace when the user has several and does not say which; pick the one that fits by name, slide count and last change, and ask when several do), or you are building a new deck (the presentation building skill, see "The reference skills"). `get_presentation` gives the deck (`slideIds` in order, "slide 5" is the fifth) and the presentation document; `get_slide` gives a slide's model. Read the slides the request is about, and the deck when the request refers to it or consistency matters (see "The rest of the presentation").
2. **Check the notes.** `list_user_notes`, then `read_user_note` for the ones that apply (once per task, not per slide): the user's preferences, brand, audience and what they told you to remember shape every slide you make for them. Then `list_shared_knowledge_notes` and `read_shared_knowledge_note` for the notes whose names match the template or task (for example `dashboard-charts`, `tray-images`): the fastest way to learn a model shape or a renderer pitfall. Trust the notes, but verify in the render and correct a note that turns out wrong.
3. **Learn the template and its elements.** The slide-elements skill (see "The reference skills") documents the model of the template's root element and of everything it nests: read the documents for the elements you are about to write. `list_slide_templates` with the `templateId` gives the template's `defaultData` (what an empty slide starts with) and capabilities (header, tray layouts, color backgrounds, ...). `get_slide_examples` gives complete, real slide models of the template: the quickest way to see which fields a working slide has. Pick an example whose amount of content resembles yours; one or two are enough. When the content needs a template (new slides, restructured content), pick it with the slide-templates skill.
4. **Build the new model.** Apply the minimal change that fulfills the request, keeping ids of existing elements and everything unrelated to the request untouched, and make the result look good: follow the design guidelines skill (see "The reference skills"), in particular give a slide a visual (an image from the source the user chose, see "Images, logos and icons", or icons) when it would otherwise be dull, and choose a layout that fills the canvas when the content is small. Keep the data consistent (adding a table column means a cell in every row; adding a chart series means a data point for every category). Keep text short: the slide has fixed space, so new or edited text should be as concise as the text around it. A new slide model carries the current version fields (`version: 10`, `migrationVersion: 10.03`, `textStylesVersion: 2`, see `Slide.md` in the slide-elements skill); without them the renderer runs legacy migrations over your model and rewrites it. Switch templates, add or remove slides only when the request asks for it or clearly requires it (see the sections below).
5. **Render and check.** `render_slide` with the model and the presentation's theme (`presentationId`, or the theme from `get_presentation_theme`). The renderer swallows layout errors and still produces a broken or partly empty image: `ok: false` with `renderErrors`/`pageErrors` tells you what failed, usually naming the element class and model field at fault, with the tail of the renderer log. Always look at the image and run the design guidelines' checklist before saving: it rendered without errors and shows the requested change; every piece of text is readable with enough contrast; nothing is crowded; nothing is left empty; the slide has something to look at; the whole looks coherent and matches the deck. If anything is off, fix the model and render again (at most 3 attempts). If a problem cannot be fully fixed within that budget, save the best working version and tell the user what remains.
6. **Save.** `update_slide` for an existing slide (send the full value of every field you change, e.g. the whole `states`; a placeholder of a deck being built is an existing slide, see the presentation building skill), `create_slide` for a new one (a full model, at the position you want in the deck). Only ever save a model you have rendered and checked in step 5: the change reaches the user immediately. A slide with a `libraryItemId` is tied to a shared slide of the team's library (see `Slide.md` in the slide-elements skill): `update_slide` takes `libraryItemId: null` along with the changes to turn it into a regular slide the user's deck owns, and tell the user it no longer follows the shared slide.
7. **Tell the user** what you changed (including slides added or removed) and any assumptions or caveats, in a few sentences; no model internals. Let them see the result: `open_presentation` in a client that renders apps (together with the editor link, recommended for its own tab, see "Previewing and showing slides"), otherwise the link to the editor opened on the slide you worked on (`get_presentation_links`, or `editorUrl` from `get_slide`) unless they are already in it, and the player link when they want to present.
8. **Leave notes.** Go back over everything you had to look up or figure out about the app and write it down with `write_shared_knowledge_note` (with nothing of the user in it, see "Knowledge base and user notes"), and over everything you learned about the user (a preference, a correction, a fact about their company or audience) and write that down with `write_user_note`. Only skip this when the notes already covered everything.

## Previewing and showing slides

`render_slide` returns the rendered slide as an image (one per stage), for any model: a stored slide (`get_slide`, then render it with its presentation's theme), a model you are working on, an alternative you are considering, or an example of a template. Use it to see a slide before you touch it and to check your work before saving. A preview changes nothing; only `update_slide` and `create_slide` do.

The rendered image is for you: most chat clients do not display images returned by tools, so never tell the user an image is "shown above" or attached. To show the user a presentation:

- In a client that renders MCP Apps (Claude, ChatGPT), `open_presentation` puts the presentation's editor in the chat itself: the app shows a button to open the editor, and the editor opens fullscreen when the user clicks it (on a phone or tablet the app only says that editing needs a desktop, so give such a user the player link; the user needs edit access, for a view-only presentation the tool answers with the player link instead). The fullscreen editor hides the conversation (the user can still type below it), which makes it the lesser experience: the better one is the editor open in its own browser tab next to the chat, where it updates live as you work. So whenever you open the app, say in the same message that the in-chat editor works but that the editor link (from the tool's result) in a separate tab is the better way to follow along, and give that link. Use it when the user wants to see, work on or present a presentation without leaving the chat, and after you changed a deck so they can look at the result in place. The editor is live (it shows the presentation as it is and picks up every save), so for a change open it after saving; when building a whole deck, open it right after creating it so the user can watch its placeholders fill in (see the presentation building skill). While the editor is open in the chat, the app tells the host which slide the user is looking at (presentation id, slide number and id), and that arrives as context with their next message: "this slide" or a request that names no slide means that one, so you do not need to ask which slide they mean.
- Otherwise give them the link to the editor opened on the slide: `get_slide` returns it as `editorUrl` (and `get_presentation_links` builds it from a slide number), and the player link when they want to see the deck as the audience does.

Describe the slide in a sentence next to the app or link (render it first so the description is right); when the client does display tool images, that is a bonus, not something to rely on.

## The rest of the presentation

The slide is part of a deck. `get_presentation` lists the slides in order; `get_slide` reads any of them; `render_slide` shows how one looks.

- Use the other slides when the request points to them ("make it match slide 2", "use the same numbers as the previous slide", "a summary of the deck"), when consistency matters (naming, number formats, capitalization, tone, how similar slides are structured: look at the neighbors or slides of the same template), or when the request is ambiguous and the deck makes the intent clear. A simple, self-contained edit does not need them.
- Change only the slides the request is about. If the user asks for a change elsewhere, say so instead of silently changing other slides.

## The reference skills

Four more skills carry the rest of the knowledge; read them as the task needs them (they are served as resources of the Beautiful.ai MCP, and ship with the plugin):

- **Presentation building** (`beautiful-ai://skills/presentation-building`): building a whole new deck: outline, theme, `create_presentation` with a placeholder per slide, opening the deck for the user right away, filling the placeholders with `update_slide`. Read it when the user asks for a new presentation; each of its slides then goes through this skill's workflow.
- **Slide design** (`beautiful-ai://skills/slide-design`): what makes a slide look good: not dull (images, icons, color), not empty (layouts that fill the canvas), not crowded, coherent with the deck; and the checklist to run on every render. Read it before building and apply its checklist before saving.
- **Slide templates** (`beautiful-ai://skills/slide-templates`): which template fits which content (with the item counts to stay within), how dashboards are composed, and how to switch a slide to another template. Read it whenever you pick a template for new or restructured content, or when the user asks for a different layout.
- **Slide elements** (`beautiful-ai://skills/slide-elements`): the model reference, one document per element: the fields of `states[0]` for every template's root element and for the elements they nest (text blocks, media slots, dashboard cells, chart data, tables, items of lists and diagrams), with allowed values, limits and pitfalls. Its SKILL.md maps each template to its root element and lists the documents (`beautiful-ai://skills/slide-elements/elements/<Element>.md`). Read the documents for the elements you are about to write before building a model, and always `TextElement.md` and `ContentElement.md` the first time you write text or media.

## Images, logos and icons

Pictures on a slide live in media elements that take a `content_type` (`"image"`, `"logo"` or `"icon"`) and a `content_value` (an asset id, or an icon key). Keep the slide's existing ones and never invent asset ids or icon keys.

- Icons are built in: `list_icons` with a few descriptive words ("growth chart", "security lock", "team") finds them by name and tags; set `content_type: "icon"` and `content_value: <key>` on the element (an icon list item of `textgrid_vertical_icons`, a `TextAndImage` cell, a step or node marker, a `Picture`). Icons follow the theme's icon style and colors, so they fit without any further work; prefer one icon per item that stands for the item's idea, and keep the set consistent (same level of detail across a list). Pick from the results, never guess a key.

- Where pictures come from is the user's choice, so ask before the first picture of a task, not per slide: one plain question (no tool names) offering their own images (files they share in the chat or that are in their project: when the client lets you read them, you upload them or pass small ones inline, see below), the workspace's Team Assets (its own brand pictures; Team plan), web search (real logos, products, places, people), stock photos, or AI-generated images, limited to what the workspace allows (`list_workspaces`, `permissions.generativeAIImages`, `webImages`, `stockLibraries`, `sharedResources`) and to what you can actually do. Skip the question when their notes already say (a `preferences` note) or the request does ("use our team photos", "no AI images"), and write their answer to their notes (`write_user_note`) so nobody asks again. When they leave it to you: Team Assets where the workspace has them, web for what must look like itself, stock or AI for generic subjects.
- To get a picture you do not have, `generate_image_asset` gets one from the source the user chose, the way the app's own generator does, and returns its asset id. `source` "team" picks one of the workspace's Team Assets (the user's own brand pictures, headshots and product shots; Team plan), "web" finds a web image (for something that must look like itself: a company logo, a product, a real place or person), "stock" a stock photo and "ai" generates one from a description (give `aspectRatio` matching the slot, and a style when the deck calls for one). Which sources the workspace allows is in `list_workspaces` (`permissions.generativeAIImages`, `webImages`, `stockLibraries`, `sharedResources`); the tool names the sources to use instead when one is not allowed, and when no Team Asset matches, try other words or another source. A web or stock result is one match among several, and a web, stock or ai search that finds nothing gives an abstract image instead, so render the slide and check that the picture fits.
- To put a picture you already have on a slide, upload it and save it as an asset: `create_upload_url` (with the file's extension) gives a file id and a Cloud Storage upload url; PUT the file's raw bytes to that url, with its content type and nothing else (no authentication; the url is good for 15 minutes, files up to 50 MB); then `save_image_asset` with the file id (`assetType` "image" or "logo" for a company logo) returns the asset id to put on the slide. One upload per file: the file id is used once. The upload needs outbound access to the domain storage.googleapis.com: when your environment restricts network access to a list of domains and that one is not on it (the PUT fails to resolve the host), skip the upload and give `save_image_asset` the image itself as base64 (`image`), which works for images up to 2 MB; say so to the user when a picture is bigger than that and you have no way to upload it. Any image you can get hold of works: one the user shares in the chat or keeps in their project (the usual choice of a user who has their own material: ask which files go where when it is not obvious), or one you obtain with your own tools (fetched, generated or drawn) when `generate_image_asset` has nothing suitable for the source the user chose; fit it to the purpose (a real logo for a logo slot, a photo or illustration that matches the slide's subject and the deck's style) and prefer images you are allowed to use. Then set `content_type: "image"` (or `"logo"`) and `content_value: <assetId>` on the image element (the `childElement` of a `TextAndImage` cell, a `Picture`, a logo item, the `image` of a title slide, a tray image); the element documents (`ContentElement.md`, `Picture.md`) and the template's examples show where image elements live and which fields (crop, scale, `aoi*`) they usually carry, which you can leave out. If the element has a `__generateImage` object, remove it, otherwise the app will try to generate an image. Pick an element or template slot whose shape suits the picture (a portrait in a side tray, a wide picture in a full-width cell).
- When the template has no image slot of its own (a bullet list, a process diagram, a table, ...), put the image in a tray: set `layout.trayLayout` to `left_tray` or `right_tray` (a full-height panel at the slide edge) or `left_inline` / `right_inline` (beside the main element, under the header), and add `states[0].tray` with `trayWidth` (pixels, typically 300–470), a `gridLayout` of one full cell (`cols: 12, rows: 12, cells: [{ x: 0, y: 0, width: 12, height: 12 }]`) and `items: [{ componentType: "TextAndImage", cellColor: "background_accent", childElement: { content_type: "image", content_value: <assetId> } }]`. Templates whose `availableTrayLayouts` is empty (`list_slide_templates`) do not support trays; `SideBarContainer.md` has the full tray model and most templates have examples with an image tray to copy from.
- Add images on your own initiative when they make the slide better (see the design guidelines: a text-only slide with free space is the typical case), and always when the user asks for them; whether to add one is your call, where it comes from is theirs (above). A picture is for one slide: every slide that gets one gets its own, for its subject (a `generate_image_asset` call or a file of the user's per slide), and an asset that is already on another slide of the deck is not put on this one, a logo excepted (see "Varied across the deck" in the design guidelines). When neither `generate_image_asset` nor an image you can get hold of gives a suitable picture, use icons instead or make the rest of the change and tell the user to share the image or add it in the editor, and when switching to a template with image slots prefer one that works without a photo, or leave the slot empty and say so.
- Render the slide afterwards and check the image like any other content: visible, fitting its slot without an awkward cut, text in front of it readable.

## Splitting a slide into several

When the user asks to split a slide ("split this into two slides", "one slide per step", "move the last three items to a new slide"), divide its content over several slides: the existing slide keeps the first part (`update_slide`), new slides get the rest in order (`create_slide` right after it, at increasing positions). Do this only when the user asks for it: when content merely does not fit, shorten it or pick a template that fits it instead, and if a split would be the better answer, say so and leave the deck alone.

- Every slide must read as a complete slide on its own: a title on each (the same title, or with a part number or subtitle, following the deck's conventions), roughly equal amounts of content, no slide with a single orphan item, no item duplicated. Pick the template for each slide by what its part of the content is, not by what the original used: a layout chosen for the full content is often not the best for half of it.
- Every resulting slide is rendered and checked (step 5) before it is saved.
- Tell the user how many slides were added, where, and what went on each.

## Combining slides into one

When the user asks to combine slides ("combine this with the next slide", "merge slides 3 and 4"), bring all of their content onto one slide: keep the first one (`update_slide`), then move the others to the presentation's trash with `update_presentation` and a `slideRefs` without them (see "Removing and restoring slides"). Save the combined slide before removing the others, so their content is never gone before it is on the combined slide. Do this only when the user asks for it.

- Carry over all of their text, numbers, images and data; nothing is dropped silently. Pick the template that presents the combined content best, whatever the slides used before (two bullet lists become one `textlist` with two columns or a `textBoxGrid`, two statistics slides become one `dashboard`, a list and a chart a `dashboard` with both). Condense wording so the result stays readable, but keep every point; if something really cannot fit, drop the least important item and say so.
- A combined slide is more crowded by nature: look especially for crammed text and overlapping labels in the render.
- Tell the user which slides were combined (by number) and that they were removed, and what, if anything, was condensed or left out.

## Removing and restoring slides

A slide of a presentation is either in its deck or in its trash; `get_presentation` lists both (`slideIds` in deck order, `deletedSlideIds` with the last trashed first) and `get_slide` reads a trashed slide like any other (its `slideNumber` is null). The deck given to `update_presentation` (`slideRefs`) decides where each slide is: a slide left out goes to the trash, a trashed slide put in comes back. Nothing is deleted for good through the tools: the app empties the trash after 30 days.

- Always send the whole deck, built from the `slideIds` of a fresh `get_presentation` with only the intended change, never from memory: whatever is missing from it is trashed. The result names the slides that moved (`trashedSlideIds`, `restoredSlideIds`); if one moved that should not have, put it back with another `update_presentation` right away.
- Removing: a `slideRefs` without the slide. Only when the user asks for a slide to go, or when a workflow calls for it (combining slides, a placeholder a new deck ends up not needing); tell the user the slide went to the trash and can be put back.
- Restoring: a `slideRefs` with the slide at the position the user wants. When the user asks what the trash holds, read the trashed slides with `get_slide` and describe them.

## Adding slides

When the user asks for new slides ("add a slide about the Q3 results", "add two slides: risks, then next steps"), build each from their instructions, taking what they do not specify from the deck (`get_presentation`, the neighboring slides) so the new slides match its tone, wording, number formats and title style and do not repeat what another slide already says. Pick the template per slide by its content and its neighbors (slide-templates skill: not a template that would make three in a row when another fits), give it a picture of its own where one belongs (not one already on another slide), build the model as in the workflow (steps 2–5), then `create_slide` at the right position. One idea per slide, text as concise as the deck's; when the user does not say how many slides, make as many as the content needs, usually one. Several new slides go in one `create_slide` at a time, in deck order, each after the previous one has returned: calls sent together land in no fixed order, and one can be refused because the deck changed under it (the answer says the slide was not added; call it again).

## Reordering, renaming, theming, linking, sharing and exporting presentations

- `update_presentation` renames a presentation (`name`), reorders its deck (`slideRefs`: slide id -> position; only the order matters), moves slides between the deck and the trash (the same `slideRefs`, see "Removing and restoring slides") and changes its theme (`theme`: the theme attributes to change, or `sharedThemeId`: a shared team theme to switch to).
- Changing a presentation's theme: `get_presentation_theme` gives the current theme model; `update_presentation` with `theme` applies the attributes you give on top of it (brand colors in `colors`, fonts in `fontHeaderFontId` / `fontTitleFontId` / `fontBodyFontId`, the look in `styleShape`, `styleElementStyle`, `iconStyle`, ...; an object like `colors` is merged one entry at a time, everything else is replaced). To give an existing presentation the look of a built-in theme, take that theme's model from `list_themes` and send it as `theme` (all of it, or just the parts the user wants). Do this only when the user asks for a different theme or look, and where the workspace's brand guardrails allow it (see below): it changes every slide of the deck at once (the slides' own background choices stay), so render one or two slides with the changed theme first (`render_slide` with `theme`) and check them like any change, and tell the user the whole deck changed. A presentation on a shared team theme becomes its own copy of that theme with your changes; say so before doing it.
- Switching a presentation to a shared team theme: `list_shared_themes` for its workspace gives the team's shared themes (its Shared Brand Kits) the user may use (each with its raw model, to render a slide with it first), and `update_presentation` with `sharedThemeId` puts the presentation on one: it follows that theme from then on and its own theme attributes are dropped, every slide re-rendered. As with any theme change, only when the user asks for it, and tell them the whole deck changed. Theme attributes (`theme`) and a shared theme (`sharedThemeId`) cannot be sent in the same call.
- Brand guardrails: whether the workspace allows themes of a presentation's own is in `list_workspaces` (`permissions.customThemes.use`). Where it does not, theme attribute changes and built-in themes are refused and every presentation uses one of the shared themes (switching between them with `sharedThemeId` is still allowed). When the user asks for a different look there, tell them their workspace's brand guardrails keep every deck on the team's Brand Kits, offer the other shared ones if there are any (by name), and say that a workspace owner would have to change the Brand Kit itself or the guardrails for anything else.
- Creating a presentation (`create_presentation`, with `list_shared_themes` / `list_themes` for its theme) and building its deck is covered by the presentation building skill (see "The reference skills").
- `get_presentation_links` gives the editor url (optionally opened on a slide, by its 1-based number) and the player url of a presentation; the editor needs the user to be signed in to an account with access, the player shows the deck as the audience sees it.
- Sharing, only when the user asks to share a presentation, and the way they ask for: `create_public_link` (a named link anyone can open; it makes the presentation public), `create_password_protected_link` (a named link whose viewers enter a password the user chooses), or `share_presentation_with_user` (one person by email, with `view` or `edit` access and an optional note for the email they get; a person without a Beautiful.ai account gets an invite that grants the access when they sign up). What each needs: every option needs edit access to the presentation (a viewer cannot share); a password-protected link also needs `permissions.securedSharing` in the workspace (`list_workspaces`; not in the Basic plan, so offer a public link or sharing with a person there); sharing with a person also needs the right to manage the presentation's sharing, which its owner has and editors usually do, and which only the tool can tell: when it refuses, say the owner has to share it; and sharing with a person is limited to the workspace's members when `permissions.externalWorkspacesCollaboration.use` is false (the Team Owner has disabled collaboration outside the workspace), so tell the user that then. The two kinds of link exclude each other: a presentation is either public (public links work) or secured (password-protected links work), and creating one kind switches it, so when the result lists links that no longer work, tell the user. Ask for what the tool needs and the user has not given (the link's name, the password, the email, view or edit) rather than inventing it, never make up a password, and give the user the link url on its own; do not repeat a password back beyond saying it is set.
- `export_presentation` gives a file when the user asks for one ("send me the PDF", "export to PowerPoint"): a `pdf`, or a `pptx` with one picture per slide, or an editable PowerPoint (`editable: true`) where the workspace allows it (`list_workspaces`: `permissions.exportPresentation` for any export, `permissions.exportPresentationToEditable` for an editable one; when the user wants an editable deck and the workspace does not allow it, say so and offer the picture-per-slide one). The file is produced in the background and the tool waits for it; when it answers that the export is still running (a large deck), call it again a little later with the same arguments. It returns a download link that is valid for 5 minutes only (`expiresAt`): give it to the user at once and say that it expires, and get a fresh one with the same call if they come back for it.

## Advice

When the user asks for your opinion rather than a change ("what would you improve here?", "is this too crowded?", "should I split this?", "is this slide needed?"), review properly before answering: render the slide, read its model, read the deck and render the neighbors and any slide on the same topic, and judge content, density, template fit, duplication with other slides, consistency with the deck and readability. If you recommend a different layout, split or combination, build and render the alternative first and recommend only what came out well, and describe what it looks like (the rendered alternative is for you to judge; the user cannot see it until it is saved). Answer the question, then give the two to four most valuable recommendations, each concrete and phrased so the user can ask for it as a change. Change nothing in an advice request.

## Knowledge base and user notes

Two sets of markdown notes, one topic per note, both written and maintained by the agents:

- The **shared knowledge base** (`list_shared_knowledge_notes`, `read_shared_knowledge_note`, `write_shared_knowledge_note`) is common to every agent working with Beautiful.ai: anything about the app an agent had to figure out. Its purpose is to make discovery cheap for the next agent: every lookup you had to do (an example, a template's default data, why a render failed) is one the next agent should not have to repeat. Record: the model shape of a template or element (the fields that matter, allowed values, a minimal snippet), a template's rules and limits, which examples are good references and why, a renderer error with its cause and fix, a layout trick that made the slide look good, how much text fits where, a dead end to avoid, a tool's quirk. Record failures too. Write only about Beautiful.ai (models, templates, tools, rendering, behavior). **Never leak user-related data into shared notes**: every agent of every account reads them, so nothing from the user's slides or messages (names, companies, products, numbers, text), nothing about the user themselves (preferences, brand, audience), no presentation, slide or asset ids, no workspace or account details may appear in them, not even as an example; make examples up from neutral placeholder content. Anything about the user belongs in their notes.
- The **user's notes** (`list_user_notes`, `read_user_note`, `write_user_note`) are private to the user you work for and are where everything about them goes: their preferences (tone, language, amount of text, favorite templates and themes, where their pictures come from, what they dislike), their company, products and brand (colors, fonts, logo asset ids), their audience and recurring subjects, corrections they made to your work, and anything they ask you to remember. Read them at the start of every task so the slides fit the user without asking again; write them as you learn (a stated preference, a correction, a fact), under small topics such as `preferences`, `brand`, `audience`, `company`. Never store secrets or credentials in them.

Rules for both: write notes generously, as you go (if you had to look something up or the user had to tell you something, it is worth a note). One topic per note, named as a lowercase slug with hyphens (`table-cell-colors`); prefer small, specific topics (`textlist-column-layout` over `textlist`). When a note on the topic exists, read it and extend or correct it rather than creating a near-duplicate (writing replaces the content); remove what you have proven wrong. Keep notes factual and compact (a title line, then bullets or a minimal snippet, usually well under 40 lines).

## Rules

- Never save (`update_slide`, `create_slide`) a model you have not rendered with `render_slide` and visually checked after your last edit against the design guidelines: all text readable with good contrast, no overflow, no crowded text or overlapping labels, no large empty area, something to look at, the slide coherent and good looking. The user sees every save immediately. The only models saved unrendered are the `ai-generation` placeholders `create_presentation` starts a new deck with (see the presentation building skill): they have no content to check.
- Keep everything of a model you did not mean to change: other fields, element ids, existing images.
- Add slides only when the user asks to split a slide, to add slides or to build a presentation; remove slides from a deck only when the user asks to combine or remove them (or a placeholder of a deck you are building is not needed), and bring slides back from the trash only when they ask for it. The slide the user is working on is never removed.
- Change only the slides the request is about; say so when the request would need changes elsewhere.
- If the request cannot be fulfilled or is too ambiguous to act on (after checking whether the deck makes it clear), change nothing and explain why, or ask one precise question.
- Keep your messages to the user short and about their slides: what you changed, what you decided, what remains. No file paths, model internals or tool names; use the app's words for things (a theme is a Brand Kit to the user). When the user wants to see a slide or the result of a change, open the presentation in the chat (`open_presentation`) or give the editor link.

View saved version →

---
name: beautiful-ai-slide-elements
description: Model reference for Beautiful.ai slides, one document per slide element - the fields each template's root element and its nested elements expect in states[0], allowed values, limits and pitfalls. Use when building or editing a slide model for create_slide or update_slide, before rendering it with render_slide.
---

# Beautiful.ai slide elements

A slide is rendered by a tree of elements, and the slide model mirrors that tree: `states[0].primary` is the model of the template's root element, and every element the root nests reads its own part of that model (an item of `items[]`, a `childElement`, a text block, a media slot). This skill documents, per element, what that part must contain. The documents are in `elements/<Element>.md` (served as `beautiful-ai://skills/slide-elements/elements/<Element>.md`).

How to use it:

1. Start with `Slide.md`: the slide model as a whole (`template_id`, `states[0]` and its keys, the `layout` object).
2. Find the template in the table below and read its root element's document, then the documents in "Also read" for the parts you are going to write.
3. Read the building blocks the first time you write them: `TextElement.md` (every text field is a `{ blocks: [...] }` object), `ContentElement.md` with `Picture.md` / `Icon.md` (every image, logo or icon slot is a `content_type` + `content_value` pair), `CollectionElement.md` (every `items[]` array), `Header.md` and `SideBarContainer.md` (the header and the side tray that most templates allow).
4. Cross-check with a real model of the template (`get_slide_examples`) and the template's `defaultData` (`list_slide_templates`), build the model, render it (`render_slide`) and fix what the render reports before saving.

The documents describe the current model. Stored slides also carry computed caches (text `blockBounds`, `textStyles`, …) and bookkeeping fields: never author those, the documents say which fields are yours to write.

## Templates and their elements

| Template id | Root element | Also read |
|---|---|---|
| `action-number` | `ActionNumber.md` | |
| `agenda` | `Agenda.md` | `TextList.md` |
| `arrow_bars` | `ArrowBars.md` | |
| `authoring` | `AuthoringCanvas.md` | `AuthoringElementContainer.md`, then per element: `AuthoringShapeElement.md`, `AuthoringPathElement.md`, `AuthoringContentElement.md`, `AuthoringVideo.md` |
| `big-numbers` | `BigNumbers.md` | |
| `calendar-month`, `calendar-week` | `Calendar.md` | `VerticalTaskLists.md` (the week view) |
| `compare_circles` | `CompareBubble.md` | `CompareValuesCollection.md` |
| `compare_horizontal_bars` | `CompareHorizontalBar.md` | `CompareValuesCollection.md` |
| `compare_radial_bars` | `CompareRadialBar.md` | `CompareValuesCollection.md`, `RadialBarInfographic.md` (the ring) |
| `compare_vertical_bars` | `CompareVerticalBar.md` | `CompareValuesCollection.md` |
| `compare_vertical_pictograph` | `CompareVerticalPictograph.md` | `CompareValuesCollection.md`, `PictorialCharts.md` (the icon grid) |
| `connection_diagram` | `ConnectionDiagram.md` | `TextAndImage.md` |
| `contactus` | `ContactInfo.md` | |
| `countdown` | `Countdown.md` | |
| `cycle_diagram` | `CycleDiagram.md` | |
| `dashboard`, `chart_line`, `chart_column`, `chart_bar`, `chart_area`, `chart_waterfall`, `chart_pie`, `table-v2` | `Dashboard.md` | `GridLayoutContainer.md`, `LayoutContainerItem.md`, then per cell: `Chart.md`, `PieChart.md`, `Statistic.md`, `RadialBarInfographic.md`, `RadialBarChart.md`, `Table.md`, `TextAndImage.md` |
| `flow_chart` | `NodeDiagram.md` | `CalloutsCanvas.md`, `ConnectorGroup.md` |
| `gantt_chart` | `GanttChart.md` | |
| `headline2`, `section` | `Headline.md` | `TextFrame.md`, `PhotoCollage.md` (the images) |
| `horizontal-funnel` | `HorizontalFunnel.md` | `Ornament.md` |
| `horizontal-task-list` | `HorizontalTaskLists.md` | |
| `hub_and_spoke` | `HubAndSpoke.md` | `ContentItem.md`, `ConnectorGroup.md` |
| `image`, `collage` | `PhotoCollage.md` | `GridLayoutContainer.md`, `LayoutContainerItem.md`, `TextAndImage.md` (the cells) |
| `journey` | `Journey.md` | |
| `kanban` | `VerticalTaskLists.md` | |
| `logogrid` | `LogoGrid.md` | |
| `orgchart` | `OrgChart.md` | |
| `product_laptop` | `ProductScreenshot.md` | `TextList.md` |
| `pyramid`, `funnel` | `Pyramid.md` | |
| `radial_bar_chart` | `RadialBarChart.md` | |
| `roi_calculator` | `ROICalculator.md` | |
| `sequence`, `gears`, `puzzle` | `Sequence.md` | |
| `slicechart` | `SliceChart.md` | `Ornament.md` |
| `slidePlaceholder` | `SlidePlaceholder.md` | |
| `stackDiagram` | `StackDiagram.md` | `GridLayoutContainer.md`, `LayoutContainerItem.md`, `TextAndImage.md` |
| `step_boxes` | `ProcessDiagramBoxes.md` | `ProcessDiagram.md` |
| `step_chevrons` | `ProcessDiagramChevrons.md` | `ProcessDiagram.md`, `Ornament.md` |
| `step_circular` | `IconCircle.md` | `ContentItem.md`, `ConnectorGroup.md` |
| `swot_diagram` | `SwotDiagram.md` | |
| `target` | `Target.md` | `CalloutsCanvas.md` (annotations) |
| `team` | `Team.md` | |
| `text`, `long_bio` | `TextSlide.md` | |
| `textBoxGrid` | `TextBoxGrid.md` | `Ornament.md` |
| `textgrid_carousel` | `ImageCarousel.md` | `PhotoCollage.md`, `GridLayoutContainer.md`, `TextAndImage.md` (the cells) |
| `textgrid_photos` | `PhotoTextList.md` | |
| `textgrid_vertical_icons` | `IconTextGrid.md` | |
| `textlist` | `TextList.md` | |
| `thermometer` | `Thermometer.md` | `CalloutsCanvas.md` (annotations) |
| `timeline` | `Timeline.md` | `ContentItem.md` (the milestones), `ConnectorGroup.md`, `CalloutsCanvas.md` (annotations) |
| `timer` | `Timer.md` | |
| `title` | `PresentationTitle.md` | `TextFrame.md` |
| `user_testimonial` | `UserTestimonial.md` | |
| `vennDiagram` | `VennDiagram.md` | |
| `video` | `Video.md` | |
| `visual_percentage` | `PictorialCharts.md` | |
| `web-view` | `WebView.md` | |
| `wordCloud` | `WordCloudElement.md` | |
| `world_map` | `WorldMap.md` | |
| `xygraph` | `XYGraph.md` | `CalloutsCanvas.md` (annotations) |

## Building blocks

Shared by many roots; their documents are the reference for the fields they read wherever they appear.

- `Slide.md`: the whole slide model and its `layout` (header position, tray layout, footer, background).
- `Header.md` (`states[0].header`), `SideBarContainer.md` (`states[0].tray`, the side trays), `BottomTray.md` (the bottom tray and the element text block / attribution), `Footer.md`, `CanvasBackground.md` (`layout.backgroundColor` and friends).
- `BaseElement.md`: the fields every element reads; `CollectionElement.md`: how `items[]` work (ids, order, counts).
- `TextElement.md`: text blocks, text styles, list styles (bullets, numbers, checklists, icons); `TextFrame.md`: the framed text block of titles and headlines.
- `ContentElement.md`: a media slot and how `content_type` picks `Picture.md` (images and logos), `Icon.md` (built-in icons, see `list_icons`), `VideoElement.md`; `MediaElement.md`: the shared crop / scale / filter fields; `FramedMediaElement.md`: a media slot with a frame shape.
- `TextAndImage.md`: text with an optional image, used by dashboard cells, trays and several diagrams.
- `GridLayoutContainer.md` and `LayoutContainerItem.md`: the grid of cells behind dashboards, photo collages, stack diagrams and trays; the cell components `Chart.md`, `PieChart.md`, `Statistic.md`, `RadialBarInfographic.md`, `Table.md`.
- `CalloutsCanvas.md`: free-floating callouts and annotations (on flow charts, targets, thermometers, XY graphs, timelines and the slide itself), whose entries are described by `CalloutElement.md` (the shared contract and the `calloutType` table) and per type by `TextCallout.md`, `MarkerCallout.md` (bullet, numbered, lettered markers), `MediaCallout.md`, `MediaAndTextCallout.md`, `FlexCircleCallout.md` and `ShapeCallout.md` (boxes, diamonds, circles, pills); `AuthoringCanvas.md`: the free-form canvas, whose entries are `AuthoringElementContainer.md` (position, size, rotation, type) around one of `AuthoringShapeElement.md` (shapes and text boxes), `AuthoringPathElement.md` (lines and arrows), `AuthoringContentElement.md` (images and icons), `AuthoringVideo.md`, and the legacy `AuthoringSvgElement.md` / `AuthoringRadialBar.md`; `ConnectorGroup.md`: the connectors between items; `ContentItem.md`: the nodes (text with a dot, number, letter, icon or shape) of hub-and-spoke, icon circle and timeline diagrams.
- `Ornament.md`: the number / letter / icon badge on the items of step chevrons, slice charts, horizontal funnels and text box grids.
- `CompareValuesCollection.md`: the shared model of the five compare charts; `ProcessDiagram.md`: the shared model of the step diagrams.

Referenced files: 103 — file references are metadata, not package contents.

View saved version →

---
name: beautiful-ai-slide-templates
description: Which Beautiful.ai slide template fits which content, what each template's model looks like and how to switch a slide to another template. Use when choosing a template for new or restructured content, when the user asks for a different layout, or when a slide's content does not fit its template.
---

# Beautiful.ai slide templates

A slide's `template_id` picks the template that renders it; each template is rendered by one root element whose model is `states[0].primary` (the element reference is in the slide-elements skill, `beautiful-ai://skills/slide-elements`). `list_slide_templates` lists the templates with their description, category and tags, and gives one template's `defaultData` (what an empty slide of it starts with) and capabilities; `get_slide_examples` gives complete, real slide models of a template.

## Which template to pick

Where several templates are listed, the first is the one the app prefers, the rest are alternatives for when the first does not fit, the user asks for that look, or the deck already leans on the first: a template should not run three or more slides in a row or carry more than about a third of a deck (see "Varied across the deck" in the slide design skill), so when a slide's content points to a template the deck already uses that much, take the next one of its list or restructure the content for another entry below. The item counts are the ones the app's own slide builder keeps to so the slide stays readable; the element documents (slide-elements skill) give each element's hard limit (`maxItemCount`), which is sometimes higher but makes the slide crowded or report as not fitting. Above the count, shorten the content or pick the next template.

- Presentation title with optional subtitle, presenter names, company logo: `title`.
- A single headline, mission statement or slogan; a section break; a quote with an author; a one-person biography with a photo; free-form paragraphs or a key concept that is not a list (optionally with an image): `headline2`; a plain section divider: `section`.
- A list of text items or bullet points: `textlist` for bullets, numbered lists and checklists (up to 6 items in 2 columns, or 1 column next to a side image tray when there are at most 4; above 6 items 3 columns and no image), `textgrid_vertical_icons` for an icon list (max 6), `textBoxGrid` for text boxes / cards / columns (max 8, one row up to 4). A before/after comparison is `textlist` with two column headers, or `textBoxGrid`. Free-form text that is not a list: `text`; a long biography: `long_bio`.
- Agenda or meeting schedule: `agenda`.
- Statistics, factoids, metrics, KPIs: `dashboard` with `Statistic`, `RadialBar`, `Chart` or text (`TextAndImage`) cells (max 8 cells); a few big numbers with change indicators: `big-numbers`; one single big number: `action-number`.
- Line, column, bar or area chart of trends: `dashboard` with a single `Chart` item (the `chart_line`, `chart_column`, `chart_bar`, `chart_area` templates are that preset); waterfall / bridge chart: `chart_waterfall`; pie chart: `dashboard` with a `PieChart` item (one series, max 8 slices; `chart_pie` is that preset). Charts are cells of a `dashboard`, so a chart can share the slide with other cells.
- Comparing two or more numeric values: `compare_vertical_bars`, `compare_horizontal_bars` (up to 7 bars), `dashboard` with a `PieChart`; `compare_circles` and `compare_radial_bars` look best with at most 4 items; `compare_vertical_pictograph` (max 4) for icon-based comparison; `radial_bar_chart` (max 8) when a radial look is requested; `arrow_bars` for values shown as arrows; `slicechart` (max 8) for a value split into slices; `visual_percentage` for percentages as filled pictograms.
- Side-by-side comparison of up to 4 non-numeric items, plans or options, and pillars / principles / core values: `stackDiagram`.
- A table or pricing table: `dashboard` with a `Table` item (`table-v2` is that preset); a heatmap or color-coded grid: the same `Table` with a cell color per value.
- Linear process or sequence of 2–10 steps: `step_chevrons` (or `step_boxes`). Circular, looping process: `cycle_diagram` (max 6) or `step_circular`. Central concept with items radiating outward: `hub_and_spoke`. Flowchart with decisions and branches, or any diagram of freely placed nodes joined by connectors (a system or data flow, a decision tree, boxes with arrows between them): `flow_chart` (the node diagram: boxes, circles, diamonds, text and icon nodes you position yourself, with labeled connectors). Sources feeding into one target: `connection_diagram`.
- Ordered sequence shown as connected shapes (2–10 items): `sequence`, `gears`, `puzzle`.
- Pyramid, funnel, hierarchy or filtering progression: `pyramid`, `funnel`; slope / ramp / wedge across 3–10 ordered stages: `horizontal-funnel`.
- Timeline of events: `timeline`, `journey`. Monthly or weekly calendar of dated events: `calendar-month`, `calendar-week`. A countdown to a date: `countdown`; a timer for a break or exercise: `timer`.
- Tasks, project plans, sprints: `gantt_chart` when tasks have dates, `kanban` when they have statuses or lanes, `horizontal-task-list` otherwise.
- SWOT analysis: `swot_diagram`. Items plotted against two dimensions (effort vs impact, priority matrix): `xygraph`. Overlapping sets (2–4 circles): `vennDiagram`. Concentric rings / layered priorities: `target`. Org chart, reporting lines: `orgchart`. Countries or regions on a map: `world_map`.
- Team members with names, titles and photos: `team`. A customer quote with the person's photo: `user_testimonial`. A wall of logos (max 12): `logogrid`. Contact information (address, phone, email, socials, optional map): `contactus`. Several photos with captions: `textgrid_photos`; a photo carousel: `textgrid_carousel`; photos only: `collage` (or a single full-bleed `image`). Word cloud of weighted terms: `wordCloud`. Product screenshot in a device mockup with bullet points: `product_laptop`. An embedded video: `video`; an embedded web page: `web-view`. An ROI / savings calculator: `roi_calculator`.
- Free-form layout: `authoring` (called "Classic" in the app) is a blank canvas of shapes, text boxes, images, icons and lines you position pixel by pixel. Use it only for complex slides that need a lot of custom layouting and that no other template can express (an architecture diagram with many parts, a custom infographic, a layout the user sketched); everything else is better served by a smart template, which lays itself out and adapts to the content. When you do use it, expect to iterate on positions and sizes with the render until it looks right.

## Dashboards

A `dashboard` is a grid of cells: `primary.gridLayout` (`cols: 12, rows: 12`, one `{ x, y, width, height }` per cell) and `primary.items` with one item per cell, matched by position in the two arrays. Each item has a `componentType` of `Chart`, `PieChart`, `Statistic`, `RadialBar`, `RadialBarChart`, `Table` or `TextAndImage`, a `cellColor`, and the cell's content in `childElement`. A dashboard can hold several cells at once, which is often the nicest answer when the user asks to add a number, a takeaway, a second chart or an image next to a chart: a full-width chart with two text cells under it, a chart beside a column of statistics, a pie chart with its key figure next to it. Keep it to a few cells (the app never builds more than 8) so each stays readable, and when adding a cell add both the grid cell and the item (and shrink the neighbors to make room). The `dashboard` examples show many such combinations; the element reference has the exact model (`Dashboard.md`, `LayoutContainerItem.md`, `Chart.md`, `PieChart.md`, `Statistic.md`, `Table.md`, `TextAndImage.md`).

## Switching templates

Switch a slide to another template when the user asks for it ("turn this into a bar chart", "make this a timeline"), when the request clearly cannot be fulfilled with the current template, or when splitting or combining slides (each resulting slide gets the template that presents its content best).

- To switch: set `template_id` to the new template and rebuild `states[0]` for it, carrying over the user's content (title, text, numbers, images) where it fits. The element reference (the root element's document in the slide-elements skill) says what each field means and what is required; for the shape and style to copy, prefer a slide of that template already in this deck (it fits the theme and the deck's style), then a real example (`get_slide_examples`), then the template's `defaultData` (`list_slide_templates`).
- Keep `layout` fields the new template supports (header position, tray) and drop the ones it does not (check its capabilities: `allowHeader`, `availableTrayLayouts`, `allowColorBackgrounds`).
- Render before saving, as for any change, and mention the template switch to the user.