@atelic-action/artifact 1.2.0 → 2.0.0

package/README.md

@@ -7,7 +7,7 @@ The documents the practice hands or sends a business, as a published package and
 
 Three layers, each a version the next depends on (ATE-671): `@atelic-action/ui` holds the pieces, this package holds the documents built from them, and each business's folder holds only its content, routes, and config. A document fix reaches a folder by bumping this package; a piece fix by bumping ui here, then this package in the folder.
 
-Five artifacts live in the template site: the **writeup** at `/writeup`, the graded document an owner gets, a web page first with its printed copy derived from it; the **read** at `/read`, what a customer gets at the end of an engagement's first week, the baseline's grades explained by cause with the plan in order; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; and the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page. The bare host sends a reader to the writeup. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
+Five artifacts live in the template site: the **writeup** at `/writeup`, the graded document an owner gets, a web page first with its printed copy derived from it; the **read** at `/the-read`, what a customer gets at the end of an engagement's first week, the baseline's grades explained by cause with the plan in order; the **proposal** at `/proposal`, sealed into the page and opened by the reader's own email address; the **monthly page** at `/report`, what an Operate client gets each month on one letter sheet; and the **note** at `/notes`, the first touch for a business whose site publishes no email address, set as a short page. The bare host sends a reader to the writeup. Every artifact prerenders to static HTML, stays out of every index, and carries the practice's brand by default.
 
 The method behind them (the seven sections, the four grades from A to D, the rented line, what moved, and when an artifact is private) is the practice repo's `FOOTPRINT.md`. This repo builds to it and never restates it.
 
@@ -21,13 +21,14 @@ Every export of the package, all from the one entry, `@atelic-action/artifact`.
 
 | Export | What it is | Route |
 |---|---|---|
+| `Topic` | The writeup's section card on its own: the trade name linked to its definition, the one liner, the grade, the why line, the blocks, and the sources, with an `extra` slot after the blocks. The read renders its sections through it | `/writeup` |
 | `Writeup`, `WriteupProps` | The graded document an owner gets: the overview, the three tiers of section cards, the close | `/writeup` |
 | `ratingCell` | A star rating table cell for a writeup table, sorted by its figure | `/writeup` |
 | `WriteupBlock`, `WriteupTopic`, `WriteupPart`, `WriteupSheet`, `WriteupSummary`, `WriteupSummaryRow`, `WriteupMarkets`, `WriteupRented`, `WriteupMark`, `WriteupCell`, `WriteupTone`, and the rest of the `Writeup*` types | The shapes a writeup's content is written in | none |
 | `WriteupGrade`, `WriteupPerson`, `WriteupShot` | The grade letter, the sign off person, and the owner's screen, shared by every document, all three re exported from ui | none |
-| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table; each section read top to bottom as where we looked (the tools, linked, at the top), what it showed (a short paragraph or two, a compact table of facts, lists of examples under their own headings, and any proof pictures), why (one sentence on a tinted panel), today and after (a two column table), and what we recommend (a checklist); then the plan in order. A beat with no data is left out, heading and all | `/read` |
-| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the gist table's columns, Where We Looked, What It Showed, Why, Today, After, What We Recommend, the plan's heading), each overridable through `labels` | `/read` |
-| `ReadTier`, `ReadSection`, `ReadTool`, `ReadFact`, `ReadExamples`, `ReadChange`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in, all plain data so a routine can write a read as JSON. A section's `tools` were its `sources` in 1.0.0; `sources` is still read, and rendered at the top as tools, and `ReadSource` names the same shape as `ReadTool` | none |
+| `Read`, `ReadProps` | The baseline's grades explained by cause: the gist table, with an optional `note` callout under it for what the read leaves out; each section on the writeup's card (`ReadSection` extends `WriteupTopic`: the trade name linked to its definition, the one liner, the grade, the why line as the summary, the writeup's blocks, and the sources at the foot) plus the read's own today and after (a two column table) and what we recommend (a checklist); then the plan in order. A beat with no data is left out | `/the-read` |
+| `readLabels`, `ReadLabels` | The fixed words the read sets (Prepared for, the gist table's columns, Today, After, Recommendations, the plan's heading), each overridable through `labels` | `/the-read` |
+| `ReadTier`, `ReadSection`, `ReadChange`, `ReadStep`, `ReadPlan`, `ReadClose`, `ReadLink`, `ReadParagraph` | The shapes a read's content is written in. `ReadSection` is a `WriteupTopic` plus `gist`, `changes`, and `recommend`; its `why` and a finding's `body` take a paragraph (a string, or runs of text and links) as well as a node, so a routine can still write a read as JSON | none |
 | `Report`, `ReportProps` | The monthly page: the four questions, the seven grades now and before, the sign off, on one letter sheet | `/report` |
 | `ReportLead`, `ReportLeads`, `ReportGradeRow` | The shapes a monthly page's content is written in | none |
 | `Note`, `NoteProps` | The first touch set as a page: the opener, two lanes of findings, where the work would start, the close | `/notes` |
@@ -44,7 +45,7 @@ What a document is built from stays in `@atelic-action/ui`, and this package imp
 bun add @atelic-action/artifact @atelic-action/ui
 ```
 
-Peer dependencies: `@atelic-action/ui` at `^2.0.0`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
+Peer dependencies: `@atelic-action/ui` at `^2.1.0`, `react` at `^19.0.0`, and `lucide-react` at `^1.23.0`. The package ships TSX and CSS as source, compiled inside the site's own Vite like ui's; a site whose `vite.config.ts` is one `artifactConfig` call from `@atelic-action/ui/vite` needs nothing more, for the build, the prerender, and the dev server alike. The default labels a document sets live in the document: the read's `readLabels` and the sealed document's gate copy are overridden through props, and the monthly page's four questions are fixed on purpose, since they are its contract with the Statement of Work.
 
 ```tsx
 import { Writeup } from "@atelic-action/artifact";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atelic-action/artifact",
-	"version": "1.2.0",
+	"version": "2.0.0",
 	"description": "The composed documents the Atelic practice hands or sends a business (the writeup, the read, the monthly page, the note, and the sealed document), built from the pieces in @atelic-action/ui",
 	"type": "module",
 	"license": "MIT",
@@ -37,12 +37,12 @@
 		"format": "biome format . --write"
 	},
 	"peerDependencies": {
-		"@atelic-action/ui": "^2.0.0",
+		"@atelic-action/ui": "^2.1.0",
 		"lucide-react": "^1.23.0",
 		"react": "^19.0.0"
 	},
 	"devDependencies": {
-		"@atelic-action/ui": "^2.0.0",
+		"@atelic-action/ui": "^2.1.0",
 		"@biomejs/biome": "^2.0.0",
 		"@playwright/test": "^1.60.0",
 		"@sentry/react": "^10.0.0",

package/src/documents/Read.tsx

@@ -4,42 +4,43 @@ import {
 	GradeChip,
 	gradeLabel,
 	isEmpty,
-	newTabProps,
 	Paragraph,
 	Runs,
-	Shot,
 	SignOff,
 	type WriteupGrade,
 	type WriteupPerson,
-	type WriteupShot,
 } from "@atelic-action/ui/artifact";
-import { ArrowUpRight, Check } from "lucide-react";
+import { IconList, type Tone } from "@atelic-action/ui/components";
+import { Check } from "lucide-react";
+import type { ReactNode } from "react";
+import { Topic, type WriteupTopic } from "./Writeup";
 
 /**
  * The read: what a customer gets at the end of an engagement's first week,
  * before anything changes. Where the writeup says what letter each section
  * earned, the read says why, and what changes. Its shape is the practice's
  * FOOTPRINT.md, under What the Owner Gets: a title and a dated lede; the gist
- * table (every section, its grade, and one line); then the tiers; then the
- * plan, in order; then one closing line and the sign off.
+ * table (every section, its grade, and one line), with a note under it for
+ * what the read leaves out; then the tiers; then the plan, in order; then one
+ * closing line and the sign off.
  *
- * Each section reads as an aggregator of the tools we looked through, top to
- * bottom: where we looked (the tools, linked, each with an optional line);
- * what it showed (a short paragraph or two, a compact table of facts, lists
- * of examples, and any proof pictures); why, in one sentence on a tinted
- * panel; today and after, a two column table of what a thing is and what it
- * becomes; and what we recommend, as a checklist. A beat with nothing in it
- * is left out, heading and all.
+ * A section is the writeup's section card, the same `Topic`, so the two
+ * documents read alike (Forni, 2026-10-16): the trade name linked to its
+ * definition, the one liner, the grade, and the why line, which here is the
+ * summary of what we saw in one or two sentences; then the writeup's blocks
+ * (findings with the owner's screens beside them, the basics, a table, a
+ * fold); then what is the read's own, today and after as a two column table
+ * and what we recommend as a checklist; and the tools we looked through at
+ * the foot, as the sources. A beat with nothing in it is left out.
  *
- * It is the writeup's sibling, not a variant: it wears the writeup's column,
- * head, grade chip and key, tier heading, section card, screen, and close
- * (the `.op` classes), and adds only what is its own (the `.rd` classes).
- * The gist table is drawn from the tiers, so a tier added later (Conversion,
- * once the analytics access lands) is one more entry in `tiers` and appears
- * in the table and the body alike, with no change to the props. Every prop
- * is plain data, so a routine can write a read as JSON; the one exception is
- * the sign off person's `role`, which takes a node and is equally happy with
- * a string.
+ * It wears the writeup's column, head, grade chip and key, tier heading,
+ * section card, and close (the `.op` classes), and adds only what is its own
+ * (the `.rd` classes). The gist table is drawn from the tiers, so a tier
+ * added later (Conversion, once the analytics access lands) is one more entry
+ * in `tiers` and appears in the table and the body alike; until then `note`
+ * says so under the table. Every prop but a finding's body and the sign off
+ * person's `role` is plain data, and both are equally happy with a string, so
+ * a routine can write a read as JSON.
  */
 
 /** A link inside running text: the words the reader clicks and where they go. */
@@ -48,65 +49,36 @@ export type ReadLink = ArtifactLink;
 /** A paragraph: a plain string, or runs of text and links in order. */
 export type ReadParagraph = ArtifactParagraph;
 
-/** A tool we looked through: its name, where it opens (in a new tab), and a line on what we read there. */
-export interface ReadTool {
-	label: string;
-	href?: string;
-	/** One short line, e.g. "Page indexing, the last 90 days". */
-	note?: string;
-}
-
-/** The 1.0.0 name for a tool; the same shape. */
-export type ReadSource = ReadTool;
-
-/** One row of a section's facts: a short label and its value, e.g. "Pages on Google" and "9 of 9". */
-export interface ReadFact {
-	label: string;
-	value: ReadParagraph;
-}
-
-/** A list of examples under its own short heading; each item a paragraph that can carry links. */
-export interface ReadExamples {
-	title?: string;
-	items: ReadParagraph[];
-}
-
 /** One row of today and after: what a thing is now, and what it becomes. */
 export interface ReadChange {
 	now: ReadParagraph;
 	after: ReadParagraph;
 }
 
-/** One section of a tier: a question, read top to bottom in five beats. */
-export interface ReadSection {
-	/** The anchor the gist table links to, e.g. "technical-seo". */
-	id: string;
-	/** The section's trade name, e.g. "Technical SEO": the gist table's Section column, and the line over the question. */
-	name: string;
-	/** The question the section answers, in the owner's words, e.g. "Can Google read the site?". The section's heading. */
-	question: string;
-	/** The baseline's grade. Omit for a section not yet graded; the table shows a quiet dash. */
-	grade?: WriteupGrade;
+/**
+ * One section of a tier: the writeup's section card (its `title`, `href`,
+ * `oneLiner`, `grade`, `why`, `blocks`, and `sources`), plus the read's own:
+ * the gist table's line, today and after, and what we recommend.
+ */
+export interface ReadSection extends Omit<WriteupTopic, "kind" | "why"> {
 	/** The one line in the gist table. */
 	gist: ReadParagraph;
-	/** Where we looked: the tools the readings came from, linked, at the top of the section. */
-	tools?: ReadTool[];
-	/** The 1.0.0 name for `tools`, still read and rendered in the same place; `tools` wins when both are set. */
-	sources?: ReadTool[];
-	/** What it showed: one or two short paragraphs. */
-	found: ReadParagraph[];
-	/** What it showed, as a compact two column table of facts under the paragraphs. */
-	facts?: ReadFact[];
-	/** What it showed, as lists of examples, each under its own short heading. */
-	examples?: ReadExamples[];
-	/** Proof pictures, each over its caption, e.g. a search result capture per market. */
-	shots?: WriteupShot[];
-	/** Why, in one sentence, set apart. */
-	why: ReadParagraph;
-	/** Today and after: what each thing is, and what it becomes. */
+	/** The summary of what we saw, in one or two sentences: the why line. A paragraph, so a read written as JSON can carry links in it. */
+	why?: ReactNode | ReadParagraph;
+	/** Today and after: what each thing is, and what it becomes. Set after the blocks. */
 	changes?: ReadChange[];
-	/** What we recommend, as a checklist. */
-	recommend?: ReadParagraph[];
+	/** The recommendations, after today and after: a paragraph each, or one with its own icon and tone. */
+	recommend?: (ReadParagraph | ReadRecommendation)[];
+}
+
+/** One recommendation with a bullet of its own: the icon it leads with, and the tone it reads in. Both fall back to the list's. */
+export interface ReadRecommendation {
+	/** The recommendation: a paragraph, or a node when it carries a table or a list. */
+	body: ReactNode | ReadParagraph;
+	/** The icon as the bullet, e.g. a lucide icon at size 16; the accent's check when left out. */
+	icon?: ReactNode;
+	/** How the item reads; the accent when left out. */
+	tone?: Tone;
 }
 
 /** A tier, e.g. Health: its heading, the question it answers, and its sections in order. */
@@ -115,7 +87,7 @@ export interface ReadTier {
 	id?: string;
 	/** The tier's name, e.g. "Health". */
 	title: string;
-	/** The question the tier answers, in the owner's words. */
+	/** The questions the tier answers, in the owner's words. */
 	lead?: string;
 	sections: ReadSection[];
 }
@@ -159,18 +131,16 @@ export interface ReadLabels {
 	gist: string;
 	/** What a screen reader hears for a section with no grade. */
 	notGraded: string;
-	/** The beat at the top of a section: the tools we looked through. */
-	tools: string;
-	/** The beat that says what the tools showed. */
-	found: string;
-	/** The one sentence beat. */
-	why: string;
 	/** The today and after table's first column. */
 	now: string;
 	/** The today and after table's second column. */
 	after: string;
 	/** The checklist beat at the foot of a section. */
 	recommend: string;
+	/** The word before the grade on a section's why line. */
+	why: string;
+	/** The label over a section's tools when it names none. */
+	sources: string;
 	/** The plan's heading when it names none. */
 	plan: string;
 }
@@ -181,12 +151,11 @@ export const readLabels: ReadLabels = {
 	grade: "Grade",
 	gist: "The Gist",
 	notGraded: "Not graded yet",
-	tools: "Where We Looked",
-	found: "What It Showed",
-	why: "Why",
 	now: "Today",
 	after: "After",
-	recommend: "What We Recommend",
+	recommend: "Recommendations",
+	why: "Why",
+	sources: "See it yourself",
 	plan: "The Plan",
 };
 
@@ -200,6 +169,8 @@ export interface ReadProps {
 	lede: ReadParagraph;
 	/** The heading over the gist table, e.g. "At a Glance". */
 	gistTitle?: string;
+	/** A callout under the gist table, e.g. what the read leaves out and when it follows. */
+	note?: ReadParagraph;
 	/** The key: what each letter means, in a few words each. */
 	gradeKey?: Array<{ grade: WriteupGrade; label: string }>;
 	/** The tiers in order. Each section appears in the gist table and in the body. */
@@ -214,51 +185,29 @@ function filled(paragraph: ReadParagraph | undefined | null): paragraph is ReadP
 	return paragraph !== undefined && paragraph !== null && !isEmpty(paragraph);
 }
 
-function Tools({ tools, label }: { tools: ReadTool[]; label: string }) {
+/** A string or runs of text and links, the shape JSON content arrives in; a node of elements is anything else. */
+function isRuns(value: unknown): value is ReadParagraph {
+	if (typeof value === "string") return true;
 	return (
-		<div className="rd-beat rd-tools">
-			<h4>{label}</h4>
-			<ul className="rd-tools-list">
-				{tools.map((tool, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: tools are static content in a fixed order, and a label may repeat
-					<li key={i}>
-						{tool.href ? (
-							<a href={tool.href} {...newTabProps(tool.href, true)}>
-								{tool.label}
-								<ArrowUpRight size={13} aria-hidden="true" />
-							</a>
-						) : (
-							<span className="rd-tool-name">{tool.label}</span>
-						)}
-						{tool.note && <span className="rd-tool-note">{tool.note}</span>}
-					</li>
-				))}
-			</ul>
-		</div>
+		Array.isArray(value) &&
+		value.every(
+			(run) =>
+				typeof run === "string" ||
+				(typeof run === "object" && run !== null && "text" in run && "href" in run),
+		)
 	);
 }
 
-function Facts({ facts }: { facts: ReadFact[] }) {
-	return (
-		<table className="rd-facts">
-			<tbody>
-				{facts.map((fact, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: facts are static content in a fixed order
-					<tr key={i}>
-						<th scope="row">{fact.label}</th>
-						<td>
-							<Runs paragraph={fact.value} />
-						</td>
-					</tr>
-				))}
-			</tbody>
-		</table>
-	);
+/** Content as a node: runs are rendered, a blank is dropped, and a node passes through. */
+function asNode(value: ReactNode | ReadParagraph | undefined | null): ReactNode {
+	if (value === undefined || value === null) return undefined;
+	if (isRuns(value)) return filled(value) ? <Runs paragraph={value} /> : undefined;
+	return value;
 }
 
 function Changes({ changes, labels }: { changes: ReadChange[]; labels: ReadLabels }) {
 	return (
-		<div className="rd-beat rd-changes">
+		<div className="op-block rd-beat rd-changes">
 			<table className="rd-changes-table">
 				<thead>
 					<tr>
@@ -288,21 +237,24 @@ function Changes({ changes, labels }: { changes: ReadChange[]; labels: ReadLabel
 	);
 }
 
-function Recommend({ items, label }: { items: ReadParagraph[]; label: string }) {
+/** A recommendation as its full shape, whichever way the content wrote it. */
+function asRecommendation(item: ReadParagraph | ReadRecommendation): ReadRecommendation {
+	return isRuns(item) ? { body: item } : item;
+}
+
+function Recommend({ items, label }: { items: ReadRecommendation[]; label: string }) {
 	return (
-		<div className="rd-beat rd-recommend">
+		<div className="op-block rd-beat rd-recommend">
 			<h4>{label}</h4>
-			<ul className="rd-checks">
-				{items.map((item, i) => (
-					// biome-ignore lint/suspicious/noArrayIndexKey: recommendations are static content in a fixed order
-					<li key={i}>
-						<Check size={16} strokeWidth={2.5} aria-hidden="true" />
-						<span>
-							<Runs paragraph={item} />
-						</span>
-					</li>
-				))}
-			</ul>
+			<IconList
+				className="rd-checks"
+				icon={<Check size={16} strokeWidth={2.5} />}
+				items={items.map((item) => ({
+					icon: item.icon,
+					tone: item.tone,
+					body: asNode(item.body),
+				}))}
+			/>
 		</div>
 	);
 }
@@ -361,7 +313,7 @@ function Gist({
 							{tier.sections.map((section) => (
 								<tr key={section.id}>
 									<th scope="row" className="rd-gist-section">
-										<a href={`#${section.id}`}>{section.name}</a>
+										<a href={`#${section.id}`}>{section.title}</a>
 									</th>
 									<td className="rd-gist-grade">
 										{section.grade ? (
@@ -391,77 +343,45 @@ function Gist({
 	);
 }
 
+/** A section: the writeup's card, with today and after and the checklist handed in after its blocks. */
 function Section({ section, labels }: { section: ReadSection; labels: ReadLabels }) {
-	const tools = (section.tools ?? section.sources ?? []).filter((tool) => tool?.label?.trim());
-	const found = (section.found ?? []).filter(filled);
-	const facts = (section.facts ?? []).filter((fact) => filled(fact?.value));
-	const examples = (section.examples ?? [])
-		.map((list) => ({ title: list?.title, items: (list?.items ?? []).filter(filled) }))
-		.filter((list) => list.items.length > 0);
-	const shots = section.shots ?? [];
 	const changes = (section.changes ?? []).filter(
 		(change) => filled(change?.now) || filled(change?.after),
 	);
-	const recommend = (section.recommend ?? []).filter(filled);
-	const showed = found.length + facts.length + examples.length + shots.length > 0;
-	return (
-		<section className="op-topic rd-section" id={section.id}>
-			<header className="op-topic-head">
-				<div>
-					<p className="rd-name">{section.name}</p>
-					<h3>{section.question}</h3>
-				</div>
-				{section.grade && (
-					<>
-						<span className="op-sr-only">{`${labels.grade} ${gradeLabel[section.grade]}`}</span>
-						<span className="rd-grade" aria-hidden="true">
-							<GradeChip grade={section.grade} />
-						</span>
-					</>
-				)}
-			</header>
-			{tools.length > 0 && <Tools tools={tools} label={labels.tools} />}
-			{showed && (
-				<div className="rd-beat rd-found">
-					<h4>{labels.found}</h4>
-					{found.map((paragraph, i) => (
-						// biome-ignore lint/suspicious/noArrayIndexKey: paragraphs are static content in a fixed order
-						<Paragraph paragraph={paragraph} key={i} />
-					))}
-					{facts.length > 0 && <Facts facts={facts} />}
-					{examples.map((list, i) => (
-						// biome-ignore lint/suspicious/noArrayIndexKey: lists are static content in a fixed order, and a title may repeat
-						<div className="rd-examples-block" key={i}>
-							{list.title && <h5>{list.title}</h5>}
-							<ul className="rd-examples">
-								{list.items.map((example, j) => (
-									// biome-ignore lint/suspicious/noArrayIndexKey: examples are static content in a fixed order
-									<li key={j}>
-										<Runs paragraph={example} />
-									</li>
-								))}
-							</ul>
-						</div>
-					))}
-					{shots.length > 0 && (
-						<div className="rd-shots" data-count={Math.min(shots.length, 3)}>
-							{shots.map((shot) => (
-								<Shot shot={shot} key={shot.src} />
-							))}
-						</div>
-					)}
-				</div>
-			)}
-			{filled(section.why) && (
-				<div className="rd-beat rd-why">
-					<h4>{labels.why}</h4>
-					<Paragraph paragraph={section.why} />
-				</div>
-			)}
-			{changes.length > 0 && <Changes changes={changes} labels={labels} />}
-			{recommend.length > 0 && <Recommend items={recommend} label={labels.recommend} />}
-		</section>
+	const recommend = (section.recommend ?? [])
+		.filter((item) => item !== undefined && item !== null)
+		.map(asRecommendation)
+		.filter((item) => (isRuns(item.body) ? filled(item.body) : item.body != null));
+	const blocks = (section.blocks ?? []).map((block) =>
+		block.kind === "findings"
+			? {
+					...block,
+					items: block.items
+						.filter((item) => item?.lead?.trim())
+						.map((item) => ({ ...item, body: asNode(item.body) })),
+				}
+			: block,
 	);
+	const sources = (section.sources ?? []).filter((source) => source?.label?.trim());
+	const topic: WriteupTopic = {
+		kind: "topic",
+		...section,
+		why: asNode(section.why),
+		whyLabel: section.whyLabel ?? labels.why,
+		gradeWord: section.gradeWord ?? labels.grade,
+		blocks,
+		sources,
+		sourcesLabel: section.sourcesLabel ?? labels.sources,
+		noShot: section.noShot ?? true,
+	};
+	const extra =
+		changes.length + recommend.length > 0 ? (
+			<>
+				{changes.length > 0 && <Changes changes={changes} labels={labels} />}
+				{recommend.length > 0 && <Recommend items={recommend} label={labels.recommend} />}
+			</>
+		) : undefined;
+	return <Topic topic={topic} extra={extra} />;
 }
 
 function Plan({ plan, labels }: { plan: ReadPlan; labels: ReadLabels }) {
@@ -500,6 +420,7 @@ export function Read({
 	date,
 	lede,
 	gistTitle,
+	note,
 	gradeKey,
 	tiers,
 	plan,
@@ -523,7 +444,14 @@ export function Read({
 					{filled(lede) && <Paragraph paragraph={lede} className="op-intro rd-lede" />}
 				</header>
 				{shownTiers.length > 0 && (
-					<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
+					<>
+						<Gist tiers={shownTiers} title={gistTitle} gradeKey={gradeKey} labels={labels} />
+						{filled(note) && (
+							<div className="rd-note" role="note">
+								<Paragraph paragraph={note} />
+							</div>
+						)}
+					</>
 				)}
 				{shownTiers.map((tier) => (
 					<div className="rd-tier" key={tier.title}>

package/src/documents/Writeup.tsx

@@ -1,7 +1,9 @@
 import {
+	type ArtifactParagraph,
 	GradeChip,
 	gradeLabel,
 	newTabProps,
+	Runs,
 	Shot,
 	SignOff,
 	type WriteupGrade,
@@ -52,8 +54,8 @@ export type WriteupTone = Tone;
 export interface WriteupBullet {
 	/** The point, in a full sentence. The icon sits beside it. */
 	lead: string;
-	/** The one explainer that says why it matters. */
-	body?: ReactNode;
+	/** The one explainer that says why it matters: a node, or a paragraph of runs when the content arrives as JSON. */
+	body?: ReactNode | ArtifactParagraph;
 	/** A win the owner already has: marked good. Everything else reads as needing work. */
 	win?: boolean;
 	/** Overrides the tone, e.g. "info" for something not yet read. */
@@ -113,6 +115,8 @@ export interface WriteupTable extends BlockBase {
 		sortable?: boolean;
 		/** The direction a first click sorts in. */
 		firstSort?: "asc" | "desc";
+		/** The column hugs its content, for a swatch or a mark. */
+		fit?: boolean;
 	}>;
 	rows: Array<{ cells: WriteupCell[]; tone?: WriteupTone }>;
 	/** The sort the table opens in. */
@@ -199,8 +203,12 @@ export interface WriteupTopic {
 	oneLiner: string;
 	/** The section's grade, beside the heading. */
 	grade?: WriteupGrade;
-	/** Why it earned that letter: the rule it met, in a sentence. */
+	/** Why it earned that letter: the rule it met, in a sentence. The read sets its summary here. */
 	why?: ReactNode;
+	/** The word before the grade on the why line; defaults to "Why". */
+	whyLabel?: string;
+	/** What a screen reader hears before the grade's letter; defaults to "Grade". */
+	gradeWord?: string;
 	/** The section's blocks, in order. */
 	blocks?: WriteupTopicBlock[];
 	/** Findings without blocks: rendered as one findings block with the shots beside it. */
@@ -388,21 +396,43 @@ function Table({ block }: { block: WriteupTable }) {
 	);
 }
 
+/** A string or runs of text and links, the shape JSON content arrives in; a node of elements is anything else. */
+function isRuns(value: unknown): value is ArtifactParagraph {
+	if (typeof value === "string") return true;
+	return (
+		Array.isArray(value) &&
+		value.every(
+			(run) =>
+				typeof run === "string" ||
+				(typeof run === "object" && run !== null && "text" in run && "href" in run),
+		)
+	);
+}
+
+/** A finding's body as a node, whichever way the content wrote it. */
+function bodyNode(body: ReactNode | ArtifactParagraph | undefined): ReactNode {
+	if (body === undefined || body === null) return undefined;
+	return isRuns(body) ? <Runs paragraph={body} /> : body;
+}
+
 function Findings({ block, brief }: { block: WriteupFindings; brief?: string }) {
 	const hasShots = Boolean(block.shot || brief);
 	return (
 		<div className={`op-block op-findings${hasShots ? " has-shots" : ""}`}>
 			<div className="op-findings-list">
-				{block.items.map((item) => (
-					<Callout
-						key={item.lead}
-						tone={item.tone ?? (item.win ? "good" : "warn")}
-						title={item.lead}
-						variant={item.box ? "box" : "plain"}
-					>
-						{item.body}
-					</Callout>
-				))}
+				{block.items.map((item, i) => {
+					const shape = {
+						tone: item.tone ?? (item.win ? "good" : "warn"),
+						title: item.lead,
+						variant: item.box ? ("box" as const) : ("plain" as const),
+					};
+					return (
+						// biome-ignore lint/suspicious/noArrayIndexKey: findings are static content in a fixed order, and a lead may repeat
+						<Callout key={i} {...shape}>
+							{bodyNode(item.body)}
+						</Callout>
+					);
+				})}
 			</div>
 			{hasShots && (
 				<div className="op-shots">
@@ -495,7 +525,14 @@ function TopicBlock({ block }: { block: WriteupTopicBlock }) {
 	}
 }
 
-function Topic({ topic }: { topic: WriteupTopic }) {
+/**
+ * The section card: the trade name linked to its definition, the one liner,
+ * the why line, the grade, the blocks, and the sources at the foot. The read
+ * renders its sections through it too, handing anything of its own (today and
+ * after, what we recommend) as `extra`, set after the blocks and before the
+ * sources, so the two documents share one layout.
+ */
+export function Topic({ topic, extra }: { topic: WriteupTopic; extra?: ReactNode }) {
 	const legacy: WriteupFindings | null = topic.bullets
 		? { kind: "findings", items: topic.bullets, shot: topic.shot, shot2: topic.shot2 }
 		: null;
@@ -519,13 +556,25 @@ function Topic({ topic }: { topic: WriteupTopic }) {
 						)}
 					</h3>
 					<p className="op-def">{topic.oneLiner}</p>
-					{topic.grade && topic.why && (
+					{topic.why && (
 						<p className="op-why">
-							<b>{`Why ${gradeLabel[topic.grade]}:`}</b> {topic.why}
+							<b>
+								{topic.grade
+									? `${topic.whyLabel ?? "Why"} ${gradeLabel[topic.grade]}:`
+									: `${topic.whyLabel ?? "Why"}:`}
+							</b>{" "}
+							{topic.why}
 						</p>
 					)}
 				</div>
-				{topic.grade && <GradeChip grade={topic.grade} />}
+				{topic.grade && (
+					<>
+						<span className="op-sr-only">{`${topic.gradeWord ?? "Grade"} ${gradeLabel[topic.grade]}`}</span>
+						<span aria-hidden="true">
+							<GradeChip grade={topic.grade} />
+						</span>
+					</>
+				)}
 			</header>
 			<div className="op-blocks">
 				{topic.blocks?.map((block, i) => (
@@ -533,13 +582,15 @@ function Topic({ topic }: { topic: WriteupTopic }) {
 					<TopicBlock block={block} key={i} />
 				))}
 				{legacy && <Findings block={legacy} brief={brief} />}
+				{extra}
 			</div>
 			{topic.sources && topic.sources.length > 0 && (
 				<footer className="op-sources">
 					<span className="op-sources-label">{topic.sourcesLabel ?? "Sources"}</span>
 					<ul>
-						{topic.sources.map((source) => (
-							<li key={source.label}>
+						{topic.sources.map((source, i) => (
+							// biome-ignore lint/suspicious/noArrayIndexKey: sources are static content in a fixed order, and a label may repeat
+							<li key={i}>
 								{source.href ? (
 									<a href={source.href} {...newTabProps(source.href, true)}>
 										{source.label}

package/src/documents/documents.css

@@ -1126,7 +1126,7 @@
 		font-weight: 650;
 		color: var(--op-ink);
 	}
-	.atelic-ui .op-topic-head > .op-grade {
+	.atelic-ui .op-topic-head .op-grade {
 		width: 42px;
 		height: 42px;
 		border-radius: 12px;
@@ -1582,7 +1582,7 @@
 		.atelic-ui .op-topic h3 {
 			font-size: 23px;
 		}
-		.atelic-ui .op-topic-head > .op-grade {
+		.atelic-ui .op-topic-head .op-grade {
 			width: 46px;
 			height: 46px;
 			border-radius: 13px;
@@ -2160,17 +2160,22 @@
 	   column, the head, the grade chip and its key, the tier heading, the
 	   section card, the screen, the close, and every print rule of the
 	   writeup's are its own already. This block adds only what the read has
-	   and the writeup does not: the gist table, the beats of a section (the
-	   tools we looked through, what they showed with its facts and
-	   examples, why, today and after, and what we recommend), the proof
-	   pictures in a row, and the numbered plan. It sets no @page; the writeup's, earlier in this sheet and the
+	   and the writeup does not: the gist table and the note under it, the
+	   two beats a section adds to the writeup's card (today and after, and
+	   what we recommend), and the numbered plan. It sets no @page; the writeup's, earlier in this sheet and the
 	   later of the two there, sets letter paper for every artifact page.
 
 	   Tokens only (theme.css).
 	   ================================================================= */
 
+	/* The lede runs the full width of the page; the writeup's intro is the one that is capped. */
+	.atelic-ui .rd-lede {
+		max-width: none;
+	}
 	/* Prose links read as links here, where the writeup's are quiet. */
 	.atelic-ui .rd-lede a,
+	.atelic-ui .rd-note a,
+	.atelic-ui .rd-doc .op-why a,
 	.atelic-ui .rd-beat a,
 	.atelic-ui .rd-gist-read a,
 	.atelic-ui .rd-plan a,
@@ -2249,22 +2254,6 @@
 		text-wrap: pretty;
 		min-width: 0;
 	}
-
-	/* ---- a section: the trade name over the question, then its beats ---- */
-	.atelic-ui .rd-name {
-		margin: 0 0 4px;
-		font-family: var(--font-mono);
-		font-size: 11.5px;
-		letter-spacing: 0.1em;
-		text-transform: uppercase;
-		color: var(--op-ink-faint);
-	}
-	.atelic-ui .rd-grade .op-grade {
-		width: 42px;
-		height: 42px;
-		border-radius: 12px;
-		font-size: 21px;
-	}
 	.atelic-ui .rd-beat {
 		margin-top: 20px;
 		min-width: 0;
@@ -2286,127 +2275,19 @@
 	.atelic-ui .rd-beat p:last-child {
 		margin-bottom: 0;
 	}
-	/* Where we looked: the tools in a row at the top of the section, each a
-	   link with its line under it. */
-	.atelic-ui .rd-tools-list {
-		list-style: none;
-		margin: 0;
-		padding: 0;
-		display: flex;
-		flex-wrap: wrap;
-		gap: 10px 28px;
-	}
-	.atelic-ui .rd-tools-list li {
-		display: flex;
-		flex-direction: column;
-		gap: 1px;
-		min-width: 0;
-		max-width: 100%;
-	}
-	.atelic-ui .rd-tools-list a,
-	.atelic-ui .rd-tool-name {
-		display: inline-flex;
-		align-items: center;
-		gap: 3px;
-		font-size: 15px;
-		font-weight: 600;
-		color: var(--op-accent);
-		text-decoration: none;
-	}
-	.atelic-ui .rd-tool-name {
-		color: var(--op-ink);
-	}
-	.atelic-ui .rd-tools-list a:hover {
-		text-decoration: underline;
-		text-underline-offset: 2px;
-	}
-	.atelic-ui .rd-tools-list svg {
-		flex: none;
-	}
-	.atelic-ui .rd-tool-note {
-		font-size: 13px;
-		line-height: 1.35;
-		color: var(--op-ink-faint);
-	}
-
-	/* What it showed: the facts as a compact table of label and value, in
-	   the writeup's table dress (an ink rule over thin row rules). */
-	.atelic-ui .rd-facts {
-		width: 100%;
-		max-width: 620px;
-		margin: 12px 0 0;
-		border-collapse: collapse;
-		border-top: 1.5px solid var(--op-ink);
-		font-size: 15px;
-		line-height: 1.4;
-	}
-	.atelic-ui .rd-facts th,
-	.atelic-ui .rd-facts td {
-		padding: 7px 14px 7px 0;
-		border-bottom: 1px solid var(--neutral-100);
-		text-align: left;
-		vertical-align: top;
-	}
-	.atelic-ui .rd-facts th {
-		width: 55%;
-		font-weight: 400;
-		color: var(--op-ink-soft);
-	}
-	.atelic-ui .rd-facts td {
-		padding-right: 0;
-		font-weight: 600;
-		color: var(--op-ink);
-		font-variant-numeric: tabular-nums;
-	}
-	.atelic-ui .rd-facts tr:last-child > * {
-		border-bottom: 0;
-	}
-
-	/* The examples: a list or more, each under its own short heading. */
-	.atelic-ui .rd-examples-block {
-		margin-top: 14px;
-		max-width: 68ch;
-	}
-	.atelic-ui .rd-examples-block h5 {
-		margin: 0 0 4px;
-		font-size: 15px;
-		font-weight: 650;
-		color: var(--op-ink);
-	}
-	.atelic-ui .rd-examples {
-		list-style: disc;
-		margin: 0;
-		padding-left: 1.2em;
-		color: var(--op-ink-soft);
-		text-wrap: pretty;
-	}
-	.atelic-ui .rd-examples li + li {
-		margin-top: 4px;
-	}
-	/* Why is one sentence, set apart: a tinted panel with the accent's rule. */
-	.atelic-ui .rd-why {
+	/* The note under the gist table: what the read leaves out, on a tinted panel with the accent's rule. */
+	.atelic-ui .rd-note {
+		margin-top: 18px;
 		padding: 12px 14px;
 		border-left: 3px solid var(--op-accent);
 		border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
 		background: var(--surface-alt);
 	}
-	.atelic-ui .rd-why p {
-		font-size: 16.5px;
-		font-weight: 550;
-		line-height: 1.45;
+	.atelic-ui .rd-note p {
+		font-size: 15.5px;
+		line-height: 1.5;
 		color: var(--op-ink);
-	}
-	/* The proof pictures sit in a row at one size, a search capture per
-	   market; a phone stacks them. */
-	.atelic-ui .rd-shots {
-		display: grid;
-		grid-template-columns: minmax(0, 1fr);
-		gap: 14px;
-		margin-top: 14px;
-	}
-	/* A lone picture keeps a screen's size rather than filling the card. */
-	.atelic-ui .rd-shots[data-count="1"] {
-		max-width: 380px;
+		text-wrap: pretty;
 	}
 
 	/* Today and after: what a thing is, and what it becomes. Two columns
@@ -2469,26 +2350,43 @@
 		color: var(--op-accent);
 	}
 
-	/* What we recommend: a checklist, each item led by the accent's check. */
-	.atelic-ui .rd-checks {
-		list-style: none;
-		margin: 0;
-		padding: 0;
-		display: grid;
-		gap: 8px;
-		max-width: 68ch;
+	/* The recommendations: ui's icon list across the card's width, each bullet the accent's check unless the item brings its own icon or tone. */
+	.atelic-ui .rd-recommend .rd-checks {
+		--tone: var(--op-accent);
 	}
-	.atelic-ui .rd-checks li {
-		display: grid;
-		grid-template-columns: auto minmax(0, 1fr);
-		column-gap: 10px;
-		align-items: start;
-		line-height: 1.45;
-		text-wrap: pretty;
+	/* A list or a table inside a finding: a little air above it. */
+	.atelic-ui .op-findings .callout-body .icon-list {
+		margin-top: 6px;
 	}
-	.atelic-ui .rd-checks svg {
-		margin-top: 0.2em;
-		color: var(--op-accent);
+	.atelic-ui .op-findings .callout-body .data-table,
+	.atelic-ui .rd-checks .data-table {
+		margin-top: 12px;
+	}
+	/* In the read, three pictures fill the card's width. */
+	.atelic-ui .rd-doc .op-shots-row[data-count="3"] {
+		max-width: none;
+	}
+	/* Content patterns for a table inside a read, written by the content with ui's swatch: a rank with its badge in one cell, two equal halves, the swatch on the left and the figure on the right. These are the read's patterns, not a piece, until a consumer beyond the first wants them, when they move to ui. */
+	.atelic-ui .rd-ranked {
+		display: inline-grid;
+		grid-template-columns: 1fr 1fr;
+		column-gap: 8px;
+		align-items: center;
+		min-width: 3.4em;
+	}
+	.atelic-ui .rd-ranked .chart-swatch {
+		justify-self: start;
+	}
+	.atelic-ui .rd-ranked > a,
+	.atelic-ui .rd-ranked > span:last-child {
+		justify-self: end;
+		font-variant-numeric: tabular-nums;
+	}
+	/* A swatch as a table cell: the chart key's box, keying the row in its tone, in a column marked fit. */
+	.atelic-ui .op-table .chart-swatch,
+	.atelic-ui .op-findings .callout-body .chart-swatch {
+		display: inline-block;
+		vertical-align: middle;
 	}
 
 	/* ---- the plan: the steps in order, numbered ---- */
@@ -2583,9 +2481,6 @@
 			padding-left: 20px;
 			padding-right: 16px;
 		}
-		.atelic-ui .rd-facts th {
-			width: 45%;
-		}
 		.atelic-ui .rd-changes-table {
 			display: table;
 			table-layout: fixed;
@@ -2646,12 +2541,6 @@
 		.atelic-ui .rd-changes-table tbody tr:last-child td {
 			border-bottom: 0;
 		}
-		.atelic-ui .rd-shots[data-count="2"] {
-			grid-template-columns: repeat(2, minmax(0, 1fr));
-		}
-		.atelic-ui .rd-shots[data-count="3"] {
-			grid-template-columns: repeat(3, minmax(0, 1fr));
-		}
 	}
 
 	/* ---- print: the writeup's rules carry the page; these hold the read's
@@ -2664,18 +2553,14 @@
 		}
 		.atelic-ui .rd-gist-table tr,
 		.atelic-ui .rd-changes-table tr,
-		.atelic-ui .rd-facts,
-		.atelic-ui .rd-tools,
 		.atelic-ui .rd-checks li,
 		.atelic-ui .rd-closing,
-		.atelic-ui .rd-why,
+		.atelic-ui .rd-note,
 		.atelic-ui .rd-step,
-		.atelic-ui .rd-close,
-		.atelic-ui .rd-shots .op-shot {
+		.atelic-ui .rd-close {
 			break-inside: avoid;
 		}
 		.atelic-ui .rd-beat h4,
-		.atelic-ui .rd-examples-block h5,
 		.atelic-ui .rd-plan h2 {
 			break-after: avoid;
 		}