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.

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.

• Size the outermost JSX/HTML element to the iframe viewport with min-h-screen or min-height: 100vh, so it fills the viewport and grows past it as content demands. Do not use h-screen or height: 100vh there: a fixed viewport height caps a flex column, so tall children shrink and clip instead of scrolling. Do not use h-full or height: 100% on that root either: a published canvas's artifact shell gives its html, body, and #root elements no explicit height, so percentage height collapses to the content height. A min-height root is not a definite height, so a descendant's percentage height still collapses; give an intermediate wrapper an explicit height when a child must fill a box.
• 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.
• Give your own CSS variables a prefix (--doc-bg, --doc-muted). Never reuse a platform token name: the bundled Quill stylesheet sets --background, --border, --card, --chrome, --input, --muted, --primary, and --fill-* on every element, so a :root or html.dark value with one of those names never reaches any element. A page that colors its text with its own --muted then renders unreadable (pale text on a pale page). Validation rejects such a declaration with platform_token_redeclared.
• 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.

• PostHog data comes only through the ph bridge (see querying-canvas-data), including ph.capture for interaction analytics. Other requests and external styles, images, fonts, media, or frames require their exact public HTTPS origins in capabilities.network.origins and work only after publishing. Remote scripts and dynamic imports remain blocked.
• A document that states PostHog numbers must make each one verifiable: an insight-backed number links its saved insight through ph.openExternal (URL from the generate-app-url MCP tool, from a click); an ad-hoc ph.query number discloses the exact query that ran in a <details> element beside the claim — see "Verifiability" in querying-canvas-data.
• 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.