# Deckard

> Next.js presentations built from editable slide patterns, with presenter tools, themes, and PDF export.

# Example presentation
Source: https://deckard.thebuilder.dk/example-deck

This engineering review uses the same content across an opener, an agenda, figures, a comparison, a roadmap, media, a quote, and a close. It is short enough to read as one talk.

[Open the presentation](https://deckard-playground.thebuilder.dk/example) to navigate it.

<ExampleDeck />

The source deck follows this order:

1. `HeroSlide` opens the review.
2. `OpenContentSlide` and `ContentsList` set the agenda.
3. `OpenContentSlide` and `StatGrid` report the figures.
4. `OpenContentSlide` and `CardGrid` compare the decision.
5. `ImageShowcaseSlide` pairs evidence with its context.
6. `OpenContentSlide` and `Timeline` set the plan.
7. `QuoteSlide` carries the reviewer's words.
8. `BreakerSlide` closes on the next action.

The [slide patterns guide](/slide-patterns) maps each job to its React components. The [feature deck](https://deckard-playground.thebuilder.dk/slides/intro) covers runtime behavior, authoring, themes, and validation in depth.

---

# Accessibility
Source: https://deckard.thebuilder.dk/guides/accessibility

The runtime gives every slide landmarks, names every control, and keeps the deck driveable from the keyboard. Everything inside the canvas is yours.

## What the runtime already does

- The shell renders `<header>`, `<main>`, `<footer>`, and a `<nav aria-label="Deck controls">`. Your slide body lands inside `<main>`.
- Every control in the cluster has an `aria-label`: the command center trigger, the presenter popout, the colour mode toggle, and previous and next.
- The controls cluster is invisible at rest but stays in the accessibility tree and in tab order. Tabbing into it reveals it.
- Unrevealed step content carries `aria-hidden` and `inert`, so a screen reader and the tab order both skip it until it appears.
- The slide title becomes the document title, through `generateMetadata`.
- The footer progress bar is `aria-hidden` and the slide counter next to it is plain text, so the position is read rather than inferred from a graphic.
- A slide that throws renders an error card with `role="alert"` and the rest of the deck keeps working.

## What it does not do

Say these out loud before you decide a deck is done, because nothing in the toolchain will tell you:

- **No live region.** Moving to the next slide or revealing a step announces nothing. A screen reader picks up the route change and the DOM mutation, and that is all.
- **No focus management on navigation.** Nothing calls `focus()` when the slide changes.
- **No skip link.**
- **No accessible name on `<main>` or on the canvas.** The deck is named only by the brand text in the header.
- **No contrast checking.** `deckard validate` reads the theme's tokens and never their values.

## Keyboard

Every binding is on `window`, so the deck responds wherever focus sits.

| Keys | What happens |
| --- | --- |
| `→` `↓` `PageDown` `Space` | Next step, then next slide |
| `←` `↑` `PageUp` | Previous step, then previous slide |
| `Cmd/Ctrl + K` | Toggle the command center |
| `P` | Open the presenter window |
| `D` | Switch colour mode, when the theme carries both |

Navigation keys are ignored inside links, buttons, inputs, textareas, selects, and `contenteditable`, and while a modifier is held, so browser zoom still zooms.

There is no `Home` or `End` binding, no `F` for fullscreen, and no help key. Use the command center to jump.

### Controls inside a slide

An interactive slide is a client component like any other, and the deck does nothing special for it. Two things to get right:

**Give every control a real accessible name.** An icon-only button needs `aria-label`.

**Expect the arrow keys to be taken.** The deck advances on arrows unless the event target is a link, button, input, textarea, select, or `contenteditable`. A custom widget that listens for arrow keys and is none of those will fire and advance the slide at the same time. Mark it so the deck leaves it alone:

```tsx
<div data-step-ignore-click="true" onKeyDown={handleKeys}>
  <Carousel />
</div>
```

Calling `preventDefault()` on the event also stops the deck, since it skips anything already handled.

## Headings

The canvas has no heading of its own, so the heading structure inside a slide is entirely yours.

`SlideHeading` renders the slide's own heading. Below it, use real heading elements in order and never skip a level to get a size, because size is a token:

```tsx
<OpenContentSlide eyebrow="Context" title="Where the time goes">
  <h3>Build</h3>
  <p>Eleven minutes, most of it typechecking.</p>
</OpenContentSlide>
```

A deck is many pages rather than one document, so each slide starting its own outline is the normal shape. The failure to avoid is a slide whose only heading is a `<div>` sized to look like one.

`Eyebrow` is a label above the heading, not a heading. It does not need to be one.

## Images

`alt` is optional on the media blocks and defaults to the empty string, which marks the image decorative and hides it from assistive technology. Nothing warns you, and `deckard validate` does not check it.

So the default is silent and wrong for any image that carries meaning. Write the alt text every time:

```tsx
{
  media: {
    src: "/revenue.png",
    alt: "Revenue climbing from 2 to 9 million across four quarters",
  },
}
```

Pass `alt=""` deliberately when the image really is decoration, so the next person can tell the difference between a decision and an omission.

Captions and credits render as their own paragraphs next to the image rather than as a `<figcaption>` tied to it, so a caption does not stand in for alt text.

## Video

`SlideMediaVideo` shows controls unless the video autoplays, and an autoplaying video is muted and looped.

It has no `<track>` support, so captions are not something the component can add for you. A video carrying speech needs either a caption track on your own `<video>` element or the content restated on the slide.

## Colour and contrast

The built-in themes ship as they are. The moment you eject one and edit `theme.css`, contrast is yours.

The rule each `THEME.md` states: body copy has to clear 4.5:1 against `--background` and against `--slide-surface`.

Check against the composite, not the token. `--slide-surface` is translucent in every built-in, so text on a surface sits over whatever background variant is painted underneath. Sampling the rendered pixels is the only reliable read.

Check both colour modes. A dark override that changes `--foreground` and leaves `--slide-surface` alone passes validation and fails a reader.

The token pairs to check when you change a colour:

| Background | Foreground |
| --- | --- |
| `--background` | `--foreground` |
| `--card` | `--card-foreground` |
| `--popover` | `--popover-foreground` |
| `--primary` | `--primary-foreground` |
| `--secondary` | `--secondary-foreground` |
| `--muted` | `--muted-foreground` |
| `--accent` | `--accent-foreground` |

`--slide-chrome-foreground` sits on the canvas background and defaults to `--muted-foreground`, which is the token most likely to be too quiet once you darken a background.

Do not carry meaning in colour alone. A room sees a projector, and a projector is not your monitor.

## Motion

The runtime honours `prefers-reduced-motion` in three places: a theme's animated background holds one still frame, the controls cluster stops sliding as it reveals, and the `phosphor` theme's blinking cursor stops and stays lit.

The background is the one that matters most, and it is the one a reader cannot turn off any other way. Dropping the preference mid-session starts it moving without a reload.

The runtime does not honour the preference anywhere else. `SlideStep` fades over 300ms with no reduced-motion guard, and so do the presenter preview crossfade and the command dialog.

Any animation you add is yours to guard:

```css app/globals.css
@media (prefers-reduced-motion: reduce) {
  .reveal-item {
    animation: none;
  }
}
```

In Tailwind that is the `motion-reduce:` variant, `motion-reduce:transition-none`.

The PDF export disables animation entirely, but it keys off the export build rather than the reader's preference, so it is not the same thing.

## Scrollable regions

The canvas clips what does not fit. Trim the slide first; `deckard check-overflow` tells you which ones and by how much.

When content genuinely has to scroll, `SlideScrollArea` is the way, and it takes a required `label`:

```tsx
<SlideScrollArea label="Full configuration" maxHeight={360}>
  <ConfigTable />
</SlideScrollArea>
```

`label` becomes `aria-label` on a `<section>`, which names the region. The component is already `tabIndex={0}`, so it is reachable and scrollable from the keyboard, and it swallows `Space`, arrows, `Home`, `End`, `PageUp`, and `PageDown` so scrolling never steps the deck.

The label is required because an unnamed scroll region is announced as a region and nothing else. Name what is in it, not what it does: `Full configuration` beats `Scrollable area`.

`CodeBlock` wraps its own content in one, labelled `Code sample`.

## HTML or PDF

These are not the same artifact.

The **deployed deck** is real HTML. It has landmarks, headings, alt text, a text layer, working links, keyboard navigation, and both colour modes.

The **PDF export** is one PNG per page. Each slide is screenshotted and drawn into the file, so it has no text layer, no headings, no alt text, no links, and no selectable or searchable text. A screen reader gets nothing from it. It is also fixed to one colour mode, and a stepped slide collapses to a single captured state.

Share the URL when the audience matters. Send the PDF as a convenience alongside it, not instead of it. [Deploying](/guides/deploying) covers getting the deck to a URL.

---

# Blocks and the registry
Source: https://deckard.thebuilder.dk/guides/blocks-and-the-registry

Slide blocks are not in `@thebuilder/deckard-core`. They install into your app as source files through shadcn, into `app/slides/blocks/`, and you edit them from then on.

Expect to edit them. A block that assumed your theme would be a block you fight. `HeroSlide` caps its headline with `text-balance` tuned for a sans display face; on a serif you will want to change it, and you can, because it is your file.

## The items

| Item | Installs | Contains |
| --- | --- | --- |
| `block-typography` | `typography.tsx` | `Eyebrow`, `SlideHeading`. Every other block depends on it. |
| `block-slide-layouts` | `templates.tsx` | `HeroSlide`, `HeroSplitSlide`, `HeroCenteredSlide`, `BreakerSlide`, `MinimalBreakerSlide`, `StatementSlide`, `CodeSplitSlide`, `ContentSlideCard`, `OpenContentSlide`, `FocusSlide`. |
| `block-collections` | `collections.tsx` | `RevealList`, `BulletList`, `ContentsList`, `ColumnGrid`, `FeatureGrid`, `CardGrid`. |
| `block-prose` | `prose.tsx` | `QuoteSlide`, `ProseSlide`. |
| `block-tables` | `tables.tsx` | `DataTable`, `Timeline`, `LogList`. |
| `block-media` | `media.tsx` | `ImageShowcaseSlide`, `MediaPair`, `MediaGallery`, `FullscreenMediaSlide`. |
| `block-metrics` | `metrics.tsx` | `StatGrid`. |
| `preset-blocks` | all of them | Plus the one stylesheet line a consumer cannot guess. |

`preset-blocks` is the one to run. Alongside the block files it adds `@import "@thebuilder/deckard-core/styles.css"` to your app stylesheet, which carries the token contract and registers the package's own compiled output as a Tailwind source. That import is the entire build wiring. There is no `transpilePackages` entry and no `@source` line for you to add.

Every block is left aligned and fills the padded frame. The source designs put content at the left margin and run it to the right one, and only `HeroCenteredSlide` and `MinimalBreakerSlide` centre anything. `ProseSlide` caps its measure, in canvas pixels rather than `ch`, because the canvas is 1920 wide and never changes.

Themes used to be registry items and are not any more. They ship as `@thebuilder/deckard-themes`, so a deck gets one by importing it rather than by installing files it did not ask to own.

## Installing

```bash
deckard add block metrics
```

Or straight through shadcn:

```bash
pnpm dlx shadcn@latest add @deckard/preset-blocks
```

`deckard add block` reads the registry URL from `components.json` under `registries["@deckard"]`, or takes `--registry <url>` with a `{name}` placeholder. It probes the host before doing anything and tells you what to start when the probe fails. `--yes` passes shadcn `-y -o`, overwriting the files it installs without asking.

shadcn is a dependency of `@thebuilder/deckard-cli`, pinned to the version the registry is built with, and `deckard add` runs that installed binary. There is no `dlx` and no download, so the same version runs on every package manager.

:::warning
`deckard init` writes `https://deckard.thebuilder.dk/r/{name}.json` into `components.json`, which is this documentation site. Nothing to run locally: `deckard add block` fetches from it directly. Point `--registry` at another URL with a `{name}` placeholder to install from your own.
:::

## Building it

From the repository root:

```bash
pnpm registry:build
```

That runs `shadcn build --output apps/docs/public/r`, writing one JSON file per item. This site serves `public/` as static files, so each item lands at `/r/<name>.json`.

The source of truth is `registry.json` at the repository root. Block files point at `apps/playground/app/slides/blocks/`; the preset barrel points at the matching CLI template source. `deckard validate --registry <path>` checks that every source path exists.

## Composing

Start with the [slide patterns gallery](/slide-patterns) when you know the job a slide has to do but not the component name. This page documents how the source files install and how their APIs compose.

Two rules cover almost every slide.

**One surface per slide.** A framed panel holds flat content, an open frame holds content that brings its own border. Blocks with a surface carry `data-slide-surface`; `ContentSlideCard`'s panel carries `data-slide-panel` and always paints its card. Nest them and you get a frame inside a frame, plus a development console warning naming `OpenContentSlide` and `FocusSlide`.

**Prefer an explicit variant component over a boolean prop.** `ContentSlideCard` takes flat content, `OpenContentSlide` takes content that brings its own border, and `FocusSlide` hands one block the whole frame.

### The layout blocks

**ContentSlideCard**

Eyebrow, heading, and lead above a bordered `--slide-surface` panel. For
body content with no surface of its own.

```tsx
<ContentSlideCard eyebrow="Context" description="Where this came from.">
  <p>Flat prose, a definition list, your own markup.</p>
</ContentSlideCard>
```

**OpenContentSlide**

The same intro with no panel, for content that brings its own frame.

```tsx
<OpenContentSlide eyebrow="Results" description="Three quarters in.">
  <FeatureGrid items={features} />
</OpenContentSlide>
```

**FocusSlide**

One block, with no heading, lead, or panel. It hands the block the whole
frame at the normal type scale, so a code sample shows more lines rather
than bigger ones, and takes one optional `kicker` for orientation.

```tsx
<FocusSlide kicker="deck/slides.tsx">
  <CodeBlock code={sample} language="typescript" />
</FocusSlide>
```

All of `HeroSlide`, `BreakerSlide`, `ContentSlideCard`, and `OpenContentSlide` fall back to the slide's own `title` through `useSlideTitle()` when you do not pass one, so a title stays defined in one place.

### Media

```tsx
<ImageShowcaseSlide
  image={{
    src: diagram,
    alt: "System architecture",
    caption: "Everything upstream of the queue.",
    placeholder: "blur",
  }}
/>
```

```tsx
<FullscreenMediaSlide
  media={{ kind: "video", src: "/videos/launch.mp4", autoplay: true }}
  overlay="strong"
>
  <h2>Launch</h2>
</FullscreenMediaSlide>
```

`FullscreenMediaSlide` takes `variant` (`"background"`, the default, bleeds to every edge; `"framed"` insets it in a bordered surface) and `overlay` (`"none"`, `"subtle"`, `"medium"` by default, `"strong"`) for text readability over media. Both blocks take `next/image` sources, forward `blurDataURL` from a static import, and accept `unoptimized` so an SVG served from `public/` skips the image optimizer instead of needing `images.dangerouslyAllowSVG`. Video goes through `SlideMediaVideo` from `@thebuilder/deckard-core/components`, which suppresses autoplay inside the presenter preview iframe, and defaults an autoplaying video to muted and looping with no controls.

Both pad against `--slide-chrome-top` and `--slide-chrome-bottom`, so the deck header and slide counter never sit on top of a caption. Use them instead of dropping an `<img>` on a slide, which will not fit the canvas and will not respect the chrome.

### Known edges

`FeatureGrid` renders three columns. Four items give you three on one row and one alone on the next; reach for `CardGrid` with `columns={2}` instead.

`MediaPair` takes a tuple of exactly two panels, so a third is a compile error. Two frames side by side is the layout; three is `MediaGallery`, which puts them on a grid rather than squeezing the row until none of them reads.

`DataTable` caps nothing. How many rows fit depends on the theme's type scale, so `deck:check-overflow` is the thing that tells you, not the type. Four or five rows and four columns is what the source templates show.

`CardGrid` marks one card with `accent`, which takes `--slide-accent-soft`. Marking two marks neither.

`StatGrid` takes two to four stats, typed as a union of tuples, so a fifth is a compile error. At five, reach for `DataTable`. Each stat takes an optional `unit` suffix and an optional `meter`, a proportion from 0 to 1 that draws a bar under the figure. Leave the meter out unless you can say what it is a proportion of. Captions are capped at a 26-character measure, sized for "up from 2.6k" and not for a sentence, so give the figure something to be measured against.

---

# Deploying
Source: https://deckard.thebuilder.dk/guides/deploying

A deck is a Next.js app, so deploying it is deploying a Next.js app. This page covers the parts that are about the deck rather than about Next.

## Build it

```bash
npm run build
```

That is `next build`, the script [`deckard init`](/reference/cli#deckard-init) wrote. Every slide prerenders to static HTML, because the slide route reads nothing from the request.

Check the deck before you build, not after:

```bash
deckard validate
deckard check-overflow
```

A duplicate slug fails the build with a message naming both slides. [Troubleshooting](/guides/troubleshooting) has that one and the rest.

## Vercel

Import the repository and deploy. A deck generated by `deckard init` sits at the repository root with its own `package.json`, so Vercel detects Next.js and needs no build settings.

If the deck lives inside a monorepo, set the project's root directory to the deck's folder and let Vercel infer the rest.

## Any Node host

`next build` then `next start`, behind whatever process manager the host uses. The default port is 3000 and `next start -p <n>` moves it.

The deck needs a Node runtime for `next start` even though every slide is static. If the host only serves files, use [static export](/reference/requirements#static-export) instead, which needs two changes to the app.

## The public site URL

`app/sitemap.ts` builds absolute URLs, and it needs to know the deck's address:

```bash
NEXT_PUBLIC_SITE_URL=https://talk.example.com
```

Without it the sitemap falls back to `http://localhost:3000` and publishes localhost URLs. Pass `siteUrl` to the adapter instead if you would rather keep it in the file:

```ts app/sitemap.ts
export default createDeckSitemap(deck, { siteUrl: "https://talk.example.com" })
```

The variable is `NEXT_PUBLIC_`, so Next inlines it at build time. Setting it after a deploy changes nothing until the next build.

That sitemap is also how `deckard screenshots`, `check-overflow`, and `export pdf` find the slide list, so keep the route even if you do not care about search engines.

## A custom domain

Point the domain at the deployment, then set `NEXT_PUBLIC_SITE_URL` to the final address and rebuild. Nothing else in the deck holds a hostname.

## Sharing one slide

Give the slide a `slug` and link to `/slides/<slug>`.

```tsx deck/slides.tsx
{ slug: "pricing", title: "Pricing", body: <PricingSlide /> }
```

A slide with no slug is served at its 1-based position, so it is `/slides/4` until someone inserts a slide above it and it becomes `/slides/5`. A slug is the link that survives reordering. [Writing slides](/guides/writing-slides#slide-ids) covers the rules; slugs take lowercase letters, digits, and hyphens.

`/` redirects to the first slide, so the bare domain is a fine thing to hand out.

## Speaker notes are public

`notes` never render in the deck, and they do ship to the browser with the slide. They are in the prerendered HTML, so anyone who can open a slide can read them in the page source.

Write notes on the assumption that the audience can read them, or keep the deployment private until after the talk.

## The presenter window

`/presenter` is an ordinary static route and deploys with the deck. Anyone who has the URL can open it.

On its own it shows nothing. The two windows sync over a `BroadcastChannel`, which is same-origin and same-browser, so a stranger loading `/presenter` gets an empty console reading `Waiting for connection from the slideshow tab.` It never reaches your machine and never pulls your notes across the network.

The exposure that matters is the one above: the notes are in the slide page, not in the presenter route. Blocking `/presenter` does not hide them.

If you want the whole deck private, put the deployment behind the host's access control. On Vercel that is deployment protection on the project.

## Fonts and assets

Files in `public/` are served from the site root, so `public/logo.svg` is `/logo.svg`. Reference them with a root-relative path; the deck holds no base path.

A built-in theme reaches no font host. The ones set in a real typeface ship it inside `@thebuilder/deckard-themes`, subset and self-hosted, and the rest use system stacks. Adding a web font of your own is `next/font` in `app/layout.tsx`, the same as any Next app.

Images in the media blocks go through `next/image`, which needs the optimizer the host runs. That is automatic on Vercel and on any Node host running `next start`. It is the one thing [static export](/reference/requirements#static-export) has to turn off.

## What deploys and what does not

| Route | Deployed | Notes |
| --- | --- | --- |
| `/` | yes | Redirects to the first slide. |
| `/slides/<id>` | yes | One static page per slide, notes included. |
| `/presenter` | yes | Empty until a deck window on the same origin syncs to it. |
| `/sitemap.xml` | yes | Absolute URLs from `NEXT_PUBLIC_SITE_URL`. |

The deck controls, the command center, and the presenter popout are client-side and need no server of their own.

## Handing out a PDF instead

[`deckard export pdf`](/reference/cli#deckard-export-pdf) writes `out/slides.pdf`, one page per slide, and needs no hosting at all. Read [Exporting](/guides/exporting) for the flags, and [Accessibility](/guides/accessibility#html-or-pdf) for what a PDF loses compared to the deployed deck.

---

# Exporting
Source: https://deckard.thebuilder.dk/guides/exporting

PDF export and screenshots build the app, serve it on a spare port, and open a browser at canvas scale. The contact-sheet command arranges screenshots that already exist.

## PDF

```bash
pnpm exec playwright install chromium
deckard export pdf
```

One page per slide at the deck's canvas size, captured from the canvas element. `1920x1080` becomes `1440x810pt`, which is the same thing at 96dpi. The page size comes from the `canvas` config in `deck/deck.ts`, the same config the deck renders with.

Output lands at `out/slides.pdf` in the deck's own directory.

| Flag | Default | What it does |
| --- | --- | --- |
| `--dark` | off, so the export is **light** | Export the dark deck instead. |
| `--skip-build` | off | Reuse whatever is in `.next`. |
| `--port <n>` | `3410`, or `PDF_EXPORT_PORT` | Move the temporary server off a busy port. |

Pass `--dark` when the PDF is for a screen rather than for print.

In export mode the build runs with `NEXT_PUBLIC_PDF_EXPORT=1`, which:

- disables animations and transitions
- drops the deck controls
- keeps the deck header and footer, exactly as each slide's own modes say

Set `PDF_EXPORT_OUTPUT` to write somewhere other than `out/slides.pdf`. It resolves against the deck directory.

:::note
The export uses its own build profile, separate from the one the screenshot and overflow commands share, because it needs the export environment variables compiled in. Expect a build the first time even after running `deckard screenshots`.
:::

## Screenshots

```bash
deckard screenshots
deckard screenshots --light --max 5
```

One PNG per slide at canvas size, written to `out/screenshots/<id>.png`, plus a `manifest.json` recording the canvas size, the color mode, and every slide's file, id, number, and title.

| Flag | Default | What it does |
| --- | --- | --- |
| `--light` | off, so **dark** | Capture light mode. |
| `--max <n>` | all | Stop after n slides. |
| `--skip-build` | off | Reuse whatever is in `.next`. |
| `--port <n>` | `3411` | Move the temporary server off a busy port. |

The directory is wiped and recreated on each run, so the manifest and the PNGs never disagree.

Every capture asserts the applied color mode matches the one requested, and throws naming the slide rather than writing a mislabelled PNG. A theme that pins itself to dark still shoots light when you ask, because the harness seeds the color-mode storage key before the page loads.

## Contact sheet

```bash
deckard screenshots
deckard contact-sheet --columns 5
```

Composes the existing screenshots into `out/contact-sheet.png`, a labelled grid of the whole deck. It does not build or serve anything; it reads `out/screenshots/manifest.json` and fails telling you to run the screenshots first if that file is missing. The color mode comes from the manifest.

`--columns <n>` sets the grid width and defaults to `4`.

Three slides in a row that all end above the halfway line, or the same numbered list twice back to back, are invisible one slide at a time and obvious in a grid.

## Build reuse

The screenshot, overflow, and PDF commands share one harness. It stamps `.next/deckard-build.json` after a build and compares that timestamp against the newest file under `app/`, `assets/`, `components/`, `deck/`, `hooks/`, `lib/`, and `public/`, plus `components.json`, `next.config.*`, `package.json`, `postcss.config.*`, `tsconfig.json`, and the resolved `@thebuilder/deckard-core` and its `src/`. A stale stamp triggers `next build`.

`--skip-build` reuses whatever is there regardless. `--port <n>` moves off the default when something else has the port; the harness refuses to start if anything already answers on it.

## Slide discovery

The harness reads slide ids from the app's own `/sitemap.xml`, which is `app/sitemap.ts` re-exporting `createDeckSitemap(deck)`. Export and screenshots stay aligned with your published slide paths, and an app that dropped that route gets an error naming it.

---

# Presenting
Source: https://deckard.thebuilder.dk/guides/presenting

## Keyboard

| Keys | What happens |
| --- | --- |
| `→` `↓` `PageDown` `Space` | Next step, then next slide |
| `←` `↑` `PageUp` | Previous step, then previous slide |
| `Cmd/Ctrl + K` | Toggle the command center |
| `P` | Open the presenter window |
| `D` | Switch the canvas between light and dark |

Navigation keys are ignored while you are typing in a field, when the event already had `preventDefault` called on it, and when a modifier is held, so browser zoom (`Cmd +`, `Cmd -`) still zooms.

On a stepped slide the arrow keys walk the steps first and only then move to the next slide, so one key drives the whole deck.

## The command center

`Cmd/Ctrl + K` opens a searchable list of every slide by number and title. Pick one and the deck navigates. It opens whether or not the controls cluster is showing.

## The deck controls

The command center trigger, presenter popout, color mode toggle, and compact previous and next buttons sit in one cluster in the bottom right corner, outside the canvas.

The cluster is hidden at rest. It reveals when the pointer comes near the corner, when anything inside it takes focus, or while the command dialog is open. A device matching `(any-pointer: coarse)` also gets a handle in the corner that expands the cluster on tap, and the proximity reveal is on wherever `(any-pointer: fine)` matches. Both queries ask per capability rather than about the primary pointer, so a hybrid laptop with a trackpad and a touchscreen gets both affordances.

Hidden means transparent, not absent. The buttons stay in the accessibility tree and tabbing into them reveals the cluster. A presenter preview and a PDF export drop the cluster entirely and keep the header and footer.

## The presenter window

Press `P` or click the popout button. A second window opens at `/presenter` and syncs with the deck over a `BroadcastChannel`, so the two stay in step without a server.

What it shows:

- The current slide, and a preview of what comes next (aware of reveal steps, so the preview advances with them)
- Speaker notes for the current slide, with font-size controls
- A timer you start, and a 24-hour clock
- A flow window: the current slide with a little of the deck behind it and more of it ahead, by title. Click any of them to jump the deck there.

Arrow keys in either window drive both.

### Notes

`notes` is speaker-only text on a slide. It never renders in the deck.

```tsx
{
  title: "Pricing",
  notes: "They will ask about the enterprise tier. The answer is 'call us'.",
  body: <PricingSlide />,
}
```

In a slide module, export it:

```tsx deck/slides/pricing.slide.tsx
export const notes = "They will ask about the enterprise tier."
```

Notes written the way a speaker writes them run three or four paragraphs. That is the usual reason a slide earns its own file.

### Detecting the preview

The presenter preview renders slide routes with `?presenterPreview=1`. A client component inside a slide can detect it:

```tsx
"use client"
import { useIsPresenterPreview } from "@thebuilder/deckard-core/components"

export function Chart() {
  const isPreview = useIsPresenterPreview()
  return isPreview ? <ChartStill /> : <ChartAnimated />
}
```

Use it to skip autoplay, audio, canvas work, or anything else expensive inside the preview iframe. The built-in video primitive already suppresses autoplay there.

The slide route itself never reads the query. `?presenterPreview=1` and `?step=` are read on the client inside a Suspense boundary that holds nothing but the reader, which is what lets every slide prerender as static HTML.

## Step reveals

Set `stepCount` on the slide and wrap each phase in `SlideStep`:

```tsx
{
  title: "The argument",
  stepCount: 3,
  body: (
    <OpenContentSlide eyebrow="Three parts" title="The argument">
      <SlideStep step={0}>Everyone agrees on the premise.</SlideStep>
      <SlideStep step={1}>Almost nobody acts on it.</SlideStep>
      <SlideStep step={2}>Here is what that costs.</SlideStep>
    </OpenContentSlide>
  ),
}
```

`step` is zero-based. A step is visible once the current step reaches it, so step `0` shows immediately.

:::note
Hidden steps stay in the layout, so a stepped slide takes its full height from the first step and nothing reflows as it reveals. [`check-overflow`](/reference/cli#deckard-check-overflow) therefore measures the fully revealed slide.
:::

| Prop | Default | What it does |
| --- | --- | --- |
| `step` | required | The zero-based index this content appears at. |
| `mountOnReveal` | `false` | Render an empty placeholder until the step arrives, instead of a hidden copy. Use it for something expensive. |
| `className` | | Applied to the step wrapper. |

`SlideStepAdvanceArea` wraps content in a click-to-advance surface. Clicks on links, buttons, inputs, and anything marked `data-step-ignore-click="true"` pass through untouched.

`useSlideStepper()` returns the current step, the count, and `advance` / `retreat` / `canAdvance` / `canRetreat` / `isReadOnly`, for a slide that wants to drive its own reveal. It returns `null` outside a stepper.

## Color mode

A theme declares which color modes it carries and what a browser opens on. `defaultColorMode: "system"` needs both modes listed. A theme that lists one pins the canvas to it and hides the light/dark toggle in the controls. There is no runtime switching between named themes.

`defaultColorMode` decides what a browser opens on, not what the checks capture. `--light` and the light PDF export force the mode they name, and a capture that came out in the other mode fails naming the slide rather than being written.

---

# The canvas
Source: https://deckard.thebuilder.dk/guides/the-canvas

Every slide is authored in one fixed coordinate space, 1920x1080 by default. `SlideViewport` measures the browser window, scales the canvas to fit, and centers it. `SlideCanvas` holds the header, footer, background, and slide body inside that space.

A slide looks the same on a laptop, a projector, a phone, and in the PDF. Only the scale changes.

## Why fixed

A presentation is shown once, at one size, to a room. Responsive layout inside a slide makes every venue a layout you did not rehearse.

The fit is measured in the browser and published as `--deckard-scale`. Slide content stays server rendered, and the canvas stays hidden until the first measurement lands, so it never flashes at the wrong size.

## Configuring it

```ts deck/deck.ts
canvas: {
  mode: "fixed",
  width: 1920,
  height: 1080,
  fit: "contain",
  margin: 0,
}
```

`margin` is the gap in browser pixels between the canvas and the window edge. At the default `0`, a window with the canvas aspect ratio shows the canvas edge to edge. Raise it if a deck wants the canvas to float inside the window.

Content spacing is a slide concern, not a canvas one: the default frame keeps slide bodies off the canvas edges, and `layout: "fullscreen"` hands the whole canvas to the slide so media can bleed to every edge.

`resolveCanvas` throws when `width` or `height` is not a positive number, or when `margin` is negative.

## No viewport units, no breakpoints

Size slide content against the canvas, with `h-full`, percentages, and fixed values.

:::warning
`svh`, `vh`, `vw`, and responsive breakpoints (`sm:`, `lg:`) react to the browser window, not to the slide. Inside the canvas they are measuring the wrong box.
:::

The same goes for colors and type sizes. Style with semantic tokens (`bg-card`, `text-muted-foreground`, `border-border`) or slide tokens (`--slide-title-size`, `--slide-code-size`, `--slide-surface`), never a hardcoded color and never a raw font size where a token exists. Changing how something looks is a `theme.css` edit, not a component edit. See the [token contract](/reference/tokens).

Outside the canvas the rules invert: the deck controls, command center, presenter console, and dialogs keep the app tokens from `app/globals.css`, so they stay readable whatever the deck looks like.

## Overflow

A slide loses content three ways, and only one of them reaches the canvas edge. Content can run past the canvas, it can sit inside the canvas and run under the header or the footer, and it can be cut off inside a box that hides its own overflow. All three are silent, and all three are measured:

1. **Development**

    `next dev` draws an amber outline around the slide and logs a warning
    naming the part, what it ran into, and by how many canvas pixels.

2. **The overflow check**

    `deckard check-overflow` builds the deck, opens every slide, and exits
    non-zero with the same findings. It runs the same measurement the amber
    ring does, so the gate and the browser cannot disagree.

3. **The contact sheet**

    `deckard screenshots` then `deckard contact-sheet` puts the whole deck in
    one grid. It catches the slide that fits but looks unfinished.

Two things are exempt, because in both the content is meant to leave its box: anything inside a [`SlideScrollArea`](#slidescrollarea), and a slide whose `layout` is `"fullscreen"`, which is handed the whole canvas with the chrome out of the way.

The usual fix is deleting a sentence.

## SlideScrollArea

When content genuinely has to scroll, wrap it. `SlideScrollArea` keeps wheel, touch, and key scrolling inside itself, so scrolling never steps the deck:

```tsx
import { SlideScrollArea } from "@thebuilder/deckard-core/components"

<SlideScrollArea label="Full config" maxHeight={360}>
  <ConfigTable />
</SlideScrollArea>
```

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | Required. Names the scrollable region for assistive tech. |
| `maxHeight` | `number` | Height cap in canvas pixels. |
| `className` | `string` | Applied to the scroll container. |
| `children` | `ReactNode` | Required. |

`CodeBlock` takes its own optional `maxHeight` and uses it for long samples.

## Where the chrome lives

Chrome splits in two.

**Inside the canvas** sit the deck header and footer. They scale with the deck, print into the PDF export, show up in a presenter preview, and belong to the theme.

**Outside the canvas** sit the deck controls: the command center trigger, the presenter popout, the color mode toggle, and compact previous and next buttons. They keep their own size and hit targets at any scale, down to a phone.

`--slide-header-space` and `--slide-footer-space` decide how much of the canvas the chrome gets; the [token reference](/reference/tokens#chrome) carries their defaults. The frame reserves them as padding, and a fullscreen slide republishes them as `--slide-chrome-top` and `--slide-chrome-bottom`, the inset a bleeding layout has to clear. A theme that redesigns the chrome to a different height sets those two and the slide content moves with it. `phosphor` does exactly that for its thinner status bar.

---

# Themes
Source: https://deckard.thebuilder.dk/guides/themes

A theme owns every audience-facing color, size, and background in the deck, including the header and the footer. Its stylesheet is scoped to a class that `SlideCanvas` puts on the canvas element, so the deck controls, command center, and presenter console keep the app tokens and stay readable whatever the deck looks like.

A theme is three files:

| File | What it holds |
| --- | --- |
| `theme.css` | Every token and every selector, scoped to the theme class. |
| `index.ts` | One `SlideTheme` object. |
| `THEME.md` | What each token controls and what this theme sets it to. |

## The built-ins

<ThemeStrip />

Each frame is a slide canvas, not a picture of one, painted by that theme's own stylesheet in the color mode the theme opens on. Follow one into the [theme gallery](/themes) for the same frames at a size you can read, with a light and dark switch on every card and the palette behind it.

<ThemeTable />

## Picking one

Import it and hand it to `defineDeck`. Importing the module pulls in its stylesheet:

```ts deck/deck.ts
import { defineDeck } from "@thebuilder/deckard-core"
import { phosphor } from "@thebuilder/deckard-themes"
import { slides } from "@/deck/slides"

export const deck = defineDeck({ slides, theme: phosphor, /* ... */ })
```

`deckard add theme <name>` makes that edit for you, rewriting both the import and the `theme` property.

Only the theme a deck imports reaches the bundle. The barrel re-exports every built-in and the bundler drops the modules nothing uses, stylesheets included.

### The stylesheet on its own

`@thebuilder/deckard-themes/<name>/theme.css` is the same file the module imports, exported as a subpath so something that is not a deck can load it:

```ts
import "@thebuilder/deckard-themes/ledger/theme.css"
```

A deck never needs this. It exists for a page that renders a slide outside the runtime, such as the [theme gallery](/themes) on this site, which builds a scaled-down canvas out of the real markup and lets each theme's own stylesheet paint it.

## Ejecting

`deckard eject theme` copies the theme the deck imports out of the installed package into `deck/theme/` as `theme.css`, `index.ts`, and `THEME.md`, then repoints `deck/deck.ts` at the copy. From then on the theme is your source and the package never touches it.

```bash
deckard eject theme
deckard eject theme --theme ledger   # eject a different built-in instead
```

It refuses when `deck/theme/` already exists.

:::warning
An ejected theme no longer receives updates from `@thebuilder/deckard-themes`. If the built-in you started from gains a token or fixes a contrast bug, your copy does not, and no check compares the two files.
:::

## The SlideTheme object

```ts deck/theme/index.ts
import type { SlideTheme } from "@thebuilder/deckard-core"

import "./theme.css"

export const theme = {
  className: "my-theme",
  colorModes: ["light", "dark"],
  defaultColorMode: "system",
  id: "my-theme",
} satisfies SlideTheme
```

| Field | Type | What it does |
| --- | --- | --- |
| `className` | `string` | The class `SlideCanvas` puts on the canvas. Every selector in `theme.css` is scoped to it. |
| `colorModes` | `("light" \| "dark")[]` | Which modes the stylesheet actually carries. |
| `defaultColorMode` | `"light" \| "dark" \| "system"` | What a browser opens on. |
| `id` | `string` | Names the theme in `deckard validate` and `deckard eject theme`. |

`defineDeck` validates this. `defaultColorMode: "system"` needs both modes in `colorModes`. A theme listing one mode pins the canvas to it and hides the light/dark toggle.

## The token contract

`@thebuilder/deckard-core/styles.css` declares every `--slide-*` token with a neutral default, in the `base` layer. A theme redefines them on the canvas and wins, because it ships unlayered CSS. The runtime depends on the tokens, never on a preset, so a deck with no theme still renders in neutral sizes with no decoration.

The [token reference](/reference/tokens) lists all of them. The short version of what a theme sets:

- **Type**: the font families, the size scale, and the label tracking.
- **Surfaces**: the two radii, a surface color, a muted surface, a border, a shadow.
- **Backgrounds**: a grid color and pitch, a rule color, and the `--slide-scanline`, `--slide-hatch` and `--slide-halo` effects, which the `background` variants paint with.
- **Chrome**: the colours and type of the header and footer, plus `--slide-header-space` and `--slide-footer-space` for how much canvas each gets.
- **Media**: a foreground pair and the overlay gradients for text over photography.
- **Figures**: `--slide-figure-size`, its unit size, and the height of a `StatGrid` meter.

## The other half of the contract

Tokens are values. Data attributes are parts, and they are the rest of the contract.

Every part of a block a theme might want to reach carries one, from `data-slide-eyebrow` and `data-slide-list-marker` to `data-stat-meter`. A theme styles those attributes, decorative `::before` and `::after` content included, which is how phosphor writes `[x]` where a list number goes and ledger hangs a rule there instead, neither of them editing the block. The [full list](/reference/tokens) is also the "Block part contract" comment at the bottom of `@thebuilder/deckard-core/styles.css`, and a block may rewrite its markup and its class names freely as long as those attributes stay put.

A theme styles parts. It does not add content. A boot log, a status table, a cursor line with words in it are slide content, so they belong in a block the deck composes, however much they look like decoration.

## Background variants

A slide picks one with `background`:

| Value | What the theme paints |
| --- | --- |
| `"default"` | The theme's standard slide background. |
| `"spotlight"` | A second texture, usually a hatch, behind an opener. |
| `"grid"` | A ruled or dotted field. |
| `"accent"` | The inverted statement slide. |
| `"none"` | Nothing painted. |

A theme may name variants of its own. A deck writes the name as `background`, the theme styles `[data-slide-background="<name>"]`, and `deckard validate` reports a name neither the runtime nor the theme paints. A theme paints one of its own variants with an animated canvas instead of CSS by naming it in `motion`, which is in the [core reference](/reference/core#motion-backgrounds).

`SlideBackground` renders one element carrying `data-slide-background`, and the canvas carries the variant name too, so a theme can restyle the chrome along with the sheet. What each variant paints lives entirely in `theme.css`, so changing the look is a theme edit. Read the theme's `THEME.md` first, and run `deckard eject theme` if it is still an import.

`"accent"` floods the canvas with the theme accent and flips the ink, chrome included. Use it once or twice in a deck, for the one sentence that has to land, and never on two slides in a row.

No variant paints a radial wash or a corner glow. The textures a theme has are flat colour, a rule, a grid, and a diagonal hatch.

## Writing your own

Start by ejecting the built-in closest to what you want. Writing `theme.css` from scratch means rediscovering which tokens the blocks actually read, and the `THEME.md` that comes with an ejected theme is that list.

Then:

1. **Rename the class and the id**

    Change `className` and `id` in `index.ts`, and the selector prefix
    throughout `theme.css`. They do not have to match; every built-in uses
    `<id>-theme` as the class.

2. **Set the tokens**

    Work top-down: the shadcn color variables first (`--background`, `--card`,
    `--primary`, `--border`, `--foreground`, `--muted`), then the `--slide-*`
    layer on top. The blocks read the slide tokens, so most visual changes are
    one line.

3. **Do both color modes**

    Or declare only one in `colorModes` and pin the deck to it. `deckard
    validate` checks that the dark block defines nothing the light block does
    not, and that `colorModes` matches the blocks the stylesheet carries.

4. **Style the chrome**

    The header and footer are yours. Core renders `[data-slide-header]` and
    `[data-slide-footer]` with named parts for the brand, title, meta line,
    counter, and progress element. See [Deck chrome](/reference/deck-config#deck-chrome).

5. **Validate**

    ```bash
    deckard validate
    ```

    It checks the theme class is a real selector in the stylesheet the deck
    renders, and names which file it read.

Style inside the canvas with semantic tokens (`bg-card`, `text-muted-foreground`) or slide tokens. Never a hardcoded color, and never a raw font size where a token exists.

---

# Troubleshooting
Source: https://deckard.thebuilder.dk/guides/troubleshooting

Two commands answer most of it before you read further.

```bash
deckard validate   # the slides changed
deckard doctor     # a deck that used to work stopped
```

`validate` loads the deck and checks its slides and its theme. `doctor` checks the app around it: Node, whether `@thebuilder/deckard-core` resolves, whether the stylesheet is imported, whether the four route files still re-export their adapter, and whether `deck/deck.ts` loads. Both exit 1 on a problem, and `doctor` keeps going so you see all of them at once.

## A slide does not appear

**Symptom.** You added `deck/slides/roadmap.slide.tsx` and the deck still has the old slide count. No error.

**Cause.** Either the file is not in the glob, or the dev server is serving stale modules.

Discovery matches one pattern:

```tsx
import.meta.glob("./slides/**/*.slide.tsx", { eager: true })
```

A file is picked up only if it is under `deck/slides/` and its name ends in `.slide.tsx`. `roadmap.tsx` is not, and neither is a file next to `slides.tsx` instead of inside `slides/`. Nothing warns about a file that misses.

**Fix.** Check the name and the directory, then restart `next dev`. Adding or deleting a matched file while the dev server runs leaves the page routes serving the modules they had at boot, so a correctly named file can still be missing until you restart.

`deckard validate` prints the count it actually resolved:

```text
deck   6 slides: 4 inline, 2 discovered
```

If the discovered number is not what you expect, it is the glob. If it is right and the browser disagrees, it is the dev server.

## Discovered slide "…" has no default export

**Symptom.**

```text
Discovered slide "slides/roadmap.slide.tsx" has no default export. A slide module exports its component as the default, plus optional meta and notes.
```

**Cause.** The module exports the component by name.

**Fix.** Export it as the default. `meta` and `notes` stay named:

```tsx deck/slides/roadmap.slide.tsx
export const meta: SlideMeta = { slug: "roadmap", title: "Roadmap" }
export const notes = "Skip the middle row if time is short."

export default function RoadmapSlide() {
  return <OpenContentSlide title="Roadmap">{/* … */}</OpenContentSlide>
}
```

## Discovered slide "…" is an async module

**Symptom.**

```text
Discovered slide "slides/api.slide.tsx" is an async module, so the glob handed back a promise instead of its exports. Import it in the deck array with slideFromModule, or drop the dependency that uses top-level await.
```

**Cause.** The module, or something it imports, uses top-level await or WebAssembly. The eager glob then returns a promise instead of the exports.

`CodeBlock` is the usual one. Shiki loads a WebAssembly regex engine, which is why it ships from `@thebuilder/deckard-core/code-block` and not from the components barrel. A discovered slide that imports it becomes async.

**Fix.** Take that slide out of discovery and wire it into the array by hand:

```tsx deck/slides.tsx
import * as apiSlide from "@/deck/slides/api.slide"
import { slideFromModule } from "@thebuilder/deckard-core/slide-from-module"

export const slides: SlideDefinition[] = [
  ...discovered,
  slideFromModule(apiSlide, "deck/slides/api.slide.tsx"),
]
```

The file keeps its name and its place, and stops going through the glob.

## Duplicate or invalid slug

All four fail the deck at load, so they surface from `deckard validate`, from `doctor`, and from the build.

**Two slides on one slug.**

```text
Slides 4 and 5 both use the slug "keyboard". Slide ids must be unique.
```

Rename one. The numbers are 1-based positions in the deck.

**A numeric slug.**

```text
Slide 3 has the numeric slug "2024". A numeric slug adds nothing over /slides/3 and breaks when slides move, so use letters or drop the slug.
```

**Characters that are not safe in a path.**

```text
Slide 3 has the slug "Q4 Results", which is not safe in a URL path. Use lowercase letters, digits, and hyphens.
```

`q4-results` works.

**An empty slug.**

```text
Slide 3 has an empty slug. Give it a value or drop the slug so the slide is served at /slides/3.
```

## A slide overflows the canvas

**Symptom, in the browser.** An amber ring around the canvas under `next dev`, and a console line:

```text
Slide content runs 794px below the canvas and is clipped.
```

**Symptom, in CI.**

```text
/slides/roadmap  slide content runs 794px below the canvas
1 of 6 slides overflow the canvas and are clipped. Trim the content, or wrap the part that has to scroll in SlideScrollArea.
```

**Cause.** The canvas is a fixed box and it clips silently. The three measured regions are the slide frame, the header, and the footer, so `the header` or `the footer` in that line means the chrome grew, not the body.

**Fix.** Cut a sentence. That is the right answer most of the time and the slide is usually better for it. When the content genuinely has to be there, wrap the part that can scroll:

```tsx
<SlideScrollArea label="Full configuration" maxHeight={360}>
  <ConfigTable />
</SlideScrollArea>
```

A stepped slide is measured fully revealed, because hidden steps keep their space in the layout. [The canvas](/guides/the-canvas#overflow) has the rest.

:::warning
The ring is development only. Run `deckard check-overflow` before you present, since a clipped slide looks fine right up until the room sees it.
:::

## Slide "…" rendered no [data-slide-frame] element

```text
Slide roadmap rendered no [data-slide-frame] element. Check that the route still renders SlideShell.
```

The overflow check found the page but not the canvas. `app/slides/[id]/page.tsx` has stopped re-exporting `createSlideRoute`. `deckard doctor` reports the same thing as a `routes` failure.

## Theme validation fails

`deckard validate` reads the stylesheet the deck actually renders, so these name either `@thebuilder/deckard-themes/<id>` or your ejected `deck/theme/theme.css`.

**The class is not in the stylesheet.**

```text
Theme "custom" sets className "custom-theme", but deck/theme/theme.css has no rule for .custom-theme. The canvas carries that class, so none of the theme reaches the slide.
```

The canvas gets the class from the theme object. If the stylesheet has no rule for it, the deck renders in app defaults. Check for a typo on one side or the other.

**A dark mode the stylesheet never paints.**

```text
Theme "custom" lists "dark" in colorModes, but deck/theme/theme.css has no dark block. The toggle switches to a mode the theme never paints.
```

**A dark block the theme does not list.**

```text
deck/theme/theme.css has a dark block, but theme "custom" does not list "dark" in colorModes.
```

Add `"dark"` to `colorModes`, or delete the block.

**A token defined only in dark.**

```text
deck/theme/theme.css defines --slide-surface-border only in the dark block. Light mode renders without it.
```

Every token needs a light value. Dark overrides a subset.

**The default names a mode the theme does not carry.** These come from the theme object rather than the stylesheet:

```text
Slide theme "custom" defaults to "system" but only supports dark. Support both color modes or pick one as the default.
```

:::note
Nothing validates that a theme defines any particular token. A theme missing `--slide-heading-size` passes `deckard validate` and renders at the inherited size. Read the ejected `THEME.md` for the set the theme was written against.
:::

## The presenter window does not open

**Symptom.** `P` or the popout button does nothing at all. No error, no console message.

**Cause.** The browser blocked the popup. `window.open` returned nothing and the code does not report it.

**Fix.** Allow popups for the deck's origin, then press `P` again.

Also check the other two reasons the key does nothing: `P` is ignored while focus is in an input, textarea, select, or `contenteditable`, and while any modifier is held. And a slide loaded with `?presenterPreview=1` is read-only by design, so its keys do not fire.

## The presenter window does not sync

**Symptom.** The presenter window opens and stays on `Waiting for connection from the slideshow tab.`

**Cause.** The two windows talk over a `BroadcastChannel` named `slideshow-presenter-sync`, and that channel is same-origin and same-browser. Nothing routes through a server.

So it will not connect when:

- The deck and the presenter window are on different origins, including `localhost:3000` against `127.0.0.1:3000`, and http against https.
- They are in different browsers, or one is in a private window.
- The browser has no `BroadcastChannel`. The runtime checks for it and carries on without sync rather than failing.

**Fix.** Open the presenter window from the deck itself, with `P` or the popout button, so it inherits the origin. It reads `Connected via BroadcastChannel.` once the first message lands.

A presenter window opened by pasting the URL into a different browser will never connect, and that is the design rather than a fault.

## PDF export cannot find Chromium

**Symptom.**

```text
Failed to launch Chromium. Run: pnpm exec playwright install chromium
```

**Cause.** The Playwright package is installed in the deck, but the browser binary is a separate download.

**Fix.** Run the line the message printed. It names your deck's package manager, so an npm deck is told `npm exec -- playwright install chromium` and a bun deck `bunx playwright install chromium`.

This hits `check-overflow`, `screenshots`, `contact-sheet`, and `export pdf`. It never hits `validate`, `doctor`, `init`, `add`, or `eject`, which drive no browser.

## A capture command cannot find playwright or pdf-lib

**Symptom.**

```text
playwright does not resolve from this deck. The capture commands load it from the deck's own node_modules. Install it: pnpm add -D playwright
```

**Cause.** The CLI does not ship the browser or the PDF writer. `deckard init` writes both into the deck's `devDependencies`; a deck added to an existing app by hand, or one that removed them, has neither.

**Fix.** Run the line the message printed, then the Chromium download above. `deckard doctor` lists both packages under `tooling`.

### The port is taken

```text
Something is already serving http://localhost:3410. Stop it, or pass --port=<free port>.
```

The capture commands refuse to run against a server they did not start, because it might be serving a different build. Stop it or move.

### No screenshots to compose

```text
No screenshots at /path/to/deck/out/screenshots. Run: pnpm run deck:screenshots
```

`contact-sheet` reads the manifest that `screenshots` writes and builds nothing itself.

### The sitemap has no slides

```text
No slide routes in the sitemap. Check that app/sitemap.ts still lists /slides/* entries.
```

The capture commands read the slide list from the deck's own `/sitemap.xml`. An app that dropped or rewrote that route breaks all three.

## The registry cannot be reached

**Symptom.**

```text
The registry at https://deckard.thebuilder.dk/r/metrics.json did not answer.
```

**Cause.** The URL in `components.json` points at the Deckard docs site, which serves every registry item at `/r/{name}.json`. Either the site is unreachable or the URL was changed.

**Fix.** Check the network, or point `deckard add block` somewhere else with `--registry <url>`. The URL carries a `{name}` placeholder.

**A different message, no registry configured at all:**

```text
No @deckard registry in components.json and no --registry flag.
Add one: { "registries": { "@deckard": "https://deckard.thebuilder.dk/r/{name}.json" } }
```

The blocks are yours as source either way. `deckard add block` is for taking an update or undoing an edit, so a deck that never needs one never needs the registry. [Blocks and the registry](/guides/blocks-and-the-registry) has the details.

## Styles are missing

**Symptom.** The deck renders as unstyled text, or the layout is right and every colour is wrong.

**Cause and fix.** `deckard doctor` names it:

```text
FAIL styles  app/globals.css never imports @import "@thebuilder/deckard-core/styles.css"
             Add @import "@thebuilder/deckard-core/styles.css"; to app/globals.css. It carries the --slide-* tokens and registers the runtime's own Tailwind source.
```

The check is a literal substring test, so the import has to read exactly `@import "@thebuilder/deckard-core/styles.css"`.

If the import is there and the deck is still unstyled, the theme class is the next thing to check. `deckard validate` prints the stylesheet it read and the token counts:

```text
theme  meridian (.meridian-theme): light and dark, default system
       57 tokens in the light block, 25 dark overrides, from @thebuilder/deckard-themes/meridian
```

Zero tokens, or a stylesheet path you did not expect, is the answer.

## Other messages

**A slide that throws under `next dev`** renders an inline card reading `Slide <id> threw while rendering`, and the rest of the deck keeps working. In a production build the same throw is fatal to the route and Next serves its own error page, so fix it before you build.

**`deckard <command> --help`** is an error rather than help. `--help` lives at the top level only.

```text
Unknown flag --help. This command takes: --light, --port, --skip-build.
```

**`deckard eject theme` run twice** refuses, because there is a local theme it will not overwrite. It is a one-way door.

**`node` fails in `doctor`:**

```text
Next 16 needs node 20.9.0 or newer.
```

[Requirements](/reference/requirements) has the full version table.

---

# Writing slides
Source: https://deckard.thebuilder.dk/guides/writing-slides

A slide is an object with a `body` and some optional metadata. The array in `deck/slides.tsx` is the deck, in order.

If you know the job the slide has to do but not the component name, start with the [slide patterns gallery](/slide-patterns).

```tsx deck/slides.tsx
export const slides: SlideDefinition[] = [
  { slug: "intro", title: "Deckard", body: <HeroSlide eyebrow="A talk" /> },
  { title: "The problem", body: <OpenContentSlide eyebrow="Context"><BulletList items={points} /></OpenContentSlide> },
]
```

## Start from a block

The blocks install into `app/slides/blocks/` as source you own. Compose from them and write your own markup only when none fits.

| Block | File | Reach for it when |
| --- | --- | --- |
| `HeroSlide` | `templates.tsx` | The opener. One headline, oversized. |
| `HeroSplitSlide` | `templates.tsx` | The opener with its facts in a side rail. |
| `HeroCenteredSlide` | `templates.tsx` | The centered opener, with an optional pill badge. |
| `BreakerSlide` | `templates.tsx` | A section divider, left aligned. |
| `MinimalBreakerSlide` | `templates.tsx` | A rule and a title, centered, with no index. |
| `StatementSlide` | `templates.tsx` | One sentence at display size. |
| `CodeSplitSlide` | `templates.tsx` | A block one side, numbered notes the other. |
| `ContentSlideCard` | `templates.tsx` | Intro copy above a bordered panel. |
| `OpenContentSlide` | `templates.tsx` | The same intro, no panel. |
| `FocusSlide` | `templates.tsx` | One block, no heading. |
| `BulletList` | `collections.tsx` | Four to six numbered points. |
| `RevealList` | `collections.tsx` | Points revealed in order, with the step wrappers inside the block. |
| `ContentsList` | `collections.tsx` | An agenda: numeral, section, folio. |
| `ColumnGrid` | `collections.tsx` | Parallel points as ruled, numbered columns. |
| `FeatureGrid` | `collections.tsx` | Three parallel cards. |
| `CardGrid` | `collections.tsx` | Cards on two or three columns, one of them tinted. |
| `StatGrid` | `metrics.tsx` | Two to four figures with their comparisons. |
| `QuoteSlide` | `prose.tsx` | Someone else's sentence, attributed on a rule. |
| `ProseSlide` | `prose.tsx` | A label rail beside running copy. |
| `DataTable` | `tables.tsx` | Columns of figures, one row highlighted. |
| `Timeline` | `tables.tsx` | Milestones as columns on one rule. |
| `LogList` | `tables.tsx` | Timestamped rows with a status. |
| `ImageShowcaseSlide` | `media.tsx` | Copy left, one image right, caption under it. |
| `MediaPair` | `media.tsx` | Two captioned frames side by side. |
| `MediaGallery` | `media.tsx` | Captioned frames on a grid. |
| `FullscreenMediaSlide` | `media.tsx` | Image or video bleeding to every canvas edge. |
| `Eyebrow`, `SlideHeading` | `typography.tsx` | Your own layout, with the deck's type rhythm. |

Every one of them is left aligned and fills the padded frame. `HeroCenteredSlide` and `MinimalBreakerSlide` are the two that centre.

Counts are yours. `FeatureGrid` is three across, but `CardGrid`, `ColumnGrid`, `Timeline`, `ContentsList`, `MediaGallery`, and `DataTable` all take as many items as you give them. Two blocks say no in the type: `StatGrid` takes two to four, and `MediaPair` takes exactly two.

Pick between `ContentSlideCard`, `OpenContentSlide`, and `FocusSlide` by what the content brings. Flat content takes the panel. Content with its own border takes the open frame. A single block that should fill the frame at the normal type scale takes `FocusSlide`.

### One surface per slide

A slide is either a framed panel holding flat content, or an open frame holding content that brings its own border. Never a bordered panel full of bordered cards.

Blocks that paint their own surface carry `data-slide-surface`. `ContentSlideCard`'s panel carries `data-slide-panel` and always paints its card, so putting a surfaced block inside one gives you a frame inside a frame plus a development console warning naming `OpenContentSlide` and `FocusSlide`. Switch to one of those.

If you write a block that paints a border or a background, put `data-slide-surface` on its outer element so a card wrapped around it says so.

## Inline, or its own file

Keep a slide in the array while it is metadata plus one block. Move it to `deck/slides/<name>.slide.tsx` once it loads data, brings a client widget, or carries speaker notes longer than the slide body.

A slide module exports the component as `default`, plus `meta` and `notes` as plain values so the deck can title and order it without rendering it:

```tsx deck/slides/pricing.slide.tsx
import type { SlideMeta } from "@thebuilder/deckard-core"

export const meta: SlideMeta = { slug: "pricing", title: "Pricing" }
export const notes = "Pause on the middle tier."

export default async function PricingSlide() {
  return <PricingTable plans={await loadPlans()} />
}
```

:::note
Extraction buys editing room, not loading speed. The discovery glob is eager, so both forms ship identical bundles.
:::

## Server components

Slide entry modules are Server Components. A body can be `async` and await its own data before it renders:

```tsx
async function ReleaseSlide() {
  const releases = await loadReleases()

  return (
    <OpenContentSlide eyebrow="Releases" title="Shipped this quarter">
      <FeatureGrid items={releases} />
    </OpenContentSlide>
  )
}
```

Never put `"use client"` at the top of `deck/slides.tsx` or a `*.slide.tsx` file. Interactivity goes one level down, in a nested client component the slide renders. The repository's decks guard this with a `deck/slides.test.ts` that fails on the directive.

A slide that throws under `next dev` renders an inline error card with the slide id and the message, and navigation keeps working. In a production build a Server Component that throws is fatal to the route, so Next serves its own error page.

## Discovery

`discoverSlides` takes an eager glob and returns slide definitions, so you skip the imports:

```tsx deck/slides.tsx
import { discoverSlides } from "@thebuilder/deckard-core/discovery"

const discovered = discoverSlides(
  import.meta.glob("./slides/**/*.slide.tsx", { eager: true }),
  { sort: "order" }
)

export const slides: SlideDefinition[] = [
  { slug: "intro", title: "Deckard", body: <HeroSlide eyebrow="A talk" /> },
  ...discovered,
  { title: "Questions", body: <HeroSlide eyebrow="Thanks" /> },
]
```

The spread decides where the group lands. Slides before and after it are manual entries and the discovered ones fill the gap in their sorted order.

### Ordering

`sort` takes three forms:

- **`"path"`** (default) compares the normalized glob keys segment by segment with numbers compared as numbers, so `2-intro.slide.tsx` sorts before `10-outro.slide.tsx`, and `10-context/20-b.slide.tsx` sorts after `10-context/10-a.slide.tsx` and before `20-solution/10-a.slide.tsx`.
- **`"order"`** reads each module's `meta.order` first and falls back to path order for ties and for modules that set none. Number the slides you care about and let filenames handle the rest.
- **A comparator** receives `{ path, meta }` for both slides and is used as given.

Sorting never reads the enumeration order of the glob object.

`meta.order` sorts inside the discovered group and nowhere else. `discoverSlides` consumes it and leaves it off the definition it returns, so a module cannot push itself past a manual slide or out of the spread.

### Two limits

**A discovered module has to be synchronous.** If it or anything it imports uses top-level await or WebAssembly, the eager glob hands back a promise instead of the exports and discovery throws naming the file. `CodeBlock` is the case that bites: shiki loads a WebAssembly regex engine, which is why it ships from `@thebuilder/deckard-core/code-block` rather than the components barrel. A slide that shows highlighted code belongs in the array, wired with `slideFromModule` if you want it in a file anyway:

```tsx
import * as pricingSlide from "@/deck/slides/pricing.slide"
import { slideFromModule } from "@thebuilder/deckard-core/slide-from-module"

slideFromModule(pricingSlide, "deck/slides/pricing.slide.tsx")
```

**Adding or deleting a matched file while `next dev` runs leaves page routes serving stale modules.** Restart the dev server after adding a slide file.

## Slide ids

Every slide gets an id, and the id is the URL.

- No `slug`: the slide is served at its 1-based position, so the fourth slide is `/slides/4`.
- A `slug`: the slide is served at `/slides/<slug>` and only there. Give a slide a slug when you want a link that survives reordering.

Slugs take lowercase letters, digits, and hyphens. The deck fails to build on a duplicate slug, an empty slug, a slug with characters unsafe in a URL path, or a slug made only of digits.

Titles never become slugs. A slide with no `title` falls back to `Slide 4` in the header, the command center, and the presenter flow.

[Slide metadata](/reference/slide-metadata) has the full field list, including the chrome and layout overrides a single slide can set.

## Check the work

```bash
deckard validate        # the deck resolves, slugs are unique, the theme is coherent
deckard check-overflow  # every slide fits the canvas
deckard contact-sheet   # every slide in one grid, after deckard screenshots
```

Run `validate` after a structural change, `check-overflow` after changing copy, and read the contact sheet before calling a deck done. It catches the things no checker can, like three slides in a row that all end above the halfway line.

Every flag on all three is in the [CLI reference](/reference/cli), and [Exporting](/guides/exporting) covers what they produce.

---

# Introduction
Source: https://deckard.thebuilder.dk/introduction

Deckard builds presentations out of React components. A slide is a `body` and some metadata, the deck is an array of those, and everything the audience sees is painted inside one fixed 1920x1080 canvas that scales to whatever screen it lands on.

That last part is the trade. You give up responsive layout inside a slide and you get back certainty: the deck looks the same on your laptop, the venue projector, a phone, and in the exported PDF. Only the scale changes.

## Who it is for

People who already write React and would rather not leave it to make slides. If a slide needs a live chart, a running demo, a table pulled from an API, or a code sample with real syntax highlighting, it is a component like any other component, and it awaits its own data before it renders.

If your deck is bullet points and a photo, Deckard will do that too, but so will Keynote, and Keynote will not ask you to run `pnpm install`.

## What a deck looks like

```tsx deck/slides.tsx
import type { SlideDefinition } from "@thebuilder/deckard-core"
import { FocusSlide, HeroSlide, StatGrid } from "@/app/slides/blocks"

const quarterly = [
  { value: "6.2s", caption: "Median build time" },
  { value: "0", unit: "%", caption: "Slides fixed after export" },
] as const

export const slides: SlideDefinition[] = [
  {
    slug: "intro",
    title: "Deckard",
    body: <HeroSlide eyebrow="A talk" />,
  },
  {
    title: "The numbers",
    notes: "Pause here. The middle figure is the one they will ask about.",
    body: (
      <FocusSlide>
        <StatGrid items={quarterly} />
      </FocusSlide>
    ),
  },
]
```

```ts deck/deck.ts
import { defineDeck } from "@thebuilder/deckard-core"
import { phosphor } from "@thebuilder/deckard-themes"
import { slides } from "@/deck/slides"

export const deck = defineDeck({
  description: "What we shipped and what it cost.",
  footer: { mode: "visible" },
  header: { brand: "Acme", href: "/", meta: "March 2026", mode: "auto" },
  slides,
  theme: phosphor,
  title: "Q1 review",
})
```

The array is the deck order. `defineDeck` resolves it: every slide gets an id, a number, a URL, and its chrome defaults filled in. Nothing reorders your array, so moving a slide in it is the only way to move it in the deck.

## The packages

<CardGroup cols={3}>
  <Card title="@thebuilder/deckard-core" icon="box">
    The deck contract and the runtime: `defineDeck`, the canvas, the slide
    shell, presenter mode, and the Next.js route adapters.
  </Card>
  <Card title="@thebuilder/deckard-themes" icon="palette">
    The built-in presets. A deck imports one and hands it to `defineDeck`, and
    can eject it into its own files later.
  </Card>
  <Card title="@thebuilder/deckard-cli" icon="terminal">
    The `deckard` binary: scaffold a deck, check that it fits, screenshot it,
    export it to PDF.
  </Card>
</CardGroup>

Slide blocks are the other piece, and not a package. They install into your app as source through a shadcn registry, and you edit them from then on.

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" href="/quickstart" icon="rocket">
    Scaffold a deck, run it, change a slide.
  </Card>
  <Card title="Writing slides" href="/guides/writing-slides" icon="file-text">
    Blocks, inline slides, file-per-slide modules, discovery.
  </Card>
  <Card title="Slide patterns" href="/slide-patterns" icon="panels-top-left">
    Choose a complete slide recipe by what the slide needs to do.
  </Card>
  <Card title="The canvas" href="/guides/the-canvas" icon="frame">
    What a fixed 1920x1080 means for the CSS inside a slide.
  </Card>
  <Card title="Theme gallery" href="/themes" icon="swatch-book">
    Every built-in as a live slide canvas, painted by its own stylesheet.
  </Card>
</CardGroup>

---

# Quickstart
Source: https://deckard.thebuilder.dk/quickstart

`deckard init` writes a Next.js app with a sample deck in it, installs the dependencies, makes the first commit, and typechecks the result.

## Scaffold a deck

1. **Run init**

    ```bash
    npx @thebuilder/deckard-cli init my-talk
    ```

    `init` installs with whichever package manager invoked it. Through `npx` that is npm, through `pnpm dlx` it is pnpm. It writes no `packageManager` field, so the deck is not locked to that choice, and later `deckard` commands read the lockfile.

2. **Start the dev server**

    ```bash
    cd my-talk
    npm run dev
    ```

    The app redirects `/` to the first slide. Arrow keys move through the deck.

3. **Edit a slide**

    Open `deck/slides.tsx`. Change the `title` of the first entry and save. The open slide updates.

## What it writes

<FileTree>

- my-talk/
  - app/
    - slides/
      - blocks/ (the block families, yours to edit)
      - [id]/page.tsx
    - presenter/page.tsx
    - page.tsx
    - sitemap.ts
    - not-found.tsx
    - layout.tsx
    - globals.css
  - deck/
    - deck.ts (the defineDeck config)
    - slides.tsx (the slide array)
  - lib/utils.ts
  - public/
  - components.json
  - next.config.ts
  - package.json

</FileTree>

The theme is not a file. `init` writes it as an import from `@thebuilder/deckard-themes` in `deck/deck.ts`, so `--theme phosphor` changes one identifier.

## init flags

| Flag | Default | What it does |
| --- | --- | --- |
| `--theme <name>` | `meridian` | Any built-in, listed on the [theme gallery](/themes). |
| `--empty` | off | A bare deck instead of the sample one. |
| `--package-manager <name>` | detected | `bun`, `npm`, `pnpm`, or `yarn`. |
| `--no-install` | install runs | Write the files and stop. Skips the typecheck too. |
| `--no-git` | git runs | Skip `git init` and the first commit. |
| `--registry <url>` | `https://deckard.thebuilder.dk/r/{name}.json` | The `@deckard` registry written into `components.json`. |
| `--core-tarball <path>` | `^<cli version>` | Install `@thebuilder/deckard-core` from a local tarball instead of npm. |
| `--themes-tarball <path>` | `^<cli version>` | Same, for `@thebuilder/deckard-themes`. |
| `--cli-tarball <path>` | `^<cli version>` | Same, for `@thebuilder/deckard-cli`. |

`init` refuses a directory that already has files in it. It asks no questions.

## The blocks

The slide blocks ship inside the CLI package, and `init` copies them into `app/slides/blocks/`, where they are source you edit. Adding a block later fetches it from the registry the docs site serves. See [Blocks and the registry](/guides/blocks-and-the-registry).

## Adding a deck to an app you already have

`init` writes a new directory. Do the same four things by hand when the deck has to live inside an existing Next.js app.

1. **Install the packages**

    ```bash
    pnpm add @thebuilder/deckard-core @thebuilder/deckard-themes
    pnpm add -D @thebuilder/deckard-cli playwright pdf-lib
    ```

    `playwright` and `pdf-lib` are what `check-overflow`, `screenshots`, `contact-sheet`, and `export pdf` load from the deck. Leave them out if the deck will only ever be presented.

2. **Import the stylesheet**

    ```css app/globals.css
    @import "tailwindcss";
    @import "@thebuilder/deckard-core/styles.css";
    ```

    That sheet carries the `--slide-*` token contract and registers the package's own compiled output as a Tailwind source, so the runtime's utility classes survive without you naming a path inside `node_modules`. There is no `transpilePackages` entry to add.

3. **Install the slide blocks**

    ```bash
    pnpm dlx shadcn@latest add https://deckard.thebuilder.dk/r/preset-blocks.json
    ```

    This writes the block source and its barrel to `app/slides/blocks/`. The Introduction imports from that barrel.

4. **Write the deck**

    Create `deck/deck.ts` and `deck/slides.tsx` as shown on the [Introduction](/introduction).

5. **Re-export the four routes**

    ```tsx app/slides/[id]/page.tsx
    import { createSlideRoute } from "@thebuilder/deckard-core/next"
    import { deck } from "@/deck/deck"

    const { Page, generateMetadata, generateStaticParams } =
      createSlideRoute(deck)

    export { generateMetadata, generateStaticParams }
    export default Page
    ```

    The other three are `app/presenter/page.tsx`, `app/sitemap.ts`, and `app/page.tsx`. See [Route adapters](/reference/core#route-adapters).

Run `deckard doctor` afterwards. It checks exactly these things and names the one you missed.

## Next steps

<CardGroup cols={2}>
  <Card title="Writing slides" href="/guides/writing-slides" icon="file-text">
    Which block to reach for, and when a slide earns its own file.
  </Card>
  <Card title="Presenting" href="/guides/presenting" icon="presentation">
    Keys, the command center, the presenter window, notes, step reveals.
  </Card>
</CardGroup>

---

# CLI
Source: https://deckard.thebuilder.dk/reference/cli

```bash
deckard <command> [options]
```

`deckard` is the only binary `@thebuilder/deckard-cli` puts on the path. Every command except `init` takes the current working directory as the deck, which is how a generated app wires its own scripts:

```json package.json
{
  "scripts": {
    "deck:validate": "deckard validate",
    "deck:check-overflow": "deckard check-overflow",
    "export:pdf": "deckard export pdf"
  }
}
```

`deckard --help` (or `-h`, or no arguments) prints the command list. `deckard --version` (or `-v`) prints the version.

## Commands

| Command | What it does |
| --- | --- |
| [`deckard init <dir>`](#deckard-init) | Write a deck, install it, commit it, typecheck it. |
| [`deckard validate`](#deckard-validate) | Load the deck, check its slides and its theme. |
| [`deckard doctor`](#deckard-doctor) | Check node, the package, the stylesheet, the deck, and the routes. |
| [`deckard check-overflow`](#deckard-check-overflow) | Fail listing the slides that lose content to the canvas, the chrome, or a clipped box. |
| [`deckard screenshots`](#deckard-screenshots) | One PNG per slide at canvas size. |
| [`deckard contact-sheet`](#deckard-contact-sheet) | Every screenshot in one labelled grid. |
| [`deckard export pdf`](#deckard-export-pdf) | One PDF page per slide. |
| [`deckard add theme <name>`](#deckard-add-theme) | Point `deck/deck.ts` at another built-in theme. |
| [`deckard add block <name>`](#deckard-add-block) | Install a registry block into `app/slides/blocks`. |
| [`deckard eject theme`](#deckard-eject-theme) | Copy the built-in the deck uses into `deck/theme`. |

## How flags parse

Only long `--flags`. There are no short aliases anywhere except the top-level `-h` and `-v`.

- **String flags** take `--flag value` and `--flag=value` alike. A missing value, or a next token starting with `--`, is an error.
- **Boolean flags** never consume the next token. `--light` is `true`; `--light true` sets the flag and leaves `true` as a stray positional.
- **`--no-<name>`** sets a declared boolean to `false`. It does not work on string flags.
- **Unknown flags** are rejected with the list of flags that command does take.

:::warning
`deckard <command> --help` is an error, not help. `--help` is not in any command's flag set, so it hits the unknown-flag check. Help lives at the top level only.
:::

The list it prints:

```bash ~/my-talk
deckard --help

deckard 0.0.1

  deckard init <dir>          create a deck: a Next.js app with slides, a theme, and the checks
    --theme <name>               meridian, atelier, aurora, blueprint, cotton,
                                 ledger, nexus, noir, phosphor, or quorum
                                 (default meridian)
    --empty                      two slides instead of the sample deck
    --package-manager <name>     npm, pnpm, yarn, or bun (default: the one that ran init)
    --no-install                 write the files and stop
    --no-git                     skip git init and the first commit
    --core-tarball <path>        install @thebuilder/deckard-core from a local tarball
    --cli-tarball <path>         install @thebuilder/deckard-cli from a local tarball
    --themes-tarball <path>      install @thebuilder/deckard-themes from a local tarball
    --registry <url>             the @deckard registry for components.json

  deckard validate           load the deck, check its slides and its theme
    --registry <path>            also check a shadcn registry.json

  deckard doctor             check node, the package, the stylesheet, the deck, and the routes

  deckard check-overflow     fail on slides the canvas clips
  deckard screenshots        one PNG per slide at canvas size, into out/screenshots
    --max <n>                    stop after n slides
  deckard contact-sheet      every screenshot in one grid, into out/contact-sheet.png
    --columns <n>                columns in the grid (default 4)
  deckard export pdf         one PDF page per slide, into out/slides.pdf
    --dark                       export the dark deck instead of the light one

  The four checks above build the app and serve it. They take --port <n> and
  --skip-build, and every one but the PDF export takes --light.

  deckard add theme <name>   point deck/deck.ts at another built-in theme
  deckard eject theme        copy the built-in the deck uses into deck/theme, yours to edit
    --theme <name>               eject that built-in instead of the imported one
  deckard add block <name>   install a block from the registry, into app/slides/blocks
    --registry <url>             a registry URL carrying a {name} placeholder
    --yes                        overwrite the files it installs without asking

Every command except init runs against the deck in the current directory.
```

## deckard init

```bash
deckard init my-talk --theme phosphor
```

Takes exactly one positional, the target directory, and refuses one that already has files in it.

| Flag | Value | Default |
| --- | --- | --- |
| `--theme <name>` | any built-in, from the [theme gallery](/themes) | `meridian` |
| `--empty` | boolean | off, so the sample deck |
| `--package-manager <name>` | `bun`, `npm`, `pnpm`, `yarn` | detected |
| `--no-install` | boolean | install runs |
| `--no-git` | boolean | git runs |
| `--registry <url>` | a URL with a `{name}` placeholder | `https://deckard.thebuilder.dk/r/{name}.json` |
| `--core-tarball <path>` | a local `.tgz` | `^<cli version>` from npm |
| `--themes-tarball <path>` | a local `.tgz` | `^<cli version>` from npm |
| `--cli-tarball <path>` | a local `.tgz` | `^<cli version>` from npm |

The package name comes from the directory basename, lowercased with anything outside `[a-z0-9-]` collapsed to a hyphen.

Package manager precedence for `init`: the `--package-manager` flag, then `npm_config_user_agent`, then the first lockfile found walking up from the target's parent (`pnpm-lock.yaml`, `bun.lock`, `bun.lockb`, `yarn.lock`, `package-lock.json`), then `npm`. Whichever wins is what the install runs with. Through `npx` it is npm:

No `packageManager` field is written into the generated `package.json`. Corepack reads that field as an enforcement lock, so recording the manager that happened to run `init` would refuse every other manager afterwards. Later `deckard` commands resolve the deck's manager from a `packageManager` field if you add one yourself, then the lockfile, then `npm_config_user_agent`, then `npm`.

```bash ~
npx @thebuilder/deckard-cli init my-talk

Created my-talk in ~/my-talk
  meridian theme, sample deck
  npm is the package manager for this deck

Installing dependencies with npm

added 453 packages, and audited 454 packages in 14s

Typechecking the new deck

> my-talk@0.1.0 typecheck
> next typegen && tsc --noEmit

Generating route types...
✓ Types generated successfully

  cd my-talk
  npm run dev

Slides are deck/slides.tsx. The theme is imported from @thebuilder/deckard-themes; run deckard eject theme to own a copy of it.
The export commands drive Chromium. Download it once with npm exec -- playwright install chromium.
```

`init` writes `playwright` and `pdf-lib` into the deck's `devDependencies`. The capture commands load both from the deck rather than from the CLI, so the CLI install itself carries neither.

`--no-install` skips the typecheck too, since there is nothing installed to typecheck against. A git failure is a warning, not an exit, and the commit prints nothing when it works. A typecheck failure exits 1 after everything is written, so the files are on disk either way.

## deckard validate

```bash
deckard validate
deckard validate --registry ../../registry.json
```

| Flag | Value | Default |
| --- | --- | --- |
| `--registry <path>` | path to a shadcn `registry.json` | none |

Loads the real `deck/deck.ts` through a throwaway in-memory Vite SSR server, in about a second, and reports three sections:

- **deck**: the deck resolves, every slide has a body, every `sourcePath` a discovered module reports is a file on disk. A duplicate slug, an unsafe slug, or a module with no default export comes back as one line naming the slide or the file, not a build-time stack trace.
- **theme**: the theme class is a real selector in the stylesheet the deck renders, the dark block defines nothing the light block does not, and `colorModes` matches the blocks that stylesheet carries. It reads `deck/theme/theme.css` for an ejected theme and the copy inside the installed package for an imported one, and names which it read.
- **registry**, only with `--registry`: every `items[].files[].path` exists, resolved against that file's own directory.

Exits 1 on any problem. Prints slide counts otherwise:

```bash ~/my-talk
deckard validate

deck   6 slides: 4 inline, 2 discovered
       3 slugs, 3 numbered
       canvas 1920x1080, margin 0
theme  meridian (.meridian-theme): light and dark, default system
       57 tokens in the light block, 25 dark overrides, from @thebuilder/deckard-themes/meridian

deckard validate passed
```

Two slides that resolve to the same route, for instance:

```bash ~/my-talk
deckard validate

deck  FAILED
      Slides 4 and 5 both use the slug "keyboard". Slide ids must be unique.
      Raised while loading deck/deck.ts, which resolves deck/slides.tsx and every deck/slides/*.slide.tsx module.

deckard validate found 1 problem
```

Only a repository that publishes blocks needs `--registry`. It is how this repository checks its own:

```bash apps/playground
deckard validate --registry=../../registry.json
```

The report adds a registry row to the deck and theme checks. It names missing source files and duplicate registry targets before returning a failure status.

## deckard doctor

```bash
deckard doctor
```

Takes no flags at all. Checks the shape of the app rather than the content of the deck:

| Check | Passes when |
| --- | --- |
| `node` | Node is at least 20.9.0. |
| `core` | `@thebuilder/deckard-core/package.json` resolves from the project. |
| `tooling` | `playwright` and `pdf-lib` resolve from the project. The capture commands load them from the deck. |
| `styles` | `app/globals.css` contains `@import "@thebuilder/deckard-core/styles.css"`. |
| `routes` | Each of the four route files re-exports its adapter. |
| `deck` | `deck/deck.ts` loads. |

```bash ~/my-talk
deckard doctor

ok node      node 24.14.0
ok core      @thebuilder/deckard-core 0.0.1
ok tooling   playwright 1.62.1, pdf-lib 1.17.1
ok styles    app/globals.css imports the slide token contract
ok routes    4 route files re-export their adapter
ok deck      deck/deck.ts loads 5 slides for "My talk"

deckard doctor found nothing wrong
```

Each failure prints what to do about it, and the run keeps going, so one run shows all of them. Exits 1 if anything failed.

```bash ~/my-talk
deckard doctor

ok node      node 24.14.0
ok core      @thebuilder/deckard-core 0.0.1
ok tooling   playwright 1.62.1, pdf-lib 1.17.1
FAIL styles  app/globals.css never imports @import "@thebuilder/deckard-core/styles.css"
             Add @import "@thebuilder/deckard-core/styles.css"; to app/globals.css. It carries the --slide-* tokens and registers the runtime's own Tailwind source.
ok routes    4 route files re-export their adapter
ok deck      deck/deck.ts loads 5 slides for "My talk"

deckard doctor found 1 problem
```

Reach for `doctor` when a deck that used to work stops, and for `validate` when the slides changed.

## deckard check-overflow

```bash
deckard check-overflow --light
```

| Flag | Value | Default |
| --- | --- | --- |
| `--light` | boolean | off, so **dark** |
| `--skip-build` | boolean | off |
| `--port <n>` | positive integer | `3412` |

Builds the deck, serves it, and opens every slide, then runs three measurements over it with a 1px tolerance, in canvas pixels:

- **The canvas edge.** The slide frame, the header, and the footer against the 1920x1080 canvas.
- **The chrome band.** Nothing inside `[data-slide-frame]` may cross the top of `[data-slide-footer]` or the bottom of `[data-slide-header]`. Absolutely positioned parts are skipped, and so is a slide whose `layout` is `"fullscreen"`, which is handed the whole canvas with the chrome out of the way.
- **Clipping.** Nothing inside the frame may hide its own overflow: a box with a non-visible `overflow` whose content is taller or wider than it is has lost that content silently.

Anything inside a `SlideScrollArea` is exempt from the last two, because outgrowing its box is what a scroll area is for.

```bash ~/my-talk
deckard check-overflow

5 slides fit the 1920x1080 canvas in dark mode, chrome included.
```

Exits 1 listing every slide that loses content, naming the part by its `data-slide-*` or `data-stat-*` attribute, which band or which axis, and by how many pixels. A container and the rows it drags with it are one finding, reported against the outermost part.

```bash ~/my-talk
deckard check-overflow

/slides/roadmap  slide content runs 794px below the canvas
1 of 6 slides overflow the canvas and are clipped. Trim the content, or wrap the part that has to scroll in SlideScrollArea.
```

`next dev` takes the same measurement after every render, rings the canvas in amber, and logs the same sentence:

```text title="Browser console"
Slide content runs 794px below the canvas and is clipped.
```

The ring is development only. Both run `measureSlideLayout` from `@thebuilder/deckard-core`, so this gate and `next dev` cannot disagree.


## deckard screenshots

```bash
deckard screenshots --max 5
```

| Flag | Value | Default |
| --- | --- | --- |
| `--light` | boolean | off, so **dark** |
| `--max <n>` | positive integer | all slides |
| `--skip-build` | boolean | off |
| `--port <n>` | positive integer | `3411` |

Writes `out/screenshots/<id>.png` per slide plus `out/screenshots/manifest.json`. Wipes the directory first.

```bash ~/my-talk
deckard screenshots

Captured intro.png
Captured 2.png
Captured 3.png
Captured keyboard.png
Captured 5.png
5 slides at 1920x1080 in ~/my-talk/out/screenshots
```

## deckard contact-sheet

```bash
deckard contact-sheet --columns 5
```

| Flag | Value | Default |
| --- | --- | --- |
| `--columns <n>` | positive integer | `4` |

Reads `out/screenshots/manifest.json` and composes `out/contact-sheet.png`. It builds and serves nothing, so run `deckard screenshots` first, and the sheet comes out in whichever color mode those were captured in.

```bash ~/my-talk
deckard contact-sheet

Contact sheet with 5 slides written to ~/my-talk/out/contact-sheet.png
```

`--port`, `--skip-build` and `--light` belong to the commands that build and serve. This one takes none of them and rejects them by name.

## deckard export pdf

```bash
deckard export pdf --dark
```

The positional must be exactly `pdf`. Anything else, including nothing, is an error.

| Flag | Value | Default |
| --- | --- | --- |
| `--dark` | boolean | off, so **light** |
| `--skip-build` | boolean | off |
| `--port <n>` | positive integer | `PDF_EXPORT_PORT`, else `3410` |

The checks default to dark and the PDF defaults to light, so pass `--dark` for a PDF meant for a screen. Writes `out/slides.pdf`, or wherever `PDF_EXPORT_OUTPUT` points, one slide to a page and sized from the canvas.

```bash ~/my-talk
deckard export pdf

Exported slide: intro
Exported slide: 2
Exported slide: 3
Exported slide: keyboard
Exported slide: 5
PDF written to ~/my-talk/out/slides.pdf
```

## deckard add theme

```bash
deckard add theme ledger
```

A pure source edit, with no install. Rewrites the `@thebuilder/deckard-themes` import and the `theme` property in `defineDeck`, keeping import order (package imports, then `@/` imports, alphabetical within each). It no-ops when the deck is already on that theme, rejects a name that is not a built-in, and warns when a stale `deck/theme` directory is still sitting there.

```bash ~/my-talk
deckard add theme ledger

deck/deck.ts now uses the ledger theme.
```

A name that is not a built-in comes back with the ones that are:

```bash ~/my-talk
deckard add theme brutalist

"brutalist" is not a Deckard theme. The built-ins are atelier, aurora, blueprint, cotton, ledger, meridian, nexus, noir, phosphor, quorum.
```

`--registry` and `--yes` are accepted on this path and do nothing.

## deckard add block

```bash
deckard add block metrics
deckard add block metrics --registry https://example.com/r/{name}.json --yes
```

| Flag | Value | Default |
| --- | --- | --- |
| `--registry <url>` | a URL carrying a `{name}` placeholder | `components.json` -> `registries["@deckard"]` |
| `--yes` | boolean | off |

Builds the item id as `block-<name>`, probes the registry with a 5-second timeout, and then runs the `shadcn` binary installed alongside the CLI as `shadcn add <target>`. `--yes` adds `-y -o`, overwriting without asking. The block families in `app/slides/blocks` arrive with `init` and are yours to edit, so this writes over the copy you have, skipping a file that already matches.

```bash ~/my-talk
deckard add block metrics

Installing @deckard/block-metrics from https://deckard.thebuilder.dk/r/block-metrics.json
✔ Checking registry.
✔ Created 1 file:
  - app/slides/blocks/metrics.tsx
```

With no `--registry` and no `registries["@deckard"]` in `components.json`, it errors naming the shape it expects:

```bash ~/my-talk
deckard add block metrics

No @deckard registry in components.json and no --registry flag.
Add one: { "registries": { "@deckard": "https://deckard.thebuilder.dk/r/{name}.json" } }
```

The URL `init` writes points at the Deckard docs site, which serves every registry item at `/r/{name}.json`. Point `--registry` at another URL with a `{name}` placeholder to install from your own.

## deckard eject theme

```bash
deckard eject theme
deckard eject theme --theme meridian
```

| Flag | Value | Default |
| --- | --- | --- |
| `--theme <name>` | a built-in theme name | the theme `deck/deck.ts` imports |

Creates `deck/theme/` with `theme.css` and `THEME.md` copied out of the installed `@thebuilder/deckard-themes`, generates an `index.ts` exporting a `SlideTheme` literal, and rewrites `deck/deck.ts` to `import { theme } from "@/deck/theme"`.

```bash ~/my-talk
deckard eject theme

Ejected the ledger theme into deck/theme/
  deck/theme/theme.css
  deck/theme/index.ts
  deck/theme/THEME.md

deck/deck.ts now imports it from "@/deck/theme". The three files are yours: read THEME.md, then edit theme.css.
```

`validate` reads whichever stylesheet the deck renders, so afterwards it names your copy rather than the package:

```bash ~/my-talk
deckard validate

deck   5 slides: 4 inline, 1 discovered
       2 slugs, 3 numbered
       canvas 1920x1080, margin 0
theme  ledger (.ledger-theme): light and dark, default system
       57 tokens in the light block, 25 dark overrides, from deck/theme/theme.css

deckard validate passed
```

It refuses when `deck/theme/` already exists, when the deck already imports from `@/deck/theme` and no `--theme` was given, and when the loaded deck's `theme.id` disagrees with the name you asked for.

## Environment variables

| Variable | Read by | What it does |
| --- | --- | --- |
| `PDF_EXPORT_OUTPUT` | `export pdf` | Output path, resolved against the deck directory. Default `out/slides.pdf`. |
| `PDF_EXPORT_PORT` | `export pdf` | Default port when `--port` is absent. |
| `npm_config_user_agent` | `init` | Package-manager detection. |

`NEXT_PUBLIC_PDF_EXPORT` and `NEXT_PUBLIC_PDF_THEME` are set by the export build, not read by the CLI.

## Exit codes

| Code | When |
| --- | --- |
| `0` | Success. |
| `1` | Any error, including `validate` and `doctor` finding problems, and `bin/deckard.mjs` running before `dist/` exists. |
| `130` | Interrupted with `Ctrl-C` during a build-and-serve session. |

## The build harness

`check-overflow`, `screenshots`, and `export pdf` share one harness, so Next's own build output scrolls past before the lines those three print:

1. **Build, unless it is fresh**

    A stamp at `.next/deckard-build.json` is compared against the newest file
    under `app/`, `assets/`, `components/`, `deck/`, `hooks/`, `lib/`,
    `public/`, plus `components.json`, `next.config.*`, `package.json`,
    `postcss.config.*`, `tsconfig.json`, and the resolved `@thebuilder/deckard-core` and
    its `src/`. `--skip-build` skips the comparison entirely.

2. **Refuse an occupied port**

    Anything already answering on the port is an error telling you to pass
    `--port`.

3. **Serve and wait**

    `next start` with `NODE_ENV=production`, polled every 500ms for up to 60
    seconds.

4. **Read the slide list**

    Slide ids come from `/sitemap.xml`, which is `app/sitemap.ts`. An empty list
    is an error naming that file.

5. **Open at scale 1**

    Headless Chromium with the requested `colorScheme`, then the viewport is
    resized to the canvas size read off the rendered page, so nothing is
    captured scaled. Every slide asserts the applied color mode matches the one
    requested.

A Chromium launch failure prints the `playwright install chromium` command for your package manager.

---

# @thebuilder/deckard-core
Source: https://deckard.thebuilder.dk/reference/core

The package compiles to `dist/` with `tsc`: ESM, `.d.ts`, and `"use client"` directives preserved. No bundler, so a stack trace still points at a file that matches the source. An app installs it and imports it like any other package, with no `transpilePackages` entry and no Tailwind `@source` of its own.

## Entry points

| Entry point | Contents |
| --- | --- |
| `@thebuilder/deckard-core` | `defineDeck`, slide resolution, summaries, theme helpers, every type |
| `@thebuilder/deckard-core/components` | The runtime components and slide context hooks |
| `@thebuilder/deckard-core/code-block` | `CodeBlock`, kept off the components barrel because shiki loads WebAssembly |
| `@thebuilder/deckard-core/discovery` | `discoverSlides` |
| `@thebuilder/deckard-core/next` | The four route adapters |
| `@thebuilder/deckard-core/slide-from-module` | `slideFromModule` |
| `@thebuilder/deckard-core/ui` | The shadcn primitives the runtime renders |
| `@thebuilder/deckard-core/utils` | `cn` |
| `@thebuilder/deckard-core/styles.css` | The `--slide-*` token contract |

`CodeBlock` is split out because shiki pulls in a WebAssembly regex engine. Importing it through the components barrel would turn every discovered slide module async, which discovery refuses. A slide that shows highlighted code belongs in the `slides` array.

## @thebuilder/deckard-core

| Export | What it does |
| --- | --- |
| `defineDeck(config)` | Resolve a `DeckConfig` into a `Deck`. |
| `resolveCanvas(partial)` | Fill in and validate the canvas config. |
| `resolveSlides(slides, defaults, slidesPath)` | Resolve a slide array. `slidesPath` defaults to `/slides`; `defineDeck` passes its resolved route. |
| `getSlideById(slides, id)` | Find a resolved slide by its id. |
| `normalizeFooterMode(mode)` | Collapse `"counter"` into `"visible"`. |
| `toSlideSummary(slide)` / `toSlideSummaries(slides)` | The serializable shape client components receive. |
| `resolveTheme(theme)` | Fill in and validate a `SlideTheme`. |
| `toDeckPresentation(deck)` | The serializable slice the shell needs. |
| `canSwitchColorMode(theme)` / `forcedColorMode(theme)` | What the color-mode toggle does for a given theme. |
| `isPdfExport()` / `pdfExportColorMode()` | Read the export environment variables. |
| `isCapturing()` | True while a capture tool is driving the page. |
| `captureAttribute` | The attribute a capture tool sets on the document element. |
| `motionField(theme, background)` | The field a theme paints a background variant with, or `undefined`. |
| `slideBackgroundModes` | The background variants the runtime paints for every deck. |
| `slideMotionFields` | The three fields a theme may name. |
| `PRESENTER_CHANNEL_NAME` | The `BroadcastChannel` name presenter mode uses. |

Types: `Deck`, `DeckConfig`, `DeckCanvasConfig`, `DeckHeaderConfig`, `DeckFooterConfig`, `DeckPresentation`, `ResolvedSlide`, `SlideDefinition`, `SlideMeta`, `SlideModule`, `SlideComponent`, `SlideDefaults`, `SlideSummary`, `SlideTheme`, `SlideColorMode`, `SlideHeaderMode`, `SlideFooterMode`, `SlideFooterModeInput`, `SlideLayoutMode`, `SlideBackgroundMode`, `BuiltInSlideBackgroundMode`, `SlideMotionMode`, `SlideMotionField`, `PresenterChannelMessage`, `PresenterPreviewState`, `PresenterSlideState`.

## @thebuilder/deckard-core/components

| Export | What it does |
| --- | --- |
| `SlideShell` | Assembles a slide: frame, canvas chrome, deck controls. |
| `SlideViewport` | Fits the canvas to the browser window and publishes `--deckard-scale`. |
| `SlideCanvas` | The fixed coordinate space slides are authored in. |
| `SlideCanvasHeader`, `SlideCanvasFooter` | The themed chrome inside the canvas. |
| `SlideBackground` | The element carrying `data-slide-background`, plus the motion canvas when the theme paints that variant with one. |
| `SlideMotionBackground` | The animated canvas itself. |
| `SlideScrollArea` | A scroll region that does not step the deck. |
| `SlideStepper`, `SlideStep`, `SlideStepAdvanceArea`, `useSlideStepper` | Step reveals. |
| `SlideCommandCenter` | The `Cmd/Ctrl + K` jump dialog. |
| `DeckControls` | The corner cluster. |
| `PresenterConsole`, `PresenterPopoutButton` | Presenter mode. |
| `ColorModeProvider`, `SlideshowColorModeToggle` | Light and dark. |
| `SlideContextProvider`, `useSlideTitle`, `useIsPresenterPreview` | Slide context. |
| `SlideErrorBoundary` | The inline error card a throwing slide renders under `next dev`. |
| `SlideMediaVideo` | A `<video>` that suppresses autoplay in the presenter preview. |
| `SlidePrefetch` | Prefetches the neighbouring slides. |
| `StaticMediaBoundary` | Freezes video and audio inside a slide the audience is not on, so a presenter preview never plays. |

### useSlideTitle

Returns the current slide's authored title, or `null`. Layout blocks call it so a slide's title stays defined in one place, and only take an explicit `title` prop when you want to override the text inside the layout.

### useIsPresenterPreview

Returns `true` inside the presenter console's preview iframe. Use it in a client component to skip autoplay, audio, canvas work, or anything else expensive.

### Motion backgrounds

A theme paints most background variants in CSS. It paints a variant in an animated canvas by naming it in `motion`, keyed by the name a deck writes as `background`:

```ts deck/theme.ts
export const aurora: SlideTheme = {
  className: "aurora-theme",
  colorModes: ["dark", "light"],
  defaultColorMode: "dark",
  id: "aurora",
  motion: { closing: "waves", hero: "aurora", statement: "wash" },
}
```

```ts deck/slides.tsx
{ background: "hero", body: <HeroSlide … />, slug: "opening" }
```

The three fields are `aurora`, banded curtains over noise; `waves`, a horizontal band that undulates; and `wash`, a soft noise field with a dither. Their colours and their speed come from the `--slide-motion-*` tokens, so the theme sets them per variant and per color mode in its stylesheet. A variant the theme never names is a CSS background like any other, and a deck whose theme names none never loads the WebGL runtime: it is fetched by the canvas component on mount.

One `requestAnimationFrame` loop drives every canvas on the page, and it skips a canvas that is off screen or has collapsed to nothing. Backing stores are half the canvas size in each axis.

#### Freezing

A frozen field still renders. It draws one frame at a fixed point in the animation and holds it, so two captures of the same slide are the same image. Five things freeze one:

| Reason | How it is decided |
| --- | --- |
| `prefers-reduced-motion: reduce` | `matchMedia`, live: dropping the preference starts the field |
| A capture is running | `isCapturing()`, which reads the PDF build flag and the `captureAttribute` marker the `deckard` capture commands set |
| The presenter preview | The `presenterPreview` query the console's iframes carry |
| The deck asked | `motion: "frozen"` in `defineDeck` |
| The slide asked | `motion: "frozen"` on the slide |

The canvas reports which of the two it is doing on `data-slide-motion-state`, valued `running` or `frozen`.

#### When there is no WebGL

The canvas paints nothing, reports `data-slide-motion-state="unavailable"`, and the background the theme painted underneath is the slide. The same holds while the runtime is loading and if the context is lost mid-presentation, so a theme paints a variant it animates as though it never would.

### useSlideStepper

Returns `{ currentStep, stepCount, advance, retreat, canAdvance, canRetreat, isReadOnly }`, or `null` outside a stepper.

## Route adapters

`@thebuilder/deckard-core/next` ships the route logic, so an app owns its deck and re-exports the routes. Each adapter takes the resolved deck and returns the route pieces.

| Adapter | File | Returns |
| --- | --- | --- |
| `createSlideRoute(deck)` | `app/slides/[id]/page.tsx` | `Page`, `generateMetadata`, `generateStaticParams` |
| `createPresenterPage(deck)` | `app/presenter/page.tsx` | `Page`, `metadata` |
| `createDeckSitemap(deck, { siteUrl })` | `app/sitemap.ts` | The sitemap function |
| `createFirstSlideRedirect(deck)` | `app/page.tsx` | `Page`, which redirects to the first slide |

<CodeGroup>

```tsx app/slides/[id]/page.tsx
import { createSlideRoute } from "@thebuilder/deckard-core/next"
import { deck } from "@/deck/deck"

const { Page, generateMetadata, generateStaticParams } = createSlideRoute(deck)

export { generateMetadata, generateStaticParams }
export default Page
```

```tsx app/presenter/page.tsx
import { createPresenterPage } from "@thebuilder/deckard-core/next"
import { deck } from "@/deck/deck"

const { Page, metadata } = createPresenterPage(deck)

export { metadata }
export default Page
```

```ts app/sitemap.ts
import { createDeckSitemap } from "@thebuilder/deckard-core/next"
import { deck } from "@/deck/deck"

export default createDeckSitemap(deck)
```

```tsx app/page.tsx
import { createFirstSlideRedirect } from "@thebuilder/deckard-core/next"
import { deck } from "@/deck/deck"

export default createFirstSlideRedirect(deck)
```

</CodeGroup>

Every slide prerenders statically. The route reads no request: `?presenterPreview=1` and `?step=` are read on the client, inside a Suspense boundary holding nothing but the reader.

`createDeckSitemap` falls back to `NEXT_PUBLIC_SITE_URL` and then to `http://localhost:3000` when you pass no `siteUrl`. That sitemap is also how `deckard screenshots`, `check-overflow`, and `export pdf` find the slide list, so an app that drops the route breaks those three.

The components the adapters compose are exported too, so a deck that needs its own route can write one.

## The dependency direction

`@thebuilder/deckard-core` holds nothing deck-specific. Colors, sizes, and backgrounds live in a theme, and a theme is data: the runtime depends on the token contract in `styles.css` and never on a preset.

`@thebuilder/deckard-themes` takes `SlideTheme` from core as a type-only import and names core a peer dependency, so nothing crosses at runtime and core does not know the themes exist.

---

# Deck config
Source: https://deckard.thebuilder.dk/reference/deck-config

`defineDeck` takes a `DeckConfig` and returns a resolved `Deck`. It resolves the canvas, resolves every slide into an id, a number, a URL and its chrome defaults, and validates the theme.

```ts deck/deck.ts
import { defineDeck } from "@thebuilder/deckard-core"
import { meridian } from "@thebuilder/deckard-themes"
import { slides } from "@/deck/slides"

export const deck = defineDeck({
  canvas: { fit: "contain", height: 1080, mode: "fixed", width: 1920 },
  description: "An engineering review built from editable slide patterns.",
  footer: { mode: "visible" },
  header: { brand: "Deckard", href: "/", meta: "March 2026", mode: "auto" },
  slides,
  theme: meridian,
  title: "Deckard",
})
```

## DeckConfig

| Prop | Type | Default | Description |
| - | - | - | - |
| `title` | `string` | - | The deck title. Used as the document title and in slide metadata. |
| `description` | `string` | - | One line describing the deck. |
| `slides` | `SlideDefinition[]` | - | The deck, in order. Never reordered. |
| `header` | `DeckHeaderConfig` | - | The header inside the canvas: brand, link, optional meta line, and the default header mode. |
| `footer` | `DeckFooterConfig` | - | The footer inside the canvas: the default footer mode and whether the progress element exists. |
| `canvas?` | `Partial<DeckCanvasConfig>` | `1920x1080, fit contain, margin 0` | Overrides on the fixed coordinate space. |
| `theme?` | `SlideTheme` | - | The theme object. A deck without one renders in neutral defaults. |
| `motion?` | `"auto" \| "frozen"` | `"auto"` | The default every slide takes. "frozen" holds every motion background in the deck on one fixed frame. Reduced motion, the capture commands, and the presenter preview freeze one either way. |
| `routes?` | `DeckRoutesConfig` | `{ slides: "/slides", presenter: "/presenter" }` | Route prefixes for slides and presenter mode. Set presenter to false when the deck has no presenter page. |

## canvas

| Prop | Type | Default | Description |
| - | - | - | - |
| `mode?` | `"fixed"` | `"fixed"` | The only mode. |
| `width?` | `number` | `1920` | Logical pixels. Has to be positive. |
| `height?` | `number` | `1080` | Logical pixels. Has to be positive. |
| `fit?` | `"contain"` | `"contain"` | How the canvas fits the window. |
| `margin?` | `number` | `0` | Browser pixels between the canvas and the window edge. Zero or more. |

`resolveCanvas` throws naming the field when `width` or `height` is not a positive number, or when `margin` is negative.

## header

| Prop | Type | Default | Description |
| - | - | - | - |
| `brand` | `string` | - | The name at the left of the header. Rendered as a link. |
| `href` | `string` | - | Where the brand links to. |
| `mode` | `"visible" \| "hidden" \| "auto"` | - | The deck-wide default. A slide can override it. |
| `meta?` | `string` | - | One line of standing detail at the right of the header, printed as written: "March 2026", "Rev. C", "Internal". |

`"auto"` renders the header in the default layout and hides it in a fullscreen layout.

## footer

| Prop | Type | Default | Description |
| - | - | - | - |
| `mode` | `"visible" \| "hidden" \| "counter"` | - | The deck-wide default. A slide can override it. |
| `progress?` | `boolean` | `true` | Whether the progress element exists at all. Setting false drops the element rather than hiding it, so no theme can paint it back. |

`"counter"` is a deprecated alias for `"visible"`. A deck that sets it resolves to `"visible"`.

```ts
footer: { mode: "visible", progress: false }
```

## theme

See [Themes](/guides/themes) for the full object. `defineDeck` validates it: `defaultColorMode: "system"` needs both modes in `colorModes`, and a theme listing one mode pins the canvas to it and hides the light/dark toggle.

## routes

`routes.slides` sets the prefix used by every resolved slide URL and presenter preview. `routes.presenter` sets the popout destination; `false` removes the presenter control and keyboard shortcut. Paths start with `/` and cannot be the site root.

```ts
routes: { slides: "/example", presenter: false }
```

## What defineDeck returns

`Deck` is `DeckConfig` with `canvas`, `slides`, and `theme` resolved. Each slide becomes a `ResolvedSlide`:

| Field | What it holds |
| --- | --- |
| `id` | The URL segment: the slug, or the 1-based position. |
| `href` | The configured slide path followed by the slide id. |
| `index` | Zero-based position in the array. |
| `number` | One-based position, what the counter shows. |
| `title` | The authored title, or the generated `Slide 4` fallback. |
| `authoredTitle` | Set only when the author gave the slide a title. The fallback in `title` names a slide in chrome but must never render as its own heading. |
| `header` `footer` `layout` `background` `motion` | The slide's own value, or the deck default. |
| `stepCount` | Defaults to `0`. |
| `notes` `slug` `sourcePath` | As authored. |
| `body` | The slide's React node. |

Only `SlideSummary` (`id`, `number`, `title`, `authoredTitle`, `href`, `stepCount`) crosses into client components, because it has to survive `BroadcastChannel` serialization for presenter mode. The rendered slide body crosses only as `children`.

## Deck chrome

The header and footer are painted inside the canvas, so they scale with the deck, print into the PDF, and show up in a presenter preview. The runtime renders the structure and the theme decides the look:

```html
<header data-slide-header>
  <a data-slide-header-brand href="/">Deckard</a>
  <span data-slide-header-title>Themed chrome</span>
  <span data-slide-header-meta>March 2026</span>
</header>

<footer data-slide-footer>
  <div data-slide-progress style="--slide-progress: 0.25"></div>
  <p data-slide-counter>
    <span data-slide-counter-current>3</span>
    <span data-slide-counter-separator> of </span>
    <span data-slide-counter-total>12</span>
  </p>
</footer>
```

The title renders only for a slide that has one, and the meta line only when the deck sets `header.meta`. `--slide-progress` is the position in the deck as a fraction, which is what a theme reads to paint a bar, a row of dots, or nothing at all.

The header row is one line inside a canvas that cannot grow. Every part clips itself rather than running off the edge, and the slide title carries by far the largest shrink factor, so it truncates before the brand loses any of itself. Both overflow checks measure the header and footer alongside the frame, so a deck finds out when its chrome asks for more room than it has.

---

# Requirements and compatibility
Source: https://deckard.thebuilder.dk/reference/requirements

A deck is a Next.js app with `@thebuilder/deckard-core` as a dependency. Everything below is what that app needs.

## Versions

| What | Version | Where it comes from |
| --- | --- | --- |
| Node | 20.9 or newer | `engines` on all three packages, and the floor `deckard doctor` checks |
| Next.js | 16 or newer | `peerDependencies` on `@thebuilder/deckard-core` |
| React | 19 or newer | `peerDependencies` on `@thebuilder/deckard-core` |
| React DOM | 19 or newer | `peerDependencies` on `@thebuilder/deckard-core` |
| Tailwind CSS | 4 | `@thebuilder/deckard-core/styles.css` uses `@source`, which is v4 only |

`deckard init` pins the versions the reference deck runs rather than the floors, so a deck generated today installs Next `16.3.3`, React `^19.2.8`, Tailwind `^4.3.3`, and TypeScript `^7.0.2`.

Tailwind is not a declared peer dependency of any Deckard package. The requirement arrives through the one stylesheet import:

```css app/globals.css
@import "tailwindcss";
@import "@thebuilder/deckard-core/styles.css";
```

That second line carries the `--slide-*` tokens and registers the runtime's own Tailwind source. Drop it and the deck renders unstyled. [`deckard doctor`](/reference/cli#deckard-doctor) checks for it by name.

:::note
The Node floor is 20.9, not a major version. Node 20.8 fails the check and Node 20.9 passes. This repository and its CI run Node 24.
:::

## Package managers

`bun`, `npm`, `pnpm`, and `yarn` all work. Pass `--package-manager <name>` to [`deckard init`](/reference/cli#deckard-init), or let it use the one that invoked it.

A generated deck carries no `packageManager` field. Corepack reads that field as an enforcement lock, so writing it would refuse every other manager afterwards. Later `deckard` commands read the lockfile instead, walking up from the deck directory: `pnpm-lock.yaml`, `bun.lock`, `bun.lockb`, `yarn.lock`, `package-lock.json`.

That detection is what fills in the commands the CLI prints. A missing Chromium tells a pnpm deck to run `pnpm exec playwright install chromium` and an npm deck to run `npm exec -- playwright install chromium`.

`init` is covered by an automated smoke test on pnpm and npm. Yarn and bun are supported in the code and are not covered by that test.

## Chromium

Four commands drive a real browser, so they need the Playwright Chromium binary on the machine:

- [`deckard check-overflow`](/reference/cli#deckard-check-overflow)
- [`deckard screenshots`](/reference/cli#deckard-screenshots)
- [`deckard contact-sheet`](/reference/cli#deckard-contact-sheet)
- [`deckard export pdf`](/reference/cli#deckard-export-pdf)

Playwright and `pdf-lib` are dev dependencies of the deck, not of the CLI. `deckard init` writes both into the generated `package.json`, and the four commands above load them from the deck's own `node_modules`. A deck built by hand adds them itself:

```bash
pnpm add -D playwright pdf-lib
```

The browser binary is a separate download on top of the package:

```bash
pnpm exec playwright install chromium
```

Without the package those four commands fail naming it and printing the install line; without the binary they fail with `Failed to launch Chromium` and the download line for your package manager. `deckard doctor` reports both packages under `tooling`. Nothing else in the CLI needs a browser: `init`, `validate`, `doctor`, `add`, and `eject` do not, and `npx @thebuilder/deckard-cli init` downloads neither.

`check-overflow`, `screenshots`, and `export pdf` also run `next build` and `next start` before they capture, so they need a machine that can build and serve the deck. `contact-sheet` needs the browser but neither the build nor the server, because it composes PNGs that `screenshots` already wrote.

## Browsers for a presented deck

The runtime is tested on Chromium, Firefox, and WebKit. Those three are what `pnpm test` runs the browser suite against, and they are the closest thing to a support matrix the repository states.

There is no `browserslist` in the repository and no configured build target, so the shipped bundle takes Next 16's defaults. That means there is no minimum browser version to quote here.

What the deck uses that a browser has to support:

- `oklch()` colours and `color-mix()`, in the token contract and every theme
- Tailwind v4 cascade layers
- `svh` units for the shell height
- `ResizeObserver`, for measuring the canvas fit
- `BroadcastChannel`, for presenter sync
- The `inert` attribute, on unrevealed step content

`ResizeObserver` is used without a fallback, so a browser without it will not scale the canvas. `BroadcastChannel` is checked before use: a browser without it runs the deck normally and the presenter window never syncs.

The canvas scale is measured in JavaScript and published as `--deckard-scale` rather than divided in CSS, because Firefox before 155 has no typed CSS arithmetic. That is the one engine difference the runtime works around by design.

## Edge runtime

Not established, and nothing in the repository claims it either way. There is no `export const runtime` anywhere, no middleware, and no test that runs a deck on Edge.

What is true: the route adapters in `@thebuilder/deckard-core/next` import no Node APIs, and the slide route reads nothing from the request. `@thebuilder/deckard-core/code-block` is the part to check first if you try it, because shiki loads a WebAssembly regex engine there.

Treat Edge as untested rather than as supported or unsupported.

## Static export

`output: "export"` works, with two changes to the app.

1. **Force the sitemap static**

    Without this the build fails with `export const dynamic = "force-static"/export const revalidate not configured on route "/sitemap.xml" with "output: export"`.

    ```ts app/sitemap.ts
    import { createDeckSitemap } from "@thebuilder/deckard-core/next"
    import { deck } from "@/deck/deck"

    export const dynamic = "force-static"

    export default createDeckSitemap(deck)
    ```

2. **Turn off image optimization**

    The media blocks use `next/image`. Left alone, the export emits `/_next/image?...` URLs, which need the optimizer a static host does not run, so every image 404s.

    ```ts next.config.ts
    const nextConfig: NextConfig = {
      images: { unoptimized: true },
      output: "export",
    }
    ```

Every slide, the presenter page, and the sitemap prerender. One thing changes: `/` becomes a page that redirects to the first slide once it loads in the browser, rather than a server 307.

The capture commands do not work against a static export. They run `next start`, which `output: "export"` disables. Build twice, or run the captures before you switch the config.

[Deploying](/guides/deploying) covers the rest of getting a built deck in front of an audience.

---

# Slide metadata
Source: https://deckard.thebuilder.dk/reference/slide-metadata

A slide is a `body` and optional metadata. Two shapes carry it: an entry in the `slides` array, and a module in `deck/slides/*.slide.tsx`.

## SlideDefinition

An entry in the array. `body` is required, everything else is optional.

| Prop | Type | Default | Description |
| - | - | - | - |
| `body` | `ReactNode` | - | The slide itself. |
| `slug?` | `string` | - | Fixes the URL at /slides/<slug>. Lowercase letters, digits, and hyphens, unique across the deck, never all digits. Without one the slide is served at its 1-based position. |
| `title?` | `string` | - | Names the slide in the header, the command center, and the presenter flow. A slide without one shows "Slide 4". Never becomes a slug. |
| `notes?` | `string` | - | Speaker-only text. Reaches the presenter window and never renders in the deck. |
| `stepCount?` | `number` | `0` | How many reveal steps the slide has. Pair it with SlideStep. |
| `header?` | `"visible" \| "hidden" \| "auto"` | `the deck's header.mode` | "auto" renders in the default layout and hides in fullscreen. |
| `footer?` | `"visible" \| "hidden" \| "counter"` | `the deck's footer.mode` | "counter" is a deprecated alias for "visible". |
| `layout?` | `"default" \| "fullscreen"` | `"default"` | fullscreen hands the whole canvas to the slide so media can bleed to every edge. |
| `background?` | `"default" \| "none" \| "spotlight" \| "grid" \| "accent" \| a name the theme adds` | `"default"` | Which background variant the theme paints. SlideBackground carries the name on data-slide-background, and deckard validate reports a name neither the runtime nor the theme paints. |
| `motion?` | `"auto" \| "frozen"` | `the deck's motion` | "frozen" holds this slide's motion background on one fixed frame. A slide whose background is painted in CSS is unaffected. |
| `sourcePath?` | `string` | - | Set by slideFromModule and discoverSlides. deckard validate checks it is a file on disk. |

Use `layout`, `header`, `footer`, and `background` to change the frame for one slide, rather than special-casing the route.

## SlideMeta

What a slide module exports as `meta`. Same fields as `SlideDefinition` minus `body` and `sourcePath`, plus one:

| Prop | Type | Default | Description |
| - | - | - | - |
| `order?` | `number` | - | Sorts this module inside the discovered group when discoverSlides runs with sort: "order". It cannot move the group. discoverSlides consumes it and leaves it off the definition, so a module can never push itself past a manual slide. |

`notes` can be exported either on `meta` or as its own top-level export. The top-level export wins.

```tsx deck/slides/pricing.slide.tsx
import type { SlideMeta } from "@thebuilder/deckard-core"

export const meta: SlideMeta = { slug: "pricing", title: "Pricing", order: 20 }
export const notes = "Pause on the middle tier."

export default async function PricingSlide() {
  return <PricingTable plans={await loadPlans()} />
}
```

A module has to export its component as `default`. Discovery throws naming the file when it does not, and when the module is async, because an eager glob hands back a promise instead of the exports.

## Slide ids

The `slides` array defines deck order. `resolveSlides` never reorders it, so moving a slide in the array is the only way to move it in the deck.

Ids are matched exactly. A slugged slide is served only at its slug and never at its position, so there is one URL per slide.

The deck fails to build on a duplicate slug, an empty slug, a slug with characters unsafe in a URL path, or a slug made only of digits.

## Step reveals

```tsx
{
  title: "The argument",
  stepCount: 3,
  body: (
    <OpenContentSlide eyebrow="Three parts" title="The argument">
      <SlideStep step={0}>Everyone agrees on the premise.</SlideStep>
      <SlideStep step={1}>Almost nobody acts on it.</SlideStep>
      <SlideStep step={2}>Here is what that costs.</SlideStep>
    </OpenContentSlide>
  ),
}
```

`step` is zero-based, and a step shows once the current step reaches it. Hidden steps stay in the layout, so a stepped slide takes its full height from the first step and `deckard check-overflow` measures it fully revealed.

The current step also rides in the URL as `?step=`, read on the client, which is how the presenter preview stays in sync without making the route dynamic.

---

# Token contract
Source: https://deckard.thebuilder.dk/reference/tokens

`@thebuilder/deckard-core/styles.css` declares every `--slide-*` token with a neutral default, inside `@layer base`. A theme redefines them on the canvas and wins, because it ships unlayered CSS and everything in the contract sits in the base layer.

The runtime depends on these names and never on a preset, so a deck with no theme still renders: neutral sizes, app surfaces, no decoration.

```css app/globals.css
@import "tailwindcss";
@import "@thebuilder/deckard-core/styles.css";
```

## Type

<SlideTokens column="Reads it" group="type" />

Every size is set against the 1920x1080 canvas at a 16px root, so `1rem` is 16 canvas pixels and the scale reads the way it does on a projector rather than the way it does in a browser window. Multiply a default above by 16 to get what it measures on a canvas 1080 pixels tall.

Line height rides along as a unitless multiplier in the blocks, so changing a size token keeps its leading proportional. Never pair a size token with a fixed `leading-7`.

## Spacing

<SlideTokens group="spacing" />

The frame those gutters leave is the whole slide, left aligned and uncapped: content starts at the left margin and runs to the right one. Blocks cap their own measure where prose needs it, and anything that wants to be centred centres itself.

## Figures

<SlideTokens group="figures" />

## Surfaces

<SlideTokens group="surfaces" />

## Backgrounds

`SlideBackground` renders one empty element carrying `data-slide-background`, and the theme paints each variant with these:

<SlideTokens group="backgrounds" />

There is no radial wash, veil, glow or spotlight token. The textures a theme has are flat colour, a rule, a grid, and a hatch, because a radial gradient reads as a smudge on a projector and as grey on paper.

The four `--slide-motion-*` tokens are read off the canvas by the animated background, and only for a variant the theme names in `motion`. See [Motion backgrounds](/reference/core#motion-backgrounds). A theme sets them per variant and per color mode the way it sets everything else it paints:

```css
.aurora-theme .slide-background[data-slide-background="hero"] {
  --slide-motion-color-1: #0a0d1f;
  --slide-motion-color-2: #3a2f86;
  --slide-motion-color-3: #1c7c96;
  background: linear-gradient(160deg, #0a0d1f, #1c2350);
}
```

That `background` is what the slide shows while the runtime loads, when the browser has no WebGL, and when the context is lost, so paint a variant you animate as though it never would.

## Media

<SlideTokens group="media" />

## Chrome

The colours, type, and spacing of the header and footer, plus the canvas each is allowed:

<SlideTokens group="chrome" />

A theme that redesigns the chrome to a different height sets `--slide-header-space` and `--slide-footer-space`, and the slide content moves with it.

## Published by the runtime

These are set in the DOM rather than declared in the contract, and a theme or a block reads them:

| Variable | Set on | What it carries |
| --- | --- | --- |
| `--slide-progress` | `[data-slide-progress]` | Position in the deck as a fraction from 0 to 1 |
| `--slide-chrome-top` | the canvas | `--slide-header-space` republished as an inset for a bleeding layout |
| `--slide-chrome-bottom` | the canvas | The same for the footer |
| `--deckard-scale` | the viewport | The measured fit, applied as a `scale()` transform |

A fullscreen block pads against the chrome insets so the deck header and slide counter never sit on top of a caption:

```tsx
className="pb-[calc(3rem+var(--slide-chrome-bottom,0px))]"
```

## Structural attributes

The runtime renders these and the theme styles them. They are as much a part of the contract as the tokens.

| Attribute | On |
| --- | --- |
| `data-slide-canvas` | The canvas element, which also carries the theme class |
| `data-slide-viewport` | The element that scales the canvas |
| `data-slide-frame` | The slide frame the overflow check measures |
| `data-slide-background` | The background element, valued with the variant name |
| `data-slide-motion` | The canvas inside it, valued with the field: `aurora`, `waves`, or `wash` |
| `data-slide-motion-state` | What that canvas is doing: `running`, `frozen`, or `unavailable` |
| `data-slide-header`, `data-slide-footer` | The chrome |
| `data-slide-header-brand`, `-title`, `-meta` | The three header parts |
| `data-slide-counter`, `-current`, `-separator`, `-total` | The counter |
| `data-slide-progress` | The progress element, absent entirely when `footer.progress` is `false` |
| `data-slide-surface` | A block that paints its own border or background |
| `data-slide-panel` | The `ContentSlideCard` panel |
| `data-slide-intro` | The eyebrow and heading block above a body |
| `data-slide-eyebrow` | The uppercase label above a title |
| `data-slide-title`, `data-slide-lead` | A slide's own headline and the sentence under it |
| `data-slide-kicker` | The label under a `FocusSlide` body |
| `data-slide-hero`, `data-slide-hero-meta` | The opener and its credit row |
| `data-slide-badge` | The pill above a centered opener's title |
| `data-slide-rail`, `-term`, `-detail` | The side column on `HeroSplitSlide` and `ProseSlide` |
| `data-slide-breaker`, `data-slide-breaker-index` | The section divider and the number it carries |
| `data-slide-accent-rule` | The short rule a minimal breaker or a statement opens on |
| `data-slide-statement`, `-text`, `-source` | The one-sentence layout, its sentence, its attribution |
| `data-slide-split`, `-main`, `-aside` | A `CodeSplitSlide` and its two sides |
| `data-slide-note`, `-index`, `-text` | One numbered note in that rail |
| `data-slide-prose`, `-body`, `-paragraph` | The label rail layout and its copy |
| `data-slide-quote`, `-text`, `-attribution`, `-portrait`, `-name`, `-source` | A pull quote, down to the portrait |
| `data-slide-list`, `-item`, `-marker`, `-text` | A `BulletList` and its three parts |
| `data-slide-reveal`, `-item`, `-item-accent`, `-title`, `-description` | A stepped `RevealList` and its parts |
| `data-slide-contents`, `-item`, `-index`, `-title`, `-folio` | A `ContentsList` row by row |
| `data-slide-columns`, `data-slide-column`, `-index`, `-label`, `-title`, `-text` | A `ColumnGrid` and one column of it |
| `data-slide-grid`, `data-slide-card`, `-accent`, `-label`, `-title`, `-body` | A `FeatureGrid` or `CardGrid` and its cards |
| `data-slide-media`, `-item`, `-frame`, `-overlay`, `-caption`, `-credit` | A media layout and its parts |
| `data-slide-table`, `-head`, `-heading`, `-row`, `-highlight`, `-cell` | A `DataTable` |
| `data-slide-timeline`, `-item`, `-marker`, `-done`, `-date`, `-label`, `-detail` | A `Timeline` and one milestone |
| `data-slide-log`, `-row`, `-tone`, `-time`, `-message`, `-status` | A `LogList`; `-tone` is valued `ok`, `note`, or `alert` |
| `data-stat-grid`, `-item`, `-value`, `-unit`, `-meter`, `-caption` | A `StatGrid`, down to the proportion bar |

These are the other half of the theme contract. Tokens are values; attributes are parts. A theme styles them, decorative `::before` and `::after` content included, which is how phosphor writes `[x]` where a list marker goes and ledger hangs a rule there instead, neither of them touching the block. A block may rewrite its markup and its class names freely as long as the attributes stay where they are.

A theme styles parts. It does not add content. A boot log, a status table, a cursor line with words in it are slide content, so they belong in a block the deck composes.

Code blocks are scoped too: `[data-slide-canvas] .shiki` has its shiki-painted background forced transparent, so a deck never restyles code the surrounding app renders.

---

# Slide patterns
Source: https://deckard.thebuilder.dk/slide-patterns

Deckard calls the source files blocks. Authors usually need a recipe: a whole-slide frame paired with the content block that belongs inside it. The visual gallery is a representative subset. The intent index below covers every author-facing pattern.

<SlidePatterns />

## Representative recipes

| Pattern | Level | Use it for | Example |
| --- | --- | --- | --- |
| `HeroSlide` | Whole slide | Open with the talk's title and premise. | [Opener](https://deckard-playground.thebuilder.dk/slides/intro) |
| `BreakerSlide` | Whole slide | Mark a section change. | [Section break](https://deckard-playground.thebuilder.dk/slides/canvas) |
| `OpenContentSlide` with `BulletList` | Slide recipe | Explain a short set of points. | [Bullets](https://deckard-playground.thebuilder.dk/slides/presenter) |
| `OpenContentSlide` with `StatGrid` | Slide recipe | Report a small set of figures. | [Figures](https://deckard-playground.thebuilder.dk/slides/numbers) |
| `ContentSlideCard` | Whole slide | Put flat prose or custom markup in one panel. | [Content card](https://deckard-playground.thebuilder.dk/slides/content-card) |
| `OpenContentSlide` with `CardGrid` | Slide recipe | Compare options or grouped ideas. | [Cards](https://deckard-playground.thebuilder.dk/slides/one-surface) |
| `OpenContentSlide` with `Timeline` | Slide recipe | Show a sequence or plan. | [Timeline](https://deckard-playground.thebuilder.dk/slides/roadmap) |
| `QuoteSlide` | Whole slide | Give one quotation the canvas. | [Quotation](https://deckard-playground.thebuilder.dk/slides/quote) |
| `ImageShowcaseSlide` | Whole slide | Pair one image with its context. | [Image](https://deckard-playground.thebuilder.dk/slides/image) |

## Choose the frame first

Use `HeroSlide`, `BreakerSlide`, `StatementSlide`, `QuoteSlide`, and `ProseSlide` as complete slides. They own the composition.

Use `OpenContentSlide` around a block that paints its own border or background, including `BulletList`, `StatGrid`, `FeatureGrid`, `CardGrid`, `DataTable`, `Timeline`, `LogList`, and `RevealList`.

Use `ContentSlideCard` for flat prose or custom markup with no frame of its own. Use `FocusSlide` when one block is the slide and a heading would repeat what the block already says.

```tsx
import { OpenContentSlide, StatGrid } from "@/app/slides/blocks"

const figures = [
  { value: "6.2s", caption: "Median build time" },
  { value: "0", unit: "%", caption: "Slides fixed after export" },
] as const

<OpenContentSlide eyebrow="Quarter in review" title="The numbers that moved">
  <StatGrid items={figures} />
</OpenContentSlide>
```

## Find a pattern by intent

| You need to | Start with |
| --- | --- |
| Open the talk | `HeroSlide`, `HeroSplitSlide`, or `HeroCenteredSlide` |
| Show the talk's structure | `OpenContentSlide` with `ContentsList` |
| Introduce a section | `BreakerSlide` or `MinimalBreakerSlide` |
| Land one claim | `StatementSlide` |
| Explain one code sample | `CodeSplitSlide` |
| Give one custom block the frame | `FocusSlide` |
| Present a longer passage | `ProseSlide` |
| Explain ordered points | `OpenContentSlide` with `BulletList` |
| Reveal an argument | `OpenContentSlide` with `RevealList` |
| Compare options | `OpenContentSlide` with `ColumnGrid`, `FeatureGrid`, or `CardGrid` |
| Report figures | `OpenContentSlide` with `StatGrid` or `DataTable` |
| Show a plan | `OpenContentSlide` with `Timeline` |
| Show an image | `ImageShowcaseSlide`, `MediaPair`, `MediaGallery`, or `FullscreenMediaSlide` |
| Quote someone | `QuoteSlide` |

The [blocks and registry guide](/guides/blocks-and-the-registry) documents installation, composition rules, and the individual source files.

---

# Theme gallery
Source: https://deckard.thebuilder.dk/themes

Each card applies one theme to the same slide in light and dark mode. The previews are `[data-slide-canvas]` elements with the chrome and progress bar the runtime renders. The stylesheet painting them is `packages/themes/src/<name>/theme.css`, the same file a deck loads.

Switch a card between light and dark, or enlarge it to take the full row. Every one of them carries both color modes; `defaultColorMode` decides which one a browser opens on.

<ThemeGallery />

Pick one by importing it:

```ts deck/deck.ts
import { meridian } from "@thebuilder/deckard-themes"
```

Or switch an existing deck with `deckard add theme meridian`. See the [themes guide](/guides/themes) for ejecting and for writing your own.

## meridian

`defaultColorMode: "system"`, both modes. This is the theme a new deck opens in.

The quietest theme here. A near-white blue-gray in light mode and a cool near-black in dark, flat surfaces with a hairline border and softly rounded corners, no shadow in either mode. A white card on a white sheet with no shadow asks a lot of its border. If a deck of yours reads flat rather than calm, that is the thing to put back.

<ThemePalette theme="meridian" />

## aurora

`defaultColorMode: "dark"`, both modes.

A live field behind the slides that open, break, state, and close a deck. Four background variants paint in a WebGL canvas rather than in CSS: `hero` and `breaker` take banded curtains, `closing` an undulating band, and `statement` a soft noise wash. Under every canvas the theme paints a gradient of the same three colours, and that gradient is the slide while the runtime loads, on a machine with no WebGL, and after a lost context. Reduced motion, a capture, and the presenter preview each hold the field on one fixed frame, so two screenshots of a slide are the same image.

Dark is home. Light mode carries its own field colours rather than the dark ones lightened, and both sets sit in `theme.css` beside the rest of the paint. Body copy runs light in Manrope under tightly tracked Space Grotesk display type.

The aurora card in the gallery is showing that painted gradient. The gallery renders slide markup and no runtime, so the card carries the `hero` variant's fallback rather than a canvas.

<ThemePalette theme="aurora" />
## blueprint

`defaultColorMode: "dark"`, both modes.

A drafting sheet. The background variant that carries the theme is `grid`, which draws a cell pitch and a division pitch over each other from the same corner. Nothing is rounded and nothing is tinted: a section number sits boxed in three strokes of the accent, a card grid is butted together over a field of the line colour so the gutters read as drawn divisions, and an opener's meta row becomes the title block along the foot of the sheet. Body copy runs a weight under regular in both modes, which is what keeps a slide reading as a drawing rather than as a web page.

<ThemePalette theme="blueprint" />

## ledger

`defaultColorMode: "system"`, both modes.

A bound report. Nothing is rounded and nothing is raised; rules carry the structure a shadow would carry elsewhere. Three families on one slide, each with exactly one job: serif says what the section is, sans argues it, mono numbers it. The accent is oxblood on paper and a warmer rust after dark.

<ThemePalette theme="ledger" />

## nexus

`defaultColorMode: "dark"`, both modes.

A flight console. Dark is home. Every heading is capitalised with a hair of positive tracking, and `h1`, `h2`, and the `StatGrid` figure carry an accent halo through `--slide-halo`. The halo is `none` in light mode, so light mode reads as the printed version of the same document rather than as a second theme.

<ThemePalette theme="nexus" />

## phosphor

`defaultColorMode: "dark"`, both modes.

A green CRT. One monospace family for every word on the slide, scanlines painted across every background variant, and a phosphor bloom on display headings. It also runs a thinner status bar than the rest, taking `--slide-footer-space` below the contract default, which hands the space back to the slide. Light mode turns the tube off, for handouts and for printing.

<ThemePalette theme="phosphor" />

## atelier

`defaultColorMode: "system"`, both modes.

A print poster. `--slide-rule` and `--slide-surface-border` are both the foreground, so every line on the slide is full-strength ink at the theme's own 4px measure rather than a tint at one. Headings are Archivo capitals at the heaviest weight the face carries, and the display size runs well past every other theme here. Grid cells and the highlighted table row are flooded with the accent and flip their ink rather than taking a tint. Nothing is rounded and nothing is raised.

<ThemePalette theme="atelier" />

## cotton

`defaultColorMode: "system"`, both modes.

The other pole from atelier. Body copy is Outfit at weight 300, headings are Bricolage Grotesque with its optical size axis mapped rather than pinned, and the corners are the largest in the gallery. `--slide-accent-soft` carries the tinted card, the metrics panel and the filled capsule; the accent itself is kept for the breaker, the closing plate and the dots. `--slide-surface-shadow` is the one lift in the theme, and only `data-slide-panel` reads it, so a slide raises at most one surface however many blocks it composes.

<ThemePalette theme="cotton" />

## noir

`defaultColorMode: "dark"`, both modes.

A fashion lookbook. Every rule is one pixel, the opener, the breaker, the statement and the quote all centre their content, and Cormorant Garamond sets the display at weight 300 with the italic kept for the statement and the quotation. There is no monospace family: `--slide-font-mono` carries the body sans, and tracked capitals up to `--slide-track` stand where another theme sets mono. Code keeps a monospaced stack of its own so a sample still lines up.

<ThemePalette theme="noir" />
## quorum

`defaultColorMode: "light"`, both modes.

A board pack. A short type scale inside a short frame, which is what lets a segment table and a five-figure band sit on one slide without shrinking. Figures and pull quotes are set in a serif and everything else in the sans, so a number being reported reads differently from a number being described. Cards hang off a stroke on their leading edge rather than sitting in a box. `background: "accent"` inverts the sheet rather than flooding it with the accent, in both colour modes.

<ThemePalette theme="quorum" />

## About the swatches

Each palette above is read out of the theme's stylesheet when this page builds: the sheet, the card, the muted surface, the border, the accent, and the text. A theme is a hundred-odd declarations and its own `THEME.md` explaining them, so this is a small slice. The preview shows you what the theme looks like; the swatches tell you what to type when you want that green.