Superable Presenter — AI Presentation Builder Instructions # Superable Presenter — AI Presentation Builder Instructions > **For AI assistants building a presentation (a "deck") for Superable Presenter.** Through the Superable Learning connector, the assistant gets these instructions with the slide layout catalog and the illustration library attached. A deck is an ordinary course package with presenter fields, so everything in the Course Builder Instructions about packages, file paths and accessibility still applies. A deck is presented from the Presenter Console: the presenter reads the speaker notes while the Audience View, shared to Zoom, Teams or a projector, shows the slides. The same deck also opens as a course, so attendees can go through it at their own pace afterwards. ## 1. Ask before you build Ask the person, in plain words, and wait for the answers: 1. **The talk:** topic, audience, and how long it should run. The length becomes `properties.pacing`. 2. **Their material:** an outline, a script, an existing course to turn into slides, or a PowerPoint file (see section 7). 3. **Images:** whether they have photos, logos or diagrams to use (see section 4). 4. **Course view:** whether people opening the deck as a course should see the speaker notes as "Talking Points" under each slide (see section 5). ## 2. The package - `course_structure.json` with `"presentable": true` in `properties`, and one module per slide, in order. - Each slide is an HTML fragment in `modules/`, with no `<html>`, `<head>` or `<body>`. - Files inside the package are referenced as `courses/{course-id}/path`, the same as in any course. Library illustrations (section 4) use their own path and aren't copied into the package. The presenter fields: | Field | Where | What it does | | :-- | :-- | :-- | | `presentable` | `properties` | `true` makes the course a deck: it gets a Present link in the Admin Panel. | | `pacing` | `properties` | `{"targetMinMinutes": 15, "targetMaxMinutes": 20}`: whole minutes, both optional. Shown to the presenter only. | | `showTalkingPoints` | `properties` | `true` shows each slide's notes as "Talking Points" in course view, minus anything marked presenter-only (section 5). Off by default. | | `notes` | a slide's module entry | The speaker notes, as simple HTML: paragraphs, bold, italic, lists, quotes, code, `<h4>` and http(s) links. Anything else is removed on upload. | | `targetTime` | a slide's module entry | A short pacing cue for the presenter, such as `"2:30"`. | | `fullBleed` | a slide's module entry | `true` only for the Full-Bleed Image layout. | Example: ```json { "properties": { "title": "Accessible Meetings in Ten Minutes", "description": "A short talk on running meetings everyone can follow.", "presentable": true, "pacing": { "targetMinMinutes": 8, "targetMaxMinutes": 10 }, "showTalkingPoints": true, "access": { "type": "protected" } }, "modules": [ { "id": "title", "title": "Accessible Meetings in Ten Minutes", "src": "modules/title.html", "notes": "<p>Welcome everyone. <span class=\"sl-presenter-only\">Wait for the room to settle.</span></p>", "targetTime": "0:30" } ] } ``` Speaker notes never go in the slide files. Slide files, and every other file in the package, can be read by anyone who can open the course, comments included. Notes go only in `notes`, which reaches the presenter alone. ## 3. Choose a layout for every slide Use the slide layout templates in the attached catalog (`slide-layouts.json`). For each slide, pick the template whose `useWhen` fits, check its `avoidWhen`, and copy its `markup` exactly, filling in the `{{...}}` placeholders. Keep within each part's `maxWords` and `maxItems`. Rules every slide follows (the validator checks them): - Wrap the slide in `<div class="sl-slide" data-sl-layout="TEMPLATE-ID">` and use one template. - Exactly one `<h1>`, and no two slides share a heading. Every slide needs a unique title, just like a PowerPoint slide. The Full-Bleed Image layout keeps its `<h1>` for screen readers with `class="sr-only"`. - Headings inside a slide continue from the `<h1>`: column headings are `<h2>`. - Every `<img>` has an `alt` attribute, and every `<iframe>` has a `title`. - No hard-coded colors. Colors come from the theme, so the organization's brand and dark mode apply. Say which layout you chose for each slide when you show the person the outline, so they can ask for a change. ## 4. Images: encouraged, never required Sighted audiences find long runs of text-only slides dull, and adding pictures fixed that for real talks. But a deck without images is still a valid deck. Never refuse to build one. When a slide could use a picture: 1. Ask whether the person has one. A photo or other raster image goes in with `add_course_image` first; use the path it returns. 2. Otherwise, offer an illustration from the attached library. Use it directly as `assets/engine/templates/illustrations/ID.svg`. Each entry has a `description` so the person can decide whether it fits without seeing it: read the description to them. 3. Or offer to draw a simple SVG for the slide. Save it in the package's `assets/` and reference it as `courses/{course-id}/assets/NAME.svg`. Alt text: - **Decorative:** a picture beside a statement that already carries the meaning gets `alt=""`. Describing it would only add noise for screen-reader users in the audience. - **Meaningful:** a picture that *is* the content, such as an Illustration Only slide used as a cue, a chart, a logo standing in for a name, or a QR code, gets real alt text. For a QR code, say what scanning it does. - The library's `description` is for reviewing the picture, not slide alt text, unless the picture carries meaning on that slide. The validator suggests an image on text-only slides (`[Slide Suggestion]`). That's advice to discuss with the person, not an error. ## 5. Mark the presenter-only parts of the notes **Don't skip this step when `showTalkingPoints` is on.** Course view shows each slide's notes to everyone who opens the deck as a course, so stage directions such as "press Next", "pause here", "don't start the timer yet" or timing cues would reach learners as if they were content. Before you turn on `showTalkingPoints`, go through every slide's notes with the person: 1. Read out, or list, the parts of each slide's notes that look like stage directions, cues or timing. 2. Ask which of them are for the presenter only. 3. Wrap each presenter-only part in `class="sl-presenter-only"`: on a `<span>` inside a sentence, or on a whole `<p>`, `<li>` or `<div>`. Everything marked this way stays in the Presenter Console and is left out of the talking points. Everything else is shared. There is still only one copy of the notes. If the person doesn't want talking points at all, leave `showTalkingPoints` off and skip the marking. ## 6. Check, publish, and tell the person how to present 1. Run `validate_course_package` and fix every `[Slide]`, `[Speaker Notes]`, `[Asset Path]`, `[Component Label]` and `[Hard-coded Color]` advisory. Discuss `[Slide Suggestion]` advisories with the person. 2. Publish with `upload_course_package` and give the person the link. 3. Tell them how to present: in the Admin Panel's Course Library, the deck's card has a **Present** link (Pro and Premium plans). It opens a launch page with **Start Presenting**, which turns that tab into the Audience View and opens the notes in a window in front of it. Pop-ups must be allowed for the site. 4. If the room needs to open the deck themselves and it isn't public, they can make a **live session access code** on the same card. Attendees enter it at the address shown there (the organization's `/join` page). ## 7. Converting a PowerPoint deck A connector can't read the person's files. Converting a `.pptx` needs the local Superable course tools (`extract_pptx_deck`), which output a deck to review. Never present a converted deck as finished. Check every slide against the original and report what you found, slide by slide: - **Animations:** builds are flattened onto one slide, so text from later steps appears at once. Split the slide, or use build steps. - **Lost content:** the author's alt text, grouped icons, picture-filled shapes, charts and embedded video can be dropped or replaced by a still. Restore them, or tell the person what's missing. - **Titles:** most PowerPoint slides have no visible title. Every slide still needs a unique `<h1>`; hide it visually only on a Full-Bleed Image slide. - **Sizing:** imported text and images often come out too small. Use the layouts' sizes rather than the original's. - **Colors:** check theme colors for contrast, and say which ones you replaced. - **Notes:** keep the notes one-to-one with the slides, and check they still line up after splitting animated slides.