Extending slidehtml

English · Deutsch · 简体中文 · 繁體中文

Deck authors never modify templates. This page is for changes to the kit itself. See also CONTRIBUTING.md.

Adding a template

Add a template only when a kind of content keeps recurring and no existing template can hold it.

  1. Create the component in src/kit/. Its props extend SlideBase; use SlideHead / SlideFoot for the shared header and footer.
  2. Put styles in the matching stylesheet under src/styles/. Use only u units (24u = 24 px on the 1920×1080 design) and the colour variables from :root. Accent colours are always var(--accent), var(--accent-ink), var(--accent-wash), var(--accent-soft), or rgb(var(--accent-rgb) / 0.16) for transparency; hard-coded colours won’t follow theme changes. Inline style only takes unitless values or CSS variables.
  3. Export it from src/kit/index.ts and register it in src/kit/catalog.ts: good for, avoid, content limits, props and an example. The catalog is the single source for the template docs.
  4. Add a slide demonstrating it to a reference deck and point demo (and deck, if not the default deck) at that slide id.
  5. For step-by-step reveals, put data-build on the outermost element of each item (same value for elements that appear together). For a number that appears on adjacent slides, give both the same data-morph.
  6. Run npx slidehtml docs to regenerate docs/*/components.md and skills/slidehtml/references/, then npx slidehtml check <deck>.

Adding a style preset

  1. Add an entry to STYLES in src/kit/theme.ts (larger presets live in src/kit/styles/<name>.ts): label, note (what it looks like and what it’s good for), optional radius, paper colours and tone: 'dark' if the whole style is dark by default.
  2. A style changes only title typography, radius, paper and decoration. Body text, sizes and spacing must stay the same so every template’s content limits remain valid.
  3. Add an example deck in a neutral topic (no real brands, products or company data) and check it at #/kit/styles.
  4. Run npx slidehtml docs (updates skills/slidehtml/references/styles.md), then check.

Adding a colour theme: add an entry to THEMES in src/kit/theme.ts and fill every field (soft is used on dark backgrounds, paper tints the background).

Icons

Icons come from the bundled icon set; the curated list is src/kit/icon-set.ts. To add one, add a line to the right group there. Name it after what it depicts. Type checking and the icon index update automatically.

QA rules

  • A change is finished when npx slidehtml check <deck> ends with PASS for the affected decks and you have reviewed the screenshots in qa/.
  • Minimum font size is 17u; QA fails below that.
  • No remote resources (fonts, images, scripts); the build fails on them.
  • Don’t add global keyboard listeners; they break navigation.
  • Templates must work at all four QA window sizes and, if listed for tone: 'dark', on dark slides.
  • Example content stays neutral: no real brand names, logos or company data.