slidewright

Files (18)

• README.md
• README.vi.md
• README.zh.md
• SKILL.md
• slidewright-remote.d.mts · assets/remote/
• slidewright-remote.mjs · assets/remote/
• evals.json · evals/
• deck-types.md · references/
• design-system.md · references/
• export-pdf.md · references/
• html-track.md · references/
• react-track.md · references/
• remote-control.md · references/
• add-remote.sh · scripts/
• export-deck-pdf.py · scripts/
• new-html-deck.sh · scripts/
• new-react-deck.sh · scripts/
• verify-slides.sh · scripts/

SKILL.md (first lines)

# Interactive presentation builder

Build slide decks that run as a website and are **projected to a room**. The deck is the
visual half of a talk; the presenter does the talking. Two ways to build, one shared
design language.

## First, the mental model (read before writing any code)

There is **one operator** (the presenter) on **one machine**. Slides go on a big screen;
the audience only **looks** — they never click, type, or interact. Everything below
follows from this. Four failure modes to avoid:

- **Text too small.** Slides are read from across a room, not on a laptop. Never use
  web-reading sizes (`text-sm`, `16px`) or fixed Tailwind text classes (`text-4xl`).
  Always use fluid `clamp()` so text scales with the screen. Honour the typography floor
  (body ≈ 30–36px, never below 28px on a 1080p canvas). See `references/design-system.md`.
- **Content hugging an edge.** Padding is a two-layer contract. Slide content must stay
  inside the viewport safe area, and content inside a card, panel, callout, bordered box,
  or other visible container must stay inset from that container's own edge. A parent
  slide's padding does not protect a nested container; `gap` and child margins are not a
  substitute for the container's own padding. Both scaffolds provide safe-area padding
  and a `.slide-surface` inset helper. Even `fullBleed` slides keep text content inset.
- **Building an app.** No input fields, no "Submit", no login, no data collection — there
  is no backend and nowhere for data to go. Interaction is only the presenter clicking to
  reveal/advance content. If a component asks "where does this data go?", it's wrong.
- **Wrong voice for the audience.** A board report is not a lesson and a pitch is not a
  status update. The deck type sets the structure and the voice. Decide it first — see
  `references/deck-types.md`.

The presenter may hold a **phone remote** (scan a QR code from the terminal, then tap
Next/Prev). It is the same single operator on a second device, not audience interaction.

`references/design-system.md` is the heart of this skill — the typography floor, two-layer
padding contract, content overflow, layout recipes, motion, and palette. Read it whenever
you design or restyle slide content.

## Workflow

1. **Understand and clarify the talk.**
   - **Content:** If the presentation content is vague or unclear, ask questions to clarify the topic, audience, speaker (name/role), and key message before building. For Vietnamese content, the default voice is plain, honest, direct — no marketing hype.
   - **Deck type:** Decide what the deck is for before writing: report upward, decision request, pitch, training, talk, or internal update. Infer it from the request and tell the user your choice in one line; ask only when two types fit equally. Then read `references/deck-types.md` and follow that type's arc, voice, and prohibitions.
   - **Style:** Ask the user for their preferred visual style and suggest these 5 modern options:
     1. *Minimalist Bauhaus*: High contrast, geometric typography, generous whitespace.
     2. *Dark Mode Cinematic*: Deep slate/black backgrounds, dramatic contrast, glowing accents.
     3. *Editorial / Magazine*: Sophisticated font pairings (serif + sans), structured grid layouts.
     4. *Glassmorphism*: Soft background gradients with blurred, translucent content panels.
     5. *Neo-Brutalism*: Bold typography, raw borders, hard shadows, high energy.
2. **Pick a track** (below). If unsure, ask once; otherwise default to plain HTML for
   small/quick decks and React for substantial, maintained talks.
3. **Scaffold** with the matching script — don't hand-assemble the boilerplate.
4. **Build slides** in the arc and voice of the deck type, following
   `references/design-system.md`: one idea per slide, few
   words, real visuals, projection-legible type, presenter-only interaction, and the
   two-layer padding contract for both viewport and content containers. Respect the
   density limits — never exceed 5 bullets, ~60 words, or 5×4 table cells per slide.
   If content doesn't fit at the typography floor, split into more slides — never shrink
   past the floor and never produce a slide that scrolls vertically.
5. **Keep the required chrome:** a visible bottom navigation slider (dot strip) and slide
   number. Both scaffolds include it — don't remove it.
6. **Write speaker notes** in the `<deck-name>-notes.md` file the scaffold creates (never
   on the slides themselves).
7. **Run the verify script** to catch text-too-small and content-too-dense violations:
   ```bash
   bash /mnt/skills/user/slidewright/scripts/verify-slides.sh <path-to-deck>
   ```
   Fix every reported issue before proceeding.
8. **Run the spacing audit before handoff.** Check every slide at 1920×1080 and at one
   smaller viewport. No text or primary content may cross the viewport safe area. For
   every element that draws a visible boundary (`background`, `border`, `outline`,
   `shadow`, rounded surface, or text-overlay panel), verify that its content has
   padding on all four sides. Media and purely decorative edge-to-edge layers are the
   only exceptions; text over them belongs in a nested padded surface.
9. **Tell the user how to present with the phone remote.** Both scaffolds include it.
   The HTML track runs `node <deck>/slidewright-remote.mjs`. The React track runs `npm run dev`.
   The terminal prints a QR code for the phone. See `references/remote-control.md`.
   Keep the deck's `window.slidewright` API and `slidewright:change` event when you edit
   navigation code.
10. **Export to PDF** if asked — see `references/export-pdf.md`.

Put each deck in its own folder. Keep any live-demo app as a separate project, not inside
the deck.

## Choosing a track

| Pick | When | Reference |
| --- | --- | --- |
| **Plain HTML** | Zero setup wanted; runs by opening a file; quick deck; shareable anywhere; no toolchain. Gets unwieldy past ~15–20 rich slides. | `references/html-track.md` |
| **Vite + React** | Many slides, reusable components, state-driven interactions, TypeScript, Framer Motion, maintained/re-run talks. | `references/react-track.md` |

Both produce the same projected experience and obey the same design system; they differ
only in implementation.

## Scaffolding

**Plain HTML** — single self-contained `index.html`, Tailwind via CDN, no build:

```bash
bash scripts/new-html-deck.sh <deck-name> [target-dir] [--title "Deck title"]
```

**Vite + React** — scaffolds with the official Vite tool and installs the **latest**
React, Tailwind, Framer Motion, and Lucide (versions are intentionally not pinned, so
each deck starts on current tooling), then layers the `App → Deck → Slide` architecture:

```bash
bash scripts/new-react-deck.sh <deck-name> [target-dir] [--no-install]
cd <deck-name> && npm run dev
```

Both scaffolds include the phone remote (`slidewright-remote.mjs`, zero dependencies).
For a deck scaffolded before the remote existed:

```bash
bash scripts/add-remote.sh <path-to-deck>
```

After scaffolding, read the matching track reference for how slides are structured and how
to add/reorder them, then build the content.

From tronghieu/agent-skills, MIT.

More from tronghieu/agent-skills