Skip to content

HTML_DECK_CONTRACT.md

Latest commit

 

History

History
95 lines (63 loc) · 5.89 KB

HTML_DECK_CONTRACT.md

File metadata and controls

95 lines (63 loc) · 5.89 KB
Raw

HTML Deck Contract

Every deck produced with this kit — by a human, an AI tool, or an automated flow — must satisfy this contract. The contract is what makes decks AI-editable: a stable, predictable structure that any AI tool can read, address, and modify without breaking the whole file.

The reference implementation is templates/base-onefile-deck.html.

1. Single standalone HTML file

  • One deck = one .html file containing all markup, CSS, and JavaScript inline.
  • No external dependencies: no CDN scripts, no external stylesheets, no web fonts, no network requests. System font stacks only.
  • The file must open correctly from the local filesystem (file://), offline, with no build step and no server.

2. Semantic slide sections

Each slide is a <section> with class slide, a unique data-slide-id, and a data-pattern naming the slide pattern it implements:

<section class="slide" data-slide-id="problem" data-pattern="problem-context">
  <h2>Problem worth solving</h2>
  ...
</section>

Rules:

  • data-slide-id is a short kebab-case identifier, unique within the deck. It is the primary handle for edit instructions ("revise only the slide with data-slide-id="problem"").
  • data-pattern names a pattern from STUDENT_DEVELOPER_PATTERNS.md (or a documented custom pattern).
  • Every slide has exactly one heading that states its point: <h1> on the title slide, <h2> on all others.
  • Slides live in document order inside <main>; order in the file is presentation order.

3. Table of contents and navigation

  • The deck has a table of contents (sidebar or overlay) with one entry per slide, linking to that slide.
  • The TOC must be derived from the slides themselves (generated by the deck's inline script from section.slide elements). This guarantees nav count always matches slide count and keeps edits safe: adding or removing a slide never requires touching the nav markup.
  • The current slide is visibly highlighted in the TOC.
  • The current section.slide receives the active state, and the matching TOC entry receives the active state.
  • The URL hash reflects the current slide's data-slide-id. Loading a valid direct hash opens that slide. Clicking a TOC entry updates the slide, active TOC state, page number, and hash together.

4. Page numbers

  • Each slide displays its position as current / total (e.g. 3 / 10).
  • Page numbers are derived from slide order by the inline script — never hardcoded per slide — so reordering slides cannot desynchronize them.

5. Keyboard navigation

Minimum bindings, implemented in the inline script:

Key Action
→, PageDown, Space Next slide
←, PageUp Previous slide
Home First slide
End Last slide

Navigation must clamp at the first and last slide; it must never move before the first slide or after the last slide. Handled presentation keys must call preventDefault() so browser scrolling is not triggered.

Navigation must not hijack keys while the user is typing in an input, textarea, select, or editable element (guard on the event target).

The inline script in base-onefile-deck.html is the canonical implementation of this contract. Generated decks must preserve it; do not replace, simplify, remove, or rewrite it during content generation. Any navigation change belongs in the template first, followed by regenerated decks and browser QA.

6. Print CSS

  • A @media print block renders each slide as one page (break-after: page or equivalent), hides navigation chrome, and uses print-appropriate colors (dark text on light background).
  • "Export to PDF" for this kit means: open the file in a browser and print. The print output must be readable without further tweaking.

7. Design tokens

  • All colors, font families, font sizes, spacing, and radii are defined as CSS custom properties on :root — the deck's design tokens.
  • Slide-level styles reference tokens (var(--accent)), never repeat raw values.
  • Re-theming a deck = editing only the :root block. Content edits must not modify tokens, and theme edits must not modify content. Edit instructions should state which side may change.

8. AI edit guidance comments

The file guides its own editing:

  • A comment block near the top of the file explains the deck's structure, the token system, and the editing rules (in essence: "edit slides by data-slide-id; don't touch tokens or the script unless asked").
  • Each structural region (<head> tokens, nav, <main>, script) carries a short <!-- ... --> comment stating what it is and whether it is normally safe to edit.
  • Guidance comments are part of the deck's interface — do not strip them when editing.

9. No unresolved placeholders in final decks

  • Finished decks (everything under examples/, and anything delivered to a user) contain zero unresolved placeholders: no TODO, TBD, double curly braces, [PLACEHOLDER], XXX, or lorem ipsum.
  • Only the reusable template under templates/ may contain placeholder content, and its placeholders must be clearly safe and self-describing (e.g. "Replace with your project name").
  • If real information is unavailable, the slide is rewritten to not need it — a placeholder is never shipped as content. Missing data belongs in the brief's missing_information, not in the deck.

10. Accessibility and readability baseline

  • Semantic heading hierarchy (one h1, then h2 per slide).
  • Body text at a size readable from a projector (≥ ~18px equivalent at 100% zoom; the template's tokens are the reference).
  • Sufficient text/background contrast in both screen and print modes.
  • Content must not overflow the viewport on a common laptop screen (1280×800 and up) at default zoom.

Compliance

Check any deck against VALIDATION.md before presenting, sharing, or committing it as an example.