@spendgraph/docs

Every page the other packages used to carry, and the figures those pages draw with.

Why it is one package

Pages used to live in the package they described, packages/stage/docs, and shipped inside it. That read well and cost more than it looked:

• docs was 6 to 22 percent of a package, worst at stage, downloaded by every install including the ones that only ever run the code
• a figure needs React, and none of those packages wanted a React dependency
• a figure shared between two pages had nowhere to live

So the pages moved here and the ten packages dropped docs from files. The version still moves with the rest, because a page describes a specific release.

Layout

figures/fig.tsx      the frame, LABEL, MONO, Arrow
figures/stage.tsx    the figures the stage pages draw with
stage/overview.mdx   the pages, one folder per package

A page imports what it draws:

import { PromptSources } from "../figures/prompt";

<PromptSources />

That is the rule this package exists to keep. A page never names a component it did not import and hope the renderer has one, which is what the old layout did: the tag was in the package and the component was in the docs host, so the page was only correct on that one site.

Rendering it

The pages are MDX with an export const meta carrying title and description. They are plain files, served through exports, so a renderer imports one by path:

import Page, { meta } from "@spendgraph/docs/stage/overview.mdx";

Two things a host has to provide:

• Callout, the one component the pages do not bring. Give it tone and title props
• the theme tokens from @spendgraph/config/css/theme.css. The figures use fill-ghost, text-s1, stroke-line and friends rather than pinning their own colours, so they follow the host's theme and its dark mode

docs.locusgraph.com renders these today, and tests/repo/package-docs.test.ts holds both rules.