tin-computer/tin/page-figures

Figures, diagrams, interactive pieces and videos

Add one only where it shows something the words can't carry as well: a process, a comparison, a structure, a measured result. Most articles need none, one or two. Never decorate.

Your output instructions name the article's assets folder. Write each file directly in it and refer to it from the article with a path that starts ./<folder name>/. Tin keeps only the files the article refers to, and the founder approves them with the words.

The project's look

Everything you draw should look like it belongs on the founder's site. When brand/BRAND.md and DESIGN.md exist, read them first and follow them: the token palette in light and dark, the type family, weight and size for each role, the corner radii and how the site frames figures, the founder's written rules, and the way the product draws its recurring subjects (a mascot, characters, its own objects or screens) in their own colours, never as a labelled placeholder shape. Name the brand's font families with their fallbacks. Without brand files, keep a plain look: system fonts and a quiet neutral palette.

Follow the site's theming. When the site has a dark theme (the brand has dark tokens, or DESIGN.md describes one), leave the background transparent so the page shows through and give the colours a dark variant; in an SVG, a prefers-color-scheme: dark block in its <style> does it. When the site is light only, or you can't tell, keep it light: color-scheme: light and the site's paper colour as its own background, so it reads on any page.

Figures and diagrams

Make each one however suits it: an SVG file for a still figure or diagram, an interactive piece when the reader should try something, or a mermaid block when the site's own pages render Mermaid. Tin shows what you make; it doesn't redraw it. For an SVG file:

![What the figure shows](./<folder name>/<file>.svg "What the reader should notice")

The alt text says what the figure shows; the caption says what to notice. Use real labels and the article's own numbers. Size it for the article's text column (DESIGN.md often records the width; otherwise about 700px), so its labels show near body-text size instead of shrinking. The SVG must have no script, no event handlers, no foreignObject and no links, images or fonts from elsewhere; Tin leaves out an SVG that has any.

Interactive piece

One self-contained HTML file in the assets folder, only when interaction teaches something a still figure can't, such as a simulation or a calculator:

src: ./<folder name>/<file>.html height: 420 title: What the reader can do with it

Inline its CSS and JavaScript. It runs with no network access: no requests, no outside libraries or images. When DESIGN.md records the font files the site itself serves, you may point @font-face at those site paths: they load on the site, and Tin's preview uses the fallbacks. Keep it small, give it a sensible default state, and make it work with a mouse, a keyboard and a touch screen.

Draw no panel, card or border around the piece; frame only the surface the reader plays with, the way the site frames figures. Set colours as CSS variables, light on :root with color-scheme: light. For a site with a dark theme, add the dark values with color-scheme: dark in both @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { … } } and :root[data-theme="dark"] { … }; Tin sets data-theme to match its reader. Let the content set its height: Tin fits the frame to it, so height is only a first guess.

Look at it before you finish

Look at every figure and piece the way a reader will, in light and in dark, at the article's column width and at a phone width, and fix what you see, then look again. Check each one against what it is meant to show: every shape, line and mark you drew must be visible in both themes, and no text may touch other text or lines. The sandbox has an offline Chromium for this. In a small Node script, require("/opt/tin-lite/diagram/node_modules/playwright"), run it with PLAYWRIGHT_BROWSERS_PATH=/opt/tin-lite/diagram/browsers, open each file with colorScheme set to light and then dark, and save screenshots under /tmp. View them with your image viewing tool. Keep the screenshots out of the assets folder.

Make this draft's figures yourself. Don't copy them from an earlier draft that wasn't approved: its problems come with it.

Video

A video that already exists at a public address, on the founder's site or on YouTube, Vimeo, Loom or Mux:

url: https://www.youtube.com/watch?v=... title: What it shows

Never invent a video or an address. A long video file is linked, never copied into the folder.

Callout

> [!NOTE], > [!TIP] or > [!WARNING] on the first line of a quote, for a short aside the reader shouldn't miss. Use one or two at most.

Existing pages

When the brief points to an existing page that has figures and you can read its source, keep them: copy an inline SVG into the folder as its own file, or rebuild an interactive piece as an embed with its script and data. Don't describe a figure in words instead of keeping it. If you can't carry one over, say which and why in Generation notes.

List every figure, diagram, interactive piece and video in Generation notes with one line on what each shows.