Designing decks

A slide deck's look comes from its theme: one shared stylesheet and presentation engine, composed with your own per-slide HTML. The theme defines the type scale, the color tokens, the spacing rhythm, and a catalog of ready-made layouts, so that most of the time you are filling in a blueprint, not designing one from scratch. This page collects the rules that guide, an AI agent authoring over MCP, or you editing in the deck maker, actually follows. For the mechanics of the tool calls themselves, see Authoring decks over MCP.

Guided mode vs freeform mode

There are two ways to author a slide's content.

• Guided mode is the default. You copy an existing layout blueprint (from list_layouts / get_layout) and edit its text, reusing the theme's classes and CSS variables. You almost never write new CSS.
• Freeform mode is for a deck that needs to look like a specific customer's brand rather than the theme's own look, custom fonts, colors, textures, bespoke section designs. You hand-author a slide's full HTML and its own scoped CSS, and it still renders inside the same presentation engine.

Freeform isn't all-or-nothing: you can mix built-in layout components (cards, KPI row, timeline, table, and so on) with custom sections in the same deck, and freeform slides can still reference the theme's own tokens (var(--cta), var(--ink), var(--line), and so on) for consistency.

The freeform slide contract

A freeform slide still has to behave as one slide in a presentation, not a scrolling web page. The rules:

1. One section per slide. Exactly one <section class="slide" data-title="…">…</section>, with a meaningful data-title (it labels the slide in the overview grid).
2. Never restyle the engine. Don't write rules for .slide, .active, .play, .deck, or the zoom/overview/progress chrome. You may set your own slide's background.
3. Scope every custom rule under one wrapper class. Add a unique class to the section (<section class="slide acme">) and prefix every selector with it (.acme h1 { … }). A bare selector like h1 or .card leaks into every other slide in the deck.
4. A slide is a fixed frame, not a scrolling page. It fills the screen at roughly 16:9 with no scroll. If content doesn't fit, split it into another slide, never shrink body text to cram it in.
5. HTML and CSS only, no <script>. Slides render server-side in headless Chromium for export and inside a sandboxed iframe live; scripts are stripped.

Type scale

All type is fluid (CSS clamp()), so it scales with the viewport. Pick the class that matches the role, don't set font-size inline.

Headline copy rules: max 8 words, sentence case (never ALL CAPS), active voice, lead with tension or outcome rather than a feature, and never a question headline.

Color tokens

Colors are CSS variables on :root. Reference them with var(--…); never hard-code a hex value that isn't one of these (in the ShareMyPage theme):

A custom theme (create_theme) substitutes its own tokens into the same system rather than replacing it, so this same set of classes and variables still applies.

Color restrictions worth calling out on their own:

• --bright fails contrast on white. Use it only on dark/navy slides, and only for large headline emphasis, never body copy, captions, or light backgrounds.
• Gradients go on backgrounds only, never on text, borders, icons, or buttons. One dominant gradient per slide.
• --red is reserved for negative-value deltas. Don't reach for it as a headline or accent color.
• Approved multi-series chart order is --cta, then --bright, then --deep, then --brand-dark. Never a rainbow palette, and never red for a negative bar or line in a chart.

Spacing rhythm

Slides frame content with padding --pad: clamp(44px, 6.5vw, 128px) inside a --maxw: 1180px content column. Beyond that, spacing sticks to one shared scale:

8 / 12 / 16 / 24 / 32 / 48 / 64 px

Between a headline and its content block, use 48px, the deck's normalized rhythm. Don't invent in-between values, and don't hard-code a tiny inline margin (style="margin-top:8px") to pull a block up under a headline, it fights the rhythm and produces a cramped slide. If spacing needs adjusting, move along the scale instead: headline to lead is 20 to 24px, block to block is 40 to 48px.

The layout catalog

list_layouts returns every insertable blueprint for a theme (id, name, and a one-line description, not the full HTML, to keep the response small); get_layout returns one blueprint's complete <section class="slide"> HTML, ready to hand to add_slide or adapt. The ShareMyPage theme ships 38 layouts, including these:

Only the layouts a given theme actually returns from list_layouts are real, insertable blueprints for that theme; don't assume a layout id from one theme exists on another without checking.

Layout variety matters. A presentation that reuses the same two or three layouts every time reads as a form, not a considered set of slides. Aim for at least 6 different layouts across a 10-slide deck, and don't repeat any one content layout more than twice (cover, section-divider, and closing are exempt, since those recur by design).

Big type, never cram

The single rule that overrides everything else on this page: never shrink type to fit. Body text stays at its normal size, the type scale above already floors it around 16px. If content doesn't fit on a slide, split it into another slide instead of shrinking, tightening line-height, or dropping padding to squeeze it in. A slide is a fixed frame, not a page that scrolls or resizes to absorb overflow.

In practice this also means: prefer 3 bullets and never more than 5 per slide, one idea per slide, and match your content to what a component is built for (a .timeline or .steps row is built for 4 beats, .cards and .kpirow for 3, .statrow for 4; more than that either needs an explicit column override or a second slide).

Do / don't checklist

Do

• Start from the story, then pick layouts to fit it, not the reverse.
• Reuse existing <section> blocks and existing classes and tokens.
• Keep to var(--…) colors and the .display / .headline / .section-h / .lead / .body type scale.
• Keep headlines to 8 words or fewer, sentence case, active voice.
• Prefer 3 bullets, never more than 5, per slide. One idea per slide.
• Add a source footnote on data slides; give real images descriptive alt text.
• Preview at narrow width before delivering (multi-column grids collapse at 860px).

Don't

• Don't hard-code hex values, invent new colors, or add a second gradient to a slide.
• Don't put --bright text on a white or light background.
• Don't use red anywhere except negative deltas.
• Don't write new CSS or add external libraries or CDNs beyond the existing font link, unless the user explicitly asks for a fully custom brand (freeform mode).
• Don't defeat prefers-reduced-motion.
• Don't leave placeholder text, image placeholder boxes, zeroed count-up targets, or lorem copy in a finished deck.
• Don't ALL-CAPS a headline, bold an entire paragraph, or phrase a headline as a question.

See also

• Slide decks for what a deck is and the slide tools themselves.
• Authoring decks over MCP for the recommended agent workflow and the full tool-by-tool capabilities.
• MCP tool reference for every deck, slide, and theme tool.