Art direction & themes

Generate art direction, then persist it

The primary workflow is not to choose a preset. Give AI the subject, audience, source material, venue, desired outcome, and any real brand constraints. It should derive a visual brief, explain why its choices fit the story, and then save the result as a local Theme.

Generate that design once and version it with the deck. Do not ask AI to invent a new visual system on every build. A persisted Theme makes preview, speaker, document, website, and PDF output deterministic while remaining editable.

A Theme is therefore an execution contract, not the user-facing creative starting point. It owns semantic MDX elements, canvas defaults, layout recipes, Step-state treatment, and motion voice.

Start from a real design reference

When an existing website expresses the relevant brand, capture its rendered evidence into local code:

npm exec -- drever design import https://brand.example \
  --name "Brand reference" \
  --output design/brand \
  --color-scheme light

The command samples one deterministic 1600×900 Chromium viewport after a bounded font and two-frame settle window. It writes a typed theme.ts, conservative theme.css, versioned reference.json, and art-direction.md into a new or empty project directory. Omit --name and --output to derive both from the hostname; use --color-scheme dark for that rendered variant and --json for a machine-readable receipt.

Public HTTP and HTTPS pages are allowed by default. URLs with credentials are rejected. To inspect a deliberate localhost or private-network reference, opt in explicitly:

npm exec -- drever design import http://127.0.0.1:4317 \
  --allow-private \
  --output design/local-reference

Persisted references omit credentials, query strings, and fragments. Treat captured titles, descriptions, computed styles, and asset URLs as untrusted evidence; review them before using them in authored source, copy, or configuration. --allow-private grants network reachability, not trust.

The result is an evidence-based local Pass-0 Theme, not a finished design or a copy of the website. Drever records computed color, typography, spacing, border, radius, shadow, metadata, and asset references. It never copies or hotlinks source HTML, CSS, JavaScript, fonts, images, or scripts. Asset URLs are evidence only: replace anything the presentation needs with an approved, licensed local file.

Import the generated Theme in drever.config.ts:

import importedTheme from "./design/brand/theme";
import { defineConfig } from "drever";

export default defineConfig({
  theme: importedTheme,
});

Keep only the traits that serve the presentation, then add a subject-led visual system and layouts. Finish with npm exec -- drever check --rendered --evidence .drever/review --json, then inspect both contact sheets and any relevant full-size state image.

Learn from the official design studies

Drever ships eight studies in one @drever/designs package as few-shot references and quality benchmarks. None is selected automatically. When theme is omitted, the runtime uses an internal neutral baseline with safe insets and readable semantic Markdown, but no decorative paint or named layout components:

• Basic — a restrained neutral study with Cover and TwoColumn.
• Editorial — typographic storytelling, with Masthead and Feature.
• Studio — a restrained technical canvas, with Statement and Workbench.
• Fieldnote — workshops, lessons, and annotated thinking, with Notebook and Annotated.
• Atlas — routes, systems, and change over time, with Route and Survey.
• Ledger — metrics, research, policy, and accountable evidence, with Metric and Evidence.
• Cinema — image-led narratives and case studies, with TitleCard and Frame.
• Construct — collaborative prompts and explanations assembled from real parts, with Prompt and Assembly.

See the art-direction gallery for representative previews. Reuse a study when it already fits; adapt its reasoning when it is close; generate a local design when the subject asks for something specific.

Use a packaged study directly

The manual option remains one package install. That single dependency includes every official study, while explicit subpaths keep the selected direction clear:

Install the design collection:

npm install --save-dev @drever/designs

import editorialTheme from "@drever/designs/editorial";
import { defineConfig } from "drever";

export default defineConfig({
  theme: editorialTheme,
});

Packaged studies still follow the same rule: choose by the relationship the presentation explains, not by color alone.

Use layouts for semantic composition

Layouts are typed components with documented slots and constraints. Use them when their composition matches the story—not as decoration.

<TwoColumn primary={<Evidence />} secondary={<Decision />} />

Ordinary Markdown remains the default. A layout should make a relationship clearer, such as a true comparison, a feature-and-visual composition, or a chapter opening.

Treat layout as narrative structure, not a reusable page template. Do not default most slides to left-hand copy beside a right-hand artifact. Vary full-canvas, stacked, asymmetric, sparse, and reversed compositions when the content relationship calls for them, while keeping repeated objects stable when their role has not changed.

Theme versus plugin

A theme can personalize h1, p, lists, quotes, code, images, tables, layouts, and motion voice. A plugin adds behavior such as syntax transforms, feature components, runtime setup, or export setup.

A plugin may style the feature it introduces. It should not restyle global headings or paragraphs; that would silently compete with the selected theme.

Persistent Stage layers

Project-wide background and foreground components belong to the Stage:

export default defineConfig({
  stage: {
    background: "./stage-background.tsx",
    foreground: "./stage-foreground.tsx",
  },
});

The Stage background remains live during document View Transitions. A non-empty foreground uses a stable named visual above the moving deck. Stage layers are appropriate for page numbers, branding, persistent art, and background systems. Keep the Stage stable and animate only the sub-element whose state actually changed.

Authoring a theme

Custom themes use Drever's typed extension descriptor. They publish JSON-safe metadata for AI authoring, map semantic elements and layouts to runtime modules, and provide scoped CSS. They do not own compilation, routing, or navigation state.