building-html-canvases

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

- 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.

## Rules that still apply

- 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`.

From PostHog/skills, MIT.