About these docs

This site is a Docusaurus 3 project in docusaurus/, separate from the npm workspace so its dependencies do not mix with the application's.

Running it

npm install --prefix docusaurus   # once
npm run docs:dev                  # regenerate the reference, then serve on :3000 with hot reload
npm run docs:build                # regenerate, then build static files into docusaurus/build

DOCS_URL and DOCS_BASE_URL set where the built site is published; the defaults suit local preview. Broken links and broken anchors fail the build.

Hand-written and generated pages

Most pages are hand-written Markdown in docusaurus/docs/. Six reference pages and the home page's numbers are generated from the code by docusaurus/scripts/generate-reference.ts, run from the repository root:

Page	Generated from
Claim schema	z.toJSONSchema(Claim), input shape, with descriptions and defaults
Capabilities	The shared catalogue and the server registry
Tools	allTools(): every definition and its parameters
Prompt catalogue	PROMPTS: ids, labels, purposes, word counts
Demo scenarios	SCENARIOS
Enumerations	The shared vocabularies
src/data/stats.json	Counts for the home page

npm run docs:reference              # write them
npm run docs:reference -- --check   # fail if any is stale (CI runs this)

Generated pages say so in a banner. Edit the source, not the page.

File formats

.md files are parsed as plain CommonMark (markdown.format: 'detect'), which keeps the generated pages safe from MDX's rules about < and {. Use .mdx only for pages that need components: the card grid, tabs, or the numbered steps.

Available in .mdx:

import CardGrid from '@site/src/components/CardGrid';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<p className="cp-lede">An opening paragraph with the salmon rule.</p>

<div className="cp-steps">

1. A step with the brand's salmon number disc.
2. Another step.

</div>

Mermaid diagrams work in both formats, in fenced mermaid blocks, and are drawn in the brand tints.

The Davies brand

The site follows the Davies Brand Book (2023).

Colour

Colour	Hex	Role here
Davies Dark Teal	#114b5f	Navigation bar, headings, links, buttons, the dark-mode canvas
Davies Salmon	#f76c6c	Accents: the rule under the navigation, heading bars, active markers, step numbers, the call to action
Davies Light Teal	#5fc7c7	Supporting elements; links in dark mode
Davies Mint Green	#8bd16e	Supporting elements; tips
Davies Grey	#54565a	Body text

Tints from the brand book (for example teal 20% #cfdbdf, salmon 20% #fde2e2) are used only for tables, diagrams and admonition backgrounds, never in place of the main colours. The brand book's pairing rules apply: white or salmon on Dark Teal is endorsed; salmon on Light Teal or Mint, and the reverse, is not. Salmon is too light for running text on white, so it is an accent and never body text or link colour.

The colours of the Davies logo (Dark Blue, Bright Blue, Green and Pink) are part of the logo only and are not used anywhere else on the site.

Logo

The logo files in static/img/ were taken directly from the vector paths in the brand book, in its official colours:

• davies-logo.svg: full colour, for light backgrounds;
• davies-logo-white.svg: all white, for dark backgrounds (the navigation bar and footer);
• davies-symbol.svg: the symbol alone, for the favicon.

The logo is always part of the page, never detached, recoloured or tinted.

Typography

The brand typeface is Gotham: Gotham Medium for headlines, Gotham Light for body copy. Gotham is licensed and not available to this site as a web font, so Montserrat, the closest open geometric sans, stands in for it: weight 500 for headings, 400 for body copy (Gotham Light's role, one step heavier because light weights read poorly on screens), with the slightly negative tracking the brand book specifies. Code is set in JetBrains Mono. Fonts are self-hosted through @fontsource, so the site makes no third-party requests. With a Gotham web-font licence, replace the imports in src/fonts.ts and the family names in src/css/custom.css.

Icons, gradients and layout

• Icons are minimal thin-line drawings (src/components/Icon.tsx), never 3D or heavy.
• Gradients are soft Dark Teal and Salmon overlays at low opacity, as on the home page.
• The home page follows the brand book's cover: a Dark Teal field, a Salmon block running off the left edge into a bold-and-light wordmark, and a Salmon rule down the right.
• Page titles sit over a heavy rule, as on the brand book's pages; section headings carry a short Salmon bar.

Writing style

We write in the Davies voice: engaging, approachable, knowledgeable and calm. In practice:

• British English, as the brand book requires.
• Active sentences, with the doer before the verb: "The Worker mints a turn id", not "A turn id is minted".
• "We" and "our" for the team. Instructions are in the imperative ("Run", "Set", "Add"), which keeps "you" out of most pages, as the brand book asks.
• Short paragraphs, mixed sentence length, and tables wherever a reader will scan.
• Short, familiar words: "use", not "utilise"; "before", not "prior to"; "because", not "due to the fact that".
• Facts that stand up to checking, with the file or function named. No empty adjectives such as "amazing" or "seamless".
• Say what something does not do, as plainly as what it does.

If a sentence needs reading twice, rewrite it.