Open Slide Best Practices

open-slide Best Practices for Israeli Developers

Adapted from 1weiho/open-slide (MIT). Hebrew and RTL adaptations by skills-il.

Problem

open-slide ships an opinionated authoring system: a fixed 1920×1080 React canvas, a typed DesignSystem const, a themes folder, an inspector that drops @slide-comment markers in source, and five built-in skills (slide-authoring, create-slide, create-theme, apply-comments, current-slide). None of those touch Hebrew or RTL. Out of the box, a deck written by a coding agent comes out left-aligned, system-font only, with paddingLeft that fights the Hebrew reading order, and no guidance for mixed Hebrew+English text. Israeli developers waste hours retrofitting RTL, loading Hebrew Google Fonts, and discovering that the type scale (140-200px hero) which works in Inter looks cramped in Heebo at the same weight.

Instructions

When to use

Use this skill whenever you are writing or editing code under slides/<id>/ in an open-slide project, creating a theme under themes/, or processing inspector comments, especially when any of that content is in Hebrew or bilingual.

New project setup

When in an empty folder or workspace with no existing open-slide project, scaffold one using:

npx @open-slide/cli init my-slide
cd my-slide
npm run dev

Replace my-slide with a suitable project name. The scaffolder installs dependencies with npm and prints npm run dev as the next step; pnpm dev works too if you re-install with pnpm.

Node version. @open-slide/cli depends on commander@15, which declares "node": ">=22.12.0", and on chalk@6 (">=22"). On Node 20 the install still completes but npm prints EBADENGINE Unsupported engine for both. Use Node 22.12 or newer.

What the scaffold gives you:

Run npm run sync:skills after upgrading @open-slide/core, otherwise the agent keeps reading the skill copies from the version you scaffolded with.

Which version you are on

Target @open-slide/core 1.19.x. That is what npx @open-slide/cli init installs today, and everything in this skill is verified against 1.19.1.

A 2.0.0 beta is published (React 19, Vite 8, TypeScript 7). It is a pre-release: npm's latest tag still resolves to 1.19.x and the beta sits behind its own beta dist-tag, so you only reach v2 by asking for it (@open-slide/cli@2.0.0-beta.1 or @beta). Do not scaffold production work onto it, and do not assume any v2 API detail is stable.

Your slide source is not the problem. The upstream migration guide is explicit that v1 slides need no changes and that the migration is confined to package.json, your Node version, and your deploy config. Everything this skill teaches about the file contract, the canvas, type scale, themes and Hebrew/RTL carries over unchanged.

The one thing that breaks on upgrade. A v1 scaffold puts vite in your devDependencies; core 2.x ships its own Vite 8 internally. Leave the old entry in place and the dev server and build both refuse to start:

✖ @tailwindcss/vite resolves vite@5.4.21 (node_modules/vite), but @open-slide/core ships
vite@8.2.2 (node_modules/@open-slide/core/node_modules/vite).
A `vite` entry in your package.json (v1 workspaces had one) shadows the copy core depends on.
Remove it and reinstall.

Delete the vite devDependency and reinstall. Fresh v2 scaffolds omit it and are unaffected. Migration guide: https://open-slide.dev/docs/migrate-to-v2.

Slide folder ids must be ASCII (Hebrew folder names are silently dropped)

Do not name a slide folder in Hebrew. Discovery filters every folder under slides/ through SLIDE_ID_RE = /^[a-z0-9_-]+$/i and skips the rest, so a folder like slides/פתיחה/ never reaches the sidebar, the browser, or the build. Re-verified on @open-slide/core@1.19.1 (the current stable release) by scaffolding a project and running npm run build:

[plugin:open-slide] [plugin open-slide] Ignoring slide folder "פתיחה": slide ids must match
/^[a-z0-9_-]+$/i (lowercase/uppercase letters, digits, "-", "_"). Rename the folder under
"slides/" to a kebab-case id so it appears in the browser and can be moved into folders.

It is only a warning, not an error, so npm run build exits 0 and the missing slide is easy to miss. Use a Latin kebab-case id (peticha, cover, q2-roadmap) and put the Hebrew in meta.title and in the page content, where it belongs.

Do not over-apply this rule. It is specific to slide folder ids. Verified as NOT affected:

Hebrew and RTL

For any Hebrew or bilingual deck, load ./rules/hebrew-rtl.md first. It covers:

• Hebrew Google Fonts (Heebo, Rubik, Assistant, Noto Sans Hebrew) loaded by head injection
• The <html dir="rtl"> set-up vs per-page dir attribute (the canvas root is the page component, not the document)
• CSS logical properties (paddingInlineStart, marginInlineStart, insetInlineStart) instead of paddingLeft/marginLeft/left
• flexDirection: 'row-reverse' vs setting dir on the flex container
• Bidirectional text with <bdi> for mixed Hebrew + Latin (brand names, code, URLs)
• Hebrew-aware type scale tuning (Hebrew renders ~10-15% wider per character at the same px size)
• Hebrew DesignSystem.fonts.display and fonts.body choices that work at hero size
• RTL-aware theme markdown patterns under themes/
• Hebrew typography pitfalls: nikkud rendering, sofit letter spacing, hyphen vs maqaf

Slide authoring (file contract, canvas, type scale, themes, design tokens)

For the technical reference on what goes inside slides/<id>/index.tsx, load ./rules/slide-authoring.md. This is the same content the upstream slide-authoring skill exposes, with Hebrew/RTL pointers inline. It covers the file contract, the 1920×1080 canvas math, the type scale, spacing, visual direction, themes, the DesignSystem design-tokens object, the starter template, assets, image placeholders, and the repeated-elements rule.

Upstream has since split its own slide-authoring skill into per-primitive reference files. Three of them cover primitives this skill does not restate, so read them upstream rather than reimplementing by hand:

Drafting a new deck

When the user asks for "make slides about X" / "create a presentation" / "draft a deck", load ./rules/create-slide.md for the workflow: theme picker, the four scoping questions (aesthetic direction, page count, text density, motion), slide id selection, structure planning, visual commitment, write, self-review, hand off.

Creating a theme

When the user asks to "create a theme" / "make a theme called X" / "extract a theme from this slide", load ./rules/create-theme.md. A theme is a two-file bundle: themes/<id>.md (Palette / Typography / Layout / Fixed components / Motion / Aesthetic) plus a paired demo module themes/<id>.demo.tsx (.jsx, .ts and .js are also accepted), a runnable 2-3 page mini-slide that the dev UI's Themes panel renders as the live preview. Writing only the markdown leaves the theme with a dead preview card.

Applying inspector comments

When the user has clicked on a rendered page in the dev server and added comments (via the in-browser inspector tool), and asks to "apply comments" / "process slide comments", load ./rules/apply-comments.md. It covers the {/* @slide-comment */} marker format, the detection regex, the base64url-decoded payload, and the apply-in-reverse-line-order procedure.

Resolving deictic references ("this page", "the slide I'm on")

When the user references the current slide without naming it, load ./rules/current-slide.md first. It explains how to read the live cursor at node_modules/.open-slide/current.json, what fields are in it, and the staleness rules. Re-read it on every deictic turn, the user navigates between turns, so a value you read earlier is almost certainly stale.

Speaker notes go in the notes export, never in a markdown file

open-slide has built-in speaker notes, and coding agents routinely miss them: asked for a talk track, an agent writes script.md or notes.md next to the slide, which the runtime never reads. The presenter view stays empty and the user assumes the feature is missing.

Notes are an optional notes export in slides/<id>/index.tsx, index-aligned with the default page array. SlideModule declares it as notes?: (string | undefined)[]. Use undefined to skip a page rather than shifting the array:

const Cover: Page = () => <div dir="rtl">שלום</div>;
const Agenda: Page = () => <div dir="rtl">סדר היום</div>;

export const notes: (string | undefined)[] = [
  'פתחו בציטוט של הלקוח, ואז הציגו את עצמכם.',
  undefined,
  `שלושה עמודי תווך, פסקה לכל אחד.
עצרו לשאלות לפני המעבר.`,
];

export default [Cover, Agenda, Pillars];

Rules:

• One entry per page, in the same order as the default export. A missing entry silently misaligns every note after it.
• Multi-line notes work; use a template literal.
• notes must be an ARRAY LITERAL. The dev server writes notes back into your source (PUT /__notes), and its parser rejects anything it cannot edit in place: a computed array, a spread, an imported constant, or a .map() all return 422 \notes` export is not an array literal` and permanently break editing notes from the drawer. Write the array out by hand.
• Hebrew notes render LTR-aligned and you cannot fix it from the slide. The notes drawer and presenter pane set no dir, so Hebrew notes inherit the viewer chrome's direction. There is no author-side hook for this. Keep notes short and hard-wrap them yourself so the ragged alignment stays readable.
• Never deliver a speech script as a separate file. If the user asks for "תסריט" / "a script" / "speaker notes", it goes in this export.

Stable ships the feature without documentation. The notes runtime is present in 1.19.1, but none of the five skills bundled with that release documents it. The word "notes" does occur in them, in a table column header, a grid-overlay bullet and a line about inspector markers, but never in reference to this export. So sync:skills will not teach an agent the feature exists. That gap is the reason this section exists.

Dev-server surfaces worth knowing

These are viewer features, not authoring APIs, but users ask about them and an agent that knows they exist avoids rebuilding them by hand:

Vertical budget reminder (the #1 source of broken slides)

Anything below 1080px on the canvas is silently cropped. Before writing any page, sum:

(font_size × line_height × number_of_lines) + gaps + (2 × padding) ≤ 1080

If you're tight, split into two pages. Never use overflow: auto/scroll/hidden, negative margins, or transforms to hide overflow. The canvas does not scroll; cropped content is gone. See ./rules/slide-authoring.md section "Vertical budget" for the full worked example.

For Hebrew text the budget is tighter than it looks: Hebrew renders ~10-15% wider per character than Latin at the same px size, so a heading that fits English on one line at 80px may wrap to two in Heebo. Either drop the size or shorten the copy. See hebrew-rtl.md for the calibration table.

Reference Links

Recommended MCP Servers

None directly, since open-slide has no API surface. The skill is purely client-side authoring guidance.

Gotchas

These are the failure modes a coding agent hits when authoring an open-slide deck in Hebrew without this skill. They are NOT user errors.

1. Using paddingLeft and marginLeft everywhere. In LTR these read as "from the start of the line". In RTL they're literally on the wrong side of the canvas. Use paddingInlineStart / paddingInlineEnd (or shorthand paddingInline) so the layout flips automatically when dir="rtl" is set on the canvas root. The same applies to left / right (use insetInlineStart / insetInlineEnd) and text-align: left/right (use text-align: start/end).

2. Setting direction: 'rtl' on <html> or globally. open-slide's canvas root is the page component, not the HTML document. The dev server chrome (file rail, navigation arrows) is upstream UI in English; flipping the document direction breaks it. Set dir="rtl" on the page component's root <div> only. The Inspector and presenter mode keep their LTR layout; only your slide content flips. There is no Hebrew option to switch them to either: OpenSlideConfig.locale is deprecated in favour of the slide UI's language switcher, and the shipped UI locales are en, zh-TW, zh-CN and ja only. Tell the user the authoring chrome stays English; only the deck is Hebrew.

3. Naming the slide folder in Hebrew. It is the natural thing to do on a Hebrew deck and it silently loses the slide: discovery filters folder names through /^[a-z0-9_-]+$/i and only warns. Latin kebab-case id, Hebrew in meta.title. See "Slide folder ids must be ASCII" above.

4. Loading the Hebrew webfont from inside the page component. A <style>@import ...</style> or a <link> rendered inside a Page re-registers the whole @font-face set once per mounted page, and the home page, the thumbnail rail, the overview grid and the PDF print root all mount every page at the same time. Upstream's rule is to inject the stylesheet once into <head> from module top level of index.tsx, with an element id keyed to the slide (osd-webfont-<slide-id>) so one slide's fonts cannot suppress another's. See hebrew-rtl.md section 3.

5. The default display font is a serif with no Hebrew glyphs. defaultDesign.fonts.display is Georgia, "Times New Roman", serif and fonts.body is -apple-system, BlinkMacSystemFont, "Inter", system-ui, sans-serif. Georgia carries no Hebrew, so an unstyled Hebrew hero silently falls back to whatever system serif the OS picks (David / Times-like). That, not the body stack, is the real cause of the "my Hebrew deck renders in a dated serif" symptom. For decks that ship beyond a dev machine, load Heebo or Rubik via Google Fonts (css2, no subset parameter, it is ignored) and put them first in the stack with the system stack as fallback. See hebrew-rtl.md.

6. Same type scale as English. 140-200px hero in Inter looks tight at the lower bound (140) for Hebrew, because Hebrew uppercase-equivalent (Hebrew has no case) sits at the cap-height-equivalent of large-x-height Latin fonts. Hebrew at 140px reads like Latin at 120px. Either bump the hero to 160-220px for Hebrew, or drop the line count.

7. Mixing Hebrew and English without <bdi>. A bullet like "השתמשו ב-React Router" with mixed Hebrew + Latin tokens often renders the punctuation in the wrong place because the browser's bidi algorithm doesn't always isolate the Latin span. Wrap mixed runs in <bdi>: השתמשו ב-<bdi>React Router</bdi>. Critical for code identifiers, brand names, and URLs inside Hebrew copy.

8. array.map for visually repeated cards. The upstream rule (one component instantiated per item, NOT map over a data array) applies in Hebrew too. The reason is the inspector: map shares one source location per item, so editing one Hebrew label changes all rendered cards. Define <Card /> once, instantiate it three times explicitly. See slide-authoring.md.

9. Ignoring node_modules/.open-slide/current.json. When the user says "תקן את הכותרת בעמוד הזה" ("fix the heading on this page"), the deictic "הזה" maps exactly the same way the English "this" does, you must read current.json to find which slide they're on. Re-read it on every turn. See current-slide.md.

10. Same vertical budget at the bumped Hebrew type scale. A cover that fits a 3-line LTR hero at 200px (3 × 200 × 0.95 = 570px) will overflow if you keep 3 lines AND bump to 232px for Hebrew (3 × 232 × 0.95 = 661px), once padding and subtitle are added you blow past 1080. Either stay at 1-2 lines for the Hebrew hero, or recompute the full budget with the bumped values before committing. Splitting is always the right answer.

11. Mis-translated technical terms inside the slide copy. Translation services and well-meaning agents render English dev terminology into Hebrew that means something else. Common traps:

• "themes" → "ערכאות" (literally "court instances", a legal term). Correct: "ערכות נושא" (theme sets) or "תמות" (transliteration).
• "resolution" (as in "resolving a reference") → "רזולוציית" (means screen/image resolution). Correct: "פיענוח" (decoding) or "זיהוי" (identification).
• "authoring" → "אוטרינג" (English transliteration, sounds techy and wrong). Correct: "כתיבה" or "יצירה".
• "tuned scale" → "סקאלה מכוונת" (literal but robotic). Better: "סקאלה מותאמת" (adapted scale). Always verify Hebrew technical terms with a native speaker or a Hebrew dev community reference before shipping.

12. Pairing brand colors as a gradient can produce an off-brand intermediate hue. A linear gradient from Israeli Blue (#003286) to YooTech Magenta (#bc46a2) blends through saturated purple, which is NOT in the agentskills.co.il palette. If a project has a brand palette, audit each combination: hold solid bold marks for primary brand colors, and only gradient between adjacent hues (e.g., Israeli Blue → Israeli Blue Light) or fade to neutral (cream / navy). One confident solid usually beats a contrived gradient.

13. Audit your own copy for bidi traps. Recursively. A skill that warns about missing <bdi> will frequently MISS its own <bdi> calls inside Hebrew sentences ("השתמשו ב-RTL" needs <bdi>RTL</bdi>). When writing prose, slides, or examples, manually scan every Latin token embedded in Hebrew runs and wrap it. Code identifiers, brand names, version numbers, file extensions, all need isolation. The author writing the rule is not exempt from the rule.

Troubleshooting

Bundled Resources

rules/
├── slide-authoring.md     # File contract, canvas, type scale, themes, design tokens, assets
├── create-slide.md        # New-deck workflow: theme picker, scoping questions, structure
├── create-theme.md        # Theme markdown authoring under themes/<id>.md
├── apply-comments.md      # @slide-comment marker handling
├── current-slide.md       # Resolving "this page" via current.json
└── hebrew-rtl.md          # Hebrew fonts, bidi, logical CSS, RTL DesignSystem (the new content)

Load on demand based on the task. Always start with hebrew-rtl.md for Hebrew or bilingual content.