page-figures · diff
git:20261006.254f994 to git:20261006.fc60f86
9 added, 13 removed. Audit A to A.
---
name: page-figures
description: Add figures, diagrams, interactive pieces, videos and callouts to an article draft only where they show what the words can't, as files in its assets folder that the founder approves with the article.
---
# 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 (characters,
animals, devices) 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 that reads on light and dark pages.
Every figure and piece works in light and dark. Leave its background transparent so the page shows
- through, and give its colours a dark variant (the brand's dark tokens when there are any).
+ through, and give its colours a dark variant (the brand's dark tokens when there are any); in an
+ SVG, a `prefers-color-scheme: dark` block in its `<style>` does it.
- ## Figure and diagram
+ ## Figures and diagrams
- An SVG file in the assets folder, for a flow, a structure, a comparison, a timeline or a measured
- result:
+ 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:
```markdown
```
- The alt text says what the figure shows; the caption says what to notice. Draw it plainly, with
- real labels and the article's own numbers, in the site's diagram style when DESIGN.md describes
- one. Use a `viewBox` and no fixed pixel width. Put colours in a `<style>` inside the SVG: the light
- values first, then the dark ones in `@media (prefers-color-scheme: dark)`. 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.
-
- Use a `mermaid` block instead only when the site's own pages already render Mermaid. Tin then
- shows its source for review, and the site draws it.
+ The alt text says what the figure shows; the caption says what to notice. Use real labels and the
+ article's own numbers. 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:
````markdown
```tin-embed
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, border or background around the piece: the page is its background. 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`, and 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.
## Video
A video that already exists at a public address, on the founder's site or on YouTube, Vimeo, Loom
or Mux:
````markdown
```tin-video
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.