# Google Slides reference

**As a first step, before you build, rewrite or restyle any slide, in a new deck or an existing one, you must read the design rules below in full. Before you add or change a chart, also read `references/charts.md`.** After the rules come the Slides connector's tools and how to carry out the rules with them.

# Slide design

When the user asks for something specific, such as a slide count, exact wording, a color or a layout, do that; these rules decide what the user left open. The rules for charts are in [charts.md](charts.md); the rules for the words on slides are under "Writing slide copy" below.

Your slides should be indistinguishable from a top strategy consultancy's deck, an investment bank's pitch book, or a front-page business story.

## Deck structure

- **One message per slide.** A deck goes theme by theme, message by message. Putting revenue next to retention on one slide, unless they are related, gives the reader two things to work out instead of one.
- **The titles tell the story.** Someone reading only the slide titles should be able to follow the whole deck.
- **A common structure is the pyramid:** the main message up front, an executive summary that previews the sections, the sections themselves, then a conclusion, usually with next steps that act on the findings.
- **Match the structure to the size of the deck.** A short deck might not need an introduction and a conclusion; a long deck might need dividers between topics.
- **Build toward what the deck is for:** a decision, consensus, a celebration, resolving a disagreement, or opening a discussion.
- **Build for how it will be used.** A live deck gets narration and possibly discussion; a pre-read has to carry the whole narrative itself. An executive audience in a live meeting needs few words and highly visual slides. Detailed, word-heavy slides are sometimes right for subject-matter experts or for a deck read offline. Analytical reports lean on charts and tables, with the titles carrying most of the narrative.
- **Size a live deck to the talk:** about 1.5 to 2 minutes per slide, with time left for questions if there will be any.

An example outline; the deck's own subject decides the titles:

1. Title slide: "Q3 Cost Review: Reducing Logistics Spend by 15%", with the presenter, date and audience when you know them.
2. Executive summary: logistics costs grew 22% year over year, driven by three controllable factors; fixing them saves $4.2M a year. Previews the deck and the recommendation.
3. "Logistics spend outpaced revenue growth 3:1 since Q1": spend against revenue, with the gap opening in Q2.
4. "Three drivers explain 80% of the increase: carrier rates, expedited shipping, and warehouse overtime": the increase broken down by driver.
5. "Two carriers raised rates 18% while volume stayed flat": rate change by carrier against volume share.
6. "Expedited orders doubled, mostly from late order entry, not customer demand": the causes of expedited volume.
7. "Overtime is concentrated in two sites with outdated staffing models": overtime hours by site.
8. "Three fixes, ranked by savings and effort": renegotiation, order cutoff enforcement and staffing changes compared.
9. "Recommendation: pursue all three fixes, starting with carrier renegotiation for fastest payback": savings and payback timeline.
10. Next steps: owners, milestones, and the decisions needed from this audience by the end of the month.

## Designing a slide

Design each slide before you build it, in this order: the message, the evidence, the layout. The layout comes last because it depends on what the slide has to hold.

### Message: the title

The title carries the slide's message, and most slides need one. There are three conventions for slide titles:

1. **Story:** one sentence that tells the reader the main takeaway: "German revenue grew 12% in 2025, three times the US rate". Active voice, a specific subject, the number in it when there is one, at most about fifteen words and never more than two lines; on a 10-inch-wide slide, two lines at 32pt hold about twelve words. Not "German market overview", and not "We analyzed the German market".
2. **Label only:** the general theme of the slide: "German revenue in 2025".
3. **Label and story:** "German revenue" on the first line and "German revenue grew 12% in 2025, three times the US rate" on the second. This shows both the theme and the takeaway.

Write every title in the deck the same way. If the deck already has a convention, use it. Otherwise default to story titles on content slides.

Structural slides (the title slide, agenda, executive summary, section dividers, next steps, appendix) take a label title whatever the deck's convention. They do not carry a single finding, so a story title reads as forced: "These are the four topics we will cover" is worse than "Agenda". The executive summary's takeaway goes in its body, not its title.

### Evidence

The content's only job is to make the reader believe the title. Before choosing a layout, decide what will do that: text, a graphic, an image, a table, a chart, footnotes, or a combination, and roughly how much of each. Most slides need one main element and a little supporting text:

- If the title is a number or a comparison, the main element is a chart ([charts.md](charts.md) picks the type).
- If it is a structure or a process, a graphic.
- If it is a claim with several reasons, short text, or a row of icons with labels when the reasons are parallel.

### Layout

Match the company's style and branding, as shown by the slide master, the finished slides already in the deck, and anything the user has said. Add new slides from the master's layouts so they inherit its fonts, sizes and positions. If no layout fits your design, start from the closest one, so the slide keeps the deck's background and fonts, and build from there.

With the message and the evidence decided, choose the layout that holds them. A text-heavy slide might suit a simple title-and-body layout; a highly visual slide might need no body text, only a graphic with the words built into it. Some common layouts:

- **Big text.** One message and nothing else. Rare; right for a quote, or a big message or number that deserves its own page.
- **Title on top and content below, or title on one side and content on the other.** Good for an agenda, an executive summary, or a key chart that speaks for itself and needs no commentary.
- **Title on top, a visual and commentary below.** The most common slide: a left/right split, with the visual on one side and the commentary on the other. A chart gets at least 60% of the width; another visual can take half or two-thirds.

Other layouts are fine if they follow the deck's design standards. When the deck has layouts to choose from, use one with text placeholders for any slide that has text, so the text takes the master's fonts and sizes; keep the blank layout for slides that are entirely visual, such as a full-bleed image or a diagram built from shapes. Don't give three or more slides in a row the same layout unless they form a deliberate series, such as one slide per team member.

## Starting from the deck's design

**A deck with its own template or theme.** Keep its design. New content uses the theme's colors exactly, and new slides use its layouts. If the user asks for a restyle, change the theme and the master rather than restyling slide by slide. A theme change does not reach text and shapes that carry their own fixed colors, which most real decks have, so replace those colors as well.

**A deck styled slide by slide on the default theme.** Someone built the deck by styling slides directly and never changed the master. The existing slides are the design system: don't create or change a master. Read a representative finished slide (background, fonts, sizes, colors, how shapes are styled) and make new slides match it, applying the styling on each slide the way the existing ones do, since the master has nothing to inherit.

**A new or blank deck.** Set the design up in the master before adding any slide: theme colors, a heading font and a body font, the background, the default text colors, and a bold title style. Text color is set in the master's text styles, not shape by shape. Let the slides inherit it, so the deck stays consistent and a later restyle is one edit. Anything that belongs on every slide, such as a background or a logo, goes on the master, never copied onto each slide. If the deck is for a company, match its brand; look up its brand guidelines if they are not obvious. Otherwise use what the user told you, and fill in the rest. Unless the palette you pick below says otherwise:

- an off-white background with no warm tint (such as #FAFAFA) and near-black text, rather than pure white and pure black;
- one or two accent colors at the same brightness;
- a look that fits this deck: a quarterly review, a pitch and a workshop deck should not look the same, and neither should two decks you make in a row.

Do not default to a dark-blue background. Pick a palette that matches the content:

- **Corporate neutral:** white or light gray background, one saturated accent, generous white space. For reports and proposals.
- **Warm editorial:** cream background with terracotta or olive accents. For case studies and narratives.
- **Bold startup:** near-white background with one high-contrast accent. For launches and pitches.
- **Academic muted:** paper-white background, steel blue and muted green, serif headings. For research and teaching.
- **Playful bright:** warm light background with several saturated accents. For events and creative work.

A cream or beige background (such as #F5F5DC, #FAF0E6, #FAEBD7 or #FFF8E1) belongs only to the warm editorial look; never use one as a default. A dark background suits the title slide and section dividers.

**Finished slides and rough slides.** Not every existing slide is a style reference. What makes a slide rough is unfinished formatting, not its words: text boxes left empty or added in the stock font and size rather than the deck's, a bare box standing in for a chart, fonts and colors that match nothing else in the deck. A title that is just "draft", "WIP", "TBD" or "placeholder", or a sticky note on the slide ("update numbers before Friday"), is a reason to look closer, not proof. Filler text or an unfilled placeholder on a designed template slide does not make it rough, and a title slide or divider that is meant to look different is not rough either. Take the deck's conventions from the finished slides: the ones styled deliberately, that agree with each other when there is more than one. If every slide is rough, there is no deck style to match: take fonts and colors from the master when the deck has its own rather than the default one, follow this guide for the rest, and tell the user so in one line. Rough slides are still slides to fill in or fix when asked; they are just not the style to copy.

## Text

Keep slide text brief. If you have more than one sentence, use bullet points.

- **Titles are bold**, in the heading font, and larger than any other text on the slide except a big number. A regular-weight title reads as body text, and the slide loses its hierarchy.
- **Structure for readability.** Keep parallel structure (all fragments or all sentences). Bold the words a reader needs to get the message. Keep each bullet to two lines.
- **Be direct.** Cut filler ("in order to", "key", "very").
- **Use active, concrete language.** Specific nouns and plain verbs: "customers left", not "we experienced customer attrition". Name the actor in every sentence.
- **Be consistent.** The title and the content must agree; if they don't, one of them is wrong.
- **Don't describe visuals.** Bullets add what the visual cannot show. If everything in a bullet is visible in the chart, cut the bullet.
- **Give data context.** Pair every standalone number with a comparison: a prior period, the plan, or a competitor. Round to the precision a decision needs ($4.2M, not $4,183,207), and use ratios or multiples ("doubled", "1 in 5") to make the size of a change clear. Keep formatting, units and abbreviations the same on every slide.
- **Claims must be defensible.** Every assertion must trace back to a verifiable data point or a clear, logical derivation. If you cannot find a direct path to the evidence, leave the claim out. When the user asks for figures you don't have ("add our financials"), ask for them; never invent figures.

When a slide needs a lot of text, break it up with callouts or a supporting visual.

## Graphics

A well-chosen graphic shows structure at a glance that a paragraph would take a while to describe: a diagram, flow chart, timeline, process map, org chart, funnel, pyramid, 2×2 matrix, Venn diagram, cycle, roadmap, before-and-after comparison, or icon-and-label layout.

- **Shape the graphic like the idea.** A sequence gets a flow or a timeline, a hierarchy a pyramid or an org chart, overlapping categories a Venn diagram, a tradeoff a 2×2, a recurring process a cycle. If the idea has no inherent structure, don't force it into one.
- **One idea per graphic.** If a graphic needs a paragraph to explain, simplify it. Cut elements until the takeaway is visible in a few seconds; details move to supporting text or a follow-up slide.
- **Label elements directly, not in a legend.** Put short labels (2–5 words) on or next to the elements themselves. Longer explanations live outside the graphic.
- **Give each color, shape and size one meaning,** the same everywhere it appears, within the graphic and across the deck. Use color to mark the element that matters, not to decorate; keep everything else neutral.
- **Flow left to right or top to bottom.** Arrows show a relationship (sequence, causation, dependency), never decoration, and all flow in one direction.
- **Size and space equal elements equally.** Equal-weight elements get equal sizes and even spacing, and alignment is exact, not approximate.

## Images

An image must carry information. A generic stock photo is worse than empty space. Use an image when it is the evidence: a product shot, a screenshot, a place, a person, a before and after. Otherwise leave it out.

- Viewers look where a pictured person is looking, so a person in a photo should face the content, not the edge of the slide.
- A photograph can fill its frame and be cropped. A screenshot or a diagram is shown whole, at its own aspect ratio, with no text laid over it.
- Text on top of a photo sits on a card or a darkened band so it stays legible.
- An image with a transparent background needs a backdrop that contrasts with its content, so its edges read.
- Never stretch or squash an image to fit a frame: crop it, or letterbox it on a neutral background.

## Icons

A small icon beside each point gives the reader something to scan before they read, and it is the simplest way to fix a slide that would otherwise be a wall of text. Use icons when a slide has three to six parallel items (features, categories, steps, risks, teams) and nothing in the content calls for a chart or a diagram: a row of icons with labels, or a grid of icon cards, reads at a glance where four bullets do not. Icons also help a text-heavy slide whose text you cannot cut, by giving each block an anchor.

- One icon per point, and the icon means the point: a shield for security, a clock for timing, a chart for growth. An icon that needs its label to make sense is decoration; leave it out.
- Every icon on a slide, and across the deck, is the same style (all filled or all outline), the same size (30–50pt beside text; larger only for a single hero icon), and aligned on one row or grid with even spacing, to the left of its label.
- Color icons in the deck's accent, or a neutral, with enough contrast against the background; not a different color per icon. An icon in a small filled circle of the accent color works well.
- Put a short label (2–5 words) next to each icon; the icon does not replace the label.
- Take icons from an icon set, never emoji, which render differently on every platform. When no icon set is available, use a filled circle with one simple symbolic shape or a number on it, and keep the same rules.

## Tables

A table is right when the reader looks up specific values across a few dimensions, or compares a small set of items on several attributes. If one comparison is the point, that is a chart, not a table. Keep the styling light so the numbers read first.

- **Borders:** thin (1pt or hairline), in the deck's light border color (about #E0E0E0 on a white background), between rows only, with one border under the header row. No column borders. A full grid looks like a spreadsheet, not a slide.
- **Header row:** bold text, no fill. That is the whole treatment. A colored header bar is the default table style in most slide tools and reads as unstyled.
- **Row labels (first column):** bold and left-aligned.
- **Alignment:** text columns left, number columns right so the digits line up. Put the unit on every value ("$42M", "61%"; a plain count such as 355 needs none), not in the row or column header, the same rule as bar labels. One number format per column, or per row in a table of metrics by period.
- **Highlighting:** the row or column that is the message gets a light tint of the deck's accent color; nothing else does. For a heat map, one hue from light to dark, never the red-yellow-green default. Bolding one cell is fine.
- **Density:** at most about six columns and eight rows on a full slide; past that, split the table or move it to an appendix. A cell that needs three or more sentences, or more than about 40 words, is too dense: shorten it to one sentence, move the detail to a footnote or a text box, or split the table.
- **Size:** text in a table you create is at least 14pt; in an existing dense template, keep the template's sizes. Give rows generous height, about 28–32pt for a one-line row and 48–56pt for a two-line row, and no zebra striping. Check that the whole table fits above the bottom margin before you build it; if it doesn't, split it across slides.
- Build it as a real table, never out of text boxes.

People read tables and charts differently. A table is read across the rows, then down, so it suits an audience where each person looks up their own row, such as regional sales where each reader finds their region. In a live presentation a table hides the point in detail. A full table in the appendix serves pre-reads and questions. Charts make a point faster and suit executive audiences. Use charts for the message and tables for reference.

## Footnotes and sources

Footnotes do two jobs.

The first is citing sources. If a number came from external research or an internal data set, put a superscript number immediately after the claim ("…grew 12%¹") and a footnote at the bottom of the slide starting with the same number, specific enough that the reader can find the original. Include the publisher and the date, because a market-size figure from 2021 and one from 2025 are different claims. Put hyperlinks behind the reference text rather than pasting raw URLs. Numbering restarts on each slide; if the deck has a sources appendix, number continuously across slides instead.

The second is methodology and caveats: detail the main message doesn't need but that matters if someone challenges the analysis, such as sample sizes, exclusions, exchange rates, or how a term like "active user" is defined. Put methodology and caveats first, then the provenance, starting "Source:".

Keep the citation format the same across the deck. Footnotes sit at the bottom of the slide at 10–12pt in a muted color. If everything on the slide came from one report, a single "Source: [report, year]" line replaces per-item footnotes.

Cite only sources you actually have, whether the user gave them to you or you read them yourself. Do not add a "Prepared by" line, a confidentiality notice, or a date outside the title slide unless the user asked for it. A source you did not have is a fabricated citation, and a chart of the user's own numbers needs none.

## Size, spacing and placement

**Visual hierarchy and size.** The reader's eye should land on the title first, then the main visual or the bold text, then the detail. Size and weight control that order. Slides are read from the back of a room, so sizes that look right on a web page are too small here. On a standard 16:9 slide:

| Element | Size |
|---|---|
| Slide title | 32–40pt bold, at least about 1.75× the body |
| Section header | 24–28pt |
| Body text | 16–18pt |
| Captions | 14pt |
| Footnotes and source lines | 10–12pt, muted |

Footnotes, source lines, the second line of a chart label, a chart's year row (11pt) and chart callouts (11–12pt) are the only text you add below 14pt, with one exception: a template whose own body text is smaller, which is common in banking and consulting decks. Match the template, since consistency with it matters more than the floor, but don't go below 10pt. Set sizes explicitly instead of leaving them to defaults.

**Fitting text.** If the content doesn't fit at these sizes, there is too much content for one slide. Don't shrink text you wrote to make it fit: resize the container, cut words, or split the slide. Text the user wrote keeps its wording; it may go modestly below its original size, and if it ends up under 10pt, tell the user. Never leave text overflowing its box or cut off.

**Use the slide.** Keep a margin of about half an inch on every side. On a slide you lay out, fill most of that area (about 70% or more of it), use most of the width, and reach toward the bottom margin rather than clustering in the top half. Open space under a short list is fine; a slide that is all margin is not. When you edit an existing slide, the user's layout is intentional; don't rearrange it to fill space.

**Spacing.** Leave 0.3–0.5 inches between content blocks, and use the same gap throughout the deck.

**The title band.** Measure where the title ends before placing content under it, since the title's height varies by template, and start the content at least 10pt below it.

**Insets.** Text on a shape or a card is inset 10–15pt from the shape's edges. Text touching the edge of its container is the most common small layout defect.

**Alignment.** Align body text left rather than centering it, so the slide has a clean edge. Title alignment follows the layout: centered on the title slide and section headers, left-aligned on content slides. A template's own title alignment always wins.

## Clutter, emphasis and variety

**Clutter.** Every element on a slide costs the audience attention. Leave off anything that does not add more than it costs, and do not fill white space for its own sake.

**Highlighting when a slide has to be dense.** Sometimes a slide or a chart has to be complicated. You can still get the message across by directing attention. If something needs to stand out and no legend has already assigned the colors, use color for it. Contrast also shows a shift, such as shading where actuals turn into projections. You can circle related elements, or put a callout on the one item with a non-obvious takeaway; draw it as a plain box and line, because the stock callout shapes look bad (a callout on a chart follows Callouts in `references/charts.md` instead, with no box). On wordy slides, bold the words someone glancing at the slide needs; they can read the full sentences if they want to.

**Variety.** The default failure is a deck where every slide is a title and a block of bullets. Nobody in the room reads a paragraph off a screen, and twelve slides with the same shape blur together. Bullets should be the minority. If more than about a third of the deck is coming out as bullet slides, some of those slides contain a number or a comparison that should be a chart, and some are two slides squeezed into one. A slide holds one message and, if it is a bullet slide, a few short lines, usually three or four. A slide that needs a paragraph is a pre-read page, not a slide: split it, or move the detail to the appendix. Vary the rhythm on purpose: a big number after two charts, a dark divider between sections, an image slide to open a section. Use different kinds of slides, and build each kind the same way every time.

## Writing slide copy

These rules cover the words you put on slides: titles, bullets, labels, callouts and footnotes.

Slide copy should read as though a person wrote it. When readers think something was written by AI, they judge it as sloppy and stop trusting it, whatever the content. They make that judgment from a set of common indicators, listed below, so take extra care to keep them out of your writing.

- Say what is true without first denying something else. "Revenue grew 12%, three times the US rate," not "This isn't a growth story, it's a market-share story." Do not open a title or bullet with "Here's the thing" or "The real story is". A title can be a question when the slide is there to raise it; when the slide answers it, the title is the answer.
- Match the number of bullets, examples, and adjectives to the content, not to a default of three. Two drivers get two bullets; five get five or a table. A list of exactly three ("fast, reliable, and scalable") usually means the third item was added for rhythm, not because there were three things to say, and readers read it as filler.
- Do not use a metaphor where a literal word will do. If a plain description exists ("the same construction," "the same pattern," "slowed," "fell"), use it. Metaphors are for when the literal version would be longer or less precise, which is rare in analytical writing. Test: if the metaphor can be replaced by a plain word without losing meaning, replace it. A metaphor makes the reader translate it back into the plain claim and carries meaning you did not choose. The ones that appear most are "north star", "move the needle", "double-click" (meaning look closer), "unpack", "journey", and "landscape" (meaning a market). Common ones in business writing: "moat", "headwind", "drag" (meaning a cost on results), "safety net", "clears the bar", and "land" meaning finish or total ("lands $4.4k under budget"). Examples:
  - Bad: "The ones it has are the same species." Good: "The ones it has follow the same pattern."
  - Bad: "A coordinated digestion pause would be visible immediately." Good: "If several large customers cut capex in the same quarter, it would show up in the next guide."
  - Bad: "Architecture transitions compressed margin on the way in and expanded it on the way out." Good: "Gross margin fell during the Hopper-to-Blackwell ramp and recovered once Blackwell shipped at volume."
  - Bad: "The lever that unlocks growth." Good: "The pricing change is what makes the target reachable."
- Cut words that claim importance without giving evidence: "genuinely", "truly", "actually", "clearly", "significantly", "robust", "leverage", "delve", "actionable insights", "learnings". Where one of them stood in for a fact, put the fact there ("margins fell 4 points", not "margins fell significantly"); otherwise delete it.
- Use full stops and commas, and a colon before a list. No emoji on slides.
- Use em dashes sparingly: at most one in a paragraph, and none in a heading, a title, or between a bold label and the text after it. Several em dashes in one paragraph is one of the first things readers use to spot machine writing. In place of one, use a comma, a colon, parentheses, or a new sentence, not an en dash or a spaced hyphen.
- On content slides, write headings as findings (see "Message: the title" above), not as a description of your process: "Europe missed plan by $1.9M", not "What I changed" or "The hard part". Structural slides (agenda, executive summary, next steps, appendix) keep a plain label.
- Keep the conversation out of the deck. When the user asks for a shorter or more formal version, make it shorter or more formal; do not title it "Executive Summary (Condensed)" or open with "Updated per your feedback" or "this streamlined deck focuses on". The audience did not see the request, so those lines mean nothing to them. Say what changed in your reply, not in the deck.
- Write in the language variety the deck already uses (US or UK English, for example), or the user's when the deck has no text yet; never mix varieties in one deck.

## Common mistakes

- **Accent lines under titles.** These are a hallmark of AI-generated slides; use white space or a background color instead.
- **Decorative color bars or accent stripes:** header or footer bars across the slide, vertical stripes down one edge, thin stripes along one edge of a card, single-side borders on rectangles. They read as filler. To set a card apart, use a light background tint, a soft shadow, or an icon.
- **Low contrast.** Icons and text need strong contrast against their background: no light text on a light background or dark text on a dark one.
- **Styling one slide and leaving the rest plain.** Apply the design to every slide, or keep every slide simple.

# Slides connector

This part covers the Slides connector: `read_presentation`, `read_slide_page`, `read_slide_page_thumbnail`, and `update_presentation`. Most of the behavior here was tested against Google's Slides API; the rest was seen through the connector, and a few rules have not been checked yet.

## Applying the design rules

The design rules are above. What follows is specific to building with `update_presentation`.

- **Building a new deck.** When you build a new deck with `update_presentation`, use two or three calls, not one call per slide. In the first call, fill the title slide's `i0` and `i1` placeholders (`insertText`, appended to `build`'s output) and add the first content slide with `build`, so the user has something to look at early; add the remaining slides in one or two more calls. Each call holds everything for its slides in one batch. Read the deck before every call, the first included, and run `build` with that read's `revisionId` so every call is guarded (see "Read before you edit, and guard the write" in SKILL.md); the read that checks one call's slides can supply the next call's `revisionId`.
- **Titles on the default page.** The type sizes above apply on the default 10 in wide page too, where a title line holds fewer words than on a wider slide. By `build`'s estimate, a bold 32 pt line in a 9 in wide box holds about 38 characters, so two lines hold about 75 characters, roughly twelve words. A two-line title needs a box about 1.3 in tall at 32 pt; if it needs more than two lines, cut words rather than shrink the font. `build` warns when a title needs more lines than its box holds.
- **Layouts.** `build` creates each new slide on the predefined layout the spec names (`BLANK` when it names none) and draws its own text boxes, without filling the layout's placeholders. For a slide with a title and text in a deck that has layouts, create the slide with the placeholder recipe in Edit recipes, so the title and body take the master's style, then add tables, cards and shapes with `build` and `"existing": true`. Use `build`'s `BLANK` slides for slides that are entirely visual, as the layout rules above say.
- **Masters.** This reference has no tested recipe for changing a deck's master or theme, so skip the master steps in "Starting from the deck's design". On a new deck, give the elements you add the same fonts and colors on every slide, and put a background or logo on each slide that needs it. For a restyle, change each slide directly and tell the user the master is unchanged.
- **Warnings.** `build` warns about text under 14 pt unless it is a footer line: a box at most 0.5 in tall that ends within 0.8 in of the bottom of the slide. The design rules allow some other small text: the second line of a chart label, a chart's year row and callouts, a source line that isn't a footer line, and text matched to a template's smaller size. Those warnings can stay; fix every other warning.
- **Fonts.** Use Google fonts, such as Arial, Roboto, Lato, Montserrat, or Merriweather.
- **Tables.** `"header": true` bolds the header row. Leave `header_fill` and `header_color` unset, because the design rules give the header row bold text and nothing else, and set `"col_align"` to `"END"` for number columns. Bold the first column with `updateTextStyle` and `cellLocation` (Tables in Edit recipes), appended after `build`'s requests, since `build` sets every cell outside the header row to not bold. This reference has no tested way to set the row-only borders the design rules ask for: `build` sets no borders, and no border request has been tested through the connector, so a new table keeps the theme's default borders.
- **Charts.** A linked Sheets chart takes its look from the chart in the Sheet, so build it there to the standard `references/charts.md` picks: the deck's chart style when its charts share one, otherwise the house standard. Under the house standard, leave the chart's title off and put its label in a text box above it on the slide. This reference has no tested way to label only chosen points in a Sheets chart, or to draw line-end names, a year row, callouts or growth arrows there, so put those on the slide as text boxes and shapes, and check their positions on the rendered slide.

## Create

Choose a route based on the deck.

- **A designed deck:** load the `pptx` skill, build a .pptx with it, and check it with that skill's QA steps. Then upload it with Drive `create_file` and let Drive convert it. The file's whole content goes inside the tool call, so the upload is slow and can fail for a large deck. You get the `pptx` skill's design tools and QA. Conversion can change fonts and spacing, so run the QA steps below on the result.
- **A few slides, or slides added to an existing deck:** create a blank presentation with Drive `create_file` and `contentMimeType: "application/vnd.google-apps.presentation"` (or open the existing deck), then build with `update_presentation`, using `slides_helper.py build` below. A new deck starts with one title slide whose placeholders are `i0` (title) and `i1` (subtitle). Fill them, or delete the slide with `deleteObject`.

## How a slide is addressed

- **Units are EMU:** 914400 per inch, 12700 per point. The default 16:9 page is 9144000 x 5143500 EMU (10 x 5.625 in). Read `pageSize` before placing anything; some decks are 4:3 or custom.
- **An element's real size is `size` times its transform scale.** The API often stores a 3000000 x 3000000 base size and scales it: a title that renders 9.32 in wide can report `size.width` of 3000000 (3.28 in) with `scaleX` 2.84. Position is `translateX` / `translateY`, the top-left corner. Always multiply before reasoning about layout.
- **A table's size comes from its columns and rows.** A table's `size` field is not its rendered size. Sum `tableColumns[].columnWidth` and `tableRows[].rowHeight` instead. Rows grow taller to fit their text, so a table can end up taller than requested.
- **Object IDs are yours to choose.** When creating a slide or element, set `objectId`: 5 to 50 characters, unique in the deck, letters, digits, `_`, `-` and `:`, starting with a letter, digit or `_`. Name them by slide and role (`s4_title`, `s4_chart`) so later requests in the same batch, and later turns, can target them.
- **Text inside a shape or table cell has its own index,** starting at 0. `textRange: {"type": "ALL"}` covers all of it and is the safest target for styling. `insertText` without `insertionIndex` inserts at 0, before the existing text; to append, pass the text's length in UTF-16 units, not counting the final newline the read shows. Unlike Docs, Slides gives no error for an index inside an emoji such as 🙂: it moves an insert past the emoji and widens a delete to the whole emoji.

## Read

- **Always pass a field mask.** An unmasked read returns every layout and master: 150 KB for a three-slide deck. This mask returns what editing and the helper need, about 5 KB for the same deck:

```json
["revisionId,pageSize,layouts(objectId,layoutProperties.name),slides(objectId,slideProperties.layoutObjectId,pageElements(objectId,size,transform,shape(shapeType,placeholder,text.textElements(textRun(content,style.fontSize,style.bold))),table(rows,columns,tableColumns,tableRows(rowHeight,tableCells(location,text.textElements.textRun.content))),image.contentUrl,sheetsChart(spreadsheetId,chartId),line.lineType,elementGroup.children.objectId))"]
```

  Unlike the Sheets connector, Slides accepts parentheses in masks.
- **One slide:** `read_slide_page` with a `pageId` and a mask starting at `pageElements(...)`.
- **Text only:** Drive `read_file_content` gives the deck's text compactly when you only need to know what it says.
- **Outline with real geometry:** save the masked read to a file and run:

```
python <skill>/scripts/slides_helper.py outline deck.json
[3] slide s4_slide  layout BLANK
  s4_title   shape  x=0.50 y=0.35 w=9.00 h=0.70  TEXT_BOX 32pt 'Revenue grew 42% year over year'
  s4_table   table  x=3.70 y=1.30 w=5.80 h=1.20  2x3 first row ['Metric', 'Q1', 'Q2']
  s4_note    shape  x=0.50 y=4.60 w=4.00 h=0.30  TEXT_BOX 12pt 'This footnote is...'  !! TEXT MAY OVERFLOW (needs ~0.80 in)
```

  It flags elements off the page, boxes that overlap, text that probably overflows its box, and empty placeholders. "inherited size" means the font size comes from the layout, so the overflow check is skipped for that box. An overlap flag means the boxes intersect; check the render to see whether the content actually collides.

## Build slides

Build new slides and elements from an inch-based spec with `slides_helper.py build`. It converts to EMU, sets unscaled transforms, checks IDs, styles text, fills tables, and warns about text that won't fit.

```json
{"slides": [
  {"id": "s4_slide", "layout": "BLANK", "index": 3,
   "elements": [
     {"id": "s4_title", "type": "text", "x": 0.5, "y": 0.35, "w": 9, "h": 0.7,
      "text": "Revenue grew 42% year over year", "size": 32, "bold": true, "color": "#1F2937"},
     {"id": "s4_card", "type": "round_rect", "x": 0.5, "y": 1.3, "w": 2.8, "h": 1.6,
      "fill": "#E8EEF7", "text": "ARR\n$4.2M", "size": 24, "bold": true, "color": "#1F3864", "align": "CENTER"},
     {"id": "s4_table", "type": "table", "x": 3.7, "y": 1.3, "w": 5.8, "size": 14,
      "rows": [["Metric", "Q1", "Q2"], ["ARR", "$3.0M", "$4.2M"]],
      "header": true, "col_align": ["START", "END", "END"]}]},
  {"id": "s3_slide", "existing": true,
   "elements": [{"id": "s3_label", "type": "text", "x": 0.5, "y": 2.1, "w": 4, "h": 0.5,
                 "text": "of pilots converted", "size": 16}]}]}
```

```
python <skill>/scripts/slides_helper.py build spec.json --revision <revisionId> [--page 10x5.625]
```

The output is the full `requests` and `writeControl` for `update_presentation`; warnings go to stderr. Fix every warning before sending, apart from the small-text ones that "Applying the design rules" allows. Slides never shrinks text to fit, so a warned box will spill. Build also warns about text boxes and shapes under 14 pt that aren't a short footer line at the bottom of the slide, and about typed bullet marks. Element types: `text`, `rect`, `round_rect`, `ellipse`, `table`. On a text element, `"bullets": true` makes each line a bullet and `"space_below"` adds points after each paragraph (about 8 to 10 points suits bulleted lines). On a table, `"col_widths"` sets each column in inches (give a label column more room than number columns) and `"col_align"` aligns each column (`"END"` for numbers). Set `"existing": true` to add elements to a slide that already exists. Pass `--page` when the deck isn't 10 x 5.625 in.

## Edit recipes

Each recipe is part of one `update_presentation` call. Send the call with `writeControl.requiredRevisionId` from a read taken after your last write, unless every request in it comes from **Change text everywhere**.

**Change text everywhere.** `replaceAllText` with `containsText: {"text": ..., "matchCase": true}` needs no IDs. Limit it with `pageObjectIds` to change only some slides. Use `{{placeholders}}` in templates for this.

**Replace one box's text.** `deleteText` with `textRange: {"type": "ALL"}`, then `insertText` at `insertionIndex: 0`. The new text keeps the box's style. Deleting from an already-empty box fails, so check the read first.

**Use a layout's placeholders.** `createSlide` with `slideLayoutReference: {"predefinedLayout": "TITLE_AND_BODY"}` and `placeholderIdMappings` naming the placeholders you'll fill:

```json
{"createSlide": {"objectId": "s2_slide", "insertionIndex": 1,
  "slideLayoutReference": {"predefinedLayout": "TITLE_AND_BODY"},
  "placeholderIdMappings": [
    {"layoutPlaceholder": {"type": "TITLE", "index": 0}, "objectId": "s2_title"},
    {"layoutPlaceholder": {"type": "BODY", "index": 0}, "objectId": "s2_body"}]}}
```

Then `insertText` into `s2_title` and `s2_body`. Placeholder text takes the theme's font and size, which keeps the deck consistent. Predefined layouts include `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `BIG_NUMBER`, and `BLANK`. A deck with a custom theme may name its layouts differently; the masked read lists them, and `slideLayoutReference: {"layoutId": ...}` picks one by ID. Fill or delete every placeholder you create, because an empty one shows prompt text in the editor.

**Bullets.** Insert lines separated by real newlines, then `createParagraphBullets` with `textRange: {"type": "ALL"}` and `bulletPreset: "BULLET_DISC_CIRCLE_SQUARE"`. Typed "- " is text, not a bullet, and `createParagraphBullets` keeps typed markers as text, so leave them out of the inserted lines.

**Style text.** `updateTextStyle` with `style` and a matching `fields` list, such as `"fontSize,bold,foregroundColor"`. Font size is `{"magnitude": 24, "unit": "PT"}`; color is `{"opaqueColor": {"rgbColor": {"red": ..., "green": ..., "blue": ...}}}` with values from 0 to 1. Alignment is a paragraph property: `updateParagraphStyle` with `style.alignment` (`START`, `CENTER`, `END`, `JUSTIFIED`).

**Shape fill and outline.** `updateShapeProperties` with `shapeBackgroundFill.solidFill.color` and `outline.propertyState: "NOT_RENDERED"` to drop the border.

**Move or resize.** `updatePageElementTransform` with `applyMode: "ABSOLUTE"` and a full transform. Remember that the element's base `size` stays the same, so set `scaleX` / `scaleY` to the rendered size divided by the base size. Moving is safer than resizing: to resize a text box, it is often simpler to delete it and create a new one at the right size.

**Tables.** `insertText` and `updateTextStyle` take `cellLocation: {"rowIndex": r, "columnIndex": c}`. `updateTableCellProperties` with a `tableRange` sets cell fills. `insertTableRows`, `deleteTableRow`, `insertTableColumns`, and `deleteTableColumn` change structure. `updateTableColumnProperties` sets column widths in EMU.

**Charts from Sheets.** `createSheetsChart` with the sheet's `spreadsheetId`, the `chartId` (from the Sheets `addChart` reply, or from `get_spreadsheet` with `fields: ["sheets.properties.title", "sheets.charts.chartId", "sheets.charts.spec.title"]`), `linkingMode: "LINKED"`, and `elementProperties`. A linked chart stays tied to its data; `refreshSheetsChart` updates it after the sheet changes. Don't paste a chart as an image.

**Images.** `createImage` needs a URL Google can fetch publicly. For a local image, build the slide in a .pptx with the `pptx` skill and upload it, or ask the user to insert the image.

**Reorder, copy, delete.** `updateSlidesPosition` with `slideObjectIds` and `insertionIndex`; `duplicateObject` for a slide or element (set `objectIds` to name the copies); `deleteObject` for either. List `slideObjectIds` in the slides' current order in the deck, or the whole batch is rejected; the listed slides move as a block and keep that order. `duplicateObject` puts each copy directly after the original, so copying one slide several times leaves the copies in the reverse of the order you sent the requests. To make several copies in a chosen order in one batch: duplicate the original once per copy, sending the requests in the reverse of that order, so the copies end up after it in the order you want. Fill them. If they belong elsewhere in the deck, move them as a block with one `updateSlidesPosition` that lists them in that order. Delete the original if it was a template.

## Verify

1. Read the deck with the mask above and run `slides_helper.py outline`. Check the text, slide order, and every flag.
2. Where you can run code, look at the rendered slides. Export with Drive `download_file_content` and `exportMimeType: "application/pdf"`; a large result is saved to a file. If the export comes back in the chat instead, skip the render rather than copying it into a file. Otherwise:

```
python <skill>/scripts/render_export.py <saved export> render --pages 3-4
```

   Open each page image and check for overflow, overlap, clipped text, and low contrast. `read_slide_page_thumbnail` returns an image URL instead; use it only if your surface can open image URLs, since some environments can't.
3. Fix the problems, then check again. If you can't run code or render, rely on step 1 and tell the user you couldn't check the layout visually.

## Slides failures

| Symptom | Cause | Fix |
|---|---|---|
| A read is 100 KB or more | No field mask, so layouts and masters came back | Use the mask in Read. |
| Elements land in the wrong place or size | Base `size` used without the transform scale | Use `slides_helper.py outline` for real geometry, and `build` for new elements. |
| A table is a different size than requested | Table size comes from columns and rows, and rows grow with text | Read `tableColumns` and `tableRows`; set widths with `updateTableColumnProperties`. |
| Text spills out of its box | Slides doesn't shrink text | Enlarge the box, cut the text, or split the slide (Fitting text above says when a smaller size is allowed). `build` warns before you send. |
| `The object ID (ab) length should not be less than 5`, or a duplicate ID error | IDs too short, reused, or with invalid characters | Use descriptive IDs such as `s4_title`, unique per deck. |
| `Unknown dimension unit UNIT_UNSPECIFIED` | A size or transform without `unit: "EMU"`, or a new shape with no size | Give every new element a full `size` and `transform` with units. `build` does this. |
| Prompt text such as "Click to add title" appears | An empty placeholder | Fill it or delete it. `outline` flags these. |
| `createImage` fails | The URL isn't publicly fetchable | Use a public URL, or the .pptx upload route. |
| `deleteText`: `The startIndex 0 must be less than the endIndex 0` | The box has no text to delete | Skip the delete when the read shows no text. |
| `createSlide`: `The placeholder (…) is not on the page` | `placeholderIdMappings` names a placeholder the layout doesn't have | Map only the placeholders that layout has; `TITLE_ONLY` has no `BODY`. |