/building-html-canvases

name: building-html-canvases
description: >
  Author a PostHog canvas with semantic HTML, CSS, and direct browser APIs — documents, articles,
  generative graphics, 2D canvas and WebGL experiences, and focused experiments where React
  components add no useful structure. Use after building-canvases has routed a canvas request to a
  plain-HTML/browser-API implementation. Covers the thin component wrapper the current runtime
  requires, styling and theming without Quill, drawing surfaces, and animation/cleanup patterns.

Building HTML canvases

Some canvases are documents or graphics programs, not applications: a written report, a diagram, a generative-art piece, a WebGL scene. For these, semantic HTML, CSS, and direct browser APIs are the right tools — don't force Quill components or React state onto a static page.

The wrapper the current runtime requires

Every canvas keeps `src/canvas.tsx` as its mounted React entry component (default export, no props). Keep the React layer as a thin shell and write the experience in HTML/CSS/browser APIs inside it:

• A document is JSX that is effectively semantic HTML — `<article>`, headings, lists, tables,

figures — with a `<style>` block for typography and layout. Write real, specific copy.

• A drawing/WebGL program renders a `<canvas>` element and drives it imperatively from a

`useEffect` via a ref: get the 2D/WebGL context, run the setup and render loop there.

• Clean up in the effect's return: cancel `requestAnimationFrame` loops, remove listeners, and

release contexts, so theme switches and remounts don't leak or double-run.

• Mixing tiers is fine: a mostly static page can mount one interactive island, and a data board

can hand a chart's `<canvas>` to imperative code while React owns the chrome.

The import allowlist still applies (react, react-dom, @posthog/quill, recharts, lucide-react, dayjs) — browser globals (`document`, `CanvasRenderingContext2D`, `WebGLRenderingContext`, `requestAnimationFrame`, `IntersectionObserver`, Web Audio, etc.) need no import. Three.js and other npm graphics libraries are not yet loadable; write against raw WebGL or 2D canvas until the build pipeline's dependency admission ships.

Styling and theme without Quill

• Use Tailwind utilities and/or a `<style>` block (keyframes and complex selectors are fine).
• The host toggles a `.dark` class on the document root when the user's PostHog theme changes.

Define your colors as CSS variables under `:root { … }` with overrides under `html.dark { … }`, or use theme token utilities (`bg-background`, `text-foreground`, `border-border`) — never a light-only hardcoded color.

• For canvas/WebGL drawing colors, read the resolved token at runtime

(`getComputedStyle(document.documentElement).getPropertyValue("--primary")`) or your own CSS variables, and re-read on theme change if the scene is long-lived.

Rules that still apply

• No `fetch()`/`XMLHttpRequest`, no `<script>` tags, no dynamic `import()`, no remote assets —

the sandbox blocks them. PostHog data comes only through the `ph` bridge (see the `querying-canvas-data` skill), including `ph.capture` for interaction analytics.

• External links go through `ph.openExternal(url)` (posthog.com origins only), from a user

interaction.

• Validate and publish through the canvas tools as described in `validating-and-publishing-canvases`.