Perun-Style Presentation Toolkit

A self-contained HTML presentation system inspired by Perun's PowerPoint aesthetic: deep black backgrounds, orange accents, sparse bullet points designed as speaker cues rather than prose, and Mermaid diagrams for architecture and flow. Each presentation is a single HTML file — open in any browser, scroll to advance slides.

---

Repository Map

presentation-tk/
│
├── example.html             # The Monika context engineering presentation
│                            # (reference implementation — complete, 22 slides)
│
├── template/
│   ├── blank.html           # Minimal starter — copy this, fill in your content
│   └── components.html      # Living component reference — every building block
│                            # shown rendered with copy-paste source
│
└── README.md                # This file

---

How the System Works

Single file. Everything — styles, scripts, Mermaid, content — lives in one .html file. No build step, no dependencies to install, no server required. open presentation.html in any modern browser.

Full-viewport slides. Every <section class="slide"> has min-height: 100vh, so each slide fills the screen. Scrolling moves you from slide to slide naturally.

Orange progress bar. A 3px fixed bar at the top tracks scroll position automatically.

Mermaid diagrams. Loaded from CDN. The dark init config is included in every file — diagrams render on page load with the correct theme.

No JavaScript framework. The only JS is ~10 lines for the scroll progress bar and the Mermaid initialisation call.

---

Making a New Presentation

1. Copy the blank template

cp template/blank.html my-new-talk.html

2. Set the page title

<title>Your Presentation Title</title>

3. Plan your slides before writing HTML

A good structure for most talks:

[01] Title slide
[02] Overview / TOC (what you're covering)
[03] Section break (first major topic)
[04] Content slide
[05] Content slide
...
[N-1] Summary / "what each thing does"
[N]   Closing slide

Section breaks (slide-section) act as visual chapter dividers — use one per major topic.

4. Write each slide

Each slide is a <section> tag. Copy the appropriate type from template/components.html, fill in your content, and increment the slide number in .slide-num.

<section class="slide" id="s04">
  <h2>Your Slide Title</h2>
  <!-- content here -->
  <div class="slide-num">04</div>
</section>

5. Keep bullets short

Bullets are speaker cues, not prose. Each bullet should be a phrase you expand on verbally, not a sentence you read aloud. Aim for 4–7 bullets per list, fewer if the slide has a diagram.

6. Use diagrams for architecture and flow

If you're explaining how components relate or how data moves, reach for a Mermaid flowchart or sequenceDiagram. The rendered diagram carries far more information per pixel than an equivalent list. Copy the diagram block from components.html and edit the Mermaid source.

---

Slide Types

There are four slide shells, each a <section> with different class combinations.

Title Slide — slide slide-title

The opening hero slide. Large h1, muted .subtitle, optional tag pills.

• No content below the title block needed
• Use h1 with a <span> for an orange accent on part of the title
• Add .tag pills to signal the topics you'll cover

Standard Slide — slide

The main workhorse. Has the orange left accent bar. Uses h2 for the slide title, h3 for sub-section labels within the slide, and any combination of content components.

Section Break — slide slide-section

Darker background (#0f0900). Used as a visual chapter divider between major topics. Keep it brief: a large h2 and one sentence of context as a <p>. Add a .status badge to the h2 if the topic has a lifecycle state (Live / In Progress / Planned).

End Slide — slide slide-end

Centred layout, no left accent bar. Use for the closing outro. Typically: .orange-rule, a large h1 with an orange <span> on the key phrase, a .subtitle paragraph, another .orange-rule, and a row of .tag pills.

---

Component Reference

Open template/components.html in a browser to see every component rendered at full scale with its copy-paste HTML source alongside. The reference below is a quick lookup.

---

Bullet Lists

Standard — spaced out, 1.05rem, each item separated by a faint border:

<ul>
  <li>First point</li>
  <li><strong>Highlighted point</strong> — orange emphasis inline</li>
  <li>Point with <em>muted secondary detail</em></li>
  <li>Point with a <code>code snippet</code> inline</li>
</ul>

Tight — condensed vertical spacing, for dense lists or inside columns:

<ul class="tight">
  <li>Compact point</li>
  <li>Another compact point</li>
</ul>

Inline modifiers within li:

• <strong> → orange, bold
• <em> → muted grey, same size (overrides italic)
• <code> → inherits monospace from browser default

---

Layouts

Full width — just put content directly inside the slide. No extra wrapper needed.

Two columns — 1fr + 1fr, 60px gap, top-aligned:

<div class="cols">
  <div><!-- left column content --></div>
  <div><!-- right column content --></div>
</div>

Three columns — 1fr + 1fr + 1fr, 40px gap:

<div class="cols-3">
  <div><!-- col 1 --></div>
  <div><!-- col 2 --></div>
  <div><!-- col 3 --></div>
</div>

Tip: Inside a .cols layout, the standard pattern is bullets on the left, a diagram or callout on the right. The right column diagram uses .diagram-sm instead of .diagram (tighter padding, no top margin override needed).

---

Callout Box

Orange left border, dark warm background. Use for key insights, caveats, analogies, or anything that deserves visual separation from the bullet list.

<div class="callout">
  Plain text callout content.
</div>

<div class="callout">
  <strong>Labelled callout:</strong> Use <code>strong</code> at the start
  for a label, then the body text.
</div>

Override top margin with style="margin-top:0;" when placing the callout at the very top of a column (e.g., right column of a .cols layout when the left column starts with an h3).

---

File / Code Example Block

For displaying actual file contents (session summaries, config snippets, etc.) in a monospace block with an orange filename header.

<div class="file-example">
  <span class="fname">filename-or-path.md</span>
  <span class="path">Optional: path / header / metadata in muted colour</span>
  <span class="body">The actual file content goes here.
Can be multi-line — whitespace is preserved.</span>
</div>

• .fname — orange, bold, separated by a bottom border
• .path — muted grey, small, for metadata/headers
• .body — light grey, main content area

---

Mermaid Diagrams

Two wrapper variants:

<!-- Full-width diagram (own slide or below content) -->
<div class="diagram">
  <div class="mermaid">
    <!-- mermaid source here -->
  </div>
</div>

<!-- Compact diagram (inside a .cols column) -->
<div class="diagram diagram-sm">
  <div class="mermaid">
    <!-- mermaid source here -->
  </div>
</div>

Always include the init comment at the top of your Mermaid source to enforce dark theme colours:

%%{init: {"theme": "dark", "themeVariables": {"lineColor": "#f97316", "primaryTextColor": "#f0f0f0", "primaryColor": "#1a1008", "edgeLabelBackground": "#0d0d0d"}}}%%

Node styling — use style NodeId fill:X,stroke:Y,color:Z after your graph definition:

• Orange-highlighted node: fill:#1f0d00,stroke:#f97316,color:#f0f0f0
• Standard dark node: fill:#141414,stroke:#333,color:#f0f0f0
• Dimmer accent node: fill:#1a1008,stroke:#c2510c,color:#f0f0f0
• Subgraph (section grouping): fill:#1f0d00,stroke:#f97316

Diagram types used in this project:

• flowchart TD — top-down flow (most common)
• flowchart LR — left-to-right flow (good for pipelines)
• flowchart TD with subgraph — grouped nodes with labelled sections
• sequenceDiagram — for time-ordered message passing

---

TOC Grid

Used on the overview/agenda slide to show the topics at a glance.

<div class="toc-grid">
  <div class="toc-item">
    <div class="num">01 · Status</div>
    <div class="label">Topic Name</div>
    <div class="sub">Subtopic · Another subtopic</div>
  </div>
  <div class="toc-item">
    <!-- ... -->
  </div>
</div>

• .toc-grid is 2-column by default
• Each .toc-item has an orange left border and dark surface background
• .num — small orange uppercase label (number + status word)
• .label — the topic name, white, medium weight
• .sub — muted secondary line for sub-topics

---

Status Badges

Inline badges for lifecycle state. Placed inside h2 on section break slides.

<h2>Topic Name <span class="status status-live">Live</span></h2>
<h2>Topic Name <span class="status status-wip">In Progress</span></h2>
<h2>Topic Name <span class="status status-planned">Planned</span></h2>

Colours:

• status-live → green on dark green
• status-wip → yellow on dark yellow
• status-planned → purple on dark purple

---

Tag Pills

Small rounded pills, typically in a row at the bottom of a title or closing slide. Use to signal technologies, stages, or topic keywords.

<span class="tag">Tag One</span>
<span class="tag">Tag Two</span>
<span class="tag">Tag Three</span>

Wrap in a <div> with margin-top spacing as needed.

---

Orange Rule

A short decorative horizontal line. Used on the closing slide as a visual bracket around the main statement.

<div class="orange-rule"></div>

Centered automatically. Pair with margin: 28px auto (already in CSS).

---

Slide Number

Every slide should have a slide number in the bottom-right corner. This is purely decorative / navigational — it doesn't affect scrolling.

<div class="slide-num">07</div>

Place it as the last child inside the <section>.

---

Muted / Explanatory Paragraphs

For introductory or context text that isn't a bullet, drop a <p> with an inline style:

<p style="color:var(--muted); font-size:0.95rem; margin-bottom: 24px;">
  A brief framing sentence before the bullets begin.
</p>

---

CSS Variables

All colours are defined as custom properties on :root. Change these to retheme the entire presentation:

Variable	Default	Role
--bg	#0d0d0d	Page / slide background
--surface	#141414	Raised surfaces (diagram bg, toc-item bg)
--orange	#f97316	Primary accent — titles, bullets, borders
--orange-dim	#c2510c	Secondary accent — dimmer orange for secondary elements
--white	#f0f0f0	Primary text
--muted	#8a8a8a	Secondary / helper text
--border	#222	Subtle dividers
--font	'Segoe UI', 'Helvetica Neue', Arial, sans-serif	Body typeface

To change the accent colour from orange to, say, cyan (#06b6d4), update --orange and --orange-dim and also update the Mermaid %%{init}%% lineColor values in each diagram block.

---

Mermaid Tips

Text in nodes — use \n for line breaks inside node labels:

A["First line\nSecond line"]

Edge labels — quote multi-word labels:

A -->|"label text"| B

Subgraph titles — keep short; they appear as a box title:

subgraph MyGroup["Group Title"]
    A --> B
end

Style subgraphs after the graph body:

style MyGroup fill:#1f0d00,stroke:#f97316

Avoid long lines in node labels. Mermaid wraps inconsistently — manual \n gives you control.

flowchart vs graph — prefer flowchart TD over graph TD. They're equivalent but flowchart supports more modern syntax.

sequenceDiagram participant spacing — set actorMargin: 50 in the JS init (already in template) to avoid cramped labels.

---

Authoring Tips

• Plan slide count before writing. Aim for one idea per slide. If a slide needs more than 2 h3 sub-sections, consider splitting.
• Bullets are speaker prompts. Write what you'll say in 4–6 words, not a full sentence. The audience reads faster than you speak.
• Section breaks earn breathing room. Don't skip them — they give the audience a moment to register the topic change and give you a pivot point.
• Right column of .cols is prime real estate. Put the diagram or the key callout there. The left column for the reasoning, the right column for the punchline.
• Callouts are for the single most important thing on the slide. One per slide maximum. If everything is highlighted, nothing is.
• Slide numbers start at 01, zero-padded. Use 01 not 1 for consistent alignment.
• id attributes on sections are optional but useful for deep-linking (#s07). Convention is s + zero-padded number.