Communicate at a Glance

The picture is the argument. Every Verdigris artifact, a page, a visualization, a diagram, a plan, a slide, makes a claim about the customer’s world that lands at a glance. The artifact never narrates itself, never explains how to read it, and never hedges with disclaimers. Restraint is the achievement, not the risk.

This is the parent principle for figure-caption.md and ../visualizations/interactive-viz.md. It governs any surface where a visual or structural artifact carries a claim.

Why this page exists

Verdigris artifacts drifted into “meta” language: they narrated the diagram, the strategy, or the plan instead of making a claim about the operator’s world. They over-explained with “how to read this” sub-captions, interaction narration, and “illustrative” disclaimers. The root cause was the canon itself, which mandated that “the caption is the argument” and prescribed a “how to read this” sub-caption as the fix for an unclear visual. That made prose the place the argument finally happened, so the picture stopped having to argue.

The new bar matches the product visuals shipped by Stripe, Linear, Vercel, Cloudflare, and Datadog, which carry a roughly 4-word claim heading and zero visible captions, and matches Mark Chung’s instrument-grade artifacts, where the trace and the number do the work. Those are reference exemplars, not the authority. The authority is the principle below.

The squint test (3 seconds)

Squint at the artifact, or look at it for three seconds, with the words covered. The claim it makes about the customer’s world should be legible from the form alone: the shape, the comparison, the one number, the marked anomaly. If you have to read a caption, a legend in prose, or a “how to read this” line to know what the artifact claims, the artifact has failed the squint test and the form is what needs fixing.

Companion check for captioned figures: the cover-the-caption test in interactive-viz.md. Mask the caption; if the picture stops arguing, fix the picture, not the caption.

The meta-language ban

Meta-language is any copy whose subject is the artifact, the interaction, or the strategy instead of the customer’s world. It is banned on every surface. Four families:

1. Artifact narration. Copy that describes the thing the reader is already looking at. “This chart shows…”, “The diagram below illustrates…”, “This framework maps…”, “The plan outlines…”. The reader can see the chart. Say what it proves about their world, or say nothing.
2. Interaction narration. “Drag to compare”, “toggle to switch views”, “click to expand”, “hover to inspect”, “scroll to reveal”. An affordance is shown, not narrated: a slider that looks draggable, a control that looks pressable. (The one exception is the pulsing first-use affordance prompt on an interactive viz, which signals that a control is interactive, not how to interpret its output. See interactive-viz.md > Interaction affordance.)
3. Disclaimers. “Illustrative”, “example”, “representative”, “for illustration only”, “notional”, “sample data”. If the data is synthetic, encode that honestly in the artifact’s design and in alt text or a footnote, never as a hedge stapled to the claim. A disclaimer in the claim slot tells the reader the artifact is not to be trusted.
4. Strategy / framework / metaphor self-naming as a label. Naming the artifact’s own device as if the name were the point: “Our flywheel”, “The X framework”, “The three-horizon model”, “the validation layer (our metaphor)”. Name the customer’s outcome, not your construct. The construct can carry the argument internally; it does not get to be the visible label.

The subject test

The subject of every line is the customer’s world, never the artifact, the strategy, or the plan. Read each visible line and ask: what is the grammatical subject? If it is “this chart”, “the diagram”, “our framework”, “the slide”, “the plan”, or “the strategy”, rewrite it so the subject is the operator, the equipment, the risk, the number, or the outcome.

Word budgets

Restraint is enforced with budgets, not vibes:

The antithesis caption ([X does A]. [Verdigris does B]) is the one place a caption may run slightly longer, because the contrast itself is the claim. See figure-caption.md rule 4.

Restraint is the achievement, not the risk

The instinct under review pressure is to add: a caption to be safe, a “how to read this” to be helpful, a disclaimer to be honest. Each addition is a small admission that the artifact does not stand on its own. The discipline is to make the artifact stand on its own and then remove the scaffolding. A signature visual with one number and no caption is not under-built; it is finished. When in doubt, cut the meta-language and fix the picture.

Enforcement

See rules/visual-rules.yml > composition.communicate-at-a-glance for the machine-enforceable rules: the banned-meta-phrase pattern check and the caption word-budget constraint.

Sources

1. Reference exemplars (not authority): Stripe, Linear, Vercel, Cloudflare, Datadog. Product marketing surfaces that ship visuals with a roughly 4-word claim heading and zero visible captions. Direct observation of their product and platform pages as of 2026.
2. Mark Chung’s instrument-grade artifacts. The house reference for “the trace and the number argue; the caption claims or disappears.”
3. categories/composition/figure-caption.md and categories/visualizations/interactive-viz.md — the surface-specific rules this principle governs.

See also

• categories/composition/figure-caption.md — caption = <=7-word claim about the customer’s world
• categories/visualizations/interactive-viz.md — the picture is the argument; the cover-the-caption test
• categories/composition/atom-id-exposure.md — internal IDs never render
• rules/visual-rules.yml > composition.communicate-at-a-glance — machine-enforceable rules