# artoo-kit 0.8.1

Long-form article layout, evidence regions, and the provenance panel.

The built-in site library: an Artoo-owned, self-contained foundation for public
artifacts. Vendored into an artifact at `site/lib/artoo-kit/` with a pinned
hash — changing the kit here does not rewrite already-vendored bytes; `artoo
lib update artoo-kit` is the explicit upgrade boundary.

Files (all under `assets/`, all vendored):

| file | role |
|------|------|
| `tokens.css` | design tokens: color, type roles, spacing, the chart palette |
| `base.css` | resets and page defaults |
| `article.css` | long-form article grid (prose + margin gutter) |
| `components.css` | nav, cards, callouts, badges, stats, colophon, provenance |
| `kit.js` | theme toggle, mobile nav, legacy mermaid.js boot |
| `provenance.js` | provenance panel hydration + in-prose claim anchors |
| `favicon.svg` | default site icon (link it to silence the `/favicon.ico` 404) |

## Favicon

Every page should carry a favicon; without one the browser requests
`/favicon.ico` and logs a 404 on every load. Reference the vendored icon in
`<head>`:

```html
<link rel="icon" href="lib/artoo-kit/favicon.svg">
```

## Provenance panel

The panel renders an artifact's lineage — sources with grades and
independence, claims with status and verification-method badges, counts, and
an optional notebook vintage — from `site/data/provenance.json`. `artoo build`
and `artoo provenance` write it from provider-neutral `artoo-evidence/1` or
adapt an attached Flip notebook's `flip-render/1` projection.

It is **progressive**: with no projection present the panel hides itself and
the page reads exactly as authored. To add it to a hand-authored page:

```html
<!-- where the panel should appear -->
<section class="provenance article-breakout" data-artoo-provenance></section>

<!-- before </body>: the offline data global, then the hydrator -->
<script src="data/provenance.js"></script>
<script src="lib/artoo-kit/provenance.js"></script>
```

`data/provenance.js` sets `window.__ARTOO_PROVENANCE__` so the panel hydrates
from a `file://` URL with no server (a bare `fetch()` of a sibling JSON is
blocked under `file://`; a `<script>` assignment is not). If you omit it, the
hydrator falls back to `fetch("data/provenance.json")`, which works over HTTP.
Both files are written by `artoo provenance`; the deterministic article and
collection renderers wire the panel automatically when a projection exists.

### Claim anchors

`provenance.js` also rewrites `[C7]` / `[A3]` bracket references **that exist
in the projection** into stable anchors: the first occurrence gets
`id="claim-C7"` and every occurrence links to its entry in the panel
(`#prov-claim-C7`), with the claim text and status in a tooltip. Ids the
projection does not know are left untouched, and text inside `<code>`/`<pre>`
is never rewritten. Scope defaults to `[data-claim-anchors]`, then `<main>`,
then the body — put `data-claim-anchors` on the article element to bound it.

This is done client-side, matching the kit's existing client-side enhancements
(theme, nav, legacy mermaid.js). Nothing rewrites the committed HTML; the anchors are an
enhancement layered at load time.

## Media figures: loops, toggles, tables

Markdown content (`[content]`) renders these without hand-written HTML:

```markdown
![What happens, for a reader who can't see it](assets/clip.mp4 "Caption. Say if it's sped up.")
```

A paragraph that is only an image whose `src` is a video (`.mp4`, `.webm`, `.mov`,
`.m4v`) becomes an `article-figure` holding a silent loop: `<video class="article-loop"
autoplay loop muted playsinline>`, named by the alt text through `aria-label`. If
`assets/clip.poster.png` exists in `site/`, it becomes the `poster`. kit.js pauses loops
and shows controls for readers who prefer reduced motion; a click toggles play. Keep
words out of the loop itself: the alt text and caption carry them.

```markdown
```toggle
Proposed: ![The backups box is dashed: proposed](assets/dashed.png)
Accepted: ![The same box, now solid](assets/solid.png)
caption: Flip between the proposal and the accepted change.
```
```

A `toggle` fence of 2–4 `Label: ![alt](src)` lines (images or videos) and an optional
`caption:` line becomes an `article-toggle` figure: one panel at a time, switched by
labelled radios. Pure CSS, so it works from `file://`. Use it when the reader should flip
a state themselves rather than watch a loop of it.

Pipe tables (`| a | b |`, a `|---|---:|` separator, then rows) render as `<table>`;
`---:` right-aligns a column and marks it `numeric`. Each sits in an `article-table`
region that scrolls sideways when the table is wider than the screen, and long inline code
wraps (in a cell or a paragraph), so neither widens the page on a phone.

A collection page can open with front matter between `---` lines: `description` (its own
dek and meta description), `kicker`, `image` (a site-relative social card, written as
`og:image` with a large Twitter card) and `image_alt`. Other keys are ignored.

## Gotchas

### SVG and CSS custom properties

`fill="var(--accent)"` **does not resolve** — SVG presentation *attributes* are
not CSS and custom properties are not looked up there. Style SVG with CSS
instead: give shapes classes and set `fill` in a `<style>` block or a
stylesheet.

```html
<!-- broken: attribute never resolves the token -->
<rect fill="var(--chart-1)" .../>

<!-- works: class + CSS property -->
<style>.bar-1 { fill: var(--chart-1); }</style>
<rect class="bar-1" .../>
```

(An inline `style="fill: var(--chart-1)"` attribute also works, because that is
the CSS `fill` *property*, not the SVG presentation attribute.)

### Charts and figures

The kit ships no chart primitive. Author a quantitative chart as inline SVG
(self-contained, no runtime); author structure — flows, sequences, states,
schemas, timelines — as a Mermaid diagram with the `artoo-diagrams` library
(`artoo docs artoo-diagrams`). Guidance:

- **Palette.** Use the Okabe–Ito tokens `--chart-1 … --chart-8` (in
  `tokens.css`); they are colorblind-safe and ordered by draw order. Do not
  invent per-chart colors.
- **Theme.** Because token colors differ between light and dark, style series
  with the classes-plus-`<style>` pattern above so a chart follows the theme;
  never bake a hex value that only reads in one theme.
- **Numerics.** Use `font-variant-numeric: tabular-nums` (the `--font-numeric`
  role sets it) so figures align.
- **Honesty.** A figure earns its place by helping the reader make a valid
  comparison — include vintages, denominators, and a source note in the
  `<figcaption>`, so the comparison can be interpreted honestly.

### Shared document saves

`store.js` implements protocol-2 ArtooStore. Await `load(name)` before editing;
`save(name, document)` uses its revision for conflict protection. Surface errors
and save status: durable disk writes do not commit or push Git. HTTP failures
never silently become browser-only saves. Inspect and explicitly compare legacy
browser data with `inspectLocal` / `importLocal`; inspect failed writes with
`inspectPending` / `recoverPending`. See `artoo docs serve` for the complete
authoring, migration, and recovery contract.

## Class vocabulary

| class | role |
|---|---|
| `article` | the long-form grid container; children sit in the prose column by default |
| `article-full` | wrapper: let this child run edge to edge |
| `article-breakout` | wrapper: wider than prose, still centered |
| `article-mrow` | row that pairs a prose block with a margin note |
| `article-masthead` | top bar; `__name` is the artifact link, `__label` the standfirst tag |
| `article-header` | the title block at the head of the piece |
| `article-kicker` | small label above the title (conventionally the artifact kind) |
| `article-title` | the h1 |
| `article-dek` | standfirst under the title |
| `article-byline` | publication line; wrap the date in `<time datetime=…>` |
| `article-lede` | opening paragraph, set larger |
| `article-figure` | figure wrapper for a table or chart; put vintage, denominator, and source in the `figcaption` |
| `article-table` | scroll region around a table (Markdown pipe tables get one): wide tables scroll sideways inside it instead of widening the page |
| `article-loop` | a silent looping video inside an `article-figure` (Markdown: an image whose src is a video); named by `aria-label`, paused with controls for reduced motion, click toggles |
| `article-toggle` | figure variant: one of 2–4 images or loops shown at a time, switched by labelled radios; `__bar` holds the labels, `__panels` the media (Markdown: a ```` ```toggle ```` fence) |
| `article-marginnote` | right-gutter note, inline on mobile; `--def`, `--source`, `--callout` variants, `.term` for the term defined |
| `article-pullquote` | breakout-width quote; attribute it with `<cite>` |
| `article-pullnumber` | breakout-width figure; `.num` is the value, `.label` its caption |
| `article-colophon` | how-it-was-made block closing the piece |
| `site-nav` | multi-page nav; `.brand`, `.nav-toggle` + `.nav-links`, and current-page links (wired by kit.js) |
| `page` | container for a non-article page; `--narrow` tightens it |
| `card-grid` | responsive grid of navigation cards |
| `nav-card` | navigation card; use on links to destinations, not as a generic container |
| `card` | deprecated compatibility alias for nav-card; prefer nav-card in new work |
| `callout` | boxed aside with a `.callout-title`; `--warn`, `--danger`, `--success` variants |
| `badge` | inline label; `--accent`, `--success`, `--warn` variants |
| `stat-row` | row of figures |
| `stat` | one figure; `.value` then `.label` |
| `toc` | table of contents, as an ordered list |
| `diagram` | wrapper for an inline SVG or an artoo-diagrams Mermaid block |
| `colophon` | build and provenance footer |
| `collection-pager` | previous and next navigation at the foot of a collection page |
| `numeric` | tabular figures, so columns of numbers align |
| `no-print` | hide this element when the page is printed |
| `provenance` | the provenance panel root; mark it `data-artoo-provenance` and provenance.js fills it from data/provenance.json |
| `claim-ref` | written by provenance.js onto `[C7]`-style references; never hand-author it |

artoo-kit owns `article-`, `provenance`. A class starting with one of those that the vendored stylesheet does not define is a guess, and `artoo build` reports it with the nearest real class. Your own classes belong outside those prefixes.
