@holistiqs/deck

v0.1.0

Published

a month ago

HolistiQs design-system presentation module on reveal.js (CSS + JS).

0High
0Medium
0Low

klaus.lehner

reveal.js reveal slides presentation deck slide-deck design-system theme holistiqs pdf

HolistiQs Deck — authoring manual

Machine- and human-readable manual for building HolistiQs-branded slides with @holistiqs/deck. An agent can read this file and compose a full deck by combining the documented classes — without writing local CSS.
This README is the manual: read it on npm, or fetch it directly at https://cdn.jsdelivr.net/npm/@holistiqs/[email protected]/README.md. In published copies the CDN URLs below are pinned to the release version. A structured (machine-readable) index of the same information is at https://cdn.jsdelivr.net/npm/@holistiqs/[email protected]/dist/manual.json.

1. Consume it

A deck is one HTML file. Link the bundle, write <section class="slide …"> blocks inside reveal's wrapper, init. No build step, no local CSS.

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="UTF-8">
  <link rel="icon" href="https://cdn.jsdelivr.net/npm/@holistiqs/[email protected]/dist/assets/favicon.ico">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@holistiqs/[email protected]/dist/holistiqs-deck.css">
  <!-- Optional: only if you use <i data-lucide="…"> icons -->
  <script src="https://unpkg.com/[email protected]/dist/umd/lucide.min.js"></script>
</head>
<body>
  <div class="reveal"><div class="slides">
    <section class="slide pad bg-mesh"> … </section>
    <!-- more slides -->
  </div></div>
  <script src="https://cdn.jsdelivr.net/npm/@holistiqs/[email protected]/dist/holistiqs-deck.js"></script>
  <script>HolistiQsDeck.init();</script>
</body>
</html>

HolistiQsDeck.init(opts?) returns the reveal instance. opts: reveal (merged over brand defaults), plugins (extra reveal plugins), lucide (default true).

Navigation: arrows / space, Esc = overview grid, S = speaker notes.

Export to PDF. Just Ctrl/Cmd+P → Save as PDF (default margins). The output is the deck verbatim — dark background, brand colours, one 1920 × 1080 slide per page — with selectable (vector) text and a small file (no screenshots). No ?print-pdf URL param needed; init() already switches off reveal's white-handout print mode. HolistiQsDeck.exportPDF() opens the same print dialog programmatically (e.g. from a button).

2. The slide model

Each <section class="slide"> is a fixed 1920 × 1080 canvas, auto-scaled to fit.
Always a direct child of .reveal > .slides.
Add .pad for the standard 96 × 80 px padding. Add an ambient background: .bg-mesh, .bg-grid, .bg-dots, or a cover’s .cover-glow (as a child <div>).
A slide is a vertical flex column. Use .chrome-top (header) and .chrome-bottom (footer) as absolutely-positioned chrome, and put the body in .slide-body (which centres vertically; .top/.between/.end change that).
Leave the footer page number empty — <div class="pages"></div> — it is auto-filled.
Reveal centres content by default; the theme resets to left-aligned (HolistiQs is left-aligned). Headings/eyebrows/paragraphs sit at the left padding edge.

Slide skeleton:

<section class="slide pad bg-mesh" data-screen-label="02 Context">
  <div class="chrome-top">
    <div class="brand"><img src=".../assets/logo-color.png" alt="HolistiQs"></div>
    <div class="meta"><span class="dot"></span><span>SECTION LABEL</span></div>
  </div>
  <div class="slide-body">
    <!-- compose the content here -->
  </div>
  <div class="chrome-bottom">
    <div class="left"><span class="bar"></span><span>HolistiQs · Engineering meets AI</span></div>
    <div class="pages"></div>
  </div>
</section>

3. The rule

Compose the documented classes. Do not write local CSS — except for something genuinely special and one-off (e.g. an interactive draggable chart / drawing area). A static grid of cards is not special. If you reach for a <style> block for layout, you are missing a class below.

4. Vocabulary

A handful of inline values are fine as one-offs (a specific font-size on a hero, a decorative absolute position, a grid column count via --rail-cols).

Typography

.eyebrow — small teal label with a glowing dot; sits above a heading.
.kicker — mono uppercase label (technical/section marker).
h1.display — hero headline. h2.title — slide headline. h3.section — sub-headline.
.lead — large intro paragraph. .body — body copy. .mono — monospaced run.
.accent — inside a heading, colours a span teal (<span class="accent">…</span>).
.divider — short teal rule. .step-num (+.solid) — giant outlined section number.

Regions & layout

.slide-body (+.top/.between/.end) — the centred main region.
.slide-head (+.narrow) — eyebrow/kicker + title + lead with built-in rhythm.
.stack (+.gap-s/.gap-m/.gap-l) — vertical stack with rhythm.
.cols + .cols-2/.cols-3/.cols-4/.cols-5 — equal-column grid (+.tight/.loose/.flush gaps, .col-span-all).
.split (+ ratio mods .tilt-left/.wide-left/.wide-right/.lead-left/.lead-right, +.start/.end) — two-column split.
.anchor (+.bl/.tl/.max/.wide) — absolutely-anchored hero content.
.section-open / .open-inline — section-opener layouts (with .step-num).
.chip-row — wrapping row of chips. .mt-s/.mt-m/.mt-l/.mt-xl — top-margin steps.
.footnote — small ruled note (rule + muted text).

Components

.card (+.tall, .flow, .orange) — base surface. Children: .num (mono label), h4, p, .icon-tile. Modifiers: .accent-top (+.orange) = 4px top border; .tint (+.orange) = gradient-tinted card.
.rule-card (+.orange) — left-rule card with .label + h4 + p.
.callout (+.orange, .boxed, .dashed, .dashed.orange) — emphasis box; put a <p> inside.
.stat — big number (.num) + .label + .sub. .stat-hero — oversized hero stat.
.bar-row — labelled comparison bar. .scorebar — label + track/fill + amount.
.metric-row / .metric — inline metric strip. .data-table (+.thead/.row/.cell).
.window (+.head/.body/.fill/.stretch, .window-foot) — terminal/window frame.
.chip / .pill-primary — inline tags. .bul (+.tick, .orange) — bullet list.
.code — code block (token spans .k/.s/.c/.n). .ghost-numeral, .ring — decorative.

Slide-specific primitives

.cover-glow — ambient radial overlay for covers. Use as a child <div class="cover-glow">. Override the 2nd accent with style="--cover-glow-2: rgba(75,101,217,.07)".
.recap-rail (+.orange) — stepped cover rail. Children: .step > .when (mono label)
- .what (display sub-label). Column count via style="--rail-cols: 4".
.checklist > .checklist-row — ruled rows. Badge slot: <span class="num">01</span> or <span class="check"></span>; then a <div> with .title + .desc. Add .has-aside and a trailing <span class="aside"> for a metadata column. Badge width via --badge-w.
.step-fade (+.shown) — entrance animation for the legacy data-step flow. For new decks, prefer reveal fragments (class="fragment fade-up") for step reveals.

Chrome & backgrounds

.chrome-top (.brand > <img>, .meta > .dot + <span>).
.chrome-bottom (.left > .bar + <span>, .pages).
Backgrounds: .bg-mesh, .bg-grid, .bg-dots, .cover-glow.

Icons

Lucide, stroke-only, via the optional CDN script: <i data-lucide="arrow-right"></i>. Colour with currentColor (use var(--primary) / var(--accent-secondary)). No emoji.

5. Slide archetypes (copy-paste)

Cover

<section class="slide pad" data-screen-label="01 Cover">
  <div class="cover-glow"></div>
  <div class="chrome-top">…</div>
  <div class="slide-body">
    <span class="eyebrow">Eyebrow</span>
    <h1 class="display">Headline<br><span class="accent">second line.</span></h1>
    <p class="lead">A one- or two-sentence lead.</p>
  </div>
  <div class="recap-rail" style="--rail-cols: 3;">
    <div class="step"><div class="when">01</div><div class="what">First</div></div>
    <div class="step"><div class="when">02</div><div class="what">Second</div></div>
    <div class="step"><div class="when">03</div><div class="what">Third</div></div>
  </div>
  <div class="chrome-bottom">…<div class="pages"></div></div>
</section>

Title + stats (split)

<div class="slide-body"><div class="split tilt-left">
  <div class="slide-head">
    <span class="eyebrow">The setup</span>
    <h2 class="title">A headline. <span class="accent">A second line.</span></h2>
    <p class="lead">Frame the challenge in two or three sentences.</p>
    <div class="cols cols-3 mt-l">
      <div class="stat"><div class="num">300+</div><div class="label">Metric</div><div class="sub">per run</div></div>
      <div class="stat"><div class="num">10⁹</div><div class="label">Metric</div><div class="sub">to evaluate</div></div>
      <div class="stat"><div class="num">Hard</div><div class="label">Problem</div><div class="sub">no shortcut</div></div>
    </div>
  </div>
  <div><!-- right column visual --></div>
</div></div>

Three pillars (card grid)

<div class="slide-body">
  <div class="slide-head"><span class="eyebrow">Approach</span><h2 class="title">Three pillars.</h2></div>
  <div class="cols cols-3 loose mt-xl">
    <div class="card accent-top"><div class="num">01</div><h4>First</h4><p>One or two lines.</p></div>
    <div class="card accent-top"><div class="num">02</div><h4>Second</h4><p>One or two lines.</p></div>
    <div class="card accent-top orange"><div class="num">03</div><h4>Third</h4><p>The orange-accented one.</p></div>
  </div>
</div>

Two-world comparison (tinted cards)

<div class="cols cols-2 mt-l">
  <div class="card tall tint"><div class="num">TODAY</div><h4>The current world</h4><p>…</p></div>
  <div class="card tall tint orange"><div class="num">TOMORROW</div><h4>The next world</h4><p>…</p></div>
</div>
<div class="callout mt-m"><p>The bridge statement between the two.</p></div>

Checklist

<div class="checklist mt-l">
  <div class="checklist-row"><span class="num">01</span><div><div class="title">Item</div><div class="desc">Description.</div></div></div>
  <div class="checklist-row"><span class="check"></span><div><div class="title">Open item</div><div class="desc">Description.</div></div></div>
  <div class="checklist-row has-aside" style="--badge-w: 40px;"><span class="check"></span><div><div class="title">With aside</div><div class="desc">Description.</div></div><span class="aside">~12 min</span></div>
</div>

Voting / bars

<div class="cols cols-2 mt-l">
  <div class="scorebar"><div class="label">Option A</div><div class="track"><div class="fill" style="width:72%"></div></div><div class="amt">72%</div></div>
  <div class="scorebar"><div class="label">Option B</div><div class="track"><div class="fill" style="width:41%"></div></div><div class="amt">41%</div></div>
</div>

Quote / voice wall

<div class="cols cols-5 tight mt-l">
  <div class="card"><p>A short quote.</p><div class="num mt-s">NAME · ROLE</div></div>
  <!-- repeat -->
</div>

Closing

<section class="slide pad" data-screen-label="NN Closing">
  <div class="cover-glow"></div>
  <div class="chrome-top">…</div>
  <div class="slide-body">
    <h1 class="display"><span class="accent">Thank you.</span><br>One closing line.</h1>
    <p class="lead">A short sign-off.</p>
  </div>
  <div class="chrome-bottom">…<div class="pages"></div></div>
</section>

6. Step reveals

Wrap progressively-revealed elements with class="fragment fade-up" — reveal shows them one arrow-press at a time, in DOM order. (The legacy data-step + .step-fade flow is still supported but fragments are preferred for new decks.)

7. When local CSS is allowed

Only for something genuinely special and non-reusable: an interactive draggable visualization, a bespoke animated diagram, a one-off drawing area. Keep it in the deck’s own <style> and scoped to that slide. Everything else composes the classes above.

8. Live references

Components showcase (every primitive, no local CSS): examples/components/index.html
Sample deck (22 archetypes): examples/sample-deck/index.html
Style guide (full catalogue): styleguide/index.html
Brand & voice: the design handoff README-brand.md.

License

MIT © HolistiQs GmbH. The published bundle redistributes reveal.js (MIT) and the Sora, Inter and Geist Mono web fonts (SIL Open Font License 1.1); their notices are in THIRD_PARTY_LICENSES.md.