ADR-081: A default example width on conventions.figma

[nathanacurtis]

Adds conventions.figma.defaultExampleWidth — an optional positive number stating the pixel width a library's components and examples are authored at, and the width consumers render them at by default.

Why

Anything that renders a spec has to pick a width first — a Figma frame written back from a spec, a generated story canvas, a screenshot harness. Nothing in the spec says which, so each consumer invents one. For a library authored at a mobile width the results diverge from the design: a fill-width root stretches across a desktop canvas, and text that wraps to two lines renders on one.

That width is not a per-run preference. It is a fact about how the library was authored — the same number for every consumer, where a different value produces output that misrepresents the design rather than merely styling it differently. That is the test ADR-071 used to separate Conventions from Settings, so it lands on Conventions.figma.

What changed

packages/schema

• Conventions.figma.defaultExampleWidth?: number and its ResolvedConventions counterpart
• conventions.schema.json — defaultExampleWidth with exclusiveMinimum: 0
• Optional, and deliberately not in DEFAULT_CONVENTIONS — there is no universal width, and absence is the statement that a library declares none
• Type tests covering the optional authored shape, the resolved shape, a rejected string width, and the absent default

packages/cli

• ConfigLoader resolves the key, dropping anything that is not a finite positive number
• The config/conventions.yaml init template carries it commented out with 375 as the sample
• Loader and template tests

site

• New settings/default-example-width page, sidebar entry, and a row in the schema/conventions table

Semver

0.31.0 — MINOR. One optional field on an existing interface, one optional property on an existing schema object. Every document valid before remains valid.

Downstream

Documented in the ADR, not done here: specs-from-figma, figma-from-specs and specs-plugin-2 should use the declared width as the default frame width when rendering, and keep their current hardcoded value only as the absent-case fallback.

Notes

• The ADR is DRAFT; run /specs.adr.accept after review.
• adr/INDEX.md claims 081 on this branch only. The cherry-pick onto main and the release branch is not done — it needs a push to main.
• 54 tests in packages/cli/tests fail in a clean worktree (DEFAULT_SETTINGS resolves to undefined through the workspace link). Identical count before and after this change — pre-existing, untouched here.

🤖 Generated with Claude Code

[nathanacurtis]

Closing unmerged. This belongs on adr/primitive-composition (PR #363), where ADR-073 makes Conventions a platform-keyed map and ADR-078 gives each platform its own file in config/conventions/. A default example width is a per-platform fact, not a Figma-only one — Figma renders a frame at one width and a Storybook canvas may use another. ADR-081 is being rewritten against that shape; the implementation here is discarded.