Building Html Canvases

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.