# catalog.json (/docs/agents/catalog)

> The machine index of Section types, Themes, Templates and docs addresses, in the shape startupbuilder.dev's sync reads.

`https://next.mdxui.dev/catalog.json` holds, for `@mdxui/site@7.0.0-alpha.0`:

| Key | Holds |
| --- | --- |
| `sectionTypes` | Each Section type: its group, job, glyph, fields and bounds, variants with their frame addresses, its schema and its docs page |
| `themes` | Each Theme: typefaces, policies, whether it emits dark, and the landing rendered in it |
| `templates` | Each Template and the worked-Site pages that use it |
| `docs` | The docs addresses an agent starts from |

startupbuilder.dev owns the definitions of the Components these types draw. Its proposed `mdxui-sync` takes three fields per Section type from this file, and only from types whose page is accepted: an example record, stills and the docs address. It takes no definition, prop or bound; those stay on each side as they are.



# For agents (/docs/agents)

> An agent writes the record, never the markup, and shortens each field the schema refuses. Four fetches, one prompt and one fix loop.

An agent never writes HTML for mdxui. It writes a JSON record of words and choices, the schema accepts it or names the field that runs long, and `renderPage` draws it in the Business's Theme. The agent cannot move the layout, so it cannot break it.

  <div><strong>Fetch</strong><span>`llms.txt`, a record that parses, and the bounds</span></div>
  <div><strong>Write</strong><span>The Business's words into that record</span></div>
  <div><strong>Parse</strong><span>`PageSchema.safeParse`, fixing each refusal at its path</span></div>
  <div><strong>Render</strong><span>`renderPage`, under one Theme or several</span></div>

## The prompt

Paste these five lines into any coding agent. The landing's closing prints the same prompt.

[Prompts](https://next.mdxui.dev/docs/agents/prompts) holds one for each task, each Template and each worked Site.

## The four fetches

| Address | Answers |
| --- | --- |
| [`https://next.mdxui.dev/llms.txt`](https://next.mdxui.dev/llms.txt) | The install, the calls, the Theme names, the record to start from, then every docs page |
| [`https://next.mdxui.dev/pages/home.json`](https://next.mdxui.dev/pages/home.json) | A whole record that already parses |
| [`https://next.mdxui.dev/docs/reference/refusals.md`](https://next.mdxui.dev/docs/reference/refusals.md) | Every bound and rule by path, with its fix |
| [`https://next.mdxui.dev/schema.json`](https://next.mdxui.dev/schema.json) | Every bound at once, for a tool definition or structured output |

Every docs page is also served as Markdown at its address plus `.md`; [Markdown and JSON twins](https://next.mdxui.dev/docs/agents/twins) lists them.

## The fix loop

A refusal is a path and a bound. `refusal-url.ts` turns each one into the address of the rule it broke, so the agent reads the fix instead of guessing:

```ts
import { PageSchema } from '@mdxui/site';

// Each refusal, then the address of its fix: the block's type, then the path after `block`, list indexes dropped.
export function refusalUrls(page: any): string[] {
  const result = PageSchema.safeParse(page);
  if (result.success) return [];
  return result.error.issues.flatMap(({ path, message }) => {
    const keys = (p: PropertyKey[]) => p.filter((s) => typeof s === 'string').join('.');
    const anchor = path[0] !== 'sections' ? `page.${keys(path)}` : path[2] === 'shell' ? `shell.${keys(path.slice(3))}` : [page.sections[path[1] as number]?.block?.type, keys(path.slice(3))].filter(Boolean).join('.');
    return [`${path.join('.')}: ${message}`, `https://next.mdxui.dev/docs/reference/refusals#${anchor}`];
  });
}
```

On the landing's record with a 71-character hero title, it prints:

```text
sections.2.block.title: Too big: expected string to have <=64 characters
https://next.mdxui.dev/docs/reference/refusals#hero.title
```

The agent shortens the title and parses again, until nothing is refused. It never asks for a longer bound: a bound is where the design was drawn.

## Next

  - [Have your agent write a page](https://next.mdxui.dev/docs/agents/write-a-page): The loop, step by step, and in CI.
  - [schema.json](https://next.mdxui.dev/docs/agents/schema): What JSON Schema carries, and what it cannot.
  - [catalog.json](https://next.mdxui.dev/docs/agents/catalog): Every Section type, Theme and Template, as data.



# llms.txt (/docs/agents/llms-txt)

> What llms.txt and llms-full.txt hold: the install, the calls and the rule first, then every docs page an agent needs.

| File | Holds |
| --- | --- |
| [`/llms.txt`](https://next.mdxui.dev/llms.txt) | The install line, the starter record, the schema, the four calls, the Theme names and the rule; then every docs page as a link with its description, the App pages last under Optional |
| [`/llms-full.txt`](https://next.mdxui.dev/llms-full.txt) | Every page an agent writing a Site needs, in full, in nav order. A page that names an unpublished export opens with a `Spec` line |

`llms-full.txt` leaves out the App studies, the App stubs, the Theme exports and the Maintainers pages; each is still served as its own [`.md` twin](https://next.mdxui.dev/docs/agents/twins).



# Prompts (/docs/agents/prompts)

> One copyable prompt per task, per Template and per worked Site, every address on this site and every one served.

Each prompt is five lines or fewer: what to read, what to start from, what to change, the rule, and what to hand back. Every address in it is a link; the build fails if one does not resolve.

## By task

**Write a new page**

```text
Read https://next.mdxui.dev/llms.txt, then fetch https://next.mdxui.dev/pages/vanroster/home.json, a page record that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0. It pins @mdxui/themes 7.0.0-alpha.0.
Rewrite its strings for my Business. Keep the Section types that fit.
Parse it with PageSchema.safeParse. When it refuses, shorten the content, never the bound.
Render it with renderPage under two of the 5 Themes and save both HTML files.
```

**Write a whole Site**

```text
Read https://next.mdxui.dev/llms.txt, then fetch https://next.mdxui.dev/sites/vanroster/records.zip, a worked Site whose records parse.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite every record for my Business. Keep one Theme for the whole Site, a 404 page and a contact page.
Parse each record with PageSchema.safeParse. When it refuses, shorten the content, never the bound.
Render each record with renderPage and save one HTML file per page.
```

**Rebrand a Site**

```text
Read https://next.mdxui.dev/docs/start/guides/rebrand.md.
Set "theme" in every record of my Site to one Theme of the five.
Render each record again and compare it with the render under the old Theme.
```

**Fix every refusal**

```text
Read https://next.mdxui.dev/docs/reference/refusals.md.
Parse my record with PageSchema.safeParse and list each issue by its path.
Shorten or cut the content at each path until the record parses. Never change a bound.
```

## By Template

Each starts from a worked page that uses the Template and parses as it stands.

**api-product, from Vanroster › home**

```text
Read https://next.mdxui.dev/docs/showcase/templates/api-product.md, then fetch https://next.mdxui.dev/pages/vanroster/home.json, a api-product page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**article, from Vanroster › security**

```text
Read https://next.mdxui.dev/docs/showcase/templates/article.md, then fetch https://next.mdxui.dev/pages/vanroster/security.json, a article page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**blog, from Vanroster › changelog**

```text
Read https://next.mdxui.dev/docs/showcase/templates/blog.md, then fetch https://next.mdxui.dev/pages/vanroster/changelog.json, a blog page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**contact, from Vanroster › contact**

```text
Read https://next.mdxui.dev/docs/showcase/templates/contact.md, then fetch https://next.mdxui.dev/pages/vanroster/contact.json, a contact page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**directory-list, from Benchlist › home**

```text
Read https://next.mdxui.dev/docs/showcase/templates/directory-list.md, then fetch https://next.mdxui.dev/pages/benchlist/home.json, a directory-list page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**directory-product, from Vanroster › product/dispatch**

```text
Read https://next.mdxui.dev/docs/showcase/templates/directory-product.md, then fetch https://next.mdxui.dev/pages/vanroster/product/dispatch.json, a directory-product page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**post, from Vanroster › changelog/route-swaps**

```text
Read https://next.mdxui.dev/docs/showcase/templates/post.md, then fetch https://next.mdxui.dev/pages/vanroster/changelog/route-swaps.json, a post page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## By worked Site

Each starts from every record of one worked Business, as one download.

**A Site like Vanroster**

```text
Read https://next.mdxui.dev/docs/showcase/vanroster.md and https://next.mdxui.dev/docs/start/ship.md.
Download https://next.mdxui.dev/sites/vanroster/records.zip: 9 records of a b2b saas that parse, under callboard.
Rewrite every record for my Business. Keep one Theme for every record, the 404 page and the contact flow.
Parse each record with PageSchema.safeParse. When one refuses, shorten the content at its path, never the bound.
Build the Site with ship.ts and show me dist/.
```

**A Site like Ledgerhouse**

```text
Read https://next.mdxui.dev/docs/showcase/ledgerhouse.md and https://next.mdxui.dev/docs/start/ship.md.
Download https://next.mdxui.dev/sites/ledgerhouse/records.zip: 9 records of a professional services that parse, under vaultline.
Rewrite every record for my Business. Keep one Theme for every record, the 404 page and the contact flow.
Parse each record with PageSchema.safeParse. When one refuses, shorten the content at its path, never the bound.
Build the Site with ship.ts and show me dist/.
```

**A Site like Diffkeel**

```text
Read https://next.mdxui.dev/docs/showcase/diffkeel.md and https://next.mdxui.dev/docs/start/ship.md.
Download https://next.mdxui.dev/sites/diffkeel/records.zip: 9 records of a developer tool that parse, under certificate.
Rewrite every record for my Business. Keep one Theme for every record, the 404 page and the contact flow.
Parse each record with PageSchema.safeParse. When one refuses, shorten the content at its path, never the bound.
Build the Site with ship.ts and show me dist/.
```

**A Site like Benchlist**

```text
Read https://next.mdxui.dev/docs/showcase/benchlist.md and https://next.mdxui.dev/docs/start/ship.md.
Download https://next.mdxui.dev/sites/benchlist/records.zip: 8 records of a directory and marketplace that parse, under directory.
Rewrite every record for my Business. Keep one Theme for every record, the 404 page and the contact flow.
Parse each record with PageSchema.safeParse. When one refuses, shorten the content at its path, never the bound.
Build the Site with ship.ts and show me dist/.
```

**A Site like Sidework**

```text
Read https://next.mdxui.dev/docs/showcase/sidework.md and https://next.mdxui.dev/docs/start/ship.md.
Download https://next.mdxui.dev/sites/sidework/records.zip: 8 records of a publication that parse, under vaultline.
Rewrite every record for my Business. Keep one Theme for every record, the 404 page and the contact flow.
Parse each record with PageSchema.safeParse. When one refuses, shorten the content at its path, never the bound.
Build the Site with ship.ts and show me dist/.
```

**A Site like Harbor tides**

```text
Read https://next.mdxui.dev/docs/showcase/harbor.md and https://next.mdxui.dev/docs/start/ship.md.
Download https://next.mdxui.dev/sites/harbor/records.zip: 10 records of a api product that parse, under quaypoint.
Rewrite every record for my Business. Keep one Theme for every record, the 404 page and the contact flow.
Parse each record with PageSchema.safeParse. When one refuses, shorten the content at its path, never the bound.
Build the Site with ship.ts and show me dist/.
```

## By guide

**Run the Quickstart**

```text
Read https://next.mdxui.dev/docs/start/quickstart.md and https://next.mdxui.dev/llms.txt.
Download https://next.mdxui.dev/starter.zip and unzip it. Run pnpm install, then pnpm render.
Rewrite the strings of pages/home.json for my Business. Keep the Section types that fit.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it under its own Theme and one more, and show me both HTML files.
```

**Ship a Site**

```text
Read https://next.mdxui.dev/docs/start/ship.md.
Run pnpm add @mdxui/site@7.0.0-alpha.0, then save ship.ts, site.ts and write-a-theme.ts as the page shows them.
Put every record of my Site in pages/, with home.json, 404.json and one Theme for every record.
Run node ship.ts. Fix each refusal at its path by shortening the content.
Deploy dist/ and confirm an unknown address answers 404 with my 404 page.
```

**Write a page from a description**

```text
Read https://next.mdxui.dev/llms.txt and https://next.mdxui.dev/docs/agents/write-a-page.md.
Fetch https://next.mdxui.dev/schema.json and use it as the structured output schema for one page record.
Write the record for the page I describe. Keep every string inside its bound.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## The rule in every prompt

When `PageSchema.safeParse` refuses, the agent shortens the content at the path it names. It never raises a bound, never adds a field the schema does not name, and never writes markup into a string.


# schema.json (/docs/agents/schema)

> The page schema and one schema per Section type, as JSON Schema, and the rules JSON Schema does not carry, so agents check with PageSchema.

| Address | Holds |
| --- | --- |
| [`/schema.json`](https://next.mdxui.dev/schema.json) | `PageSchema.toJSONSchema()`: the whole record, every bound as `maxLength`, `minItems` and `maxItems` |
| `/schema/sections/<type>.json` | One Section type's schema, such as [`/schema/sections/stats.json`](https://next.mdxui.dev/schema/sections/stats.json), for all 27 types |

Hand `/schema.json` to a model as its structured output or tool schema. Then check what it returns with `PageSchema.safeParse`, never with a JSON Schema validator alone.

## What JSON Schema leaves out

Some rules span fields, or allow only some counts inside a range. `/schema.json` does not carry them; `PageSchema` does. Each section below keeps every bound in `/schema.json`, and `schema-gap.ts` shows `PageSchema` refusing it:

```ts
// Three sections that keep every maxLength, minItems and maxItems in /schema.json,
// and that PageSchema still refuses: rules JSON Schema has no keyword for.
const brand = { href: '/' };
const probes: Record<string, unknown> = {
  'a brand with neither wordmark nor mark': { type: 'nav', menu: 'none', brand, links: [] },
  'a feature grid of five': { type: 'feature-grid', cellHead: 'none', items: Array.from({ length: 5 }, () => ({ title: 'A feature' })) },
  'a footer in columns with no "For agents" column': {
    type: 'footer', layout: 'columns', brand: { href: '/', text: 'Vanroster' }, note: ['Vanroster', 'Rendered by @mdxui/site.'],
    columns: [{ title: 'Product', links: [['/pricing', 'Pricing']] }, { title: 'Company', links: [['/contact', 'Contact']] }],
  },
};

export function gaps(): string[] {
  return Object.entries(probes).map(([what, block]) => {
    const page = { theme: 'callboard', title: 'Probe', description: 'A probe.', frame: 'none', sections: Array.from({ length: 3 }, () => ({ kind: 'section', shell: { inset: 'contained', density: 'section' }, block })) };
    const result = PageSchema.safeParse(page);
    const issue = result.success ? undefined : result.error.issues[0];
    return `${what}: ${issue ? `${issue.path.join('.')}: ${issue.message}` : 'accepted'}`;
  });
}
```

```text title="node schema-gap.ts"
a brand with neither wordmark nor mark: sections.0.block.brand: a brand needs a wordmark or a mark
a feature grid of five: sections.0.block.items: a feature grid holds 2, 3, 4, 6, 8 cells: a count that fills its rows at every width
a footer in columns with no "For agents" column: sections.0.block: a footer in columns has a "For agents" column
```

[Refusals](https://next.mdxui.dev/docs/reference/refusals) lists every rule with its message.



# Markdown and JSON twins (/docs/agents/twins)

> Every docs page as Markdown at its address plus .md, and every record a page renders as JSON beside its render.

An agent reads text, not layout. Every page here has a twin an agent can fetch whole: Markdown for a docs page, JSON for a rendered one.

## Markdown for every docs page

Add `.md` to any docs address: [`/docs/start/quickstart`](https://next.mdxui.dev/docs/start/quickstart) is [`/docs/start/quickstart.md`](https://next.mdxui.dev/docs/start/quickstart.md). The twin holds what the page holds:

- every included example inlined, as the page shows it;
- every address written in full on this site's origin;
- a Section type preview as the address of the manifest that lists its frames;
- no MDX comments; a component stays as a tag around its content, so every step of a guide is in the text.

Copy Markdown and Open, under every page title, use the same twin.

## JSON for every rendered page

| You have | Its record |
| --- | --- |
| A worked-Site page, such as [`/sites/harbor/pricing`](https://next.mdxui.dev/sites/harbor/pricing) | [`/pages/harbor/pricing.json`](https://next.mdxui.dev/pages/harbor/pricing.json) |
| The landing, [`/`](https://next.mdxui.dev/) | [`/pages/home.json`](https://next.mdxui.dev/pages/home.json) |
| A whole worked Site | [`/sites/harbor/records.zip`](https://next.mdxui.dev/sites/harbor/records.zip) |
| A docs page that renders or cites a record | View as JSON, under its title |
| A Section type exemplar | Its `record` in [`/components/manifest.json`](https://next.mdxui.dev/components/manifest.json) |

A record is served byte for byte as the build renders it, so the JSON an agent copies parses.

## Why both

The Markdown says what to do; the JSON is what to change. An agent that reads the guide's twin and starts from the record's twin edits words in a structure that already parses, and fetches no HTML.


# Have your agent write a page (/docs/agents/write-a-page)

> Prompt, record, safeParse, fix at the path, render; then the same check on every push, so no refused record ships.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/llms.txt and https://next.mdxui.dev/docs/agents/write-a-page.md.
Fetch https://next.mdxui.dev/schema.json and use it as the structured output schema for one page record.
Write the record for the page I describe. Keep every string inside its bound.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

Copy the five-line prompt that runs these steps.

You describe the page; the agent writes the record, parses it, fixes each refusal at its path and renders it. Then one script keeps every record parsing on every push.

## Prerequisites

- `@mdxui/site` installed, as in the [Quickstart](https://next.mdxui.dev/docs/start/quickstart).
- A coding agent that can fetch an address and run a script.

**File: prompt**

**Write a page from a description**

```text
Read https://next.mdxui.dev/llms.txt and https://next.mdxui.dev/docs/agents/write-a-page.md.
Fetch https://next.mdxui.dev/schema.json and use it as the structured output schema for one page record.
Write the record for the page I describe. Keep every string inside its bound.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

**File: refusal-url.ts**

```ts
import { PageSchema } from '@mdxui/site';

// Each refusal, then the address of its fix: the block's type, then the path after `block`, list indexes dropped.
export function refusalUrls(page: any): string[] {
  const result = PageSchema.safeParse(page);
  if (result.success) return [];
  return result.error.issues.flatMap(({ path, message }) => {
    const keys = (p: PropertyKey[]) => p.filter((s) => typeof s === 'string').join('.');
    const anchor = path[0] !== 'sections' ? `page.${keys(path)}` : path[2] === 'shell' ? `shell.${keys(path.slice(3))}` : [page.sections[path[1] as number]?.block?.type, keys(path.slice(3))].filter(Boolean).join('.');
    return [`${path.join('.')}: ${message}`, `https://next.mdxui.dev/docs/reference/refusals#${anchor}`];
  });
}
```

**File: check-records.ts**

```ts
// node check-records.ts: every record in pages/ parses, or each refusal prints with the address of its fix.
let refused = 0;
const files = (await readdir('pages', { recursive: true })).filter((f) => f.endsWith('.json')).sort();
for (const file of files) {
  const lines = refusalUrls(JSON.parse(await readFile(`pages/${file}`, 'utf8')));
  if (lines.length) refused++;
  for (let i = 0; i < lines.length; i += 2) console.error(`pages/${file}: ${lines[i]}\n  fix: ${lines[i + 1]}`);
}
if (refused) process.exitCode = 1;
else console.log(`${files.length} records parse`);
```

## Hand it the prompt and the schema

The prompt names what to read and the rule. `/schema.json` makes a good structured output schema: the model sees every bound as `maxLength`, `minItems` and `maxItems` while it writes. It cannot see every rule, so the next step still parses.

## Parse what it wrote

`PageSchema.safeParse` accepts the record or returns its issues, each a path and a message. Nothing renders until it accepts. A hero title of 71 characters returns:

```text
sections.1.block.title: Too big: expected string to have <=64 characters
```

## Fix it at the path

`refusalUrls` turns each issue into the address of its rule on [Refusals](https://next.mdxui.dev/docs/reference/refusals). The agent reads the rule, shortens the content at that path and parses again. It never raises a bound or drops the section to make the error go away.

## Render it

Once the record parses, `renderPage(record)` returns the page, and `renderPage(record, { theme })` the same page under another Theme. The agent hands back the record and the HTML; you review a JSON diff of words.

## Check on every push

Run `node check-records.ts` in CI. It parses every record in `pages/` and fails the run on any refusal, with the address of its fix. On records that parse:

```text title="node check-records.ts"
10 records parse
```

With one plan named `Every berth, all year`, 21 characters:

```text title="node check-records.ts"
pages/pricing.json: sections.1.block.tiers.0.name: Too big: expected string to have <=16 characters
fix: https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.name
```

## Result

Every record the agent writes parses before it renders, and none that is refused reaches a deploy.

## Next steps

  - [Prompts](https://next.mdxui.dev/docs/agents/prompts): One for each task, Template and worked Site.
  - [schema.json](https://next.mdxui.dev/docs/agents/schema): What the schema carries, and what it leaves out.
  - [Refusals](https://next.mdxui.dev/docs/reference/refusals): Every rule, by path, with its message.



# Brand and Theme (/docs/components/brand-and-theme)

> startupbuilder.dev defines the Brand and the Theme; mdxui draws a Theme as a Brand's tokens plus its render policies, named in one field.

> A Brand is a name, a voice, a logo, and a style under which a Startup makes Offers.
>
> startupbuilder.dev, [Brand](https://startupbuilder.dev/business/nouns/brand)

> A Theme is the design tokens of a Brand, its color, type, spacing, radius, and motion, that every Component reads when it renders.
>
> startupbuilder.dev, [Theme](https://startupbuilder.dev/business/nouns/theme)

mdxui draws a Theme as the Brand's tokens plus its render policies. A policy is a choice a design makes once, such as what falls between two sections. A Page names its Theme in one field, `theme`.

## What mdxui renders

One record, Harbor's home page, under each of the five bundled Themes. Only the `theme` field differs.

## How it maps

  - **Brand name** (alpha): `brand.text` in the `nav` and `footer` sections, with an optional accent `suffix`
  - **Brand voice** (gap): No field: the agent writes in the voice, and the bounds keep it short
  - **Brand logo** (gap): `brand.mark`, a glyph from [Icons](https://next.mdxui.dev/docs/reference/icons); no logo file
  - **Brand style** (alpha): The Theme the record names
  - **Theme tokens** (alpha): Roles: 21 every Theme sets, the rest derived with defaults
  - **light and dark modes** (alpha): A dark palette, and the `scheme` policy that decides whether a page follows the reader
  - **Theme css** (gap): None, by design: no page carries its own CSS
  - **every Component reads it** (alpha): Every Section type reads roles, never a literal color

## Status

The five Themes and `compileTheme`, which turns your own tokens and policies into a Theme, ship in `@mdxui/themes@7.0.0-alpha.0`. The Brand's voice and logo have no field: the [Site record](https://next.mdxui.dev/docs/components/site#intended-noun) drafts the logo.

## Related

  - [Themes](https://next.mdxui.dev/docs/themes): The five, each worn by a Business.
  - [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme): Your Brand's tokens, compiled.
  - [The Theme contract](https://next.mdxui.dev/docs/themes/contract): Every role a Theme fills.



# Components (/docs/components)

> startupbuilder.dev defines every Component; mdxui shows how each one looks and behaves, which Section type draws it, and what is still a gap.

startupbuilder.dev owns each definition and its props. Every page here quotes that definition word for word, renders what mdxui draws for it, and states each gap.

## What startupbuilder.dev defines, what mdxui draws

  - **Site** (spec): [Site](https://next.mdxui.dev/docs/components/site): a folder of Page records under one Theme
  - **Page** (alpha): [Page](https://next.mdxui.dev/docs/components/page): one record, one document
  - **Component** (alpha): [Section](https://next.mdxui.dev/docs/components/section): a kind, a shell and one Section type
  - **Template** (alpha): [Template](https://next.mdxui.dev/docs/components/template): seven page kinds
  - **Brand, Theme** (alpha): [Brand and Theme](https://next.mdxui.dev/docs/components/brand-and-theme): tokens plus render policies
  - **Product** (spec): [The Product record](https://next.mdxui.dev/docs/components/product-record): one record behind every rendering
  - **Interface** (alpha): [Interface](https://next.mdxui.dev/docs/components/interface): the Site, and Interface against rendering
  - **App** (study): [App](https://next.mdxui.dev/docs/components/app), with 13 [App types](https://next.mdxui.dev/docs/app) studied
  - **View** (study): [View](https://next.mdxui.dev/docs/components/view); startupbuilder.dev has no View Noun
  - **Dashboard** (study): [Dashboard](https://next.mdxui.dev/docs/components/dashboard), which extends View

## The UI catalog, mapped

startupbuilder.dev's [UI catalog](https://startupbuilder.dev/code/ui) names 26 components, each with a web, a native and a Markdown renderer. mdxui draws the web rendering of the Site ones with Section types. The App and Dashboard ones are App and View territory, studied in the Apps tab.

  - **Hero** (alpha): The headline is `title`, the line is `lede`; an action is a link, not a bound Offer
  - **Features** (alpha): Lines the agent writes, not drawn from the Product's Nouns and Verbs
  - **PriceTable** (alpha): Plans as OfferTiles with prices and actions; the buying Verb is a link
  - **Faq** (alpha): Question and answer pairs, written out rather than bound to records
  - **CallToAction** (alpha): Actions under a closing head
  - **WaitlistJoin** (alpha): A form that posts to its `action`; the join is the host's
  - **Reserve** (gap): A form; no deposit and no Evidence for a Hypothesis
  - **Changelog** (alpha): Posts newest first, each linked; no link to the Version that shipped it
  - **Footer** (alpha): The Brand, link columns and a note; the terms and privacy links are written out
  - **Navigation** (alpha): The same links for every reader; no Persona grants
  - **VerbReference** (alpha): One call on each Interface: `terminal` tabs, or `api-call` examples
  - **VerbSheet and 4 more** (study): ActionStatus, ThingDetail, Board and Timeline: App territory; see [App types](https://next.mdxui.dev/docs/app)
  - **MetricTile and 9 more** (study): KeyResult, GoalTree, PendingFeed, TaskInbox, ApprovalSheet, VarianceAlert, DataTable, LensGrid and Benchmark: View territory; see [Dashboard](https://next.mdxui.dev/docs/components/dashboard)

Twelve Section types draw no catalog entry: `statement`, `stats`, `facts`, `compare`, `steps`, `text-stack`, `command-row`, `agent-prompt`, `page-head`, `article`, `product-head` and `product-list`. All 27 are on [Section types](https://next.mdxui.dev/docs/sections).


# Interface (/docs/components/interface)

> A Site and an App are each an Interface of a Product; a rendering is one output format of a record, and an Interface has several.

> An Interface is how a person or an Agent reaches a Product: an API, MCP server, CLI, SDK, Site, or App.
>
> startupbuilder.dev, [Interface](https://startupbuilder.dev/business/nouns/interface)

A Site and an [App](https://next.mdxui.dev/docs/components/app) each extend Interface on startupbuilder.dev. mdxui renders a Site's pages today, one `renderPage` call per record, with `site()` for a whole Site written as Spec; the App's design is open.

## Interface and rendering

The two words never trade places:

| | Interface | Rendering |
| --- | --- | --- |
| Is | How a person or an agent reaches a Product | One output format of one record |
| Belongs to | A Product | A record |
| Examples | A Site, an App, an API, a CLI | HTML, JSON, Markdown, a share image, an email |
| On this site | [Site](https://next.mdxui.dev/docs/components/site) | [Renderings](https://next.mdxui.dev/docs/components/renderings) |

## What mdxui renders

One page of one Site Interface, in two renderings. The Preview tab is the HTML a person reads; the Record tab is the JSON an agent reads and writes.

The rendered page: https://next.mdxui.dev/sites/harbor/; its record: https://next.mdxui.dev/pages/harbor/home.json

## How it maps

startupbuilder.dev's eight Interface kinds. mdxui serves one, the Site, and draws the Site pages that document four more.

  - **site** (alpha): Page records, rendered under one Theme
  - **api** (alpha): Documented on a Site: a call with its response, and the list of endpoints
  - **cli** (alpha): Documented on a Site: the install line and a session
  - **sdk** (alpha): Documented on a Site: one call per language, as tabs
  - **mcp** (alpha): Documented on a Site: the prompt a reader pastes into an agent
  - **app** (study): Studied for 13 App types; see [App types](https://next.mdxui.dev/docs/app)
  - **docs** (gap): No docs Interface: these docs run on Fumadocs, beside the renderer
  - **webhooks** (gap): No Section type of its own; `endpoints` lists webhook paths as rows
  - **path** (host): Where the host mounts the Site on its Domain

## Status

The Site Interface renders today in two renderings, HTML and JSON. The Markdown, share image and email renderings are Spec, each on its own page under [Renderings](https://next.mdxui.dev/docs/components/renderings).

## Related

  - [Site](https://next.mdxui.dev/docs/components/site): The Interface mdxui renders.
  - [Renderings](https://next.mdxui.dev/docs/components/renderings): One record, every output format.
  - [App types](https://next.mdxui.dev/docs/app): The other Interface, studied.



# Page (/docs/components/page)

> A Page is one record: its Theme, an optional Template, its frame, its head and three to twenty sections, rendered as one document.

> A Page is an addressable page of a Site, of a named type such as pricing, about one Thing or each member of a Collection.
>
> startupbuilder.dev, [Page](https://startupbuilder.dev/business/nouns/page)

## What mdxui renders

One record, parsed by `PageSchema` and rendered by `renderPage`. This is Harbor's pricing page, five sections; open the Record tab to read the record that drew it, or pick another Theme.

The rendered page: https://next.mdxui.dev/sites/harbor/pricing; its record: https://next.mdxui.dev/pages/harbor/pricing.json

Each field decides one thing; a section decides its own layout and content.

From `@mdxui/site@7.0.0-alpha.0`.

| Field | Type and bound | Required | Decides |
| --- | --- | --- | --- |
| `theme` | `"certificate" \| "vaultline" \| "quaypoint" \| "callboard" \| "directory"` | yes | The Brand the page wears: tokens, typefaces and policies |
| `template` | `"api-product" \| "article" \| "blog" \| "post" \| "contact" \| "directory-list" \| "directory-product"` | no | The page kind; it names the slots the sections fill |
| `title` | `string ≤64` | yes | The document title and the share title |
| `description` | `string ≤320` | yes | The meta and share description |
| `meta` | `object` | no | The head: canonical address, icons, share image, `noindex` |
| `meta.canonical` | `string ≤160` | no | — |
| `meta.type` | `"website" \| "article"` | no | — |
| `meta.icon` | `string ≤160` | no | — |
| `meta.iconFallback` | `string ≤160` | no | — |
| `meta.appleTouchIcon` | `string ≤160` | no | — |
| `meta.image` | `object` | no | — |
| `meta.noindex` | `boolean` | no | — |
| `jsonLd` | `0–4 × object` | no | Structured data, written into the head as given |
| `frame` | `"none" \| "sheet" \| "split"` | yes | The frame around every section: none, one ruled sheet, or a split with an aside |
| `sections` | `3–20 × section` | yes | The page itself, in order |

Every bound, with its refusal, is on [Page fields and bounds](https://next.mdxui.dev/docs/reference/page-schema).

## How it maps

  - **path** (gap): Not in the record: the file's place decides it, so `pages/harbor/pricing.json` serves `/pricing`
  - **kind** (alpha): `template`, one of seven. A `landing` or `pricing` page is `api-product`; a `terms` page is `article`
  - **from** (gap): Not in the record: no lineage back to a Hypothesis slot
  - **uses Components** (alpha): `sections`, three to twenty, each one Section type
  - **about one Thing** (gap): Literal props: the agent writes the Thing's facts into the record
  - **each member of a Collection** (gap): One record per member, written out

## Status

A Page record parses and renders today, and none of its fields is a Spec. The record binds to no other record: an agent fills every field with literal words, and the bounds keep those words inside the design.

## Intended Noun

The three Page props the record lacks, drafted as the fields that close the gap.

```yaml title="intended Noun: Page record, the startupbuilder.dev props (mdxui.dev namespace)"
noun: Page record
projects: startupbuilder.dev Page, quoted above; defines nothing new
adds:
  path: { type: string, pattern: "^/[a-z0-9/-]*$", max: 160, required: true, note: the address under its Site; today the file path }
  kind: { type: enum, values: the startupbuilder.dev page types, required: false, note: maps onto template }
  from: { type: string, pattern: "Hypothesis#<slot>@v<version>", required: false, note: lineage, never rendered }
  about: { type: Thing reference, required: false, note: the Thing whose fields fill the sections }
```

## Related

  - [Section](https://next.mdxui.dev/docs/components/section): What one entry of `sections` holds.
  - [Template](https://next.mdxui.dev/docs/components/template): The seven page kinds.
  - [Pages are data](https://next.mdxui.dev/docs/start/pages-are-data): Why a page is a record.



# The Product record (/docs/components/product-record)

> Spec: written ahead of the package. Not in the published packages: agentPrompt, og, email

> One bounded record of a product feeds its landing, emails, share image, directory entry and agent prompt, so it says one thing everywhere.

> A Product is what a Customer gets from a Startup, with a promise the Customer can rely on.
>
> startupbuilder.dev, [Product](https://startupbuilder.dev/business/nouns/product)

> An Offer is a Product, under a Brand, at a price, on terms, made by a Startup.
>
> startupbuilder.dev, [Offer](https://startupbuilder.dev/business/nouns/offer)

The Product record is one bounded record of a product: its name, Theme, addresses, plans and first calls. Every rendering of the product reads it, so the landing, the emails and the agent prompt never disagree. It projects startupbuilder.dev's Product, its Offers and their Prices, and defines no second Product.

## What mdxui renders

Today each Page record carries the product's facts itself. Harbor's plans below are written into `pages/harbor/pricing.json` by hand, and its home page repeats the name and the first call.

The rendered page: https://next.mdxui.dev/sites/harbor/pricing; its record: https://next.mdxui.dev/pages/harbor/pricing.json

## How it maps

  - **the landing** (alpha): The name, the Theme, the plans and the first call, written into each record by hand
  - **the directory entry** (alpha): The category, the tags, the summary and the date it listed, written by hand
  - **the agent prompt** (spec): The quickstart calls in agent order: the CLI, the MCP server, the SDKs, then `curl`
  - **the share image** (spec): The name, the summary and the Theme; see [Share image](https://next.mdxui.dev/docs/components/renderings/share-image)
  - **the emails** (spec): The name, the Theme and the dashboard address; see [Email](https://next.mdxui.dev/docs/components/renderings/email)

## Status

The record and every rendering that reads it are Spec. The landing and the directory entry render today from Page records that repeat the same facts. A price changed in one record and not another is a disagreement no parse catches.

## Intended Noun

```yaml title="intended Noun: Product record (mdxui.dev namespace)"
noun: Product record
projects: startupbuilder.dev Product, its Offers and Prices; defines nothing new
fields:
  name: { type: string, bound: open, required: true }
  theme: { type: Theme, required: true }
  mark: { type: icon name, required: false }
  apiBase: { type: URL, required: true }
  docsUrl: { type: URL, required: true }
  dashboardUrl: { type: URL, required: false }
  contactUrl: { type: URL, required: false }
  statusUrl: { type: URL, required: false }
  keyPrefix: { type: string, bound: open, required: false }
  quickstart: { type: list of call, count: open, required: true, order: [cli, mcp, sdk, curl] }
  plans: { type: list of Offer, count: open, required: true, each: [price or contact, limit, retention, seats, feature lines, action] }
  questions: { type: list of onboarding question, count: open }
  directory: { category: string, tags: list of string, summary: string, since: date }
```

Every bound is open until the record ships. Each string gets one, measured from real products, as every Section type's strings have.

## Related

  - [Renderings](https://next.mdxui.dev/docs/components/renderings): Every output format of one record.
  - [pricing](https://next.mdxui.dev/docs/sections/pricing): Plans as OfferTiles.
  - [Harbor tides](https://next.mdxui.dev/docs/showcase/harbor): The product these facts describe.



# Document and head (/docs/components/renderings/document-and-head)

> The document around a page: its head lines, the Theme's typefaces and browser color, its color scheme and one style element.

`document()` wraps a page body in its head and one stylesheet. Run the four steps of `renderPage` by hand and the result is the same string.

## Prerequisites

- The [quickstart](https://next.mdxui.dev/docs/start/quickstart) runs in your project, with `@mdxui/themes` installed as on [Packages and versions](https://next.mdxui.dev/docs/start/packages).

## Steps

1. Parse the record:

   ```ts
   const page = PageSchema.parse({
     theme: 'callboard',
     title: 'Harbor tides',
     description: 'Tide tables for every berth.',
     frame: 'none',
     sections: [
       { kind: 'hero', shell: { inset: 'contained', density: 'hero' }, block: { type: 'hero', layout: 'centered', stack: 560, title: 'Every berth, every tide.', lede: 'One call returns the tide table for any berth.', actions: [], fine: [] } },
       { kind: 'band', shell: { inset: 'contained', density: 'section' }, block: { type: 'statement', text: 'A tide table is a *promise*.' } },
       { kind: 'section', shell: { inset: 'contained', density: 'section' }, block: { type: 'command-row', command: 'npm i @example/harbor-tides' } },
     ],
   });
   ```

2. Render each section under the record's Theme, then compose the body:

   ```ts
   const { theme, css, head } = THEMES[page.theme];
   const sections = page.sections.map((s) => ({
     kind: s.kind,
     shell: s.shell,
     html: renderBlock(s.block, context(theme, s.shell.surface ?? 'paper', theme.icons)),
   }));
   const body = compose({ frame: page.frame, sections, dividers: theme.dividers });
   ```

3. Wrap the body. The Theme supplies the head lines and the tokens:

   ```ts
   const html = document({
     title: page.title,
     description: page.description,
     colorScheme: theme.dark && theme.scheme !== 'light' ? 'light dark' : 'light',
     jsonLd: page.jsonLd ?? [],
     head,
     css: `${css()}${baseCss}${primitivesCss}${shellCss}${blocksCss}`,
     body,
   });
   ```

4. Compare it with `renderPage`:

   ```ts
   if (html !== renderPage(page)) throw new Error('the document differs from renderPage');
   await writeFile('harbor.html', html);
   ```

## Result

The document equals `renderPage(page)` byte for byte; `pnpm check` runs the example and fails otherwise. With a `meta` of a canonical address and a type, its head reads:

| Head line | From |
| --- | --- |
| `<meta charset="utf-8">` | Fixed |
| `<meta name="viewport" content="width=device-width, initial-scale=1">` | Fixed |
| `<title>Harbor tides</title>` | `title` |
| `<meta name="description" content="Tide tables for every berth.">` | `description` |
| `<meta name="color-scheme" content="light">` | The Theme: `light dark` with a dark palette under `scheme: auto` |
| `<meta property="og:title" content="Harbor tides">` | `title`, `description` |
| `<meta property="og:description" content="Tide tables for every berth.…` | `title`, `description` |
| `<meta name="theme-color" content="#F4F6F8">` | The Theme's head lines |
| `<link rel="preconnect" href="https://fonts.googleapis.com">` | The Theme's head lines: its typefaces |
| `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>` | The Theme's head lines: its typefaces |
| `<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family…` | The Theme's head lines: its typefaces |
| `<link rel="canonical" href="https://harbor.example/">` | `meta.canonical` |
| `<meta property="og:type" content="website">` | `meta.type` |

Then 1 `<style>` element: the Theme's tokens, the base, the primitives, the shell and every Section type.

## Related

  - [HTML](https://next.mdxui.dev/docs/components/renderings/html): The same document in one call.
  - [Typefaces](https://next.mdxui.dev/docs/themes/typefaces): The head lines each Theme loads.
  - [Share image](https://next.mdxui.dev/docs/components/renderings/share-image): What `meta.image` points at.



# Email (/docs/components/renderings/email)

> Spec: written ahead of the package. Not in the published packages: email

> Six kinds of mail a product sends, drawn from the Product record and one event, each in the product's Theme with a plain-text twin.

`email(kind, product, event)` returns one message: `{ subject, html, text }`. The HTML is a table layout with its styles inline, in the product's Theme, because mail clients drop a stylesheet. The text is the same message without markup.

## What it renders

| Kind | Sent when | Reads from the event |
| --- | --- | --- |
| `welcome` | A key is issued | The key prefix and the first call |
| `usage` | A usage threshold is crossed | The calls used and the plan's limit |
| `limit` | The plan's limit is reached | The limit, the date it resets and the next plan |
| `webhook` | A webhook endpoint keeps failing | The endpoint, the last status and the retry count |
| `plan` | The plan changes | The old and the new plan |
| `billing` | A charge fails | The amount and the payment page |

Every kind reads the product's name, Theme and dashboard address from the [Product record](https://next.mdxui.dev/docs/components/product-record), so no message names a plan the pricing page does not.

## How it maps

startupbuilder.dev's [Template](https://startupbuilder.dev/business/nouns/template) renders "a Message, Document, or Page". Each kind of mail here is the Message rendering of one Template, filled from the event's records.

## Status

**Spec · email.**

`email` is not in `@mdxui/site@7.0.0-alpha.0`, and no Section type renders inside a message. Sending is the host's: the function returns the message and never sends it.

## Related

  - [The Product record](https://next.mdxui.dev/docs/components/product-record): What every message reads.
  - [Template](https://next.mdxui.dev/docs/components/template): A Message is one of its renderings.
  - [Renderings](https://next.mdxui.dev/docs/components/renderings): Every output format of one record.



# Embed (/docs/components/renderings/embed)

> One rendered section inside another site's page, isolated in a declarative shadow root, with no script.

Embed one section in another site's page through a declarative shadow root. Its styles stay inside, the host's stay out, and no script runs.

## What it renders

The section the steps below embed, a `command-row`, rendered alone as this site draws every preview:

Preview: every frame of command-row is listed in https://next.mdxui.dev/components/manifest.json

## Prerequisites

- The [quickstart](https://next.mdxui.dev/docs/start/quickstart) runs in your project, with `@mdxui/themes` installed as on [Packages and versions](https://next.mdxui.dev/docs/start/packages).
- A host page that loads the Theme's typefaces, since a shadow root inherits fonts from its host.

## Steps

1. Render the section under a Theme:

   ```ts
   const block = BlockSchema.parse({ type: 'command-row', command: 'npm i @example/harbor-tides', note: 'Node.js 22 or later' });
   const { theme, css } = THEMES.quaypoint;
   const html = renderBlock(block, context(theme, 'paper', theme.icons));
   ```

2. Wrap it in a shadow root with the Theme's tokens and the Section type CSS. The tokens move from `:root` to `:host`:

   ```ts
   // A declarative shadow root: the section's styles stay inside it, and the host's stay out. No script.
   const embed = `<div class="mdxui-embed">
     <template shadowrootmode="open">
       <style>${css().replaceAll(':root', ':host')}${baseCss}${primitivesCss}${blocksCss}</style>
       ${html}
     </template>
   </div>`;
   ```

3. Write `embed` into the host page's HTML, where the browser attaches the shadow root as it parses.

## Result

`embed.html`: a host paragraph, then the `command-row` in `quaypoint`, styled by its own sheet and untouched by the host's.

A React page that is prerendered, as a Fumadocs page is, writes the same string into its HTML. A page rendered in the browser attaches a shadow root with `attachShadow` and sets its `innerHTML` instead. This site's previews take a third path: each is a frame, an `iframe` of one prerendered section.

## Related

  - [HTML](https://next.mdxui.dev/docs/components/renderings/html): The four steps `renderBlock` is one of.
  - [The Theme contract](https://next.mdxui.dev/docs/themes/contract): The tokens the shadow root carries.
  - [command-row](https://next.mdxui.dev/docs/sections/command-row): The section this example embeds.



# HTML (/docs/components/renderings/html)

> Parse, render each Section type, compose, then wrap: how one Page record becomes one HTML document with one stylesheet and no framework.

`renderPage(page, { theme })` runs four steps and returns one HTML string: a document with one `<style>` element and no framework.

## What it renders

Harbor's blog index, one `renderPage` call. Widen it, narrow it to 390, or pick another Theme: every frame is a file the build wrote.

The rendered page: https://next.mdxui.dev/sites/harbor/blog; its record: https://next.mdxui.dev/pages/harbor/blog.json

## Four steps

| Step | Export | Does |
| --- | --- | --- |
| 1 | `PageSchema.parse` | Accepts the record or refuses it, naming each field over its bound |
| 2 | `renderBlock` | Renders each section's Section type, with a render context for the Theme and the shell `surface` it sits on |
| 3 | `compose` | Wraps each section in its shell, derives every divider from its neighbors, and draws the frame |
| 4 | `document` | Wraps the body in the head lines, the Theme's typefaces and one stylesheet |

[Document and head](https://next.mdxui.dev/docs/components/renderings/document-and-head) runs the four steps by hand and gets `renderPage`'s output byte for byte.

## A string, not a server

`renderPage` returns a string, so a build writes it to a file, as [Ship a Site](https://next.mdxui.dev/docs/start/ship) does, and a Worker returns it per request. Neither needs a runtime of its own.

## Without a script

27 of 27 Section types render no `<script>` element, each measured with every optional field set.

| Mechanism | Section types |
| --- | --- |
| `<details>` | `faq` |
| radio inputs | `terminal` |
| `popover` | `product-list` |
| inline `onclick` | `hero`, `feature-split`, `bento`, `steps`, `command-row`, `agent-prompt`, `closing`, `article` |

Every inline handler is a button's `onclick` that writes text to the clipboard: a copy control, or the article's copy-link button.

## Related

  - [Document and head](https://next.mdxui.dev/docs/components/renderings/document-and-head): The four steps, run by hand.
  - [Embed](https://next.mdxui.dev/docs/components/renderings/embed): One section inside another page.
  - [Ship a Site](https://next.mdxui.dev/docs/start/ship): Every record, written to files.



# Renderings (/docs/components/renderings)

> One Page record, seven renderings: HTML for people, JSON for agents, one section embedded elsewhere, and three written ahead of the package.

A rendering is one output format of a record. Every rendering reads the same fields under the same Theme, so a page and its share image never disagree. An [Interface](https://next.mdxui.dev/docs/components/interface), such as a Site, reaches its readers through several.

The badges are computed: Alpha ships in `@mdxui/site@7.0.0-alpha.0`, and Spec is written ahead of it.


# JSON (/docs/components/renderings/json)

> The record is its own JSON rendering: served beside each page, with the page schema and one schema per Section type beside it.

A Page record needs no converter to become JSON: it is JSON. This site serves every record beside its render, byte for byte. An agent reads the exact input of the page a person sees.

## What mdxui renders

Harbor's contact page as a person reads it, and as an agent reads it: open the Record tab.

The rendered page: https://next.mdxui.dev/sites/harbor/contact; its record: https://next.mdxui.dev/pages/harbor/contact.json

## Where this site serves it

| Address | Holds |
| --- | --- |
| [`/pages/home.json`](https://next.mdxui.dev/pages/home.json) | The landing's record |
| [`/pages/harbor/contact.json`](https://next.mdxui.dev/pages/harbor/contact.json) | One worked page's record; every worked page has one at `/pages/<site>/<path>.json` |
| [`/schema.json`](https://next.mdxui.dev/schema.json) | `PageSchema` as JSON Schema, for an editor or an agent |
| [`/schema/sections/hero.json`](https://next.mdxui.dev/schema/sections/hero.json) | One Section type's schema; there is one for each of the 27 |
| [`/components/variant/hero/split.json`](https://next.mdxui.dev/components/variant/hero/split.json) | One section record, as a Section type page's Record tab shows it |

## Validate it

JSON Schema carries the shape and the bounds. `PageSchema` carries them and the refinements JSON Schema cannot say, such as a head that needs a title or a lede, so validate with it:

```ts title="validate.ts"
import { PageSchema } from '@mdxui/site';

const record = await (await fetch('https://next.mdxui.dev/pages/harbor/contact.json')).json();
const result = PageSchema.safeParse(record);
if (!result.success) for (const issue of result.error.issues) console.log(issue.path.join('.'), issue.message);
```

Each issue names the path and the bound; [Refusals](https://next.mdxui.dev/docs/reference/refusals) gives the fix for each.

## Related

  - [schema.json](https://next.mdxui.dev/docs/agents/schema): Where JSON Schema stops.
  - [Page fields and bounds](https://next.mdxui.dev/docs/reference/page-schema): Every field, beside the smallest record.
  - [HTML](https://next.mdxui.dev/docs/components/renderings/html): The same record, for people.



# Markdown (/docs/components/renderings/markdown)

> Spec: written ahead of the package. Not in the published packages: pageMarkdown

> A page as Markdown, for an agent that reads text: every heading, line, list, table and code window of the record, in page order.

`pageMarkdown(page)` returns a Page record as one Markdown string, in the order the sections render. It reads the record, not the HTML, so nothing the Theme draws reaches the text.

## What it returns

Each Section type writes the Markdown form of its own fields:

| Section type | Writes |
| --- | --- |
| `hero` | The title as `#`, the lede as a paragraph, each action as a link |
| Any section head | Its title as `##` and its lede; the eyebrow is dropped |
| `feature-grid`, `feature-split`, `steps` | A list: each item's title in bold, then its text |
| `pricing`, `plan-table`, `compare`, `facts` | A table |
| `faq` | Each question as `###`, its answer as a paragraph |
| `terminal`, `api-call`, `command-row`, `agent-prompt` | A fence, with its language |
| `endpoints` | A table of method, path and text |
| `nav`, `footer` | A list of links, once |
| `article` | Its body, as written |

Harbor's pricing section, as specified:

```md title="pageMarkdown, the pricing section of pages/harbor/pricing.json"
## Priced by the call.

| Plan | Price | Includes |
| --- | --- | --- |
| Deck | $0 a month | 1,000 calls a month · Every berth · Fourteen days ahead |
| Bridge (Most chosen) | $49 a month | 50,000 calls a month · Draft windows · Webhook alerts |
| Harbor | $490 a month | 1,000,000 calls a month · Every Bridge feature · A named harbor master |
```

## Status

**Spec · pageMarkdown.**

`pageMarkdown` is not in `@mdxui/site@7.0.0-alpha.0`. Until it is, an agent reads the record itself, as [JSON](https://next.mdxui.dev/docs/components/renderings/json).

The `.md` twin of every docs page, such as [`/docs/components/site.md`](https://next.mdxui.dev/docs/components/site.md), is a feature of this docs site. It is built from the page's own MDX source, not by `pageMarkdown`. [Markdown and JSON twins](https://next.mdxui.dev/docs/agents/twins) covers it.

## Related

  - [JSON](https://next.mdxui.dev/docs/components/renderings/json): The rendering an agent reads today.
  - [Markdown and JSON twins](https://next.mdxui.dev/docs/agents/twins): This site's own text renderings.
  - [Renderings](https://next.mdxui.dev/docs/components/renderings): Every output format of one record.



# Share image (/docs/components/renderings/share-image)

> Spec: written ahead of the package. Not in the published packages: og

> The 1200 × 630 picture a shared link shows, drawn from the page's title and description, or the Product record, in the page's Theme.

`og(page, { theme })` draws the share image of a page: 1200 by 630 pixels, as an SVG string and as a PNG. The page's `meta.image` points at the file, and `renderPage` writes the share tags from it.

## What it draws

| Part | From |
| --- | --- |
| The Brand | The `nav` section's `brand`: its mark and its text |
| The title | The page's `title`, at most 64 characters, so it sets in two lines at most |
| The line beneath | The page's `description`, cut at a word to two lines |
| The paint | The Theme: its paper, ink, accent, display typeface and divider policy |
| The address | `meta.canonical`, less its scheme |

For a product, `og(product)` draws from the [Product record](https://next.mdxui.dev/docs/components/product-record) in place of a page: its name, its summary and its Theme.

## How it maps

The head half ships today. A record with a `meta.image` of a URL, a width and a height renders the `og:image` and `twitter:image` tags. [Document and head](https://next.mdxui.dev/docs/components/renderings/document-and-head) traces each tag to its field. The image itself is drawn by hand.

## Status

**Spec · og.**

`og` is not in `@mdxui/site@7.0.0-alpha.0`. A record with no `meta.image` shares as its title and description alone.

## Related

  - [Document and head](https://next.mdxui.dev/docs/components/renderings/document-and-head): The tags that point at it.
  - [The Product record](https://next.mdxui.dev/docs/components/product-record): What a product's image reads.
  - [Renderings](https://next.mdxui.dev/docs/components/renderings): Every output format of one record.



# Section (/docs/components/section)

> A section is a kind, a shell and one Section type: the kind places it among its neighbors, and the shell paints behind it.

> A Component is a named block of a Page, such as a hero, a pricing table, or a form, filled from records through typed props.
>
> startupbuilder.dev, [Component](https://startupbuilder.dev/business/nouns/component)

A section is one entry of a Page's `sections`: `{ kind, shell, block }`. The `block` is one [Section type](https://next.mdxui.dev/docs/sections), the mdxui drawing of a Component.

## What mdxui renders

The same `feature-grid` record on the four `surface` values of its shell. The record does not change; only the paint behind it does.

The kind picks the section's landmark and the divider before it, so no record names an element.

| `kind` | Wraps, on the living pages |
| --- | --- |
| `nav` | [`nav`](https://next.mdxui.dev/docs/sections/nav) |
| `bar` | [`nav`](https://next.mdxui.dev/docs/sections/nav) |
| `hero` | [`hero`](https://next.mdxui.dev/docs/sections/hero) |
| `band` | [`stats`](https://next.mdxui.dev/docs/sections/stats), [`statement`](https://next.mdxui.dev/docs/sections/statement), [`command-row`](https://next.mdxui.dev/docs/sections/command-row) |
| `section` | [`steps`](https://next.mdxui.dev/docs/sections/steps), [`compare`](https://next.mdxui.dev/docs/sections/compare), [`product-list`](https://next.mdxui.dev/docs/sections/product-list), [`feature-split`](https://next.mdxui.dev/docs/sections/feature-split), [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid), [`bento`](https://next.mdxui.dev/docs/sections/bento), [`facts`](https://next.mdxui.dev/docs/sections/facts), [`faq`](https://next.mdxui.dev/docs/sections/faq), [`terminal`](https://next.mdxui.dev/docs/sections/terminal), [`api-call`](https://next.mdxui.dev/docs/sections/api-call), [`endpoints`](https://next.mdxui.dev/docs/sections/endpoints), [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack), [`agent-prompt`](https://next.mdxui.dev/docs/sections/agent-prompt), [`post-list`](https://next.mdxui.dev/docs/sections/post-list), [`page-head`](https://next.mdxui.dev/docs/sections/page-head), [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form), [`pricing`](https://next.mdxui.dev/docs/sections/pricing), [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table), [`product-head`](https://next.mdxui.dev/docs/sections/product-head) |
| `article` | [`article`](https://next.mdxui.dev/docs/sections/article) |
| `closing` | [`closing`](https://next.mdxui.dev/docs/sections/closing) |
| `footer` | [`footer`](https://next.mdxui.dev/docs/sections/footer) |

| Shell field | Values | Required |
| --- | --- | --- |
| `id` | `string, pattern ^[a-z][a-z0-9-]{0,23}$` | no |
| `inset` | `"contained" \| "bleed" \| "article" \| "listing"` | yes |
| `density` | `"none" \| "section" \| "compact" \| "hero" \| "closing" \| "footer" \| "access" \| "article" \| "listing"` | yes |
| `surface` | `"paper" \| "tint" \| "plate" \| "glass"` | no |
| `background` | `"none" \| "dots" \| "grain" \| "glow"` | no |
| `sticky` | `boolean` | no |
| `aside` | `boolean` | no |

A Section type never paints itself: the shell carries the `surface`, the `background`, the `inset` and the `density`. A sticky bar names its `surface`, so it stays opaque.

## How it maps

  - **name** (alpha): `block.type`, one of 27 Section types; `Pricing` is drawn by `pricing`
  - **props** (alpha): The `block` fields: every string bounded, every list counted
  - **region: header** (alpha): `kind: nav`, the bar a page opens with
  - **region: section** (alpha): `kind`: `hero`, `band`, `section`, `article` or `closing`
  - **region: footer** (alpha): `kind: footer`, the last section of every page
  - **region: notice** (gap): No notice Section type. `kind: bar` opens a page in place of `nav`, and no worked Site uses it
  - **interactive** (alpha): No script beyond copy buttons: `faq` opens with `details`, `terminal` switches with radio inputs
  - **filled from records** (gap): Literal props, written by the agent from the records

## Sections inside a section

Four Section types hold others in their `specimen` field: `hero`, `feature-split`, `steps` and `closing`, one to three each. A `bento` panel holds exactly one [`terminal`, `agent-prompt` or `api-call`](https://next.mdxui.dev/docs/reference/refusals#bento.panels). Nesting stays data: a slot holds records, never markup.

## The section head

`SectionHeadSchema` is the head most Section types share: an `eyebrow`, an optional `title` and `lede`, a `scale` and a `split` layout. The eyebrow is required, and a head needs a title or a lede.

## Status

Every field above parses and renders in `@mdxui/site@7.0.0-alpha.0`. The one gap is the binding: a section takes literal words, not a record to read them from.

## Related

  - [Section types](https://next.mdxui.dev/docs/sections): All 27, each rendered in five Themes.
  - [Page](https://next.mdxui.dev/docs/components/page): Three to twenty sections, in order.
  - [The catalog, mapped](https://next.mdxui.dev/docs/components): startupbuilder.dev's UI catalog against the Section types.



# Site (/docs/components/site)

> Spec: written ahead of the package. Not in the published packages: site, sitemap

> A Site's Pages, navigation and Brand, rendered as a folder of Page records under one Theme, with its 404, contact and terms pages.

> A Site is a website as a Thing: its Pages, navigation, and Brand, served on one or more Domains.
>
> startupbuilder.dev, [Site](https://startupbuilder.dev/business/nouns/site)

## What mdxui renders

A Site is a folder of [Page](https://next.mdxui.dev/docs/components/page) records that all name one Theme, plus a 404 record. Each worked Site below is one, rendered whole by `@mdxui/site`.

| Part | Comes from | Built by |
| --- | --- | --- |
| Every Page under the origin | One [Page](https://next.mdxui.dev/docs/components/page) record each, all naming one Theme | `renderPage` per record, or `site.ts`'s `render` under your own Theme |
| The header on every Page | One `nav` section, the same on each Page | the [`nav`](https://next.mdxui.dev/docs/sections/nav) Section type |
| The footer on every Page | One `footer` section, the same on each Page | the [`footer`](https://next.mdxui.dev/docs/sections/footer) Section type |
| A 404 page | `pages/harbor/404.json`, the `article` Template | `ship.ts`, as `dist/404.html` |
| A contact page | `pages/harbor/contact.json`, the `contact` Template | the [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) Section type, and `worker.ts` on `/contact/send` |
| A terms page | `pages/harbor/terms.json`, the `article` Template | `renderPage` |
| `sitemap.xml` and `robots.txt` | The Pages, less the 404 and any record marked `noindex` | `ship.ts`; `@mdxui/site#sitemap`, intended |
| Share images | One per Page, from its `meta.image` | `renderPage` writes the tags; the images are drawn by hand, and generated images are intended |

## How it maps

  - **Pages** (alpha): One Page record per address, `pages/<site>/<path>.json`, rendered by `renderPage`
  - **navigation** (alpha): A `nav` and a `footer` section in each record
  - **Brand** (alpha): The record's `theme`: one of five Themes, the same on every Page
  - **Domains** (host): The host serves the files; [Ship a Site](https://next.mdxui.dev/docs/start/ship) deploys them to a Worker
  - **sites/[site]/** (alpha): A folder of JSON records in place of MDX Page files
  - **layout.mdx** (gap): No shared layout: each record repeats its `nav` and `footer` sections
  - **[key]/ routes** (gap): No Collection route: each member is a record of its own
  - **not-found.mdx** (alpha): `404.json`, an `article` record, written as `404.html`
  - **Portal** (study): The signed-in part belongs to the App; see [App types](https://next.mdxui.dev/docs/app)
  - **the whole Site in one call** (spec): `site({ origin, theme, pages })`
  - **sitemap and robots** (spec): `sitemap(pages)`; [Ship a Site](https://next.mdxui.dev/docs/start/ship) writes both by hand

## Status

Every Page of a Site renders today, one `renderPage` call per record. A Site renders whole or not at all, so [Ship a Site](https://next.mdxui.dev/docs/start/ship) refuses a folder with no 404 record or with a second Theme.

**Spec · site() and sitemap().**

`site()` builds a whole Site in one call and refuses the same two cases. Neither it nor `sitemap()` is in `@mdxui/site@7.0.0-alpha.0`.

```ts title="site(), as specified"
// path → file: every Page as HTML, then 404.html, sitemap.xml and robots.txt
const files: Map<string, string> = site({ origin, theme, pages });
// theme: a bundled name or a Theme entry, the shape THEMES holds each Theme in
// pages: path → Page record; '/404' and '/terms' are required
// refused: a missing 404 or terms page, or a record under a second Theme
```

## Intended Noun

The record a Site needs, drafted where today's folder of records has a gap: one header, one footer and one logo, written once.

```yaml title="intended Noun: Site record (mdxui.dev namespace)"
noun: Site record
projects: startupbuilder.dev Site, quoted above; defines nothing new
fields:
  origin: { type: URL, required: true }
  theme: { type: Theme, required: true, note: one Theme for every Page }
  pages: { type: Page, count: 1 or more, required: true }
  header: { type: section, holds: nav, required: true, note: written once, drawn on every Page }
  footer: { type: section, holds: footer, required: true, note: written once, drawn on every Page }
  logo: { type: SVG asset path, required: false, note: drawn at the brand mark's size in the Theme's ink }
  contact: { type: URL, required: false, note: the address /contact/send forwards to }
  terms: { type: Page, template: article, required: true }
  notFound: { type: Page, template: article, required: true }
```

## Related

  - [Page](https://next.mdxui.dev/docs/components/page): One record, one address.
  - [Brand and Theme](https://next.mdxui.dev/docs/components/brand-and-theme): The one line every Page shares.
  - [Ship a Site](https://next.mdxui.dev/docs/start/ship): Every record to one served Site.



# Template (/docs/components/template)

> Each kind of page is a Template: a Page names one of seven in its template field, and the Template says which Section types it carries.

> A Template is reusable Content with variables, filled from Things in the graph and authored as MDX, rendering a Message, Document, or Page.
>
> startupbuilder.dev, [Template](https://startupbuilder.dev/business/nouns/template)

In mdxui, each kind of page is a Template, and a Page names its kind in `template`. A set of packages styled for one look is a template package, never a Template.

## What mdxui renders

The seven Templates, each drawn from a worked Site that uses it. Open one for its Section types in order and a starter record.

| `template` | The page | Section types it carries |
| --- | --- | --- |
| `api-product` | A product landing | `nav`, `hero`, the feature and code types, `pricing`, `faq`, `closing`, `footer` |
| `article` | A reading page, a 404 or terms | `article` |
| `blog` | A blog index | `post-list` |
| `post` | One post | `page-head`, `article` |
| `contact` | A contact page | `cta-form` |
| `directory-list` | A directory of products | `product-list` |
| `directory-product` | One product in a directory | `product-head`, `facts`, `pricing` |

The two directory kinds wear the `directory` Theme: monochrome, one typeface, a tool rather than a landing.

## How it maps

  - **rendering a Page** (alpha): `template`, one of seven page kinds
  - **places Components** (spec): Slots: which Section type fills each, in order, and how many
  - **variables** (gap): None: the agent writes every value into the record
  - **authored as MDX** (gap): Authored as JSON, so a page parses or is refused
  - **rendering a Message** (spec): The [Email](https://next.mdxui.dev/docs/components/renderings/email) rendering
  - **rendering a Document** (gap): No Document rendering

## Status

`PageSchema` accepts the seven ids and checks no slot: a `blog` page that holds a `pricing` section parses.

**Spec · slot rules.**

A Template states its slots in page order: the Section types that may fill each, whether it is required, and its count. A page that breaks a slot rule is refused at its path, as a field past its bound is. The rules are not in `@mdxui/site@7.0.0-alpha.0`.

## Intended Noun

```yaml title="intended Noun: Template slots (mdxui.dev namespace)"
noun: Template slots
projects: startupbuilder.dev Template, quoted above; the page kinds only
fields:
  id: { type: enum, values: [api-product, article, blog, post, contact, directory-list, directory-product], required: true }
  slots:
    type: list of Slot, in page order, required: true
    Slot:
      name: { type: string, max: 32, required: true, example: how it works }
      fills: { type: list of Section type, count: 1 or more, required: true }
      required: { type: boolean, required: true }
      count: { type: integer range, example: exactly 4 }
  rules: { type: list of cross-slot rules, example: at least one section shows code }
example: api-product
  slots: nav, hero with an action, how it works, compare?, product, integration?, provenance?, confidence?, developers?, pricing?, faq, closing with actions, footer with a For agents column
```

## Related

  - [Templates](https://next.mdxui.dev/docs/showcase/templates): Each one live, with a starter record.
  - [Page](https://next.mdxui.dev/docs/components/page): The record that names a Template.
  - [Renderings](https://next.mdxui.dev/docs/components/renderings): One record, every output format.



# Sites your agent writes. Brands it cannot break. (/docs)

> mdxui renders a Business's pages from records its agent writes, in its own brand, and the design holds whatever the agent writes.



## Tasks

## Start from a Business like yours

Six worked examples, not customers. Each is a whole Site: real records, one Theme, a 404 and a contact flow. Open the one closest to yours and copy its records.

## What ships

Every page carries one badge. Alpha ships on npm, Spec is written ahead of the package, and Study defines nothing.

## For agents

An agent reads the same docs as text, starts from a record that parses and checks its work against the schema.

  - [llms.txt](https://next.mdxui.dev/llms.txt): The install, the calls and the docs index, instructions first.
  - [schema.json](https://next.mdxui.dev/schema.json): Every bound of a Page record as JSON Schema.
  - [catalog.json](https://next.mdxui.dev/catalog.json): Section types, Themes, Templates and frames, by address.
  - [starter.zip](https://next.mdxui.dev/starter.zip): One record and the script that renders it.



# Release notes (/docs/reference/changelog)

> What each publish of @mdxui/site and @mdxui/themes holds, from 7.0.0-alpha.0, and what each leaves to a later one.

Both packages publish together, at one version. They are alpha, unlicensed and closed source: install them from npm, and read their types, schemas and renders here.

## 7.0.0-alpha.0

Published to npm on 8 October 2026: the first release of `@mdxui/site`, and `@mdxui/themes` at the same version. Earlier versions under the mdxui name are an earlier design; [Coming from earlier mdxui](https://next.mdxui.dev/docs/start/from-earlier-mdxui) maps one to the other.

```bash
pnpm add @mdxui/site@7.0.0-alpha.0 @mdxui/themes@7.0.0-alpha.0
```

### @mdxui/site

| Holds | Detail |
| --- | --- |
| The record | `PageSchema`, `SectionSchema`, `SectionHeadSchema` and `BlockSchema`, each a Zod schema with every string bounded and every list counted |
| 27 Section types | `BLOCKS`: each type's CSS and renderer, from `nav` to `product-list` |
| The renderer | `renderPage`, and its four steps: `renderBlock`, `compose`, `document` and the shell CSS |
| Code | `highlight` and `HIGHLIGHT_LANGUAGES`, 44 names |
| Icons | 52 Lucide glyphs and 7 brand marks, inline or as images |
| In all | 33 runtime exports; each is on [@mdxui/site exports](https://next.mdxui.dev/docs/reference/site-exports) |

### @mdxui/themes

| Holds | Detail |
| --- | --- |
| Five Themes | `THEMES`: `certificate`, `vaultline`, `quaypoint`, `callboard` and `directory`, each with its typefaces' head lines |
| The contract | `CORE`, the 21 roles every Theme sets, and `DEFAULTS`, the derived roles |
| Your own Theme | `compileTheme` and `resolveTokens` |
| In all | 8 runtime exports; each is on [@mdxui/themes exports](https://next.mdxui.dev/docs/reference/themes-exports) |

### Not in this publish

Each of these has a page written ahead of it, badged Spec:

| Export | Page |
| --- | --- |
| `site`, `sitemap` | [Site](https://next.mdxui.dev/docs/components/site) |
| `pageMarkdown` | [Markdown](https://next.mdxui.dev/docs/components/renderings/markdown) |
| `og` | [Share image](https://next.mdxui.dev/docs/components/renderings/share-image) |
| `email` | [Email](https://next.mdxui.dev/docs/components/renderings/email) |
| `agentPrompt` | [The Product record](https://next.mdxui.dev/docs/components/product-record) |
| `templates` and its slot rules | [Template](https://next.mdxui.dev/docs/components/template#status) |
| `@mdxui/app` | [App](https://next.mdxui.dev/docs/components/app), a Study |

Every page's badge against this publish is on Maintainers › [Status](https://next.mdxui.dev/docs/maintainers/status).


# Closed sets (/docs/reference/closed-sets)

> Every value an enum field accepts: icon names, brand marks, highlighter languages and each smaller set, by field.

A closed set is the list of values one field accepts; any other value is refused. Generated from `PageSchema.toJSONSchema()`.

From `@mdxui/site@7.0.0-alpha.0`. The language set equals `HIGHLIGHT_LANGUAGES`, 44 names.

## Icon names

52 values, accepted by `closing.actions.icon`, `feature-grid.items.icon`, `feature-split.items.icon`, `footer.brand.mark`, `footer.cta.icon`, `hero.actions.icon`, `nav.brand.mark`, `product-head.actions.icon`, `product-head.mark`, `product-list.rows.mark`, `product-list.views.icon`, `stats.items.icon`.

```text
activity anchor arrow-right arrow-up-right badge-check bell blocks bot check chevron-down chevron-left chevron-right clock code compass copy credit-card database file-code-2 file-text files film fingerprint gauge git-commit-horizontal globe history key-round landmark layers layout-grid library link list map-pin menu message-square mic plug radar refresh-cw search shield-check ship shopping-cart sliders-horizontal sparkles terminal ticket waves webhook x
```

## Highlighter languages

44 values, accepted by `terminal.lang`.

```text
text bash sh shell zsh console curl http json jsonc js javascript jsx ts typescript tsx py python go golang rb ruby php java kt kotlin cs csharp rs rust swift sql graphql gql yaml yml toml ini env dotenv html xml diff patch
```

## Every other set

| Values | Fields |
| --- | --- |
| `"none"`, `"section"`, `"compact"`, `"hero"`, `"closing"`, `"footer"`, `"access"`, `"article"`, `"listing"` | `shell.density` |
| `"nav"`, `"bar"`, `"hero"`, `"band"`, `"section"`, `"article"`, `"closing"`, `"footer"` | `section.kind` |
| `"bluesky"`, `"github"`, `"linkedin"`, `"npm"`, `"reddit"`, `"x"`, `"ycombinator"` | `footer.social.mark` |
| `"api-product"`, `"article"`, `"blog"`, `"post"`, `"contact"`, `"directory-list"`, `"directory-product"` | `page.template` |
| `"label"`, `"icon-index"`, `"icon-label"`, `"icon"`, `"none"` | `feature-grid.cellHead` |
| `"GET"`, `"POST"`, `"PUT"`, `"PATCH"`, `"DELETE"` | `api-call.method`, `endpoints.rows.method` |
| `"reddit"`, `"x"`, `"linkedin"`, `"bluesky"`, `"hackernews"` | `article.share.on` |
| `"certificate"`, `"vaultline"`, `"quaypoint"`, `"callboard"`, `"directory"` | `page.theme` |
| `"contained"`, `"bleed"`, `"article"`, `"listing"` | `shell.inset` |
| `"paper"`, `"tint"`, `"plate"`, `"glass"` | `shell.surface` |
| `"none"`, `"dots"`, `"grain"`, `"glow"` | `shell.background` |
| `"columns"`, `"areas"`, `"row"` | `footer.layout` |
| `"none"`, `"sheet"`, `"split"` | `page.frame` |
| `"overlay"`, `"push"` | `nav.menu` |
| `820`, `880` | `nav.collapse` |
| `"centered"`, `"split"` | `hero.layout` |
| `560`, `640` | `hero.stack` |
| `"solid"`, `"ghost"` | `closing.actions.kind`, `hero.actions.kind`, `product-head.actions.kind` |
| `"none"`, `"field"` | `closing.specimen.panel`, `feature-split.specimen.panel`, `hero.specimen.panel`, `steps.specimen.panel` |
| `"compact"`, `"large"` | `bento.head.scale`, `closing.head.scale`, `compare.head.scale`, `cta-form.head.scale`, `endpoints.head.scale`, `faq.head.scale`, `feature-grid.head.scale`, `feature-split.head.scale`, `pricing.head.scale`, `stats.head.scale`, `steps.head.scale`, `text-stack.head.scale` |
| `"stack"`, `"grid"` | `text-stack.layout` |
| `"after"`, `"both"` | `terminal.tabs.lines.space` |
| `"sm"`, `"lg"` | `terminal.tabs.lines.gap` |
| `"ruled"`, `"cards"` | `pricing.layout` |
| `"stack"`, `"split"` | `closing.layout` |
| `"list"`, `"cards"` | `product-list.view` |



# Glossary (/docs/reference/glossary)

> One meaning per term: startupbuilder.dev terms quoted and linked, terms these docs define, and mdxui-only terms marked provisional.

startupbuilder.dev, its sites and these docs share one vocabulary. A term startupbuilder.dev defines is quoted here, never redefined. Earlier meanings of each term, and what became of them, are under Maintainers › [Prior definitions](https://next.mdxui.dev/docs/maintainers/prior-definitions).

## From startupbuilder.dev

  - **App** ([definition](https://startupbuilder.dev/business/nouns/app)): An App is an Interface where people work with a Product’s Nouns and Verbs through screens, backed by its API.
  - **Brand** ([definition](https://startupbuilder.dev/business/nouns/brand)): A Brand is a name, a voice, a logo, and a style under which a Startup makes Offers.
  - **Component** ([definition](https://startupbuilder.dev/business/nouns/component)): A Component is a named block of a Page, such as a hero, a pricing table, or a form, filled from records through typed props.
  - **Dashboard** ([definition](https://startupbuilder.dev/business/nouns/dashboard)): A Dashboard is one unified view of a scope, rendered as Markdown for Agents, screens for Humans, and JSON for native clients.
  - **Domain** ([definition](https://startupbuilder.dev/business/nouns/domain)): A Domain is a hostname that points at a Thing, with a role, a status, and a lifecycle tracked as data.
  - **Interface** ([definition](https://startupbuilder.dev/business/nouns/interface)): An Interface is how a person or an Agent reaches a Product: an API, MCP server, CLI, SDK, Site, or App.
  - **Offer** ([definition](https://startupbuilder.dev/business/nouns/offer)): An Offer is a Product, under a Brand, at a price, on terms, made by a Startup.
  - **Page** ([definition](https://startupbuilder.dev/business/nouns/page)): A Page is an addressable page of a Site, of a named type such as pricing, about one Thing or each member of a Collection.
  - **Product** ([definition](https://startupbuilder.dev/business/nouns/product)): A Product is what a Customer gets from a Startup, with a promise the Customer can rely on.
  - **Site** ([definition](https://startupbuilder.dev/business/nouns/site)): A Site is a website as a Thing: its Pages, navigation, and Brand, served on one or more Domains.
  - **Startup** ([definition](https://startupbuilder.dev/business/nouns/startup)): A Startup is the smallest business that can be moved, promoted, or sold on its own, with its own Products, Offers, Customers, and P&L.
  - **Template** ([definition](https://startupbuilder.dev/business/nouns/template)): A Template is reusable Content with variables, filled from Things in the graph and authored as MDX, rendering a Message, Document, or Page.
  - **Theme** ([definition](https://startupbuilder.dev/business/nouns/theme)): A Theme is the design tokens of a Brand, its color, type, spacing, radius, and motion, that every Component reads when it renders.

## Defined here

  - **Business**: The genus of Startup: every Startup is a Business, and not every Business is one. A page says what holds for any Business first, then what the Startup layer adds.
  - **frame**: The page frame only: the `frame` field, `none`, `sheet` or `split`.
  - **ListSection**: The list a Component holds, such as the items of a feature grid.
  - **OfferTile**: One Offer drawn as a Tile: its name, price, lines and action. The `tiers` field of `pricing` holds them.
  - **rendering**: One output format of a record: HTML, JSON, Markdown, a share image or an email. Never an Interface.
  - **Section type**: One of the 27 layouts a section names in `block.type`, such as `hero` or `pricing`: the mdxui drawing of a Component.
  - **template package**: A set of packages styled for one look. Never a Template.
  - **Theme, as mdxui draws it**: The same Theme: a Brand's tokens plus its render policies, named by a Page in its `theme` field.
  - **Tile**: The root of every item a section lists, such as a feature or a plan. The payment credential keeps the startupbuilder.dev name.
  - **typeface**: A letterform family a Theme loads: display, text and mono.
  - **UsageGauge**: The display of usage against a limit. Billable usage keeps the startupbuilder.dev name.
  - **View**: An arrangement of Components bound to records. Dashboard extends View.

## Working terms

Working terms: mdxui-only words, each used in one meaning while the vocabulary settles.

  - **bound**: The most characters or items one field accepts.
  - **closed set**: The values one field accepts; any other value is refused.
  - **policy**: A render choice a Theme makes once, such as `dividers` or `featured`.
  - **preview**: A live render of a record on a docs page: an iframe of a file the build wrote. Maintainers call it a specimen.
  - **record**: A Page record: the JSON `PageSchema` parses. A record this site renders on every build is a living page.
  - **refusal**: The parse error that names a field past its bound, at its path.
  - **Slot**: A position a Template names for a section, such as the hero of a landing; slot rules are Spec. The App design has not settled what a slot is inside an App, so this name can change.
  - **role**: A named Theme token, such as `paper` or `accent`, that a Section type reads.
  - **section**: One entry of a Page's `sections`: a kind, a shell and one Section type.
  - **shell**: The fields that place and paint a section: `inset`, `density`, `surface`, `background`, `sticky` and `aside`.
  - **theme contract**: The roles and policies every Theme fills.
  - **worked Site**: A Site built here for one kind of Business: a worked example, not a customer.



# Icons (/docs/reference/icons)

> Every Lucide glyph and brand mark a record may name, drawn by the renderer itself.

A record names a glyph and never carries one. The renderer draws it in the ink of the text beside it, inline or as an image, as the Theme's `icons` policy says. Each glyph below is that drawing, from `context(THEMES.certificate.theme).icon()` at build. Any other name is refused at its path, as [Closed sets](https://next.mdxui.dev/docs/reference/closed-sets#icons) lists.

## Glyphs

## Brand marks

A mark links a footer to a profile on another site. It is never an endorsement.



# Reference (/docs/reference)

> Every export, field, bound, refusal and closed set of the published packages, generated from them on every build.

Each page below is read from `@mdxui/site@7.0.0-alpha.0` and `@mdxui/themes@7.0.0-alpha.0` as installed, so a table here cannot drift from the packages: `pnpm check` fails first.

## The record

  - [Page fields and bounds](https://next.mdxui.dev/docs/reference/page-schema): Every Page, section and shell field, beside the smallest record that parses.
  - [Refusals](https://next.mdxui.dev/docs/reference/refusals): Every bound by path, the exact message, and the fix.
  - [Closed sets](https://next.mdxui.dev/docs/reference/closed-sets): Every value an enum field accepts.
  - [Icons](https://next.mdxui.dev/docs/reference/icons): Each glyph and brand mark, drawn by the renderer.
  - [Highlight languages](https://next.mdxui.dev/docs/reference/languages): Each name with a sample line, colored by the highlighter.

## The packages

  - [@mdxui/site exports](https://next.mdxui.dev/docs/reference/site-exports): Each runtime export with its signature.
  - [@mdxui/themes exports](https://next.mdxui.dev/docs/reference/themes-exports): Each export, and every role a Theme fills.

## Words and releases

  - [Glossary](https://next.mdxui.dev/docs/reference/glossary): One meaning per term, with its owner.
  - [Release notes](https://next.mdxui.dev/docs/reference/changelog): What each publish holds.

## How these docs are built

  - [Maintainers](https://next.mdxui.dev/docs/maintainers): Page status, render checks, coverage and prior definitions, for the people who keep these docs.



# Highlight languages (/docs/reference/languages)

> Every language and alias a code window highlights, each with a sample line colored by the renderer's own highlighter.

A `terminal` section's `lang`, and every code window a Section type draws, names one of these. The highlighter is small and fixed: keywords, strings, comments and the added and removed lines of a diff. A name it does not know is refused at its path, as [Closed sets](https://next.mdxui.dev/docs/reference/closed-sets#languages) lists.



# Page fields and bounds (/docs/reference/page-schema)

> Every Page, section and shell field: its type, its bounds and the anchor of its refusal, beside the smallest record that parses.

Point at a field to light the line of the smallest record that sets it. Each Section type's own fields are on its page under [Section types](https://next.mdxui.dev/docs/sections).



# Refusals (/docs/reference/refusals)

> Every refusal PageSchema returns, by path, with its bound and the fix.

A refusal is the parse error naming a field over its bound, and the fix is shorter content. A path's anchor is the block's `type`, then the path after `block` with list indexes dropped: `sections.1.block.title` on a `hero` is `#hero.title`. A shell path is `#shell.<field>`, and a field of the Page is `#page.<field>`.

From `@mdxui/site@7.0.0-alpha.0`: 285 anchors. `pnpm check` trips 262 of the bounds on a built record and checks each message below against the one returned.

| Refusal | Message, as `safeParse` returns it | Fix |
| --- | --- | --- |
| A string past its bound | `Too big: expected string to have <=160 characters` | Shorten the content |
| A list past its count | `Too big: expected array to have <=6 items` | Drop items |
| A list short of its count | `Too small: expected array to have >=1 items` | Add items |
| A list off its one count | `Too big: expected array to have exactly 3 items` | Hold the count exactly |
| A number past its range | `Too big: expected number to be <=640` | Use a value inside the range |
| An empty string | `Too small: expected string to have >=1 characters` | Write the value, or leave the field out where it is optional |

## page

| Anchor | Bound |
| --- | --- |
| `page.title` | 64 characters |
| `page.description` | 320 characters |
| `page.meta.canonical` | 160 characters |
| `page.meta.icon` | 160 characters |
| `page.meta.iconFallback` | 160 characters |
| `page.meta.appleTouchIcon` | 160 characters |
| `page.meta.image.url` | 160 characters |
| `page.meta.image.width` | 200 to 2400 |
| `page.meta.image.height` | 200 to 2400 |
| `page.sections` | 3 to 20 items |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `page.theme` | `Invalid option: expected one of "certificate"\|"vaultline"\|"quaypoint"\|"callboard"\|"directory"` | Name a bundled Theme, or render under your own with `render`, as in [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme) |

## shell

| Anchor | Bound |
| --- | --- |
| `shell.id` | `^[a-z][a-z0-9-]{0,23}$`: a lowercase letter, then at most 23 letters, digits and hyphens |

## nav

| Anchor | Bound |
| --- | --- |
| `nav.brand.href` | 160 characters |
| `nav.brand.text` | 16 characters |
| `nav.brand.suffix` | 8 characters |
| `nav.links` | at most 6 items |
| `nav.cta.href` | 160 characters |
| `nav.cta.label` | 24 characters |
| `nav.search.action` | 160 characters |
| `nav.search.placeholder` | 40 characters |
| `nav.search.query` | 120 characters |
| `nav.search.clear` | 160 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `nav.brand` | `a brand needs a wordmark or a mark` | Give the brand a wordmark (`text`) or a `mark` |
| `nav` | `a bar's row holds 96 units (its link labels, 3 a link, and twice the wider of the brand and the button); shorten a label or drop a link` | Shorten a link label or drop a link |

## footer

| Anchor | Bound |
| --- | --- |
| `footer.brand.href` | 160 characters |
| `footer.brand.text` | 16 characters |
| `footer.brand.suffix` | 8 characters |
| `footer.blurb` | 160 characters |
| `footer.columns` | at most 4 items |
| `footer.columns.title` | 16 characters |
| `footer.columns.label` | 40 characters |
| `footer.columns.links` | 1 to 12 items |
| `footer.cta.href` | 160 characters |
| `footer.cta.label` | 24 characters |
| `footer.social` | at most 6 items |
| `footer.social.href` | 160 characters |
| `footer.form.action` | 160 characters |
| `footer.form.label` | 24 characters |
| `footer.form.placeholder` | 32 characters |
| `footer.form.submit` | 16 characters |
| `footer.note` | exactly 2 items |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `footer.brand` | `a brand needs a wordmark or a mark` | Give the brand a wordmark (`text`) or a `mark` |
| `footer` | `a footer in columns holds two or three of them` | Use two or three columns |
| `footer` | `a footer in columns has a "For agents" column` | Title one column "For agents" |

## hero

| Anchor | Bound |
| --- | --- |
| `hero.kicker.text` | 40 characters |
| `hero.title` | 64 characters |
| `hero.lede` | 260 characters |
| `hero.actions` | at most 2 items |
| `hero.actions.href` | 160 characters |
| `hero.actions.label` | 24 characters |
| `hero.command.command` | 40 characters |
| `hero.command.note` | 48 characters |
| `hero.fine` | at most 4 items |
| `hero.specimen.blocks` | 1 to 3 items |

## statement

| Anchor | Bound |
| --- | --- |
| `statement.text` | 140 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `statement.text` | `` a statement is plain words and one `*accent phrase*`: no code, link, strong or mark `` | Write plain words and at most one `*accent phrase*` |

## page-head

| Anchor | Bound |
| --- | --- |
| `page-head.title` | 64 characters |
| `page-head.lede` | 200 characters |

## stats

| Anchor | Bound |
| --- | --- |
| `stats.head.eyebrow` | 28 characters |
| `stats.head.title` | 72 characters |
| `stats.head.lede` | 300 characters |
| `stats.head.tag` | 8 characters |
| `stats.items` | 3 to 4 items |
| `stats.items.value` | 6 characters |
| `stats.items.label` | 72 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `stats.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## facts

| Anchor | Bound |
| --- | --- |
| `facts.title` | 48 characters |
| `facts.items` | 1 to 16 items |
| `facts.items.label` | 24 characters |
| `facts.items.value` | 80 characters |
| `facts.items.href` | 160 characters |

## feature-grid

| Anchor | Bound |
| --- | --- |
| `feature-grid.head.eyebrow` | 28 characters |
| `feature-grid.head.title` | 72 characters |
| `feature-grid.head.lede` | 300 characters |
| `feature-grid.head.tag` | 8 characters |
| `feature-grid.aside.command` | 12 characters |
| `feature-grid.aside.note` | 40 characters |
| `feature-grid.items` | 2 to 8 items |
| `feature-grid.items.label` | 24 characters |
| `feature-grid.items.index` | 2 characters |
| `feature-grid.items.title` | 40 characters |
| `feature-grid.items.text` | 200 characters |
| `feature-grid.items.href` | 160 characters |
| `feature-grid.items.linkLabel` | 24 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `feature-grid.head` | `a head needs a title or a lede` | Give the head a title or a lede |
| `feature-grid.items` | `a feature grid holds 2, 3, 4, 6, 8 cells: a count that fills its rows at every width` | Use 2, 3, 4, 6 or 8 items |
| `feature-grid.items` | `an item needs a title or a text` | Give the item a title or a text |

## feature-split

| Anchor | Bound |
| --- | --- |
| `feature-split.head.eyebrow` | 28 characters |
| `feature-split.head.title` | 72 characters |
| `feature-split.head.lede` | 300 characters |
| `feature-split.head.tag` | 8 characters |
| `feature-split.bases` | exactly 2 items |
| `feature-split.items` | exactly 3 items |
| `feature-split.items.index` | 2 characters |
| `feature-split.items.title` | 28 characters |
| `feature-split.items.text` | 96 characters |
| `feature-split.items.bullets` | at most 4 items |
| `feature-split.specimen.blocks` | 1 to 3 items |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `feature-split.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## bento

| Anchor | Bound |
| --- | --- |
| `bento.head.eyebrow` | 28 characters |
| `bento.head.title` | 72 characters |
| `bento.head.lede` | 300 characters |
| `bento.head.tag` | 8 characters |
| `bento.panels` | 2 to 4 items |
| `bento.panels.title` | 48 characters |
| `bento.panels.text` | 120 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `bento.head` | `a head needs a title or a lede` | Give the head a title or a lede |
| `bento.panels` | `a bento panel holds one specimen: terminal, agent-prompt, api-call` | Hold one `terminal`, `agent-prompt`, `api-call` in the tile |

## compare

| Anchor | Bound |
| --- | --- |
| `compare.head.eyebrow` | 28 characters |
| `compare.head.title` | 72 characters |
| `compare.head.lede` | 300 characters |
| `compare.head.tag` | 8 characters |
| `compare.cons.label` | 24 characters |
| `compare.cons.items` | 1 to 8 items |
| `compare.pros.label` | 24 characters |
| `compare.pros.items` | 1 to 8 items |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `compare.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## steps

| Anchor | Bound |
| --- | --- |
| `steps.head.eyebrow` | 28 characters |
| `steps.head.title` | 72 characters |
| `steps.head.lede` | 300 characters |
| `steps.head.tag` | 8 characters |
| `steps.more` | at most 2 items |
| `steps.steps` | 3 to 5 items |
| `steps.specimen.blocks` | 1 to 3 items |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `steps.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## text-stack

| Anchor | Bound |
| --- | --- |
| `text-stack.head.eyebrow` | 28 characters |
| `text-stack.head.title` | 72 characters |
| `text-stack.head.lede` | 300 characters |
| `text-stack.head.tag` | 8 characters |
| `text-stack.items` | 3 to 6 items |
| `text-stack.items.title` | 28 characters |
| `text-stack.items.text` | 160 characters |
| `text-stack.items.href` | 160 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `text-stack.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## terminal

| Anchor | Bound |
| --- | --- |
| `terminal.title` | 48 characters |
| `terminal.lines` | 1 to 32 items |
| `terminal.tabs` | 1 to 4 items |
| `terminal.tabs.label` | 6 characters |
| `terminal.tabs.lines` | 1 to 24 items |
| `terminal.tabs.lines.cmd` | 64 characters |
| `terminal.tabs.lines.row` | exactly 2 items |
| `terminal.tabs.lines.out` | 64 characters |
| `terminal.tabs.lines.text` | 128 characters |

## command-row

| Anchor | Bound |
| --- | --- |
| `command-row.command` | 40 characters |
| `command-row.note` | 48 characters |

## api-call

| Anchor | Bound |
| --- | --- |
| `api-call.path` | 72 characters |
| `api-call.note` | 32 characters |
| `api-call.examples` | 1 to 4 items |
| `api-call.examples.label` | 28 characters |
| `api-call.examples.request` | 1008 characters |
| `api-call.examples.status` | 28 characters |
| `api-call.examples.response` | 1728 characters |
| `api-call.examples.events` | 1 to 10 items |
| `api-call.examples.events.at` | 12 characters |
| `api-call.examples.events.name` | 40 characters |
| `api-call.examples.events.ref` | 16 characters |
| `api-call.examples.events.text` | 80 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `api-call.examples` | `an example answers with a response or with events, one of them` | Answer with a `response` or with `events`, one of them |

## endpoints

| Anchor | Bound |
| --- | --- |
| `endpoints.head.eyebrow` | 28 characters |
| `endpoints.head.title` | 72 characters |
| `endpoints.head.lede` | 300 characters |
| `endpoints.head.tag` | 8 characters |
| `endpoints.rows` | 3 to 16 items |
| `endpoints.rows.path` | 64 characters |
| `endpoints.rows.text` | 96 characters |
| `endpoints.rows.href` | 160 characters |
| `endpoints.note` | 160 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `endpoints.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## agent-prompt

| Anchor | Bound |
| --- | --- |
| `agent-prompt.label` | 24 characters |
| `agent-prompt.lines` | 1 to 6 items |

## pricing

| Anchor | Bound |
| --- | --- |
| `pricing.head.eyebrow` | 28 characters |
| `pricing.head.title` | 72 characters |
| `pricing.head.lede` | 300 characters |
| `pricing.head.tag` | 8 characters |
| `pricing.tiers` | 1 to 4 items |
| `pricing.tiers.name` | 16 characters |
| `pricing.tiers.price` | 16 characters |
| `pricing.tiers.note` | 24 characters |
| `pricing.tiers.desc` | 80 characters |
| `pricing.tiers.features` | 1 to 10 items |
| `pricing.tiers.cta` | 40 characters |
| `pricing.tiers.href` | 160 characters |
| `pricing.featuredBadge` | 16 characters |
| `pricing.note` | 120 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `pricing.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## plan-table

| Anchor | Bound |
| --- | --- |
| `plan-table.title` | 48 characters |
| `plan-table.columns` | 1 to 6 items |
| `plan-table.rows` | 1 to 8 items |
| `plan-table.rows.name` | 24 characters |
| `plan-table.rows.cells` | 1 to 6 items |
| `plan-table.rows.note` | 40 characters |
| `plan-table.foot` | 160 characters |

## faq

| Anchor | Bound |
| --- | --- |
| `faq.head.eyebrow` | 28 characters |
| `faq.head.title` | 72 characters |
| `faq.head.lede` | 300 characters |
| `faq.head.tag` | 8 characters |
| `faq.items` | 1 to 10 items |
| `faq.items.q` | 64 characters |
| `faq.items.a` | 420 characters |
| `faq.groups` | 1 to 4 items |
| `faq.groups.title` | 24 characters |
| `faq.groups.items` | 1 to 6 items |
| `faq.groups.items.q` | 64 characters |
| `faq.groups.items.a` | 420 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `faq.head` | `a head needs a title or a lede` | Give the head a title or a lede |
| `faq` | `items or groups, not both` | Keep `items` or `groups`, never both |

## closing

| Anchor | Bound |
| --- | --- |
| `closing.head.eyebrow` | 28 characters |
| `closing.head.title` | 72 characters |
| `closing.head.lede` | 300 characters |
| `closing.head.tag` | 8 characters |
| `closing.specimen.blocks` | 1 to 3 items |
| `closing.fine` | at most 4 items |
| `closing.stats` | at most 4 items |
| `closing.stats.value` | 6 characters |
| `closing.stats.label` | 24 characters |
| `closing.actions` | at most 2 items |
| `closing.actions.href` | 160 characters |
| `closing.actions.label` | 24 characters |
| `closing.command` | 40 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `closing.head` | `a head needs a title or a lede` | Give the head a title or a lede |
| `closing` | `a closing ends on its buttons or on one command, never both (review 2026-09-14)` | Keep the `actions` or the `command`, never both |

## cta-form

| Anchor | Bound |
| --- | --- |
| `cta-form.head.eyebrow` | 28 characters |
| `cta-form.head.title` | 72 characters |
| `cta-form.head.lede` | 300 characters |
| `cta-form.head.tag` | 8 characters |
| `cta-form.action` | 160 characters |
| `cta-form.fields` | 1 to 8 items |
| `cta-form.fields.label` | 16 characters |
| `cta-form.fields.placeholder` | 32 characters |
| `cta-form.fields.options` | at most 12 items |
| `cta-form.submit` | 24 characters |
| `cta-form.note` | 80 characters |

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `cta-form.head` | `a head needs a title or a lede` | Give the head a title or a lede |

## article

| Anchor | Bound |
| --- | --- |
| `article.head.back.href` | 160 characters |
| `article.head.back.label` | 16 characters |
| `article.head.tag` | 20 characters |
| `article.head.dateline.read.minutes` | 1 to 180 |
| `article.head.dateline.read.unit` | 12 characters |
| `article.head.title` | 80 characters |
| `article.head.dek` | 360 characters |
| `article.share.url` | 160 characters |
| `article.share.title` | 80 characters |
| `article.share.label` | 16 characters |
| `article.share.on` | 1 to 5 items |
| `article.body` | 12000 characters |

## post-list

| Anchor | Bound |
| --- | --- |
| `post-list.head.eyebrow` | 28 characters |
| `post-list.head.title` | 64 characters |
| `post-list.head.lede` | 200 characters |
| `post-list.read` | 16 characters |
| `post-list.posts` | 1 to 24 items |
| `post-list.posts.href` | 160 characters |
| `post-list.posts.tag` | 20 characters |
| `post-list.posts.dateline.read.minutes` | 1 to 180 |
| `post-list.posts.dateline.read.unit` | 12 characters |
| `post-list.posts.title` | 80 characters |
| `post-list.posts.dek` | 360 characters |

## product-head

| Anchor | Bound |
| --- | --- |
| `product-head.name` | 32 characters |
| `product-head.summary` | 120 characters |
| `product-head.chips` | at most 9 items |
| `product-head.chips.label` | 24 characters |
| `product-head.chips.href` | 160 characters |
| `product-head.actions` | 1 to 2 items |
| `product-head.actions.href` | 160 characters |
| `product-head.actions.label` | 24 characters |

## product-list

| Anchor | Bound |
| --- | --- |
| `product-list.title` | 48 characters |
| `product-list.note` | 24 characters |
| `product-list.rail.groups` | 1 to 4 items |
| `product-list.rail.groups.label` | 20 characters |
| `product-list.rail.groups.links` | 1 to 12 items |
| `product-list.rail.groups.links.href` | 160 characters |
| `product-list.rail.groups.links.label` | 24 characters |
| `product-list.rail.groups.links.count` | 0 to 1000000 |
| `product-list.sort` | at most 4 items |
| `product-list.sort.href` | 160 characters |
| `product-list.sort.label` | 16 characters |
| `product-list.views` | at most 2 items |
| `product-list.views.href` | 160 characters |
| `product-list.views.label` | 16 characters |
| `product-list.rows` | at most 50 items |
| `product-list.rows.href` | 160 characters |
| `product-list.rows.name` | 32 characters |
| `product-list.rows.summary` | 120 characters |
| `product-list.rows.tag` | 24 characters |
| `product-list.rows.note` | 32 characters |
| `product-list.pager.prev` | 160 characters |
| `product-list.pager.next` | 160 characters |
| `product-list.pager.page` | 1 to 10000 |
| `product-list.pager.pages` | 1 to 10000 |
| `product-list.empty` | 80 characters |

## compileTheme

| Anchor | Rule, as `safeParse` returns it | Fix |
| --- | --- | --- |
| `compile-theme` | `theme "fieldnote" is missing core roles: panel, ink, …` | Set every [core role](https://next.mdxui.dev/docs/themes/contract) in `light` or `invariant` |



# @mdxui/site exports (/docs/reference/site-exports)

> Every runtime export of @mdxui/site: its kind, what it does and its signature.

Every runtime export of `@mdxui/site`, read from the installed package and its type declarations.

33 runtime exports of `@mdxui/site@7.0.0-alpha.0`, read from the package and its `index.d.ts`.

| Export | Kind | Does | Signature or type |
| --- | --- | --- | --- |
| `BENTO_SPECIMENS` | 3 values | The Section types a bento tile holds | `readonly ["terminal", "agent-prompt", "api-call"]` |
| `BLOCKS` | object, 27 keys | Every Section type: its CSS and its renderer | — |
| `BlockSchema` | Zod schema | Parses one Section type | — |
| `FEATURE_GRID_COUNTS` | 5 values | The item counts `feature-grid` admits | `readonly [2, 3, 4, 6, 8]` |
| `HIGHLIGHT_LANGUAGES` | 44 values | Every language a fence may name | `string[]` |
| `NAV_ROW_BUDGET` | number, 96 | The units one `nav` row holds | — |
| `PageSchema` | Zod schema | Parses a Page record | — |
| `SectionHeadSchema` | Zod schema | Parses a section head | — |
| `SectionSchema` | Zod schema | Parses one section | — |
| `baseCss` | CSS, 2 KB | The reset and body type | — |
| `blockTitle` | function | A plain title over a table or list | `blockTitle(title: string, opts?: { level?: 1 \| 2; note?: string; }): string` |
| `blocksCss` | CSS, 68 KB | Every Section type, styled | — |
| `buttonIcon` | function | A button glyph in the button ink | `buttonIcon(ctx: RenderContext, name: IconName, kind: 'solid' \| 'ghost' \| 'invert'): string` |
| `compose` | function | Sections to a page body, dividers derived | `compose(c: Composition): string` |
| `context` | function | The render context for a Theme and a surface | `context(theme: Theme, surface?: Surface, delivery?: IconDelivery): RenderContext` |
| `copyControl` | function | A copy button that needs no script | `copyControl(ctx: RenderContext, label: string, o?: { from?: string; float?: boolean; }): string` |
| `dividerBetween` | function | The divider between two sections | `dividerBetween(prev: SectionSpec, next: SectionSpec, p: DividerPolicy): Divider` |
| `document` | function | A body to a whole document | `document(d: DocumentProps): string` |
| `esc` | function | Escapes text for HTML | `esc(text: string): string` |
| `findBlock` | function | The first section of a type in a record | `findBlock(p: Page, type: Block['type']): Block \| undefined` |
| `highlight` | function | Code to highlighted HTML | `highlight(lang: string \| undefined, code: string): string` |
| `metaRow` | function | A tag and dateline row | `metaRow(m: { tag?: string; dateline?: Dateline; }, cls: string): string` |
| `navRowCost` | function | The units a `nav` row costs | — |
| `page` | function | The page frame around every section | `page(p: PageShell, sections: string): string` |
| `panel` | function | A painted panel around part of a section | `panel(p: PanelShell, inner: string): string` |
| `primitivesCss` | CSS, 11 KB | The shared pieces every Section type uses | — |
| `renderBlock` | function | One Section type to HTML | `renderBlock(b: Block, ctx: RenderContext): string` |
| `renderPage` | function | A Page record to one HTML document | `renderPage(p: Page, opts?: RenderOptions): string` |
| `renderSpecimen` | function | A specimen slot to HTML | `renderSpecimen(s: Specimen, ctx: RenderContext): string` |
| `resolveRole` | function | A role to its literal value on a surface | `resolveRole(theme: Theme, role: string, surface: Surface, seen?: Set<string>): string` |
| `section` | function | One section shell around rendered HTML | `section(s: SectionShell, block: string, tag?: 'section' \| 'header' \| 'div'): string` |
| `sectionHead` | function | A section head to HTML | `sectionHead(h: SectionHead, ctx: RenderContext, opts?: { level?: 1 \| 2; }): string` |
| `shellCss` | CSS, 7 KB | The shell, frame and dividers | — |



# @mdxui/themes exports (/docs/reference/themes-exports)

> Every export of @mdxui/themes, and every Theme role with its tier, its default and the Section types that read it.

Every runtime export of `@mdxui/themes`, then every role a Theme fills.

8 runtime exports of `@mdxui/themes@7.0.0-alpha.0`.

| Export | Kind | Does | Signature or type |
| --- | --- | --- | --- |
| `CORE` | 21 values | The roles every Theme sets | — |
| `DEFAULTS` | object, 325 keys | The derived roles and their defaults | `Tokens` |
| `PINNED` | function | Whether a role keeps its root value on a plate | `PINNED(role: string): boolean` |
| `PLATE_REMAP` | object, 18 keys | The roles a plate surface re-tokens | `Record<string, string>` |
| `THEMES` | object, 5 keys | The bundled Themes, each with its head lines | — |
| `THEME_NAMES` | 5 values | The bundled Theme names | `[ThemeName, ...ThemeName[]]` |
| `compileTheme` | function | A Theme to CSS custom properties | `compileTheme(t: Theme): string` |
| `resolveTokens` | function | A Theme to literal values, every chain followed | `resolveTokens(t: Theme): Tokens` |

## Roles

21 core roles and 325 derived roles. "Read by" counts the Section types whose CSS reads the role directly; a role read only through another role shows —.

| Role | Tier | Default | Read by |
| --- | --- | --- | --- |
| `paper` | core | — | `nav`, `product-list` |
| `panel` | core | — | 9 Section types |
| `ink` | core | — | 20 Section types |
| `ink-soft` | core | — | 11 Section types |
| `rule` | core | — | 16 Section types |
| `rule-soft` | core | — | 5 Section types |
| `accent` | core | — | 16 Section types |
| `accent-ink` | core | — | `footer` |
| `pass` | core | — | `cta-form`, `article` |
| `fail` | core | — | `cta-form` |
| `warn` | core | — | — |
| `plate` | core | — | `pricing`, `cta-form` |
| `plate-ink` | core | — | `cta-form` |
| `plate-rule` | core | — | — |
| `sans` | core | — | 7 Section types |
| `mono` | core | — | 19 Section types |
| `text` | core | — | `plan-table`, `product-head`, `page-head`, `product-list` |
| `lh` | core | — | `text-stack`, `feature-split` |
| `shell-max` | core | — | `nav` |
| `shell-inset` | core | — | `nav`, `stats` |
| `shell-d-section` | core | — | — |
| `tint` | derived | `var(--paper)` | — |
| `panel-inset` | derived | `var(--panel)` | 6 Section types |
| `panel-muted` | derived | `var(--panel)` | `compare` |
| `track` | derived | `var(--rule-soft)` | `product-list` |
| `rule-faint` | derived | `var(--rule-soft)` | — |
| `ghost-border` | derived | `var(--rule)` | `nav`, `product-head`, `product-list`, `footer` |
| `glass` | derived | `var(--paper)` | — |
| `glass-blur` | derived | `0px` | — |
| `ink-lede` | derived | `var(--ink-soft)` | `product-head`, `page-head`, `faq`, `post-list` |
| `ink-body` | derived | `var(--ink)` | `text-stack`, `feature-split` |
| `ink-note` | derived | `var(--ink-soft)` | `pricing` |
| `ink-muted` | derived | `var(--ink-soft)` | 11 Section types |
| `ink-quiet` | derived | `var(--ink-muted)` | `compare`, `article` |
| `ink-faint` | derived | `var(--ink-muted)` | `command-row`, `cta-form` |
| `ink-ghost` | derived | `var(--ink-faint)` | — |
| `accent-hover` | derived | `var(--accent)` | `post-list` |
| `accent-muted` | derived | `var(--accent)` | — |
| `accent-soft` | derived | `var(--panel)` | `nav` |
| `accent-soft-rule` | derived | `var(--accent)` | — |
| `accent-rule` | derived | `var(--accent)` | `compare` |
| `cta` | derived | `var(--accent)` | `nav`, `footer` |
| `cta-ink` | derived | `var(--accent-ink)` | `nav`, `footer` |
| `plate-panel` | derived | `var(--plate)` | — |
| `plate-well` | derived | `var(--plate)` | — |
| `plate-sunken` | derived | `var(--plate)` | — |
| `plate-rule-soft` | derived | `var(--plate-rule)` | — |
| `plate-rule-faint` | derived | `var(--plate-rule-soft)` | — |
| `plate-ghost-border` | derived | `var(--plate-rule)` | — |
| `plate-ink-soft` | derived | `var(--plate-ink)` | — |
| `plate-ink-lede` | derived | `var(--plate-ink-soft)` | — |
| `plate-ink-body` | derived | `var(--plate-ink-soft)` | — |
| `plate-ink-muted` | derived | `var(--plate-ink-soft)` | — |
| `plate-ink-faint` | derived | `var(--plate-ink-muted)` | — |
| `plate-ink-ghost` | derived | `var(--plate-ink-faint)` | — |
| `plate-accent` | derived | `var(--accent)` | — |
| `plate-accent-hover` | derived | `var(--plate-accent)` | — |
| `plate-accent-soft` | derived | `var(--plate-accent)` | — |
| `plate-accent-ink` | derived | `var(--plate)` | `pricing` |
| `plate-pass` | derived | `var(--pass)` | — |
| `plate-control-ink` | derived | `var(--plate-ink-muted)` | — |
| `plate-command-ink` | derived | `var(--plate-ink-soft)` | — |
| `code-ink` | derived | `var(--plate-ink)` | `terminal`, `article` |
| `code-comment` | derived | `var(--plate-ink-muted)` | `terminal` |
| `code-string` | derived | `var(--plate-accent)` | `terminal` |
| `code-keyword` | derived | `var(--plate-accent)` | `terminal` |
| `display` | derived | `var(--sans)` | 6 Section types |
| `text-sm` | derived | `calc(var(--text) * .875)` | `nav`, `facts`, `plan-table`, `product-list` |
| `text-xs` | derived | `calc(var(--text) * .75)` | `plan-table`, `product-head`, `product-list` |
| `mono-sm` | derived | `var(--text-sm)` | `facts` |
| `mono-xs` | derived | `var(--text-xs)` | `pricing`, `feature-split` |
| `brand-weight` | derived | `700` | — |
| `brand-face` | derived | `var(--mono)` | — |
| `brand-tracking` | derived | `-.02em` | — |
| `brand-transform` | derived | `none` | — |
| `display-weight` | derived | `700` | 6 Section types |
| `figures` | derived | `normal` | — |
| `link` | derived | `currentColor` | — |
| `link-hover` | derived | `var(--link)` | — |
| `h1-size` | derived | `clamp(2.2rem,7vw,3.4rem)` | `hero` |
| `h1-lh` | derived | `1.06` | `hero` |
| `h1-tracking` | derived | `-.028em` | `hero`, `article`, `post-list` |
| `title-size` | derived | `var(--h1-size)` | `product-head`, `page-head` |
| `title-lh` | derived | `var(--h1-lh)` | `product-head`, `page-head` |
| `title-tracking` | derived | `var(--h1-tracking)` | `product-head`, `page-head` |
| `btitle-size` | derived | `var(--h2-size)` | — |
| `btitle-lh` | derived | `var(--h2-lh)` | — |
| `eyebrow-size` | derived | `var(--mono-xs)` | `faq` |
| `eyebrow-tracking` | derived | `.16em` | `faq` |
| `eyebrow-color` | derived | `var(--ink-soft)` | — |
| `btn-face` | derived | `var(--mono)` | `footer` |
| `btn-size` | derived | `var(--mono-sm)` | — |
| `btn-gap` | derived | `.5rem` | — |
| `btn-solid-pad` | derived | `.6rem 1rem` | — |
| `btn-ghost-pad` | derived | `.6rem 1rem` | — |
| `btn-solid-weight` | derived | `600` | `footer` |
| `btn-ghost-weight` | derived | `400` | — |
| `btn-solid-tracking` | derived | `0` | — |
| `btn-invert-weight` | derived | `600` | — |
| `btn-ghost-hover-border` | derived | `var(--accent)` | — |
| `btn-ghost-hover-color` | derived | `var(--accent)` | — |
| `btn-ghost-hover-bg` | derived | `transparent` | — |
| `btn-solid-hover-bg` | derived | `var(--accent)` | `nav` |
| `btn-solid-hover-ink` | derived | `var(--accent-ink)` | `nav` |
| `btn-invert-bg` | derived | `var(--plate-ink)` | `footer` |
| `btn-invert-ink` | derived | `var(--plate)` | `footer` |
| `btn-invert-hover-bg` | derived | `var(--accent)` | — |
| `btn-invert-hover-ink` | derived | `var(--plate)` | — |
| `h2-size` | derived | `clamp(1.4rem,3.4vw,2.15rem)` | — |
| `h2-lh` | derived | `1.1` | — |
| `h2-tracking` | derived | `-.024em` | `statement` |
| `heading-wrap` | derived | `balance` | — |
| `sechead-max` | derived | `none` | — |
| `sechead-h2-gap` | derived | `.9rem` | — |
| `sechead-lede-gap` | derived | `.9rem` | — |
| `sechead-lede-size` | derived | `var(--text)` | — |
| `sechead-lede-lh` | derived | `var(--lh)` | — |
| `sechead-lede-color` | derived | `var(--ink-soft)` | — |
| `sechead-lede-max` | derived | `62ch` | — |
| `h2-size-compact` | derived | `var(--h2-size)` | — |
| `h2-lh-compact` | derived | `var(--h2-lh)` | — |
| `sechead-lede-size-compact` | derived | `var(--sechead-lede-size)` | — |
| `sechead-lede-gap-compact` | derived | `var(--sechead-lede-gap)` | — |
| `h2-size-large` | derived | `var(--h2-size)` | `statement` |
| `h2-lh-large` | derived | `var(--h2-lh)` | `statement` |
| `compare-no` | derived | `var(--ink-faint)` | — |
| `compare-yes` | derived | `var(--accent)` | — |
| `fg-gap` | derived | `1.9rem` | `feature-grid`, `bento`, `endpoints` |
| `fg-radius` | derived | `var(--radius-card)` | `feature-grid` |
| `fg-radius-dense` | derived | `var(--radius-cell)` | `feature-grid` |
| `fsplit-copy` | derived | `400px` | `feature-split` |
| `fsplit-specimen` | derived | `400px` | `feature-split` |
| `fg-pad` | derived | `1.25rem 1.35rem` | `feature-grid` |
| `fg-pad-dense` | derived | `var(--fg-pad)` | `feature-grid` |
| `fg-head-gap` | derived | `.5rem` | `feature-grid` |
| `fg-head-gap-dense` | derived | `var(--fg-head-gap)` | `feature-grid` |
| `fg-icon-gap` | derived | `14px` | `feature-grid` |
| `fg-icon-size` | derived | `22px` | — |
| `fg-index-size` | derived | `var(--mono-sm)` | `feature-grid` |
| `fg-index-color` | derived | `var(--ink-faint)` | `feature-grid` |
| `fg-label-size` | derived | `var(--mono-xs)` | `feature-grid`, `endpoints` |
| `fg-label-tracking` | derived | `.12em` | `feature-grid` |
| `fg-label-transform` | derived | `uppercase` | `feature-grid` |
| `fg-label-color` | derived | `var(--accent)` | `feature-grid` |
| `fg-title-face` | derived | `var(--sans)` | `feature-grid`, `bento` |
| `fg-title-weight` | derived | `600` | `feature-grid`, `bento` |
| `fg-title-size` | derived | `1.05rem` | `feature-grid`, `bento` |
| `fg-title-size-dense` | derived | `var(--fg-title-size)` | `feature-grid` |
| `fg-title-tracking` | derived | `-.015em` | `feature-grid`, `bento` |
| `fg-title-lh` | derived | `1.25` | `feature-grid`, `bento` |
| `fg-title-gap` | derived | `.45rem` | `feature-grid`, `bento` |
| `fg-text-size` | derived | `.87rem` | `feature-grid`, `bento`, `endpoints` |
| `fg-text-size-dense` | derived | `var(--fg-text-size)` | `feature-grid` |
| `fg-text-lh` | derived | `1.55` | `feature-grid`, `bento`, `endpoints` |
| `fg-text-lh-dense` | derived | `var(--fg-text-lh)` | `feature-grid` |
| `fg-text-color` | derived | `var(--ink-soft)` | `feature-grid` |
| `tier-gap` | derived | `1.9rem` | `pricing` |
| `tier-pad` | derived | `1.35rem` | `pricing` |
| `tier-head-gap` | derived | `0` | `pricing` |
| `tier-name-face` | derived | `var(--sans)` | `pricing` |
| `tier-name-size` | derived | `1rem` | `pricing` |
| `tier-name-weight` | derived | `600` | `pricing` |
| `tier-name-tracking` | derived | `-.01em` | `pricing` |
| `tier-name-transform` | derived | `none` | `pricing` |
| `tier-name-color` | derived | `var(--ink)` | `pricing` |
| `tier-name-featured-color` | derived | `var(--tier-name-color)` | `pricing` |
| `tier-price-gap` | derived | `0` | `pricing` |
| `tier-amt-face` | derived | `var(--mono)` | `pricing` |
| `tier-amt-size` | derived | `1.9rem` | `pricing` |
| `tier-amt-weight` | derived | `700` | `pricing` |
| `tier-amt-tracking` | derived | `-.04em` | `pricing` |
| `tier-amt-lh` | derived | `1` | `pricing` |
| `tier-amt-margin` | derived | `.75rem 0 .1rem` | `pricing` |
| `tier-desc-color` | derived | `var(--ink-soft)` | `pricing` |
| `tier-desc-featured-color` | derived | `var(--tier-desc-color)` | `pricing` |
| `tier-list-margin` | derived | `1.05rem 0 1.35rem` | `pricing` |
| `tier-list-gap` | derived | `.45rem` | `pricing` |
| `tier-item-size` | derived | `.845rem` | `pricing` |
| `tier-item-color` | derived | `var(--ink-soft)` | `pricing` |
| `tier-bullet` | derived | `"+"` | `pricing` |
| `tier-btn-pad` | derived | `var(--btn-solid-pad)` | `pricing` |
| `tier-btn-size` | derived | `var(--btn-size)` | `pricing` |
| `tier-btn-ghost-weight` | derived | `var(--btn-ghost-weight)` | `pricing` |
| `hero-h1-gap` | derived | `1.1rem` | `hero` |
| `hero-h1-max` | derived | `26ch` | `hero` |
| `hero-lede-size` | derived | `1.02rem` | `hero` |
| `hero-lede-lh` | derived | `var(--lh)` | `hero` |
| `hero-lede-color` | derived | `var(--ink-soft)` | `hero` |
| `hero-lede-max` | derived | `64ch` | `hero` |
| `hero-lede-gap` | derived | `1.1rem` | `hero` |
| `hero-actions-gap` | derived | `.6rem` | `hero`, `closing` |
| `hero-actions-top` | derived | `1.75rem` | `hero` |
| `hero-fine-size` | derived | `var(--mono-sm)` | — |
| `hero-fine-color` | derived | `var(--ink-soft)` | — |
| `hero-fine-tracking` | derived | `0` | — |
| `hero-fine-gap` | derived | `1.35rem` | — |
| `hero-specimen-gap` | derived | `clamp(1.6rem,4vw,2.5rem)` | `hero` |
| `nav-height` | derived | `58px` | `nav` |
| `nav-gap` | derived | `1.5rem` | `nav` |
| `nav-brand-size` | derived | `var(--text)` | `nav` |
| `nav-link-face` | derived | `var(--mono)` | `nav` |
| `nav-link-size` | derived | `var(--mono-sm)` | `nav` |
| `nav-link-color` | derived | `var(--ink-soft)` | `nav` |
| `nav-link-hover` | derived | `var(--accent)` | `nav` |
| `nav-link-gap` | derived | `1.6rem` | `nav` |
| `nav-cta-gap` | derived | `.6rem` | `nav` |
| `nav-burger-size` | derived | `1.2rem` | `nav` |
| `nav-burger-pad` | derived | `.4rem` | `nav` |
| `nav-burger-margin` | derived | `-.4rem` | `nav` |
| `nav-burger-color` | derived | `var(--ink-soft)` | `nav` |
| `nav-burger-hover` | derived | `var(--accent)` | `nav` |
| `nav-slim-rule` | derived | `var(--rule)` | `nav` |
| `nav-slim-brand-size` | derived | `var(--nav-brand-size)` | `nav` |
| `nav-slim-link-face` | derived | `var(--nav-link-face)` | `nav` |
| `nav-slim-link-size` | derived | `var(--nav-link-size)` | `nav` |
| `nav-slim-link-tracking` | derived | `0` | `nav` |
| `nav-slim-link-color` | derived | `var(--nav-link-color)` | `nav` |
| `nav-slim-link-hover` | derived | `var(--nav-link-hover)` | `nav` |
| `meta-accent` | derived | `var(--eyebrow-color)` | `post-list` |
| `article-rule` | derived | `var(--rule-soft)` | `article`, `post-list` |
| `article-title-size` | derived | `clamp(30px,5.4vw,46px)` | `article` |
| `article-title-lh` | derived | `1.08` | `article` |
| `article-dek-face` | derived | `var(--display)` | `article` |
| `article-dek-size` | derived | `clamp(18px,1.9vw,21px)` | `article` |
| `article-dek-ink` | derived | `var(--ink-lede)` | `article` |
| `listing-title-size` | derived | `clamp(34px,6vw,52px)` | `post-list` |
| `listing-title-lh` | derived | `1.06` | `post-list` |
| `listing-lede-size` | derived | `clamp(17px,1.4vw,19px)` | `post-list` |
| `post-title-size` | derived | `clamp(23px,3.2vw,30px)` | `post-list` |
| `post-title-lh` | derived | `1.16` | `post-list` |
| `post-title-weight` | derived | `var(--prose-h2-weight)` | `post-list` |
| `post-dek-size` | derived | `clamp(15.5px,1.2vw,17px)` | `post-list` |
| `share-label-ink` | derived | `var(--ink-muted)` | `article` |
| `share-border` | derived | `var(--rule)` | `article` |
| `share-glyph` | derived | `var(--ink-soft)` | `article` |
| `share-hover-bg` | derived | `var(--panel-inset)` | `article` |
| `prose-ink` | derived | `var(--ink-soft)` | `article` |
| `prose-size` | derived | `var(--text)` | `article` |
| `prose-lh` | derived | `1.7` | `article` |
| `prose-h1-face` | derived | `var(--display)` | `article` |
| `prose-h1-weight` | derived | `var(--display-weight)` | `article` |
| `prose-h1-size` | derived | `var(--article-title-size)` | `article` |
| `prose-h1-lh` | derived | `var(--article-title-lh)` | `article` |
| `prose-h1-tracking` | derived | `var(--h1-tracking)` | `article` |
| `prose-h1-ink` | derived | `var(--ink)` | `article` |
| `prose-h1-margin` | derived | `0 0 .5em` | `article` |
| `prose-h2-face` | derived | `var(--display)` | `article` |
| `prose-h2-weight` | derived | `var(--display-weight)` | `article` |
| `prose-h2-size` | derived | `clamp(23px,2.6vw + 8px,31px)` | `article` |
| `prose-h2-lh` | derived | `1.18` | `article` |
| `prose-h2-tracking` | derived | `-.018em` | `article`, `post-list` |
| `prose-h3-face` | derived | `var(--sans)` | `article` |
| `prose-h3-weight` | derived | `600` | `article` |
| `prose-h3-size` | derived | `clamp(17px,1vw + 13px,20px)` | `article` |
| `prose-link` | derived | `var(--accent)` | `article` |
| `prose-link-hover` | derived | `var(--accent-hover)` | `article` |
| `prose-link-rule` | derived | `color-mix(in srgb, var(--accent) 45%, transpare…` | `article` |
| `prose-link-rule-hover` | derived | `var(--accent)` | `article` |
| `prose-mark` | derived | `var(--accent)` | `article` |
| `prose-quote-ink` | derived | `var(--ink-soft)` | `article` |
| `prose-quote-face` | derived | `var(--display)` | `article` |
| `prose-quote-size` | derived | `clamp(18px,1.4vw + 12px,22px)` | `article` |
| `prose-code-bg` | derived | `var(--panel-inset)` | `article` |
| `footer-brand-size` | derived | `var(--text)` | `footer` |
| `footer-blurb-size` | derived | `var(--text-sm)` | `footer` |
| `footer-blurb-lh` | derived | `var(--lh)` | `footer` |
| `footer-blurb-color` | derived | `var(--ink-soft)` | `footer` |
| `footer-blurb-max` | derived | `32ch` | `footer` |
| `footer-blurb-gap` | derived | `.75rem` | `footer` |
| `footer-head-size` | derived | `var(--mono-xs)` | `footer` |
| `footer-head-tracking` | derived | `.14em` | `footer` |
| `footer-head-color` | derived | `var(--ink)` | `footer` |
| `footer-head-weight` | derived | `700` | `footer` |
| `footer-head-gap` | derived | `.65rem` | `footer` |
| `footer-link-face` | derived | `var(--sans)` | `footer` |
| `footer-link-size` | derived | `var(--text-sm)` | `footer` |
| `footer-link-color` | derived | `var(--ink-soft)` | `footer` |
| `footer-link-hover` | derived | `var(--accent)` | `footer` |
| `footer-link-pad` | derived | `.16rem` | `footer` |
| `footer-link-gap` | derived | `0px` | `footer` |
| `footer-note-gap` | derived | `1.75rem` | `footer` |
| `footer-note-pad` | derived | `1rem` | `footer` |
| `footer-note-rule` | derived | `var(--rule-soft)` | `footer` |
| `footer-note-face` | derived | `var(--mono)` | `footer` |
| `footer-note-size` | derived | `var(--mono-xs)` | `footer` |
| `footer-note-color` | derived | `var(--ink-soft)` | `footer` |
| `footer-note-flex-gap` | derived | `.4rem 1.25rem` | `footer` |
| `footer-motto-size` | derived | `var(--footer-note-size)` | `footer` |
| `footer-motto-tracking` | derived | `0` | `footer` |
| `footer-motto-color` | derived | `var(--footer-note-color)` | `footer` |
| `radius-control` | derived | `0` | 6 Section types |
| `radius-field` | derived | `var(--radius-control)` | 5 Section types |
| `radius-cell` | derived | `var(--radius-control)` | `product-head`, `product-list`, `feature-grid` |
| `radius-row` | derived | `var(--radius-control)` | `command-row` |
| `radius-card` | derived | `var(--radius-control)` | 10 Section types |
| `shadow-card` | derived | `none` | — |
| `shadow-card-soft` | derived | `var(--shadow-card)` | `compare` |
| `shadow-plate-card` | derived | `var(--shadow-card)` | `pricing` |
| `shadow-terminal` | derived | `var(--shadow-card)` | `terminal`, `article`, `api-call` |
| `field-a` | derived | `color-mix(in oklch, var(--accent), white 18%)` | — |
| `field-b` | derived | `color-mix(in oklch, var(--accent), black 18%)` | — |
| `field-c` | derived | `color-mix(in oklch, var(--accent), black 32%)` | — |
| `term-bg` | derived | `var(--plate-well)` | `terminal`, `article`, `api-call` |
| `term-row-bg` | derived | `var(--plate-sunken)` | `command-row`, `agent-prompt` |
| `term-ink` | derived | `var(--plate-ink)` | `terminal`, `agent-prompt`, `api-call` |
| `term-ink-soft` | derived | `var(--plate-ink-soft)` | `terminal`, `api-call` |
| `term-ink-muted` | derived | `var(--plate-ink-muted)` | `terminal`, `api-call` |
| `term-rule-soft` | derived | `var(--plate-rule-soft)` | 5 Section types |
| `term-rule-faint` | derived | `var(--plate-rule-faint)` | `terminal`, `api-call` |
| `term-accent` | derived | `var(--plate-accent)` | `terminal`, `command-row`, `agent-prompt`, `api-call` |
| `term-pass` | derived | `var(--plate-pass)` | `terminal`, `api-call` |
| `term-control-ink` | derived | `var(--plate-control-ink)` | — |
| `term-command-ink` | derived | `var(--plate-command-ink)` | `command-row` |
| `term-hover` | derived | `var(--plate-panel)` | — |
| `hatch` | derived | `color-mix(in srgb, var(--ink) 16%, transparent)` | — |
| `scrim` | derived | `rgba(0, 0, 0, 0.58)` | `nav`, `product-list` |
| `ease-out` | derived | `cubic-bezier(0.16, 1, 0.3, 1)` | `nav`, `footer`, `article`, `post-list` |
| `dur-fast` | derived | `120ms` | `nav`, `footer`, `article`, `post-list` |
| `dur-base` | derived | `220ms` | `nav` |
| `app-nav-active-bg` | derived | `color-mix(in srgb, var(--accent) 10%, transpare…` | — |
| `app-hover-bg` | derived | `color-mix(in srgb, var(--ink) 4%, transparent)` | — |
| `app-selected-bg` | derived | `color-mix(in srgb, var(--accent) 8%, transparen…` | — |
| `app-field-bg` | derived | `var(--panel)` | — |
| `app-chip-ok-bg` | derived | `color-mix(in srgb, var(--pass) 12%, transparent)` | — |
| `app-chip-warn-bg` | derived | `color-mix(in srgb, var(--warn) 14%, transparent)` | — |
| `app-chip-fail-bg` | derived | `color-mix(in srgb, var(--fail) 12%, transparent)` | — |
| `app-focus` | derived | `var(--accent)` | — |
| `app-radius` | derived | `var(--radius-control)` | — |
| `app-radius-sm` | derived | `var(--radius-field)` | — |
| `app-chip-ok-ink` | derived | `color-mix(in srgb, var(--pass) 78%, var(--ink))` | — |
| `app-chip-warn-ink` | derived | `color-mix(in srgb, var(--warn) 72%, var(--ink))` | — |
| `app-chip-fail-ink` | derived | `color-mix(in srgb, var(--fail) 85%, var(--ink))` | — |
| `app-danger` | derived | `var(--fail)` | — |
| `app-danger-ink` | derived | `var(--paper)` | — |
| `app-danger-hover` | derived | `color-mix(in srgb, var(--fail) 85%, var(--ink))` | — |
| `z-nav` | derived | `50` | — |
| `shell-d-compact` | derived | `var(--shell-d-section)` | — |
| `shell-d-hero` | derived | `var(--shell-d-section)` | — |
| `shell-d-closing` | derived | `var(--shell-d-section)` | — |
| `shell-d-footer` | derived | `var(--shell-d-section)` | — |
| `shell-d-access` | derived | `var(--shell-d-section)` | — |
| `shell-rule-gap` | derived | `0` | — |
| `shell-max-article` | derived | `720px` | — |
| `shell-max-listing` | derived | `820px` | — |
| `shell-d-article` | derived | `var(--shell-d-section)` | — |
| `shell-d-listing` | derived | `var(--shell-d-article)` | — |



# agent-prompt (/docs/sections/agent-prompt)

> The prompt a reader pastes into a coding agent, copied in one action.

Preview: every frame of agent-prompt is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use an agent-prompt for the task a reader hands to a coding agent: install this, call that, print the result. It holds a label of 24 characters and one to six lines of 200, copied together in one action.

Write each line as an instruction. For a shell command, use `command-row`.

Write lines an agent can act on with no docs open: the package, the input and what to print. Keep secrets out; the prompt is copied as written.

- [`command-row`](https://next.mdxui.dev/docs/sections/command-row): a shell command, not a prompt

## The record

```json title="pages/harbor/home.json, section 11"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "agent-prompt",
    "label": "Paste into your agent",
    "lines": ["Install @example/harbor-tides from npm.", "Fetch the tide window for a 3.2 m draft at pier 4 today.", "Print when it opens and when it closes."]
  }
}
```

## Smallest that parses

```json
{
  "type": "agent-prompt",
  "label": "Paste into your agent",
  "lines": ["Install @example/harbor-tides from npm."]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

| Prop | Type and bound | Required |
| --- | --- | --- |
| `label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#agent-prompt.label) | yes |
| `lines` | [`1–6 × string ≤200`](https://next.mdxui.dev/docs/reference/refusals#agent-prompt.lines) | yes |

## Variants and counts

One layout: the label, the lines and the copy control.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article` and `directory-product` Templates. Seen on `pages/harbor/home.json`, section 11.

  - Harbor tides: An API product hands an agent the install, the call and what to print.
  - Vanroster: A scheduling product hands an agent the import of an existing roster.
  - Ledgerhouse: A bookkeeping firm hands an agent the export its close needs.
  - Diffkeel: A developer tool hands an agent the setup for its CI step.
  - Benchlist: A directory hands an agent the search for a bench near a city.
  - Sidework: A weekly letter hands an agent the feed to summarize.

## Do and do not

  - Do: Three instructions an agent can follow.
  - Don't: A shell command in a prompt: a `command-row` copies it without the label.

  - Do: At most six lines, one task.
  - Don't: Seven lines are refused: the prompt holds one to six.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Copy controls that announce the result | all | 0 of 1 | no |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The prompt sits in `main`. It adds no landmark.
- **Heading level** It carries no heading; the label names it.
- **Focus order** The copy control takes focus, named Copy the prompt. It does not announce that it copied in 7.0.0-alpha.0, as counted above.

## Related

  - [command-row](https://next.mdxui.dev/docs/sections/command-row): Use it for a shell command, not a prompt.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/agent-prompt.md. Add an agent-prompt section to pages/home.json: a label of at most 24 characters and one to six instruction lines of at most 200 that install and use my product. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# Anatomy of a page (/docs/sections/anatomy)

> A page holds sections; each section has a kind, a shell and one Section type, and the Section type holds a head, its items and a preview.

Every page `@mdxui/site` renders is one JSON record. Read it from the outside in, and each level answers one question: which brand, which bands, which design, which words.

## The page

A Page names its Theme, its frame, a title of 64 characters, a description of 320, and three to twenty sections in order. An optional Template names the kind of page it is, such as `api-product` or `contact`. Change `theme` and every section redraws in the other brand; nothing else in the record moves.

## The section

A section is three fields. `kind` says what the band is to the page: `nav`, `hero`, `band`, `section`, `article`, `closing` or `footer`, or `bar` for the slim bar of an inner page. The kind decides the landmark the band lands in and the divider the Theme draws beside it.

`shell` paints and paces the band: its inset and density, and optionally its `surface`, `background`, `sticky` and `aside`. `block` is the Section type itself, named by `type`.

## The Section type

Inside the block, most Section types share three parts. The **head** is an eyebrow, a title and a lede. The **items** are the list the type was drawn for, at the counts it was drawn at. The **preview** is a slot, `specimen` in the record, that holds one to three other Section types, so a page nests a code window inside a feature split without holding markup.

Each field has a maximum, and every list a designed count. A record past either is refused at its path; see [Why the design holds](https://next.mdxui.dev/docs/sections/bounds).

## What a record never holds

No markup, no class names, no colors, no sizes and no fonts. The Theme supplies every one of those, so an agent that writes the record writes words and choices only. The [Section types](https://next.mdxui.dev/docs/sections) show each design the words fill.


# api-call (/docs/sections/api-call)

> One API call beside its answer, a JSON response or an event stream.

Preview: every frame of api-call is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use an api-call to prove an API with one real exchange. It holds a method, a path of 72 characters and up to four examples, each a request, a status and either a response or a stream of events.

Several examples share a `group`, which renders them as chips. For every route at a glance, use `endpoints`; for a whole session, use `terminal`.

Use a request a reader can paste, on a real domain or an `.example` one, and trim the response to the fields the claim names.

- [`endpoints`](https://next.mdxui.dev/docs/sections/endpoints): every route at a glance
- [`terminal`](https://next.mdxui.dev/docs/sections/terminal): a session, not one call

## The record

```json title="pages/harbor/home.json, section 4"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section", "surface": "plate" },
  "block": {
    "type": "api-call",
    "method": "GET",
    "path": "/v1/berths/{berth}/tides",
    "note": "One berth, 14 days",
    "examples": [
      {
        "label": "Pier 4, today",
        "request": "curl https://api.harbor-tides.example/v1/berths/pier-4/tides?days=1",
        "status": "200 OK",
        "response": "{\n  \"berth\": \"pier-4\",\n  \"datum\": \"chart datum\",\n  \"tides\": [\n    { \"at\": \"04:12\", \"type\": \"low\", \"m\": 0.6 },\n    { \"at\": \"10:31\", \"type\": \"high\", \"m\": 4.1 },\n    { \"at\": \"16:40\", \"type\": \"low\", \"m\": 0.8 },\n    { \"at\": \"22:58\", \"type\": \"high\", \"m\": 3.9 }\n  ]\n}"
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "api-call",
  "method": "GET",
  "path": "/v1/berths/{berth}/tides",
  "examples": [
    {
      "label": "Pier 4, today",
      "request": "curl https://api.harbor-tides.example/v1/berths/pier-4/tides?days=1",
      "status": "200 OK",
      "response": "{\n  \"berth\": \"pier-4\",\n  \"datum\": \"chart datum\",\n  \"tides\": [\n    { \"at\": \"04:12\", \"type\": \"low\", \"m\": 0.6 },\n    { \"at\": \"10:31\", \"type\": \"high\", \"m\": 4.1 },\n    { \"at\": \"16:40\", \"type\": \"low\", \"m\": 0.8 },\n    { \"at\": \"22:58\", \"type\": \"high\", \"m\": 3.9 }\n  ]\n}"
    }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 3 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `method` | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"` | yes |
| `path` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#api-call.path) | yes |
| `examples` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples) | yes |

<details>
<summary>Show all 15 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `method` | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"` | yes |
| `path` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#api-call.path) | yes |
| `note` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#api-call.note) | no |
| `group` | `string (pattern)` | no |
| `examples` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples) | yes |
| `examples[].label` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.label) | yes |
| `examples[].request` | [`string ≤1008`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.request) | yes |
| `examples[].status` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.status) | yes |
| `examples[].response` | [`string ≤1728`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.response) | no |
| `examples[].events` | [`1–10 × object`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.events) | no |
| `examples[].events[].at` | [`string ≤12`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.events.at) | yes |
| `examples[].events[].name` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.events.name) | yes |
| `examples[].events[].ref` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.events.ref) | no |
| `examples[].events[].text` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples.events.text) | yes |
| `examples[].events[].open` | `boolean` | no |

</details>

## Variants and counts

One layout, with one to four examples. Each answers with a JSON response or with events.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product` and `directory-product` Templates. Seen on `pages/harbor/home.json`, section 4.

  - Harbor tides: An API product shows the tide table for one berth, today.
  - Vanroster: A scheduling product shows the call that moves a crew.
  - Ledgerhouse: A bookkeeping firm shows the call a client portal makes.
  - Diffkeel: A developer tool shows its hosted diff call and the result.
  - Benchlist: A directory shows its search call and the benches it returns.
  - Sidework: A weekly letter shows the call that lists its issues.

## Do and do not

  - Do: A request with the answer it returns.
  - Don't: A request with no answer is refused: an example answers with a response or with events.

  - Do: One example, or several that differ.
  - Don't: Four tabs that show one call make the reader click for nothing.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The call sits in `main`. It adds no landmark.
- **Heading level** It carries no heading; the method and path label it.
- **Focus order** Example chips, when there are several, and the copy controls take focus in record order.

## Related

  - [endpoints](https://next.mdxui.dev/docs/sections/endpoints): Use it for every route at a glance.
  - [terminal](https://next.mdxui.dev/docs/sections/terminal): Use it for a session, not one call.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/api-call.md. Add an api-call section to my API page: one method and path, and one example with a request of at most 1008 characters and its JSON response. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# article (/docs/sections/article)

> A reading page: an optional head and share bar, then the body as prose.

Preview: every frame of article is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use an article for a page read top to bottom: terms, a guide, a post. It holds an optional head with a back link, a tag, a dateline, a title of 80 characters and a dek of 360, an optional share bar, and a body of up to 12,000 characters.

The body is a Markdown subset: headings, lists, quotes, a rule and fenced code that names its language. For a few titled paragraphs, use `text-stack`.

Open with the point, then the detail, and give each part its own `##` heading.

- [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack): a few titled paragraphs

## The record

```json title="pages/benchlist/terms.json, section 1"
{
  "kind": "article",
  "shell": { "inset": "article", "density": "article" },
  "block": {
    "type": "article",
    "head": { "title": "Terms", "dek": "Benchlist is a worked example. It shows a whole Site rendered by `@mdxui/site`, and it lists no real bench." },
    "body": "Every bench, rate and rule on these pages is invented. The neighborhoods are real places in Duluth; the workshops in them are not.\n\n## One bench in full\n\nThe example builds one listing in full, [Kiln room 4](/bench/kiln-room-4). The other benches in the Duluth list link to the not-found page.\n\n## What does not run\n\nSearch, sorting and the kind filters reload the Duluth list unchanged, and the listing form sends nothing. A static host answers a page, not a query.\n\n## The records\n\nEach page of this Site is a JSON record served beside its render. Copy any record and rewrite it for your own Business."
  }
}
```

## Smallest that parses

```json
{
  "type": "article",
  "body": "Every bench, rate and rule on these pages is invented. The neighborhoods are real places in Duluth; the workshops in them are not.\n\n## One bench in full\n\nThe example builds one listing in full, [Kiln room 4](/bench/kiln-room-4). The other benches in the Duluth list link to the not-found page.\n\n## What does not run\n\nSearch, sorting and the kind filters reload the Duluth list unchanged, and the listing form sends nothing. A static host answers a page, not a query.\n\n## The records\n\nEach page of this Site is a JSON record served beside its render. Copy any record and rewrite it for your own Business."
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 1 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `body` | [`string ≤12000`](https://next.mdxui.dev/docs/reference/refusals#article.body) | yes |

<details>
<summary>Show all 17 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | `object` | no |
| `head.back` | `object` | no |
| `head.back.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#article.head.back.href) | yes |
| `head.back.label` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#article.head.back.label) | yes |
| `head.tag` | [`string ≤20`](https://next.mdxui.dev/docs/reference/refusals#article.head.tag) | no |
| `head.dateline` | `object` | no |
| `head.dateline.date` | `string (pattern)` | yes |
| `head.dateline.read` | `object` | no |
| `head.title` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#article.head.title) | yes |
| `head.dek` | [`string ≤360`](https://next.mdxui.dev/docs/reference/refusals#article.head.dek) | no |
| `share` | `object` | no |
| `share.url` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#article.share.url) | yes |
| `share.title` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#article.share.title) | yes |
| `share.label` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#article.share.label) | yes |
| `share.on` | [`1–5 × "reddit" \| "x" \| "linkedin" \| "bluesky" \| "hackernews"`](https://next.mdxui.dev/docs/reference/refusals#article.share.on) | yes |
| `body` | [`string ≤12000`](https://next.mdxui.dev/docs/reference/refusals#article.body) | yes |
| `copy` | `boolean` | no |

</details>

## Variants and counts

One layout. The share bar and copy controls on code are optional.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `article` and `post` Templates. Seen on `pages/benchlist/terms.json`, section 1.

  - Harbor tides: An API product renders its terms and its posts as articles.
  - Vanroster: A scheduling product renders its security page as an article.
  - Ledgerhouse: A bookkeeping firm explains each service in an article.
  - Diffkeel: A developer tool renders its install guide and first diff.
  - Benchlist: A directory renders its about page and its terms.
  - Sidework: A weekly letter renders every issue as an article with a share bar.

## Do and do not

  - Do: Fenced code that names its language.
  - Don't: A fence with no language is refused; name one, or `text` for plain.

  - Do: Headings that break the body into parts.
  - Don't: One unbroken paragraph gives a reader no place to stop.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The article renders an `article` element inside `main`.
- **Heading level** The title renders as the page `h1`. Write body headings from `##`, so the title stays the one `h1`.
- **Focus order** Tab runs the back link, the share controls, the links in the body, then the share bar at the end.

## Related

  - [text-stack](https://next.mdxui.dev/docs/sections/text-stack): Use it for a few titled paragraphs.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/article.md. Add an article section to my terms page: a head with a title of at most 80 characters, and a Markdown body where every code fence names its language. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# bento (/docs/sections/bento)

> Two to four panels, each a claim with its own preview, laid out from their count.

Preview: every frame of bento is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a bento when each claim has its own proof: a script, a prompt, a call. It holds two to four panels under a head, and each panel holds a title, a line and one preview that is a `terminal`, an `agent-prompt` or an `api-call`.

The count lays the panels out; no field sizes them. For claims with no preview, use `feature-grid`.

Give each panel a claim a reader can check against its own preview, and make every preview different.

- [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid): claims with no preview

## The record

```json title="pages/diffkeel/home.json, section 5"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "bento",
    "head": { "eyebrow": "Where it runs", "title": "Laptop, team, agent." },
    "panels": [
      {
        "title": "On a laptop",
        "text": "Before the pull request.",
        "specimen": {
          "type": "terminal",
          "variant": "plain",
          "title": "zsh · feature/shorter-timeouts",
          "lang": "console",
          "lines": [
            "$ diffkeel diff staging",
            "rendered staging from 2 files in 18 ms",
            "api.yaml     timeout          30s  ->  10s",
            "api.yaml     retries          3    ->  5",
            "1 file, 2 changes, 0 secrets",
            "$ diffkeel render staging --key api.timeout",
            "10s   from staging.yaml, line 12",
            "      over base.yaml, line 4 (30s)",
            "$ diffkeel diff staging --json | wc -l",
            "2"
          ]
        }
      },
      {
        "title": "For the team",
        "text": "Stored diffs and approvals, on Team.",
        "specimen": {
          "type": "api-call",
          "method": "POST",
          "path": "/v1/diffs/{id}/approve",
          "examples": [
            { "label": "Approve", "request": "{ \"env\": \"prod\" }", "status": "200 OK", "response": "{ \"id\": \"df_8k2\", \"approved\": true }" }
          ]
        }
      },
      {
        "title": "In an agent",
        "text": "JSON output an agent reads.",
        "specimen": {
          "type": "agent-prompt",
          "label": "Ask an agent",
          "lines": ["Run diffkeel diff prod --json and explain each change in one line."]
        }
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "bento",
  "head": { "eyebrow": "Where it runs", "title": "Laptop, team, agent." },
  "panels": [
    {
      "title": "On a laptop",
      "text": "Before the pull request.",
      "specimen": {
        "type": "terminal",
        "variant": "plain",
        "title": "zsh · feature/shorter-timeouts",
        "lang": "console",
        "lines": [
          "$ diffkeel diff staging",
          "rendered staging from 2 files in 18 ms",
          "api.yaml     timeout          30s  ->  10s",
          "api.yaml     retries          3    ->  5",
          "1 file, 2 changes, 0 secrets",
          "$ diffkeel render staging --key api.timeout",
          "10s   from staging.yaml, line 12",
          "      over base.yaml, line 4 (30s)",
          "$ diffkeel diff staging --json | wc -l",
          "2"
        ]
      }
    },
    {
      "title": "For the team",
      "text": "Stored diffs and approvals, on Team.",
      "specimen": {
        "type": "api-call",
        "method": "POST",
        "path": "/v1/diffs/{id}/approve",
        "examples": [
          { "label": "Approve", "request": "{ \"env\": \"prod\" }", "status": "200 OK", "response": "{ \"id\": \"df_8k2\", \"approved\": true }" }
        ]
      }
    },
    {
      "title": "In an agent",
      "text": "JSON output an agent reads.",
      "specimen": {
        "type": "agent-prompt",
        "label": "Ask an agent",
        "lines": ["Run diffkeel diff prod --json and explain each change in one line."]
      }
    }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 2 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#bento.head) | yes |
| `panels` | [`2–4 × object`](https://next.mdxui.dev/docs/reference/refusals#bento.panels) | yes |

<details>
<summary>Show all 14 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#bento.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#bento.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#bento.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#bento.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#bento.head.tag) | no |
| `head.layout` | `"split"` | no |
| `panels` | [`2–4 × object`](https://next.mdxui.dev/docs/reference/refusals#bento.panels) | yes |
| `panels[].title` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#bento.panels.title) | yes |
| `panels[].text` | [`string ≤120`](https://next.mdxui.dev/docs/reference/refusals#bento.panels.text) | no |
| `panels[].specimen` | `Section type (nested)` | yes |

</details>

## Variants and counts

Three designed counts, 2, 3 and 4, each with its own arrangement.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article` and `directory-product` Templates. Seen on `pages/diffkeel/home.json`, section 5.

  - Harbor tides: An API product shows a script, a prompt and a plotter call.
  - Vanroster: A scheduling product shows four places a schedule reaches a crew.
  - Ledgerhouse: A bookkeeping firm shows the two reports a client receives.
  - Diffkeel: A developer tool shows the CLI, the CI step and the prompt.
  - Benchlist: A directory shows its search call and its listing feed.
  - Sidework: A weekly letter shows its feed and its prompt for an agent.

## Do and do not

  - Do: Each panel holds one of the three preview types.
  - Don't: A command row in a panel is refused: a panel holds a terminal, an agent-prompt or an api-call.

  - Do: Each panel proves a different claim.
  - Don't: Three panels showing one call teach one thing three times.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Scroll regions a keyboard cannot reach | 0 | 1 of 1 | no |
| Copy controls that announce the result | all | 0 of 1 | no |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The bento sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2` and each panel title as an `h3`.
- **Focus order** Tab reaches each panel copy control in record order. A window that scrolls sideways takes no focus, and a copy does not announce itself; both are counted above.

## Related

  - [feature-grid](https://next.mdxui.dev/docs/sections/feature-grid): Use it for claims with no preview.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/bento.md. Add a bento section to pages/home.json with two to four panels, each with a title of at most 48 characters and one terminal, agent-prompt or api-call preview. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# Why the design holds (/docs/sections/bounds)

> Every string has a maximum and every list a designed count, so a record an agent writes either fits the design or is refused at its path.

A brand survives an agent for one reason: the agent cannot write past the design. Each Section type was drawn by hand at the lengths and counts its fields allow, and the schema refuses a record that steps outside them. A page either renders as drawn or does not render at all.

## A bound is the drawing, written down

Each maximum is the longest instance on the pages the Section types were drawn from, plus about a fifth. A hero title holds [64 characters](https://next.mdxui.dev/docs/reference/refusals#hero.title) because the hero was drawn at that length. A longer title breaks the lines the hero was drawn on, so the schema refuses it before it renders.

## One refusal, end to end

Set the quickstart's hero title to the 71 characters of `A truly stunning, beautiful and modern page for every brand you launch.` and run it. `PageSchema.safeParse` refuses the record and names the field:

```text
sections.1.block.title: Too big: expected string to have <=64 characters
```

The path is the address of the fix. Cut words until the title fits; the bound never moves. Every bound and its message is on [Refusals](https://next.mdxui.dev/docs/reference/refusals).

## A count is part of the design

A list's count is drawn too. A feature grid holds 2, 3, 4, 6 or 8 cells, the counts that fill every row at every width; five would leave a ragged last row, so five is refused.

  - Do: Three cells fill the row and stack cleanly on a phone.
  - Don't: Five cells are refused with the reason in the message.

| List | Holds |
| --- | --- |
| [`nav.links`](https://next.mdxui.dev/docs/reference/refusals#nav.links) | at most 6 items |
| [`footer.columns`](https://next.mdxui.dev/docs/reference/refusals#footer.columns) | at most 4 items |
| [`footer.social`](https://next.mdxui.dev/docs/reference/refusals#footer.social) | at most 6 items |
| [`hero.actions`](https://next.mdxui.dev/docs/reference/refusals#hero.actions) | at most 2 items |
| [`hero.fine`](https://next.mdxui.dev/docs/reference/refusals#hero.fine) | at most 4 items |
| [`stats.items`](https://next.mdxui.dev/docs/reference/refusals#stats.items) | 3 to 4 items |
| [`facts.items`](https://next.mdxui.dev/docs/reference/refusals#facts.items) | 1 to 16 items |
| [`feature-grid.items`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items) | 2, 3, 4, 6, 8 items |
| [`feature-split.items`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items) | exactly 3 items |
| [`bento.panels`](https://next.mdxui.dev/docs/reference/refusals#bento.panels) | 2 to 4 items |
| [`steps.more`](https://next.mdxui.dev/docs/reference/refusals#steps.more) | at most 2 items |
| [`steps.steps`](https://next.mdxui.dev/docs/reference/refusals#steps.steps) | 3 to 5 items |
| [`text-stack.items`](https://next.mdxui.dev/docs/reference/refusals#text-stack.items) | 3 to 6 items |
| [`terminal.lines`](https://next.mdxui.dev/docs/reference/refusals#terminal.lines) | 1 to 32 items |
| [`api-call.examples`](https://next.mdxui.dev/docs/reference/refusals#api-call.examples) | 1 to 4 items |
| [`endpoints.rows`](https://next.mdxui.dev/docs/reference/refusals#endpoints.rows) | 3 to 16 items |
| [`agent-prompt.lines`](https://next.mdxui.dev/docs/reference/refusals#agent-prompt.lines) | 1 to 6 items |
| [`pricing.tiers`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers) | 1 to 4 items |
| [`plan-table.columns`](https://next.mdxui.dev/docs/reference/refusals#plan-table.columns) | 1 to 6 items |
| [`plan-table.rows`](https://next.mdxui.dev/docs/reference/refusals#plan-table.rows) | 1 to 8 items |
| [`faq.items`](https://next.mdxui.dev/docs/reference/refusals#faq.items) | 1 to 10 items |
| [`faq.groups`](https://next.mdxui.dev/docs/reference/refusals#faq.groups) | 1 to 4 items |
| [`closing.fine`](https://next.mdxui.dev/docs/reference/refusals#closing.fine) | at most 4 items |
| [`closing.stats`](https://next.mdxui.dev/docs/reference/refusals#closing.stats) | at most 4 items |
| [`closing.actions`](https://next.mdxui.dev/docs/reference/refusals#closing.actions) | at most 2 items |
| [`cta-form.fields`](https://next.mdxui.dev/docs/reference/refusals#cta-form.fields) | 1 to 8 items |
| [`post-list.posts`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts) | 1 to 24 items |
| [`product-head.chips`](https://next.mdxui.dev/docs/reference/refusals#product-head.chips) | at most 9 items |
| [`product-head.actions`](https://next.mdxui.dev/docs/reference/refusals#product-head.actions) | 1 to 2 items |
| [`product-list.sort`](https://next.mdxui.dev/docs/reference/refusals#product-list.sort) | at most 4 items |
| [`product-list.views`](https://next.mdxui.dev/docs/reference/refusals#product-list.views) | at most 2 items |
| [`product-list.rows`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows) | at most 50 items |

## Rules that read more than one field

Some designs hold only when two fields agree. A nav row has a budget of 96 units: each link label, plus 3 a link, plus twice the wider of the brand and the button. Harbor tides' bar spends 76. Six long labels and a call spend 142, and the record is refused with the formula in the message.

A `closing` ends on buttons or one command, never both. A footer in columns holds two or three of them, one titled For agents. An FAQ holds items or groups, not both. Each rule is on [Refusals](https://next.mdxui.dev/docs/reference/refusals).

## What a bound is not

A bound is not validation hygiene, and the fix is never a looser one. When a real Business needs more room, the change starts from a render: a new count or a new Section type, decided by eye. Shorter content is the fix for a record, and a record that parses is a page that holds.


# Choosing a Section type (/docs/sections/choosing)

> From what a part of the page must show to the Section type that shows it, with the neighbor to use when the job is a little different.

Start from what the reader must take away from that part of the page, never from a layout. Find the job in the left column, then read the neighbor beside it: two types often do nearly the same job, and the difference decides.

Then fit the counts. Each Section type holds the counts it was drawn at, and the schema refuses others; [Why the design holds](https://next.mdxui.dev/docs/sections/bounds) lists them. When no type fits, the job belongs on another page, or it is a request for a new Section type.

## Not drawn in 7.0.0-alpha.0

A founder asks for a few things a landing page often carries that no Section type draws. Each has a stand-in today.

| Need | Use instead | Status |
| --- | --- | --- |
| An image or a video | The Theme's backgrounds and a [`terminal`](https://next.mdxui.dev/docs/sections/terminal) or [`api-call`](https://next.mdxui.dev/docs/sections/api-call) preview. No field holds a picture, so no page breaks on a missing or oversized one | Not drawn; no image field is specified |
| A gallery | [`bento`](https://next.mdxui.dev/docs/sections/bento), each panel with a preview of the product | Not drawn |
| Testimonials or a quote | [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) with the quote as a titled paragraph, attributed in its text | Not drawn; a worked Site carries no testimonial, since every one is an example |
| A logo wall | [`stats`](https://next.mdxui.dev/docs/sections/stats) or [`facts`](https://next.mdxui.dev/docs/sections/facts): proof as numbers and terms, never as borrowed logos | Not drawn |
| A team | [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack), one titled paragraph per person | Not drawn |

A need that none of these meets is a request for a new Section type.

## Where each type appears

| Job | Section type | Carried by |
| --- | --- | --- |
| Brand and links up top | [`nav`](https://next.mdxui.dev/docs/sections/nav) | every Template |
| Links and notes at the foot | [`footer`](https://next.mdxui.dev/docs/sections/footer) | every Template |
| Open the page with one claim | [`hero`](https://next.mdxui.dev/docs/sections/hero) | `api-product`, `blog`, `directory-list` |
| One claim, set large | [`statement`](https://next.mdxui.dev/docs/sections/statement) | `article`, `blog` |
| A plain page title | [`page-head`](https://next.mdxui.dev/docs/sections/page-head) | `article`, `directory-list` |
| Three or four figures | [`stats`](https://next.mdxui.dev/docs/sections/stats) | `api-product`, `blog`, `directory-list` |
| Labels and values | [`facts`](https://next.mdxui.dev/docs/sections/facts) | `article`, `contact`, `directory-product` |
| Features as a ruled grid | [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) | `api-product`, `article`, `blog`, `directory-product` |
| Three features beside a preview | [`feature-split`](https://next.mdxui.dev/docs/sections/feature-split) | `api-product` |
| Claims, each with a preview | [`bento`](https://next.mdxui.dev/docs/sections/bento) | `api-product`, `article`, `directory-product` |
| The old way against this one | [`compare`](https://next.mdxui.dev/docs/sections/compare) | `api-product` |
| How it works, in order | [`steps`](https://next.mdxui.dev/docs/sections/steps) | `api-product`, `article`, `contact` |
| Titled paragraphs beside copy | [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) | `api-product`, `article`, `blog`, `directory-product` |
| Code or a session | [`terminal`](https://next.mdxui.dev/docs/sections/terminal) | `api-product`, `article` |
| One command to copy | [`command-row`](https://next.mdxui.dev/docs/sections/command-row) | `api-product`, `article`, `blog`, `directory-product` |
| A request beside its answer | [`api-call`](https://next.mdxui.dev/docs/sections/api-call) | `api-product`, `directory-product` |
| Every route at a glance | [`endpoints`](https://next.mdxui.dev/docs/sections/endpoints) | `api-product`, `directory-product` |
| A prompt to paste | [`agent-prompt`](https://next.mdxui.dev/docs/sections/agent-prompt) | `api-product`, `article`, `directory-product` |
| Plans to choose from | [`pricing`](https://next.mdxui.dev/docs/sections/pricing) | `api-product`, `contact`, `directory-product` |
| Plans compared fact by fact | [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) | `api-product`, `directory-product` |
| Questions that open in place | [`faq`](https://next.mdxui.dev/docs/sections/faq) | `api-product`, `contact`, `directory-product` |
| The last call to act | [`closing`](https://next.mdxui.dev/docs/sections/closing) | `api-product`, `article`, `blog`, `directory-list`, `post` |
| A short form to send | [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) | `contact` |
| A page of prose | [`article`](https://next.mdxui.dev/docs/sections/article) | `article`, `post` |
| Posts as ruled rows | [`post-list`](https://next.mdxui.dev/docs/sections/post-list) | `blog` |
| A listing header | [`product-head`](https://next.mdxui.dev/docs/sections/product-head) | `directory-product` |
| Listings as linked rows | [`product-list`](https://next.mdxui.dev/docs/sections/product-list) | `article`, `directory-list` |



# closing (/docs/sections/closing)

> The final call of a page: a head, then buttons or one command, never both.

Preview: every frame of closing is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a closing as the last section before the footer: one head and one way to act. It ends on up to two buttons or on one command of 40 characters, never both, with up to four fine-print lines and up to four figures.

`stack` sets the head above the call; `split` sets them side by side. When the call is a form, use `cta-form`.

Repeat the page's main action, with the same label as the solid action of the hero.

- [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form): the call is a form

## The record

```json title="pages/ledgerhouse/home.json, section 6"
{
  "kind": "closing",
  "shell": { "inset": "contained", "density": "closing" },
  "block": {
    "type": "closing",
    "layout": "stack",
    "head": {
      "eyebrow": "Intake",
      "title": "Start with last month.",
      "lede": "Answer eight questions. A partner replies within two working days with a fixed fee and a start date."
    },
    "actions": [
      { "href": "/intake", "label": "Start intake", "kind": "solid" },
      { "href": "/services", "label": "Read the services", "kind": "ghost" }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "closing",
  "head": { "eyebrow": "Intake", "title": "Start with last month." }
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 1 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#closing.head) | yes |

<details>
<summary>Show all 25 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `layout` | `"stack" \| "split"` | no |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#closing.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#closing.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#closing.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#closing.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#closing.head.tag) | no |
| `head.layout` | `"split"` | no |
| `specimen` | `object` | no |
| `specimen.panel` | `"none" \| "field"` | no |
| `specimen.blocks` | [`1–3 × Section type (nested)`](https://next.mdxui.dev/docs/reference/refusals#closing.specimen.blocks) | yes |
| `fine` | [`0–4 × string ≤72`](https://next.mdxui.dev/docs/reference/refusals#closing.fine) | no |
| `stats` | [`0–4 × object`](https://next.mdxui.dev/docs/reference/refusals#closing.stats) | no |
| `stats[].value` | [`string ≤6`](https://next.mdxui.dev/docs/reference/refusals#closing.stats.value) | yes |
| `stats[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#closing.stats.label) | yes |
| `actions` | [`0–2 × object`](https://next.mdxui.dev/docs/reference/refusals#closing.actions) | no |
| `actions[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#closing.actions.href) | yes |
| `actions[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#closing.actions.label) | yes |
| `actions[].kind` | `"solid" \| "ghost"` | yes |
| `actions[].icon` | `icon or mark name (52)` | no |
| `actions[].external` | `boolean` | no |
| `command` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#closing.command) | no |

</details>

## Variants and counts

Two layouts, `stack` and `split`. A preview of nested sections can sit inside it.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article`, `blog`, `directory-list` and `post` Templates. Seen on `pages/ledgerhouse/home.json`, section 6.

  - Harbor tides: An API product ends on one button to ask for a berth.
  - Vanroster: A scheduling product ends split, with the trial button beside the head.
  - Ledgerhouse: A bookkeeping firm ends on one button to book an intake.
  - Diffkeel: A developer tool ends on the install command, split beside its head.
  - Benchlist: A directory ends on one button to list a bench.
  - Sidework: A weekly letter ends on one button to subscribe.

## Do and do not

  - Do: One button, one decision.
  - Don't: Buttons and a command together are refused: a closing ends on one or the other.

  - Do: One fine-print line at most, under the call.
  - Don't: Four fine-print lines bury the call under conditions.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The closing is the last section of `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2`.
- **Focus order** Tab reaches the buttons in record order, or the copy control of the command.

## Related

  - [cta-form](https://next.mdxui.dev/docs/sections/cta-form): Use it for the call is a form.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/closing.md. Add a closing section as the last section of pages/home.json: a head and either one or two buttons or one command, never both. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# command-row (/docs/sections/command-row)

> One command to copy, with a note beneath it.

Preview: every frame of command-row is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a command row for the one command a reader copies: an install, an init. It holds a command of 40 characters and a note of 48, and renders a copy control that strips the prompt.

Place it right after the hero, as a band. When the reader needs more than one line, use `terminal`.

Show the command exactly as it runs, with no placeholder to edit. Use the note for what it needs, such as a runtime version.

- [`terminal`](https://next.mdxui.dev/docs/sections/terminal): more than one line

## The record

```json title="pages/harbor/home.json, section 2"
{
  "kind": "band",
  "shell": { "inset": "contained", "density": "compact" },
  "block": { "type": "command-row", "command": "npm i @example/harbor-tides", "note": "Node.js 22 or later" }
}
```

## Smallest that parses

```json
{ "type": "command-row", "command": "npm i @example/harbor-tides" }
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

| Prop | Type and bound | Required |
| --- | --- | --- |
| `command` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#command-row.command) | yes |
| `note` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#command-row.note) | no |

## Variants and counts

One layout: the command, its copy control and the note.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article`, `blog` and `directory-product` Templates. Seen on `pages/harbor/home.json`, section 2.

  - Harbor tides: An API product puts its npm install under the hero.
  - Vanroster: A scheduling product gives the command that installs its CLI.
  - Ledgerhouse: A bookkeeping firm gives no command; its reader is not at a shell.
  - Diffkeel: A developer tool puts its one-line install under the hero.
  - Benchlist: A directory gives the command that fetches its listings.
  - Sidework: A weekly letter gives the command that adds its feed.

## Do and do not

  - Do: A note adding a fact: the runtime it needs.
  - Don't: A note repeating the command spends the line on nothing.

  - Do: A command short enough to read at a glance.
  - Don't: A pipeline past 40 characters is refused; move it to a `terminal`.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Copy controls that announce the result | all | 0 of 1 | no |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The row sits in `main`. It adds no landmark.
- **Heading level** It carries no heading.
- **Focus order** The copy control takes focus, named Copy command. It does not announce that it copied in 7.0.0-alpha.0, as counted above.

## Related

  - [terminal](https://next.mdxui.dev/docs/sections/terminal): Use it for more than one line.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/command-row.md. Add a command-row section under the hero of pages/home.json: the one install command of at most 40 characters, with a note of at most 48. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# compare (/docs/sections/compare)

> Two columns side by side: what the old way costs and what this one gives.

Preview: every frame of compare is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use compare when the reader already does the job another way. It holds a head and two labeled columns, the old way and this one, with one to eight items of 56 characters each.

Pair the items line by line, so each cost sits across from its answer. When the reader compares plans rather than approaches, use `plan-table`.

Name the old way by what the reader uses today, such as station tables, never by a competitor's name.

- [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table): plans, not approaches

## The record

```json title="pages/harbor/home.json, section 8"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "compare",
    "head": { "eyebrow": "Against station tables", "title": "The berth, not the nearest station." },
    "cons": {
      "label": "Station tables",
      "items": ["Heights at the station", "One PDF per month", "Datum in the small print", "Math done by hand"]
    },
    "pros": {
      "label": "Harbor tides",
      "items": ["Heights at the berth", "Fourteen days per call", "Datum on every height", "The window computed"]
    }
  }
}
```

## Smallest that parses

```json
{
  "type": "compare",
  "head": { "eyebrow": "Against station tables", "title": "The berth, not the nearest station." },
  "cons": {
    "label": "Station tables",
    "items": ["Heights at the station"]
  },
  "pros": {
    "label": "Harbor tides",
    "items": ["Heights at the berth"]
  }
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 3 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#compare.head) | yes |
| `cons` | `object` | yes |
| `pros` | `object` | yes |

<details>
<summary>Show all 16 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#compare.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#compare.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#compare.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#compare.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#compare.head.tag) | no |
| `head.layout` | `"split"` | no |
| `cons` | `object` | yes |
| `cons.label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#compare.cons.label) | yes |
| `cons.items` | [`1–8 × string ≤56`](https://next.mdxui.dev/docs/reference/refusals#compare.cons.items) | yes |
| `pros` | `object` | yes |
| `pros.label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#compare.pros.label) | yes |
| `pros.items` | [`1–8 × string ≤56`](https://next.mdxui.dev/docs/reference/refusals#compare.pros.items) | yes |

</details>

## Variants and counts

One layout: two columns side by side, stacked on a phone.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product` Template. Seen on `pages/harbor/home.json`, section 8.

  - Harbor tides: An API product sets station tables against tides per berth.
  - Vanroster: A scheduling product sets the group chat against one schedule.
  - Ledgerhouse: A bookkeeping firm sets a year-end scramble against a monthly close.
  - Diffkeel: A developer tool sets a review by eye against a diff before deploy.
  - Benchlist: A directory sets a rented shop against a bench by the hour.
  - Sidework: A weekly letter sets scattered advice against one letter a week.

## Do and do not

  - Do: Four items each side, each cost across from its answer.
  - Don't: Eight costs against one vague answer reads as a rant, not a comparison.

  - Do: Items of three to six words.
  - Don't: An item written as a sentence runs past 56 characters and is refused.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** Compare sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2`; each column is a labeled list, `ul`.
- **Focus order** Nothing in it takes focus.

## Related

  - [plan-table](https://next.mdxui.dev/docs/sections/plan-table): Use it for plans, not approaches.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/compare.md. Add a compare section to pages/home.json: the old way against mine, up to eight items a side of at most 56 characters, paired line by line. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# Composition and dividers (/docs/sections/composition)

> How sections compose into a page: the Theme draws every divider from the pair it sits between, the kind picks the landmark, and the frame sets the page.

A page lists its sections in order and says nothing about what goes between them. The composer reads each adjacent pair and the Theme's divider policy, and draws the divider; it reads each kind and places the band in its landmark.

## The Theme draws the dividers

A section never declares a divider. A divider that reads well between a dark band and a light one reads as broken between two light ones, so each Theme states its rule as data, evaluated pair by pair. Swap the Theme on the page below and watch the joins change.

The rendered page: https://next.mdxui.dev/sites/harbor/; its record: https://next.mdxui.dev/pages/harbor/home.json

| Theme | Between sections | After a kind | Around a kind | After a plate | Between two plates |
| --- | --- | --- | --- | --- | --- |
| certificate | hatch | `hero`: hatch | `band`, `closing`: rule | | |
| vaultline | rule | `article`: none | | none | contained rule |
| quaypoint | rule | `article`: none | | none | contained rule |
| callboard | rule | `article`: none | | none | contained rule |
| directory | none | | | | none |

The policy is read from `@mdxui/themes@7.0.0-alpha.0`. "After a kind" wins over the rest; a contained rule spans the content width only.

## The kind picks the landmark

The first `nav` or `bar` becomes the page's `header`, the `footer` its `footer`, and every section between them lands in one `main`, the target of the skip link. A record never names an element, so no page nests a landmark inside itself.

## The frame sets the page

`frame` is one of three. Harbor tides uses `none`; no record in this build uses `sheet` or `split`, so they are drawn here as diagrams of the published shell rules.

On a `split` page, set `aside` on the shell of each section that belongs in the side column, such as a `product-head`. Below 1,024 px the aside stacks first, as the head of the page.

## No two bands share a skeleton

Two adjacent sections that could swap layouts unnoticed read as one long band. Harbor tides' home alternates on purpose: a centered hero, a one-line command, a grid, a request on a plate, a list of routes, copy beside a window, panels, two columns, numbered steps. Each band changes the shape the eye follows, so the reader always knows a new idea has begun.


# cta-form (/docs/sections/cta-form)

> Copy beside a short form: a plain post, answered with no script.

Preview: every frame of cta-form is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a CTA form when the call is to send something: a question, an intake, an email address. It holds a head, one to eight fields, a submit label of 24 characters and a note of 80, and posts to its `action` with no script.

Ask only for what the answer needs. When the call is a button or a command, use `closing`.

Label each field with the noun the reader fills in, and use the note for when an answer comes.

- [`closing`](https://next.mdxui.dev/docs/sections/closing): the call is a button or a command

## The record

```json title="pages/benchlist/list-a-bench.json, section 2"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section", "surface": "tint" },
  "block": {
    "type": "cta-form",
    "head": { "eyebrow": "Listing request", "title": "Tell Benchlist about it.", "lede": "Six answers. The tools you name become the listing." },
    "action": "/list-a-bench/sent",
    "fields": [
      { "name": "workshop", "type": "text", "label": "Workshop", "placeholder": "Where the bench is" },
      { "name": "email", "type": "email", "label": "Email", "placeholder": "host@workshop.example" },
      {
        "name": "city",
        "type": "select",
        "label": "City",
        "options": ["Duluth", "Superior", "Two Harbors", "Cloquet", "Another city"]
      },
      {
        "name": "kind",
        "type": "select",
        "label": "Kind",
        "options": ["Kiln room", "Woodshop", "Metal", "Print", "Textile", "Jewelry", "Other"]
      },
      { "name": "rate", "type": "text", "label": "Hourly rate", "placeholder": "$20" },
      { "name": "tools", "type": "textarea", "label": "Tools included", "placeholder": "One tool per line" }
    ],
    "submit": "Send listing",
    "note": "Benchlist takes 12 percent of each booking."
  }
}
```

## Smallest that parses

```json
{
  "type": "cta-form",
  "head": { "eyebrow": "Listing request", "title": "Tell Benchlist about it." },
  "action": "/list-a-bench/sent",
  "fields": [
    { "name": "workshop", "type": "text", "label": "Workshop" }
  ],
  "submit": "Send listing"
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 4 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#cta-form.head) | yes |
| `action` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#cta-form.action) | yes |
| `fields` | [`1–8 × object`](https://next.mdxui.dev/docs/reference/refusals#cta-form.fields) | yes |
| `submit` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#cta-form.submit) | yes |

<details>
<summary>Show all 19 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#cta-form.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#cta-form.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#cta-form.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#cta-form.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#cta-form.head.tag) | no |
| `head.layout` | `"split"` | no |
| `action` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#cta-form.action) | yes |
| `fields` | [`1–8 × object`](https://next.mdxui.dev/docs/reference/refusals#cta-form.fields) | yes |
| `fields[].name` | `string (pattern)` | yes |
| `fields[].type` | `"text" \| "email" \| "select" \| "textarea"` | yes |
| `fields[].label` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#cta-form.fields.label) | yes |
| `fields[].placeholder` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#cta-form.fields.placeholder) | no |
| `fields[].options` | [`0–12 × string ≤32`](https://next.mdxui.dev/docs/reference/refusals#cta-form.fields.options) | no |
| `submit` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#cta-form.submit) | yes |
| `note` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#cta-form.note) | no |

</details>

## Variants and counts

One layout, from 1 field to 8. Field names are lowercase, so the post reads cleanly.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `contact` Template. Seen on `pages/benchlist/list-a-bench.json`, section 2.

  - Harbor tides: An API product asks for a name, an email, a topic and a message.
  - Vanroster: A scheduling product asks for a crew size and an email.
  - Ledgerhouse: A bookkeeping firm runs its intake in eight fields.
  - Diffkeel: A developer tool asks for an email and the repository host.
  - Benchlist: A directory asks a host for the bench, its city and its price.
  - Sidework: A weekly letter asks for one field: an email address.

## Do and do not

  - Do: Four fields for a question the harbor answers.
  - Don't: Eight fields to ask a question make the reader do the answer work.

  - Do: Field names in lowercase, like `email`.
  - Don't: A name with a space is refused by its pattern.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The form sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2`. Every field has a `label`, and a status region announces the result.
- **Focus order** Tab runs the fields in record order, then submit. A hidden trap field takes no focus.

## Related

  - [closing](https://next.mdxui.dev/docs/sections/closing): Use it for the call is a button or a command.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/cta-form.md. Add a cta-form section to my contact page: the fewest fields the answer needs, at most eight, lowercase field names and a submit label of at most 24 characters. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# endpoints (/docs/sections/endpoints)

> An API at a glance: one ruled row per route, with its method, path and job.

Preview: every frame of endpoints is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use endpoints to show the shape of an API: every route on one screen. It holds a head and three to sixteen rows, each a method, a path of 64 characters and a job of 96, with an optional link to the route's docs.

Write the job as what the route returns. For one route with its answer, use `api-call`.

Order the routes as a reader meets them: list, read, then write.

- [`api-call`](https://next.mdxui.dev/docs/sections/api-call): one call with its answer

## The record

```json title="pages/harbor/home.json, section 5"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "endpoints",
    "head": { "eyebrow": "The API", "title": "Four routes, one shape." },
    "rows": [
      { "method": "GET", "path": "/v1/berths", "text": "Every berth in a harbor, with its charted depth" },
      { "method": "GET", "path": "/v1/berths/{berth}/tides", "text": "High and low water for one berth" },
      { "method": "GET", "path": "/v1/berths/{berth}/window", "text": "The hours a given draft clears" },
      { "method": "POST", "path": "/v1/alerts", "text": "A webhook before a window closes" }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "endpoints",
  "head": { "eyebrow": "The API", "title": "Four routes, one shape." },
  "rows": [
    { "method": "GET", "path": "/v1/berths", "text": "Every berth in a harbor, with its charted depth" },
    { "method": "GET", "path": "/v1/berths/{berth}/tides", "text": "High and low water for one berth" },
    { "method": "GET", "path": "/v1/berths/{berth}/window", "text": "The hours a given draft clears" }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 2 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#endpoints.head) | yes |
| `rows` | [`3–16 × object`](https://next.mdxui.dev/docs/reference/refusals#endpoints.rows) | yes |

<details>
<summary>Show all 16 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#endpoints.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#endpoints.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#endpoints.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#endpoints.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#endpoints.head.tag) | no |
| `head.layout` | `"split"` | no |
| `rows` | [`3–16 × object`](https://next.mdxui.dev/docs/reference/refusals#endpoints.rows) | yes |
| `rows[].method` | `"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"` | yes |
| `rows[].path` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#endpoints.rows.path) | yes |
| `rows[].text` | [`string ≤96`](https://next.mdxui.dev/docs/reference/refusals#endpoints.rows.text) | yes |
| `rows[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#endpoints.rows.href) | no |
| `note` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#endpoints.note) | no |

</details>

## Variants and counts

One layout, from 3 to 16 rows.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product` and `directory-product` Templates. Seen on `pages/harbor/home.json`, section 5.

  - Harbor tides: An API product lists its four routes: berths, tides, windows, alerts.
  - Vanroster: A scheduling product lists its crew, job and route endpoints.
  - Ledgerhouse: A bookkeeping firm lists the routes its client portal reads.
  - Diffkeel: A developer tool lists its hosted diff and history routes.
  - Benchlist: A directory lists its bench, city and booking routes.
  - Sidework: A weekly letter lists its issue and archive routes.

## Do and do not

  - Do: Four routes show the shape of the API.
  - Don't: Two routes are refused: the list holds three to sixteen. Show one with `api-call`.

  - Do: Each job says what the route returns.
  - Don't: Jobs that restate the path tell the reader nothing new.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The list sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2`; the routes are a list, `ul`.
- **Focus order** Only a row with a link takes focus, in record order.

## Related

  - [api-call](https://next.mdxui.dev/docs/sections/api-call): Use it for one call with its answer.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/endpoints.md. Add an endpoints section to my API page: every route, three to sixteen rows, each with its method, a path of at most 64 characters and what it returns in at most 96. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# facts (/docs/sections/facts)

> Labels and values a buyer decides on, as one ruled list.

Preview: every frame of facts is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use facts on a listing or a product page for what a buyer compares: what it reads, how often it updates, what it runs on. It holds up to 16 pairs, a label of 24 characters and a value of 80, under an optional title.

Set `code` on a value that is a package or a command, so it renders in mono. When the values are three or four big numbers, use `stats`.

Order the pairs by what a buyer asks first. Keep each value a fact, never an adjective.

- [`stats`](https://next.mdxui.dev/docs/sections/stats): three or four big numbers

## The record

```json title="pages/benchlist/about.json, section 4"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "facts",
    "title": "Benchlist",
    "items": [
      { "label": "Cities", "value": "Duluth" },
      { "label": "Benches listed", "value": "10", "href": "/city/duluth" },
      { "label": "Host fee", "value": "12 percent of each booking" },
      { "label": "Renter fee", "value": "None" },
      { "label": "Write to", "value": "hello@benchlist.example", "code": true }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "facts",
  "title": "Benchlist",
  "items": [
    { "label": "Cities", "value": "Duluth" }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

| Prop | Type and bound | Required |
| --- | --- | --- |
| `title` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#facts.title) | no |
| `items` | [`1–16 × object`](https://next.mdxui.dev/docs/reference/refusals#facts.items) | yes |
| `items[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#facts.items.label) | yes |
| `items[].value` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#facts.items.value) | yes |
| `items[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#facts.items.href) | no |
| `items[].code` | `boolean` | no |

## Variants and counts

One layout, from 1 to 16 pairs.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `article`, `contact` and `directory-product` Templates. Seen on `pages/benchlist/about.json`, section 4.

  - Harbor tides: An API listing gives what the integration reads, how often, and its package name.
  - Vanroster: A scheduling product gives each feature its limits and where it runs.
  - Ledgerhouse: A bookkeeping firm gives each service its scope, its price and its timing.
  - Diffkeel: A developer tool gives the formats, the platforms and the license terms.
  - Benchlist: A directory listing gives a bench size, its tools and its hours.
  - Sidework: A weekly letter gives its day, its length and its price.

## Do and do not

  - Do: Values a buyer can compare: an interval, a protocol, a package.
  - Don't: Adjectives in the value slot give the buyer nothing to decide on.

  - Do: Labels of one or two words.
  - Don't: A label written as a question runs past 24 characters and is refused.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** Facts sit in `main`. They add no landmark.
- **Heading level** The title renders as an `h2`; the pairs are a description list, `dl`, so each label names its value.
- **Focus order** Only a value with a link takes focus, in record order.

## Related

  - [stats](https://next.mdxui.dev/docs/sections/stats): Use it for three or four big numbers.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/facts.md. Add a facts section to my listing page: up to 16 label and value pairs, labels of at most 24 characters and values of at most 80. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# faq (/docs/sections/faq)

> A heading beside questions that open in place, every one closed at first.

Preview: every frame of faq is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use an FAQ for the questions a buyer asks before choosing: what counts, what happens past a limit, how to leave. It holds up to ten items, or up to four titled groups of six, with questions of 64 characters and answers of 420.

Every item opens in place with no script, and all start closed. When the answers should stay open, use `text-stack`.

Write each question in the buyer's words and answer it in the first sentence; add the condition after.

- [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack): answers that stay open

## The record

```json title="pages/benchlist/list-a-bench.json, section 3"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "faq",
    "head": { "eyebrow": "Questions", "title": "Before you list." },
    "items": [
      { "q": "What does Benchlist charge?", "a": "12 percent of each booking, taken when it is paid. Listing costs nothing." },
      { "q": "Who sets the rules?", "a": "The host. House rules print on the listing and every renter accepts them before booking." },
      { "q": "What can be listed?", "a": "A bench, a room or a machine, by the hour. Benchlist lists things, never people or lessons." }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "faq",
  "head": { "eyebrow": "Questions", "title": "Before you list." },
  "items": [
    { "q": "What does Benchlist charge?", "a": "12 percent of each booking, taken when it is paid. Listing costs nothing." },
    { "q": "Who sets the rules?", "a": "The host. House rules print on the listing and every renter accepts them before booking." },
    { "q": "What can be listed?", "a": "A bench, a room or a machine, by the hour. Benchlist lists things, never people or lessons." }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 1 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#faq.head) | yes |

<details>
<summary>Show all 18 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#faq.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#faq.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#faq.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#faq.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#faq.head.tag) | no |
| `head.layout` | `"split"` | no |
| `items` | [`1–10 × object`](https://next.mdxui.dev/docs/reference/refusals#faq.items) | no |
| `items[].q` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#faq.items.q) | yes |
| `items[].a` | [`string ≤420`](https://next.mdxui.dev/docs/reference/refusals#faq.items.a) | yes |
| `groups` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#faq.groups) | no |
| `groups[].title` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#faq.groups.title) | yes |
| `groups[].items` | [`1–6 × object`](https://next.mdxui.dev/docs/reference/refusals#faq.groups.items) | yes |
| `groups[].items[].q` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#faq.groups.items.q) | yes |
| `groups[].items[].a` | [`string ≤420`](https://next.mdxui.dev/docs/reference/refusals#faq.groups.items.a) | yes |

</details>

## Variants and counts

Two shapes: `items`, or `groups` with titles. A record holds one or the other.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `contact` and `directory-product` Templates. Seen on `pages/benchlist/list-a-bench.json`, section 3.

  - Harbor tides: An API product answers what a call is and what happens past the limit.
  - Vanroster: A scheduling product groups its questions by billing and setup.
  - Ledgerhouse: A bookkeeping firm answers what the monthly price covers.
  - Diffkeel: A developer tool answers what it sends off the machine.
  - Benchlist: A directory answers how booking and refunds work.
  - Sidework: A weekly letter answers how to cancel.

## Do and do not

  - Do: Answers that state the rule.
  - Don't: One-word answers make the reader open a question for nothing.

  - Do: Items or groups, one shape.
  - Don't: Items and groups together are refused: a record holds one or the other.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The FAQ sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2` and group titles as `h3`. Each item is a `details` with its question as the `summary`.
- **Focus order** Tab reaches each question; Enter or Space opens it.

## Related

  - [text-stack](https://next.mdxui.dev/docs/sections/text-stack): Use it for answers that stay open.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/faq.md. Add a faq section to my pricing page: up to ten questions of at most 64 characters, each answered in at most 420. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# feature-grid (/docs/sections/feature-grid)

> A section head over a hairline grid of two, three, four, six or eight cells.

Preview: every frame of feature-grid is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a feature grid for features that stand on their own, each with a title and a line. It holds 2, 3, 4, 6 or 8 cells, the counts that fill every row at every width, under a head.

Pick a cell head: a label, an icon, an icon with an index or a label, or none. When three features need one preview beside them, use `feature-split`; when each needs its own, use `bento`.

Write each title as the thing a reader gets, and each line as how. Keep every cell to the same fields.

- [`feature-split`](https://next.mdxui.dev/docs/sections/feature-split): three features beside one preview
- [`bento`](https://next.mdxui.dev/docs/sections/bento): each claim with its own preview

## The record

```json title="pages/diffkeel/home.json, section 4"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "feature-grid",
    "head": { "eyebrow": "Four commands", "title": "Render, diff, mask, gate." },
    "cellHead": "icon-label",
    "items": [
      {
        "icon": "layers",
        "label": "Render",
        "title": "The config each env gets",
        "text": "Overlays, defaults and env files resolved into the final values."
      },
      {
        "icon": "git-commit-horizontal",
        "label": "Diff",
        "title": "Against what runs now",
        "text": "Compared with the live config, key by key, not file by file."
      },
      {
        "icon": "shield-check",
        "label": "Mask",
        "title": "Secrets stay masked",
        "text": "A changed secret shows as changed, with a short hash. Its value never prints."
      },
      {
        "icon": "check",
        "label": "Gate",
        "title": "Unreviewed changes fail",
        "text": "A prod change without a review exits 1, in any CI that runs a container."
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "feature-grid",
  "cellHead": "icon-label",
  "items": [
    { "title": "The config each env gets" },
    { "title": "Against what runs now" }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 2 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `cellHead` | `"label" \| "icon-index" \| "icon-label" \| "icon" \| "none"` | yes |
| `items` | [`2–8 × object`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items) | yes |

<details>
<summary>Show all 23 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.head) | no |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.head.tag) | no |
| `head.layout` | `"split"` | no |
| `aside` | `object` | no |
| `aside.command` | [`string ≤12`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.aside.command) | yes |
| `aside.note` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.aside.note) | yes |
| `cellHead` | `"label" \| "icon-index" \| "icon-label" \| "icon" \| "none"` | yes |
| `dense` | `boolean` | no |
| `items` | [`2–8 × object`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items) | yes |
| `items[].icon` | `icon or mark name (52)` | no |
| `items[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items.label) | no |
| `items[].index` | [`string ≤2`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items.index) | no |
| `items[].title` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items.title) | no |
| `items[].text` | [`string ≤200`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items.text) | no |
| `items[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items.href) | no |
| `items[].linkLabel` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#feature-grid.items.linkLabel) | no |

</details>

## Variants and counts

Five designed counts. Any other count is refused, because it leaves a ragged last row.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article`, `blog` and `directory-product` Templates. Seen on `pages/diffkeel/home.json`, section 4.

  - Harbor tides: An API product gives three things one call returns.
  - Vanroster: A scheduling product lays out six features of the dispatch board.
  - Ledgerhouse: A bookkeeping firm sets the two halves of its monthly close side by side.
  - Diffkeel: A developer tool gives four checks its diff runs.
  - Benchlist: A directory gives three ways to find a bench.
  - Sidework: A weekly letter gives three things each issue holds.

## Do and do not

  - Do: Three cells fill one row and stack cleanly on a phone.
  - Don't: Five cells are refused: a feature grid holds 2, 3, 4, 6 or 8.

  - Do: Every cell carries the same fields: icon, title, line.
  - Don't: Cells with different fields read as broken: one long, one bare, one untitled.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The grid sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2` and each cell title as an `h3`.
- **Focus order** Only a cell with a link takes focus, in record order: left to right, then down.

## Related

  - [feature-split](https://next.mdxui.dev/docs/sections/feature-split): Use it for three features beside one preview.
  - [bento](https://next.mdxui.dev/docs/sections/bento): Use it for each claim with its own preview.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/feature-grid.md. Add a feature-grid section to pages/home.json for my Business with 3, 4 or 6 cells, each with an icon, a title of at most 40 characters and a line of at most 200. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# feature-split (/docs/sections/feature-split)

> Copy with exactly three features beside one preview window.

Preview: every frame of feature-split is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a feature split when one artifact proves three features: a response, a config, a prompt. It holds a head, exactly three items and a preview of one to three nested sections, such as a `terminal`.

Each item holds a title of 28 characters, a line of 96 and up to four bullets. For more or fewer than three features, use `feature-grid`.

Pick the preview first, then write the three features it shows, so each item points at something in the window.

- [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid): more or fewer than three features

## The record

```json title="pages/harbor/home.json, section 6"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "feature-split",
    "head": { "eyebrow": "For the bridge", "title": "Plan the passage, not the math." },
    "items": [
      { "icon": "clock", "title": "Windows, not tables", "text": "Ask for a draft and get the hours it clears." },
      { "icon": "bell", "title": "Alerts before the turn", "text": "A webhook fires an hour before a window closes." },
      { "icon": "shield-check", "title": "One source per berth", "text": "Each answer names its station and its datum." }
    ],
    "specimen": {
      "blocks": [
        {
          "type": "terminal",
          "variant": "plain",
          "title": "A 3.2 m draft at pier 4",
          "lang": "json",
          "lines": ["{", "  \"draft\": 3.2,", "  \"opens\": \"08:05\",", "  \"closes\": \"12:50\"", "}"]
        }
      ]
    }
  }
}
```

## Smallest that parses

```json
{
  "type": "feature-split",
  "head": { "eyebrow": "For the bridge", "title": "Plan the passage, not the math." },
  "items": [
    { "title": "Windows, not tables", "text": "Ask for a draft and get the hours it clears." },
    { "title": "Alerts before the turn", "text": "A webhook fires an hour before a window closes." },
    { "title": "One source per berth", "text": "Each answer names its station and its datum." }
  ],
  "specimen": {
    "blocks": [
      {
        "type": "terminal",
        "variant": "plain",
        "title": "A 3.2 m draft at pier 4",
        "lines": ["{"]
      }
    ]
  }
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 3 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#feature-split.head) | yes |
| `items` | [`3 × object`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items) | yes |
| `specimen` | `object` | yes |

<details>
<summary>Show all 20 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#feature-split.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#feature-split.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#feature-split.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#feature-split.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#feature-split.head.tag) | no |
| `head.layout` | `"split"` | no |
| `bases` | [`[integer 240–640, integer 240–640]`](https://next.mdxui.dev/docs/reference/refusals#feature-split.bases) | no |
| `items` | [`3 × object`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items) | yes |
| `items[].icon` | `icon or mark name (52)` | no |
| `items[].index` | [`string ≤2`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items.index) | no |
| `items[].title` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items.title) | yes |
| `items[].text` | [`string ≤96`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items.text) | yes |
| `items[].bullets` | [`0–4 × string ≤48`](https://next.mdxui.dev/docs/reference/refusals#feature-split.items.bullets) | no |
| `specimen` | `object` | yes |
| `specimen.panel` | `"none" \| "field"` | no |
| `specimen.blocks` | [`1–3 × Section type (nested)`](https://next.mdxui.dev/docs/reference/refusals#feature-split.specimen.blocks) | yes |

</details>

## Variants and counts

One layout: copy at the left, the preview at the right, stacked on a phone.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product` Template. Seen on `pages/harbor/home.json`, section 6.

  - Harbor tides: An API product sets three bridge features beside the answer for one draft.
  - Vanroster: A scheduling product sets three dispatch features beside a crew schedule.
  - Ledgerhouse: A bookkeeping firm sets three close steps beside a sample report.
  - Diffkeel: A developer tool sets three checks beside the diff they produce.
  - Benchlist: A directory sets three listing features beside a sample bench.
  - Sidework: A weekly letter sets three sections of an issue beside its first lines.

## Do and do not

  - Do: Three features, one line each, beside the preview.
  - Don't: A fourth feature is refused: the split holds exactly three.

  - Do: Short lines leave the preview the weight.
  - Don't: Four bullets under every item outweigh the preview they sit beside.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Scroll regions a keyboard cannot reach | 0 | 1 of 1 | no |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The split sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2` and each item title as an `h3`. The preview adds no heading.
- **Focus order** Tab reaches a copy control in the preview after the items. A window that scrolls sideways takes no focus, as counted above, so keep its lines short.

## Related

  - [feature-grid](https://next.mdxui.dev/docs/sections/feature-grid): Use it for more or fewer than three features.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/feature-split.md. Add a feature-split section to pages/home.json: exactly three features with titles of at most 28 characters, beside one terminal preview that shows them working. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# footer (/docs/sections/footer)

> The foot of a page: brand and blurb, link columns and a ruled note row.

Preview: every frame of footer is listed in https://next.mdxui.dev/components/manifest.json

## When to use

End every page of a Site with one footer. `columns` sets two or three titled link columns beside the brand and its blurb, and one column is titled For agents. `areas` places the same columns in a grid with the call under the brand.

`row` puts the brand and a single row of links on one line, for a Site of a few pages. Every layout ends on a note of two lines, at most 96 characters each.

In the For agents column, link what an agent reads: the page records, the schema, `llms.txt`.

No neighbor does this job.

## The record

```json title="pages/ledgerhouse/home.json, section 7"
{
  "kind": "footer",
  "shell": { "inset": "contained", "density": "footer" },
  "block": {
    "type": "footer",
    "layout": "columns",
    "brand": { "href": "/", "text": "Ledgerhouse", "mark": "landmark" },
    "blurb": "Bookkeeping and tax for small businesses, by two partners and no handoffs.",
    "columns": [
      {
        "title": "The firm",
        "links": [
          ["/services", "Services"],
          ["/services/monthly-close", "Monthly close"],
          ["/pricing", "Fees"],
          ["/about", "About"]
        ]
      },
      {
        "title": "Clients",
        "links": [
          ["/intake", "Intake"],
          ["/terms", "Terms of engagement"]
        ]
      },
      {
        "title": "For agents",
        "links": [
          ["/records.zip", "Site records (.zip)"],
          ["/services/monthly-close", "What a close report holds"]
        ]
      }
    ],
    "note": ["Ledgerhouse is a worked example on mdxui.dev, not a customer.", "Rendered by @mdxui/site. Forms here do not send."]
  }
}
```

## Smallest that parses

```json
{
  "type": "footer",
  "layout": "columns",
  "brand": { "href": "/", "text": "Ledgerhouse" },
  "columns": [
    {
      "title": "The firm",
      "links": [
        ["/services", "Services"],
        ["/services/monthly-close", "Monthly close"],
        ["/pricing", "Fees"],
        ["/about", "About"]
      ]
    },
    {
      "title": "Clients",
      "links": [
        ["/intake", "Intake"],
        ["/terms", "Terms of engagement"]
      ]
    },
    {
      "title": "For agents",
      "links": [
        ["/records.zip", "Site records (.zip)"],
        ["/services/monthly-close", "What a close report holds"]
      ]
    }
  ],
  "note": ["Ledgerhouse is a worked example on mdxui.dev, not a customer.", "Rendered by @mdxui/site. Forms here do not send."]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 4 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `layout` | `"columns" \| "areas" \| "row"` | yes |
| `brand` | [`object`](https://next.mdxui.dev/docs/reference/refusals#footer.brand) | yes |
| `columns` | [`0–4 × object`](https://next.mdxui.dev/docs/reference/refusals#footer.columns) | yes |
| `note` | [`[string ≤96, string ≤96]`](https://next.mdxui.dev/docs/reference/refusals#footer.note) | yes |

<details>
<summary>Show all 25 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `layout` | `"columns" \| "areas" \| "row"` | yes |
| `brand` | [`object`](https://next.mdxui.dev/docs/reference/refusals#footer.brand) | yes |
| `brand.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#footer.brand.href) | yes |
| `brand.text` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#footer.brand.text) | no |
| `brand.mark` | `icon or mark name (52)` | no |
| `brand.suffix` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#footer.brand.suffix) | no |
| `brand.tile` | `boolean` | no |
| `blurb` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#footer.blurb) | no |
| `columns` | [`0–4 × object`](https://next.mdxui.dev/docs/reference/refusals#footer.columns) | yes |
| `columns[].title` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#footer.columns.title) | yes |
| `columns[].label` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#footer.columns.label) | no |
| `columns[].links` | [`1–12 × [string ≤160, string ≤48]`](https://next.mdxui.dev/docs/reference/refusals#footer.columns.links) | yes |
| `cta` | `object` | no |
| `cta.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#footer.cta.href) | yes |
| `cta.label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#footer.cta.label) | yes |
| `cta.icon` | `icon or mark name (52)` | no |
| `social` | [`0–6 × object`](https://next.mdxui.dev/docs/reference/refusals#footer.social) | no |
| `social[].mark` | `"bluesky" \| "github" \| "linkedin" \| "npm" \| "reddit" \| "x" \| "ycombinator"` | yes |
| `social[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#footer.social.href) | yes |
| `form` | `object` | no |
| `form.action` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#footer.form.action) | yes |
| `form.label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#footer.form.label) | yes |
| `form.placeholder` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#footer.form.placeholder) | yes |
| `form.submit` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#footer.form.submit) | yes |
| `note` | [`[string ≤96, string ≤96]`](https://next.mdxui.dev/docs/reference/refusals#footer.note) | yes |

</details>

## Variants and counts

Three layouts: `columns`, `areas` and `row`. Any of them can carry a sign-up form and up to six social marks.

### One record in five Themes

## Shells

## In three Businesses

Carried by every Template. Seen on `pages/ledgerhouse/home.json`, section 7.

  - Harbor tides: An API product keeps one row: pricing, integrations, blog, contact and terms, and a note naming it a worked example.
  - Vanroster: A scheduling product lays its columns out in areas, with the trial call under the brand.
  - Ledgerhouse: A bookkeeping firm sets its services, its firm and the For agents column in three columns.
  - Diffkeel: A developer tool links install, changelog and the records an agent reads.
  - Benchlist: A directory links cities and the form to list a bench.
  - Sidework: A weekly letter ends on one row and the field to subscribe.

## Do and do not

  - Do: Two or three columns, one of them For agents, beside the brand.
  - Don't: Four one-link columns, none For agents, are refused: a footer in columns holds two or three.

  - Do: A note of two short facts a reader can scan.
  - Don't: A note running to a paragraph in each line crowds the last thing on the page.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Unnamed nav landmarks | 0 | 3 of 3 | no |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The footer renders the page `footer`, after `main`. Each link column is its own `nav`; give it a `label` to name it, as the check above counts.
- **Heading level** Column titles render as `h4`.
- **Focus order** Tab runs brand, then each column top to bottom, then the form and the social marks.

## Related

No neighbor does this job.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/footer.md. Add a footer section to every page of my Site: two or three link columns, one of them titled For agents, and a two-line note of at most 96 characters a line. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# hero (/docs/sections/hero)

> The opening of a page: headline, lede, actions, fine print and an optional preview window.

Preview: every frame of hero is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Open every landing page with one hero. It says what the Business sells in at most 64 characters, adds a lede of at most 260 and offers at most two actions.

Choose `split` when a preview proves the claim: a request, a record or a command beside the words. Choose `centered` when the words carry the page, as on a services firm or a publication. Fine print holds up to four short facts a buyer checks before acting, such as a free allowance.

Write the title as the outcome, not the mechanism: what the buyer has afterward, in the buyer's words.

- [`page-head`](https://next.mdxui.dev/docs/sections/page-head): a plain heading with no actions
- [`product-head`](https://next.mdxui.dev/docs/sections/product-head): a product in a directory

## The record

```json title="pages/ledgerhouse/home.json, section 1"
{
  "kind": "hero",
  "shell": { "inset": "contained", "density": "hero", "background": "grain" },
  "block": {
    "type": "hero",
    "layout": "centered",
    "stack": 560,
    "title": "Books closed by the *fifth*.",
    "lede": "Ledgerhouse closes a small business’s books every month by the fifth working day. Two partners sign every close and every return, with no handoffs.",
    "actions": [
      { "href": "/intake", "label": "Start intake", "kind": "solid" },
      { "href": "/pricing", "label": "See the fees", "kind": "ghost" }
    ],
    "fine": ["Fixed monthly fees", "A missed date waives the fee"]
  }
}
```

## Smallest that parses

```json
{
  "type": "hero",
  "layout": "centered",
  "stack": 560,
  "title": "Books closed by the *fifth*.",
  "lede": "Ledgerhouse closes a small business’s books every month by the fifth working day. Two partners sign every close and every return, with no handoffs.",
  "actions": [],
  "fine": []
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 6 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `layout` | `"centered" \| "split"` | yes |
| `stack` | `560 \| 640` | yes |
| `title` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#hero.title) | yes |
| `lede` | [`string ≤260`](https://next.mdxui.dev/docs/reference/refusals#hero.lede) | yes |
| `actions` | [`0–2 × object`](https://next.mdxui.dev/docs/reference/refusals#hero.actions) | yes |
| `fine` | [`0–4 × string ≤72`](https://next.mdxui.dev/docs/reference/refusals#hero.fine) | yes |

<details>
<summary>Show all 20 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `layout` | `"centered" \| "split"` | yes |
| `stack` | `560 \| 640` | yes |
| `kicker` | `object` | no |
| `kicker.kind` | `"eyebrow"` | yes |
| `kicker.text` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#hero.kicker.text) | yes |
| `title` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#hero.title) | yes |
| `lede` | [`string ≤260`](https://next.mdxui.dev/docs/reference/refusals#hero.lede) | yes |
| `actions` | [`0–2 × object`](https://next.mdxui.dev/docs/reference/refusals#hero.actions) | yes |
| `actions[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#hero.actions.href) | yes |
| `actions[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#hero.actions.label) | yes |
| `actions[].kind` | `"solid" \| "ghost"` | yes |
| `actions[].icon` | `icon or mark name (52)` | no |
| `actions[].external` | `boolean` | no |
| `command` | `object` | no |
| `command.command` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#hero.command.command) | yes |
| `command.note` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#hero.command.note) | no |
| `fine` | [`0–4 × string ≤72`](https://next.mdxui.dev/docs/reference/refusals#hero.fine) | yes |
| `specimen` | `object` | no |
| `specimen.panel` | `"none" \| "field"` | no |
| `specimen.blocks` | [`1–3 × Section type (nested)`](https://next.mdxui.dev/docs/reference/refusals#hero.specimen.blocks) | yes |

</details>

## Variants and counts

Two layouts, `centered` and `split`, at a stack of 560 or 640 pixels. Only `split` sets a preview beside the words.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `blog` and `directory-list` Templates. Seen on `pages/ledgerhouse/home.json`, section 1.

  - Harbor tides: An API product opens on the call it sells, then sends the reader to the plans.
  - Vanroster: A scheduling product opens on the outcome a dispatcher buys, with the schedule beside the words.
  - Ledgerhouse: A bookkeeping firm opens on its promise and one way to start a conversation.
  - Diffkeel: A developer tool opens on the command, so the claim and the install share one screen.
  - Benchlist: A directory opens on what a visitor finds before the first listing.
  - Sidework: A weekly letter opens on what arrives each week, centered, with one way to subscribe.

## Do and do not

  - Do: One solid action and one ghost: the eye lands on the plans first.
  - Don't: Two solid actions: both ask equally, so neither wins.

  - Do: A title that names the outcome in 24 characters.
  - Don't: A 90-character title is refused at its path. Cut words; the bound stays.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The hero sits first in the page `main`, after the header the nav opens. It adds no landmark of its own.
- **Heading level** The title renders as the page `h1`. Use one hero, or one `page-head`, per page.
- **Focus order** Tab reaches the actions in record order. Put the solid action first, so it is first to focus.

## Related

  - [page-head](https://next.mdxui.dev/docs/sections/page-head): Use it for a plain heading with no actions.
  - [product-head](https://next.mdxui.dev/docs/sections/product-head): Use it for a product in a directory.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/hero.md. Add one hero section to pages/home.json for my Business. Keep the title within 64 characters and the lede within 260, and give at most two actions with the solid one first. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# Section types (/docs/sections)

> Twenty-seven Section types, each drawn once by hand, as live previews grouped by job and redrawn in any Theme you pick.

A Section type is one band of a page, drawn once by hand and filled from a record. Each preview below is a real render of a worked Site's section by `@mdxui/site@7.0.0-alpha.0`. Pick a Theme in the filter and all 27 redraw in that brand.

  - [Choosing a Section type](https://next.mdxui.dev/docs/sections/choosing): From what the page must show to the type that shows it.
  - [Anatomy of a page](https://next.mdxui.dev/docs/sections/anatomy): Page, section, kind, shell and Section type, labeled on one render.
  - [Why the design holds](https://next.mdxui.dev/docs/sections/bounds): Every field has a maximum, and a record past it is refused.

Each worked Site is also rendered whole under every Theme: see the [Showcase](https://next.mdxui.dev/docs/showcase) and the [Themes](https://next.mdxui.dev/docs/themes).


# Inline grammar (/docs/sections/inline-grammar)

> Rich text fields carry emphasis, strong, code and links, a code window carries color marks, and an article body carries a Markdown subset.

A rich text field carries four inline forms; every other string renders as plain text, escaped.

## The grammar

| Source | Renders |
| --- | --- |
| `*a tide*` | `<em>a tide</em>` |
| `**a tide**` | `<b>a tide</b>` |
| `` `berth` `` | `<code>berth</code>` |
| `[the docs](/docs)` | `<a href="/docs">the docs</a>` |

A `statement` takes plain words; mark one phrase with `*asterisks*` and it sets in the accent.

The record behind it is one string: `Ask an AI site generator for one edit and it redraws the page. mdxui drew the design once, *so no edit can.*`

## Which fields

Measured on `@mdxui/site@7.0.0-alpha.0` by rendering each string field with `*qzx*`: 51 fields render the grammar.

`footer.blurb`, `footer.note`, `hero.title`, `hero.lede`, `statement.text`, `page-head.title`, `page-head.lede`, `stats.head.title`, `stats.head.lede`, `facts.title`, `facts.items.value`, `feature-grid.head.title`, `feature-grid.head.lede`, `feature-split.head.title`, `feature-split.head.lede`, `bento.head.title`, `bento.head.lede`, `compare.head.title`, `compare.head.lede`, `steps.head.title`, `steps.head.lede`, `steps.more`, `text-stack.head.title`, `text-stack.head.lede`, `endpoints.head.title`, `endpoints.head.lede`, `endpoints.note`, `agent-prompt.lines`, `pricing.head.title`, `pricing.head.lede`, `pricing.note`, `plan-table.title`, `plan-table.rows.cells`, `plan-table.foot`, `faq.head.title`, `faq.head.lede`, `faq.items.a`, `closing.head.title`, `closing.head.lede`, `cta-form.head.title`, `cta-form.head.lede`, `article.head.title`, `article.head.dek`, `article.body`, `post-list.head.title`, `post-list.head.lede`, `post-list.posts.title`, `post-list.posts.dek`, `product-head.summary`, `product-list.title`, `product-list.rows.summary`

Color marks render in `terminal.lines`, in a window that names no `lang`, under 7 names: `@acc{…}`, `@cmt{…}`, `@dim{…}`, `@ink{…}`, `@kw{…}`, `@pass{…}`, `@str{…}`.

## Prose

An `article` body is a Markdown subset. It holds headings of one to three `#`, lists that open with `-` or `1.`, quotes, a `---` rule and fenced code. A fence names one of the [highlighter languages](https://next.mdxui.dev/docs/reference/closed-sets#languages), so no snippet goes uncolored by accident.


# nav (/docs/sections/nav)

> The bar at the top of a page: brand, links, one call to action and a menu that needs no script.

Preview: every frame of nav is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Put one nav at the top of every page of a Site. It holds the brand, up to six links and one call to action, and a budget of 96 units keeps them on one row at full width.

Choose `menu: "none"` for three links or fewer, or for a directory that needs a search field in the bar. Choose `overlay` or `push` when the links outgrow a phone: under the collapse width a link to `#menu` opens the menu, with no script.

Label each link with the noun a reader looks for: Pricing, Docs, Blog.

No neighbor does this job.

## The record

```json title="pages/benchlist/home.json, section 0"
{
  "kind": "nav",
  "shell": { "inset": "bleed", "density": "none", "surface": "glass", "sticky": true },
  "block": {
    "type": "nav",
    "menu": "none",
    "brand": { "href": "/", "text": "Benchlist", "mark": "layout-grid" },
    "links": [
      ["/city/duluth", "Duluth"],
      ["/about", "About"]
    ],
    "cta": { "href": "/list-a-bench", "label": "List a bench" },
    "search": { "action": "/city/duluth", "placeholder": "Kiln, lathe, loom, press" }
  }
}
```

## Smallest that parses

```json
{
  "type": "nav",
  "menu": "none",
  "brand": { "href": "/", "text": "Benchlist" },
  "links": []
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 4 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `menu` | `"overlay" \| "push"` | yes |
| `collapse` | `820 \| 880` | yes |
| `brand` | [`object`](https://next.mdxui.dev/docs/reference/refusals#nav.brand) | yes |
| `links` | [`0–6 × [string ≤160, string ≤20]`](https://next.mdxui.dev/docs/reference/refusals#nav.links) | yes |

<details>
<summary>Show all 17 fields</summary>

#### `menu: "overlay" | "push"`

| Prop | Type and bound | Required |
| --- | --- | --- |
| `menu` | `"overlay" \| "push"` | yes |
| `collapse` | `820 \| 880` | yes |
| `brand` | [`object`](https://next.mdxui.dev/docs/reference/refusals#nav.brand) | yes |
| `brand.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#nav.brand.href) | yes |
| `brand.text` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#nav.brand.text) | no |
| `brand.mark` | `icon or mark name (52)` | no |
| `brand.suffix` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#nav.brand.suffix) | no |
| `brand.tile` | `boolean` | no |
| `links` | [`0–6 × [string ≤160, string ≤20]`](https://next.mdxui.dev/docs/reference/refusals#nav.links) | yes |
| `cta` | `object` | no |
| `cta.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#nav.cta.href) | yes |
| `cta.label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#nav.cta.label) | yes |

#### `menu: "none"`

| Prop | Type and bound | Required |
| --- | --- | --- |
| `menu` | `"none"` | yes |
| `brand` | [`object`](https://next.mdxui.dev/docs/reference/refusals#nav.brand) | yes |
| `brand.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#nav.brand.href) | yes |
| `brand.text` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#nav.brand.text) | no |
| `brand.mark` | `icon or mark name (52)` | no |
| `brand.suffix` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#nav.brand.suffix) | no |
| `brand.tile` | `boolean` | no |
| `links` | [`0–3 × [string ≤160, string ≤20]`](https://next.mdxui.dev/docs/reference/refusals#nav.links) | yes |
| `cta` | `object` | no |
| `cta.href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#nav.cta.href) | yes |
| `cta.label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#nav.cta.label) | yes |
| `search` | `object` | no |
| `search.action` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#nav.search.action) | yes |
| `search.placeholder` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#nav.search.placeholder) | yes |
| `search.query` | [`string ≤120`](https://next.mdxui.dev/docs/reference/refusals#nav.search.query) | no |
| `search.clear` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#nav.search.clear) | no |

</details>

## Variants and counts

The menu is the variant: `none`, `overlay` or `push`. The search field comes with `none` only.

### One record in five Themes

## Shells

## In three Businesses

Carried by every Template. Seen on `pages/benchlist/home.json`, section 0.

  - Harbor tides: An API product links its plans, integrations and blog, and asks the reader to talk.
  - Vanroster: A scheduling product keeps three links and one trial call in the bar.
  - Ledgerhouse: A bookkeeping firm links its services and prices, and asks for an intake.
  - Diffkeel: A developer tool links install and docs, so the first command is one tap away.
  - Benchlist: A directory puts search in the bar, because finding a bench is the job.
  - Sidework: A weekly letter keeps the bar quiet: the archive, about, and subscribe.

## Do and do not

  - Do: Three short links and one call fit the row with room to spare.
  - Don't: Six long labels and a call overrun the 96-unit row, so the record is refused.

  - Do: The call names the one thing the bar asks a reader to do.
  - Don't: A call that repeats a link spends the row twice on one address.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Unnamed nav landmarks | 0 | 0 of 1 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The nav renders the page `header` with one `nav` named Primary inside it. A skip link to `main` comes first.
- **Heading level** The bar carries no heading. The brand is a link home, never the `h1`.
- **Focus order** Tab runs skip link, brand, links in record order, then the call. Under the collapse width the menu link takes the place of the row.

## Related

No neighbor does this job.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/nav.md. Add a nav section to every page of my Site: the brand, at most six short links and one call to action, inside the 96-unit row budget. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# page-head (/docs/sections/page-head)

> A plain page heading: a title and one line, with no actions.

Preview: every frame of page-head is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a page-head to title an inner page: terms, a contact page, a 404, a blog index with no list. It holds a title of 64 characters and a lede of 200, and nothing else.

A page that sells needs actions, so it opens on a `hero`. A listing in a directory opens on a `product-head`.

Write the title as the name of the page, and the lede as where the reader is and what to do next.

- [`hero`](https://next.mdxui.dev/docs/sections/hero): the page opens with a claim and actions

## The record

```json title="pages/benchlist/404.json, section 1"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "page-head",
    "title": "No bench page here.",
    "lede": "This worked example builds one bench in full, Kiln room 4. The other listings link here."
  }
}
```

## Smallest that parses

```json
{ "type": "page-head", "title": "No bench page here." }
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

| Prop | Type and bound | Required |
| --- | --- | --- |
| `title` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#page-head.title) | yes |
| `lede` | [`string ≤200`](https://next.mdxui.dev/docs/reference/refusals#page-head.lede) | no |

## Variants and counts

One layout: a title and an optional lede.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `article` and `directory-list` Templates. Seen on `pages/benchlist/404.json`, section 1.

  - Harbor tides: An API product heads its 404 and its sent page with one plain line each.
  - Vanroster: A scheduling product heads its security page before the paragraphs.
  - Ledgerhouse: A bookkeeping firm heads its terms and its intake confirmation.
  - Diffkeel: A developer tool heads its contact page and its 404.
  - Benchlist: A directory heads its about page and its terms.
  - Sidework: A weekly letter heads its about page and the page after subscribing.

## Do and do not

  - Do: A 404 headed in four words, with one line of where the reader is.
  - Don't: A landing claim set as a page-head has no actions, so the reader has nowhere to go.

  - Do: A lede of one short sentence.
  - Don't: A lede that runs past 200 characters is refused at its path.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The page-head sits first in `main`. It adds no landmark.
- **Heading level** The title renders as the page `h1`. Use it instead of a hero, never beside one.
- **Focus order** Nothing in it takes focus.

## Related

  - [hero](https://next.mdxui.dev/docs/sections/hero): Use it for the page opens with a claim and actions.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/page-head.md. Add a page-head section to the inner page I name: a title of at most 64 characters and a lede of at most 200. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# plan-table (/docs/sections/plan-table)

> Plans as one ruled comparison table: a row per plan, a column per fact.

Preview: every frame of plan-table is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a plan table under `pricing` when buyers compare plans on the same facts. It holds up to six columns of 16 characters and up to eight rows, each a plan name, its cells and an optional note, with a foot line.

Give every row a cell for every column. To choose among one to four plans with actions, use `pricing`.

Keep cells short: a number, yes or no. Put a condition in the row note.

- [`pricing`](https://next.mdxui.dev/docs/sections/pricing): one to four plans to choose from

## The record

```json title="pages/diffkeel/pricing.json, section 2"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "plan-table",
    "title": "Every plan, line by line",
    "columns": ["Diff", "CI check", "Stored diffs", "Approvals", "API"],
    "rows": [
      {
        "name": "CLI",
        "cells": ["yes", "yes", "no", "no", "no"]
      },
      {
        "name": "Team",
        "cells": ["yes", "yes", "1 year", "yes", "yes"]
      },
      {
        "name": "Org",
        "cells": ["yes", "yes", "7 years", "yes, with roles", "yes"]
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "plan-table",
  "title": "Every plan, line by line",
  "columns": ["Diff"],
  "rows": [
    {
      "name": "CLI",
      "cells": ["yes"]
    }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

| Prop | Type and bound | Required |
| --- | --- | --- |
| `title` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#plan-table.title) | no |
| `columns` | [`1–6 × string ≤16`](https://next.mdxui.dev/docs/reference/refusals#plan-table.columns) | yes |
| `rows` | [`1–8 × object`](https://next.mdxui.dev/docs/reference/refusals#plan-table.rows) | yes |
| `rows[].name` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#plan-table.rows.name) | yes |
| `rows[].cells` | [`1–6 × string ≤32`](https://next.mdxui.dev/docs/reference/refusals#plan-table.rows.cells) | yes |
| `rows[].note` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#plan-table.rows.note) | no |
| `foot` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#plan-table.foot) | no |

## Variants and counts

One layout. On a phone each row stacks, with its column names beside the values.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product` and `directory-product` Templates. Seen on `pages/diffkeel/pricing.json`, section 2.

  - Harbor tides: An API product compares calls, days ahead, windows and alerts per plan.
  - Vanroster: A scheduling product compares crews, routes and integrations per plan.
  - Ledgerhouse: A bookkeeping firm compares accounts, payroll and filings per package.
  - Diffkeel: A developer tool compares seats, history and hosted runs.
  - Benchlist: A directory compares listing plans by photos and placement.
  - Sidework: A weekly letter compares the free and paid issues.

## Do and do not

  - Do: A cell for every column in every row.
  - Don't: Rows short of the columns leave blank cells a buyer reads as a missing feature.

  - Do: Four facts a buyer weighs.
  - Don't: Seven columns are refused: the table holds up to six.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The table sits in `main`. It adds no landmark.
- **Heading level** The title renders as an `h2`. Columns are headed `th scope="col"` and each plan name `th scope="row"`.
- **Focus order** Nothing in it takes focus.

## Related

  - [pricing](https://next.mdxui.dev/docs/sections/pricing): Use it for one to four plans to choose from.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/plan-table.md. Add a plan-table section under the pricing on my pricing page: up to six fact columns and one row per plan, with a cell for every column. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# post-list (/docs/sections/post-list)

> A blog index: a head, then the posts as ruled rows.

Preview: every frame of post-list is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a post list for a blog index or a changelog. It holds a head and one to 24 posts, each with a tag of 20 characters, a dateline, a title of 80 and a dek of 360.

Write the dek as what the reader learns. For products or listings, use `product-list`.

Date every post and keep the newest first. Tag by topic, in one word where it fits.

- [`product-list`](https://next.mdxui.dev/docs/sections/product-list): products, not posts

## The record

```json title="pages/sidework/home.json, section 4"
{
  "kind": "section",
  "shell": { "inset": "listing", "density": "listing" },
  "block": {
    "type": "post-list",
    "head": {
      "eyebrow": "Latest",
      "title": "Recent issues",
      "lede": "The newest three, and issue 1. Issue 1 is free to read; the rest come with the paid letter."
    },
    "read": "Read",
    "posts": [
      {
        "href": "/subscribe",
        "tag": "Pricing",
        "dateline": {
          "date": "2026-10-20",
          "read": { "minutes": 5, "unit": "min read" }
        },
        "title": "Pricing a rush job",
        "dek": "A rush costs your evenings twice: the work and what it pushes out. Price both, and say the rush fee first."
      },
      {
        "href": "/subscribe",
        "tag": "Work",
        "dateline": {
          "date": "2026-10-13",
          "read": { "minutes": 7, "unit": "min read" }
        },
        "title": "When to quit the day job",
        "dek": "Three numbers decide it: months of costs saved, months of revenue booked, and the hours the side work takes."
      },
      {
        "href": "/subscribe",
        "tag": "Tax",
        "dateline": {
          "date": "2026-10-06",
          "read": { "minutes": 6, "unit": "min read" }
        },
        "title": "The year-end checklist, early",
        "dek": "Twelve items to clear in October, so January holds a return and not a search for receipts."
      },
      {
        "href": "/issues/the-first-invoice",
        "tag": "Money",
        "dateline": {
          "date": "2026-05-12",
          "read": { "minutes": 6, "unit": "min read" }
        },
        "title": "The first invoice",
        "dek": "What goes on it, when to send it, and the one line that gets it paid on time."
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "post-list",
  "head": {
    "eyebrow": "Latest",
    "title": "Recent issues",
    "lede": "The newest three, and issue 1. Issue 1 is free to read; the rest come with the paid letter."
  },
  "read": "Read",
  "posts": [
    {
      "href": "/subscribe",
      "tag": "Pricing",
      "dateline": { "date": "2026-10-20" },
      "title": "Pricing a rush job",
      "dek": "A rush costs your evenings twice: the work and what it pushes out. Price both, and say the rush fee first."
    }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 3 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | `object` | yes |
| `read` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#post-list.read) | yes |
| `posts` | [`1–24 × object`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts) | yes |

<details>
<summary>Show all 13 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | `object` | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#post-list.head.eyebrow) | yes |
| `head.title` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#post-list.head.title) | yes |
| `head.lede` | [`string ≤200`](https://next.mdxui.dev/docs/reference/refusals#post-list.head.lede) | yes |
| `read` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#post-list.read) | yes |
| `posts` | [`1–24 × object`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts) | yes |
| `posts[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts.href) | yes |
| `posts[].tag` | [`string ≤20`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts.tag) | yes |
| `posts[].dateline` | `object` | yes |
| `posts[].dateline.date` | `string (pattern)` | yes |
| `posts[].dateline.read` | `object` | no |
| `posts[].title` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts.title) | yes |
| `posts[].dek` | [`string ≤360`](https://next.mdxui.dev/docs/reference/refusals#post-list.posts.dek) | yes |

</details>

## Variants and counts

One layout, from 1 post to 24.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `blog` Template. Seen on `pages/sidework/home.json`, section 4.

  - Harbor tides: An API product lists notes on how its tables are made.
  - Vanroster: A scheduling product lists its changelog, newest first.
  - Ledgerhouse: A bookkeeping firm lists notes for clients before each deadline.
  - Diffkeel: A developer tool lists releases with what each changed.
  - Benchlist: A directory lists news from new cities.
  - Sidework: A weekly letter lists 24 issues in its archive.

## Do and do not

  - Do: A dek that says what the reader learns.
  - Don't: A dek that repeats the title gives the reader no reason to open the post.

  - Do: A tag of one or two words.
  - Don't: A tag past 20 characters is refused at its path.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The list sits in `main`. It adds no landmark.
- **Heading level** The head title renders as the page `h1` and each post title as an `h2`.
- **Focus order** Each post is one link, in record order.

## Related

  - [product-list](https://next.mdxui.dev/docs/sections/product-list): Use it for products, not posts.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/post-list.md. Add a post-list section to my blog page: one row per post with a tag of at most 20 characters, a date, a title of at most 80 and a dek of at most 360. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# pricing (/docs/sections/pricing)

> One to four plans under a section head, one of them featured.

Preview: every frame of pricing is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use pricing to set the plans as OfferTiles a buyer chooses from. It holds one to four, each with a name of 16 characters, a price, up to ten features and one action. Mark one plan `featured`; the badge text is yours, up to 16 characters.

`ruled` sets the plans in hairline columns; `cards` sets each plan in its own panel. To compare plans fact by fact, add a `plan-table` below.

Write each feature as what the buyer gets, in three to six words, and keep shared features in the same order across plans.

- [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table): plans compared fact by fact

## The record

```json title="pages/ledgerhouse/pricing.json, section 1"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "pricing",
    "head": {
      "eyebrow": "Fees",
      "title": "Fixed fees, set at intake.",
      "lede": "Fees follow transactions a month, never hours. Each fee holds for twelve months."
    },
    "layout": "ruled",
    "tiers": [
      {
        "name": "Close",
        "price": "$450",
        "note": "a month",
        "desc": "Up to 150 transactions a month.",
        "features": ["Monthly close by the fifth", "One signed report", "Two bank accounts"],
        "cta": "Start intake",
        "href": "/intake"
      },
      {
        "name": "Close and tax",
        "price": "$750",
        "note": "a month",
        "desc": "Up to 400 transactions, with tax.",
        "features": ["Everything in Close", "Quarterly tax estimates", "The annual business return", "Five bank accounts"],
        "cta": "Start intake",
        "href": "/intake",
        "featured": true
      },
      {
        "name": "Partner",
        "price": "$1,400",
        "note": "a month",
        "desc": "Up to 1,000 transactions, two entities.",
        "features": ["Everything in Close and tax", "Returns for two owners", "Payroll posted monthly", "A quarterly review call"],
        "cta": "Start intake",
        "href": "/intake"
      }
    ],
    "featuredBadge": "Includes tax",
    "note": "Catch-up months are quoted once, at intake. Fees exclude sales tax where it applies."
  }
}
```

## Smallest that parses

```json
{
  "type": "pricing",
  "head": { "eyebrow": "Fees", "title": "Fixed fees, set at intake." },
  "layout": "ruled",
  "tiers": [
    {
      "name": "Close",
      "price": "$450",
      "features": ["Monthly close by the fifth"],
      "cta": "Start intake",
      "href": "/intake"
    }
  ],
  "featuredBadge": "Includes tax"
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 4 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#pricing.head) | yes |
| `layout` | `"ruled" \| "cards"` | yes |
| `tiers` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers) | yes |
| `featuredBadge` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#pricing.featuredBadge) | yes |

<details>
<summary>Show all 22 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#pricing.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#pricing.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#pricing.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#pricing.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#pricing.head.tag) | no |
| `head.layout` | `"split"` | no |
| `layout` | `"ruled" \| "cards"` | yes |
| `tiers` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers) | yes |
| `tiers[].name` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.name) | yes |
| `tiers[].price` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.price) | yes |
| `tiers[].note` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.note) | no |
| `tiers[].desc` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.desc) | no |
| `tiers[].features` | [`1–10 × string ≤56`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.features) | yes |
| `tiers[].cta` | [`string ≤40`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.cta) | yes |
| `tiers[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#pricing.tiers.href) | yes |
| `tiers[].featured` | `boolean` | no |
| `featuredBadge` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#pricing.featuredBadge) | yes |
| `note` | [`string ≤120`](https://next.mdxui.dev/docs/reference/refusals#pricing.note) | no |

</details>

## Variants and counts

Two layouts, `ruled` and `cards`. Each Theme draws the featured plan by its own policy: a rule or a plate.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `contact` and `directory-product` Templates. Seen on `pages/ledgerhouse/pricing.json`, section 1.

  - Harbor tides: An API product prices by the call in three plans, the middle one featured.
  - Vanroster: A scheduling product prices per crew, with the team plan featured.
  - Ledgerhouse: A bookkeeping firm prices monthly packages in ruled columns.
  - Diffkeel: A developer tool keeps a free CLI and one paid plan for teams.
  - Benchlist: A directory prices a listing by the month.
  - Sidework: A weekly letter sets a free plan and a paid one side by side.

## Do and do not

  - Do: One featured plan the eye finds first.
  - Don't: Two featured plans: the badge appears twice and no plan stands out.

  - Do: Three plans a buyer holds in mind.
  - Don't: Five plans are refused: pricing holds one to four OfferTiles.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** Pricing sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2` and each plan name as an `h3`; features are a list, `ul`.
- **Focus order** Tab reaches each plan action in record order, left to right.

## Related

  - [plan-table](https://next.mdxui.dev/docs/sections/plan-table): Use it for plans compared fact by fact.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/pricing.md. Add a pricing section to my pricing page: one to four plans as OfferTiles, names of at most 16 characters, up to ten features each, and exactly one featured. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# product-head (/docs/sections/product-head)

> A listing page header in a directory: mark, name, one sentence, category and tags.

Preview: every frame of product-head is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a product head at the top of a listing page in a directory. It holds a mark, a name of 32 characters, a summary of 120, up to nine chips and one or two actions, with marks for an OpenAPI file, an MCP server, webhooks or a free plan.

Every listing gets at least one action. For a product landing rather than a listing, use `hero`.

Write the summary as what the listing does for the reader, in one sentence.

- [`hero`](https://next.mdxui.dev/docs/sections/hero): a product landing, not a listing

## The record

```json title="pages/benchlist/bench/kiln-room-4.json, section 1"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "product-head",
    "mark": "sparkles",
    "name": "Kiln room 4",
    "summary": "Two electric kilns to cone 10 in a shared clay studio in Lincoln Park, Duluth.",
    "chips": [
      { "label": "Kiln room", "href": "/city/duluth?kind=kiln" },
      { "label": "Duluth", "href": "/city/duluth" },
      { "label": "Lincoln Park" },
      { "label": "Cone 10" }
    ],
    "actions": [
      { "href": "mailto:kiln-room-4@benchlist.example?subject=Booking%20Kiln%20room%204", "label": "Book by email", "kind": "solid" },
      { "href": "#rates", "label": "See the rates", "kind": "ghost" }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "product-head",
  "name": "Kiln room 4",
  "summary": "Two electric kilns to cone 10 in a shared clay studio in Lincoln Park, Duluth.",
  "actions": [
    { "href": "mailto:kiln-room-4@benchlist.example?subject=Booking%20Kiln%20room%204", "label": "Book by email", "kind": "solid" }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 3 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `name` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#product-head.name) | yes |
| `summary` | [`string ≤120`](https://next.mdxui.dev/docs/reference/refusals#product-head.summary) | yes |
| `actions` | [`1–2 × object`](https://next.mdxui.dev/docs/reference/refusals#product-head.actions) | yes |

<details>
<summary>Show all 17 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `mark` | `icon or mark name (52)` | no |
| `name` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#product-head.name) | yes |
| `summary` | [`string ≤120`](https://next.mdxui.dev/docs/reference/refusals#product-head.summary) | yes |
| `chips` | [`0–9 × object`](https://next.mdxui.dev/docs/reference/refusals#product-head.chips) | no |
| `chips[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#product-head.chips.label) | yes |
| `chips[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-head.chips.href) | no |
| `marks` | `object` | no |
| `marks.openapi` | `boolean` | no |
| `marks.mcp` | `boolean` | no |
| `marks.webhooks` | `boolean` | no |
| `marks.free` | `boolean` | no |
| `actions` | [`1–2 × object`](https://next.mdxui.dev/docs/reference/refusals#product-head.actions) | yes |
| `actions[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-head.actions.href) | yes |
| `actions[].label` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#product-head.actions.label) | yes |
| `actions[].kind` | `"solid" \| "ghost"` | yes |
| `actions[].icon` | `icon or mark name (52)` | no |
| `actions[].external` | `boolean` | no |

</details>

## Variants and counts

One layout. On a `split` frame, set `aside` on its shell to pin it in the side column.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `directory-product` Template. Seen on `pages/benchlist/bench/kiln-room-4.json`, section 1.

  - Harbor tides: An API product heads its Chartplot integration page.
  - Vanroster: A scheduling product heads each feature page it lists.
  - Ledgerhouse: A bookkeeping firm heads each service page.
  - Diffkeel: A developer tool heads each plugin listing.
  - Benchlist: A directory heads each bench page with its size and city.
  - Sidework: A weekly letter heads each series it lists.

## Do and do not

  - Do: One action that says what the reader gets.
  - Don't: A listing with no action is refused: a product head holds one or two.

  - Do: Two chips: a category and a capability.
  - Don't: Nine chips read as a tag cloud, and none is the category.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The head sits first in `main`. It adds no landmark.
- **Heading level** The name renders as the page `h1`. The capability marks are a list named Has.
- **Focus order** Tab runs the chips with links, then the actions.

## Related

  - [hero](https://next.mdxui.dev/docs/sections/hero): Use it for a product landing, not a listing.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/product-head.md. Add a product-head section to my listing page: a name of at most 32 characters, a summary of at most 120, up to three chips and one or two actions. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# product-list (/docs/sections/product-list)

> A directory list: one linked row per listing, as a list or as Tiles.

Preview: every frame of product-list is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a product list for a directory index or a category page. It holds up to 50 rows, each a link with a mark, a name of 32 characters, a summary of 120, a tag and a note, under an optional title, sort links, view links and a pager.

`list` sets one row per listing; `cards` sets each as a Tile in a grid. Every control is a link, so sorting and paging need no script. For posts, use `post-list`.

Write each summary as what the listing does, so a reader chooses from the list without opening every row.

- [`post-list`](https://next.mdxui.dev/docs/sections/post-list): posts, not listings

## The record

```json title="pages/benchlist/home.json, section 3"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "product-list",
    "title": "Benches in Duluth, by kind",
    "note": "8 kinds",
    "view": "cards",
    "views": [
      { "href": "/", "label": "Kinds", "icon": "layout-grid", "on": true },
      { "href": "/city/duluth", "label": "List", "icon": "list" }
    ],
    "rows": [
      {
        "href": "/city/duluth?kind=kiln",
        "mark": "sparkles",
        "name": "Kiln rooms",
        "summary": "Electric kilns to cone 10, with shelves and posts. Bisque or glaze.",
        "tag": "Clay",
        "note": "2 listed, from $18 an hour"
      },
      {
        "href": "/city/duluth?kind=wood",
        "mark": "blocks",
        "name": "Woodshop benches",
        "summary": "Hardwood benches beside a cabinet saw, jointer and planer.",
        "tag": "Wood",
        "note": "2 listed, from $16 an hour"
      },
      {
        "href": "/city/duluth?kind=metal",
        "mark": "gauge",
        "name": "Metal bays",
        "summary": "A metal lathe with tooling, or a ventilated welding booth.",
        "tag": "Metal",
        "note": "2 listed, from $24 an hour"
      },
      {
        "href": "/city/duluth?kind=print",
        "mark": "files",
        "name": "Print presses",
        "summary": "A tabletop letterpress with type, or a four-color screen press.",
        "tag": "Print",
        "note": "2 listed, from $14 an hour"
      },
      {
        "href": "/city/duluth?kind=textile",
        "mark": "layers",
        "name": "Looms",
        "summary": "A four-shaft floor loom, warped on request a day ahead.",
        "tag": "Textile",
        "note": "1 listed, $12 an hour"
      },
      {
        "href": "/city/duluth?kind=jewelry",
        "mark": "badge-check",
        "name": "Jewelry benches",
        "summary": "A bench pin, flex shaft and torch, in a room with a safe.",
        "tag": "Jewelry",
        "note": "1 listed, $9 an hour"
      },
      {
        "href": "/list-a-bench",
        "mark": "sparkles",
        "name": "Glass studios",
        "summary": "No glass kiln or torch bench is listed yet. A host who lists one sets its rate.",
        "tag": "Glass",
        "note": "0 listed"
      },
      {
        "href": "/list-a-bench",
        "mark": "film",
        "name": "Darkrooms",
        "summary": "No darkroom is listed yet. Enlargers, trays and a sink by the hour.",
        "tag": "Photo",
        "note": "0 listed"
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "product-list",
  "title": "Benches in Duluth, by kind",
  "rows": []
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 1 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `rows` | [`0–50 × object`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows) | yes |

<details>
<summary>Show all 29 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `title` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#product-list.title) | no |
| `note` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#product-list.note) | no |
| `rail` | `object` | no |
| `rail.groups` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#product-list.rail.groups) | yes |
| `rail.groups[].label` | [`string ≤20`](https://next.mdxui.dev/docs/reference/refusals#product-list.rail.groups.label) | yes |
| `rail.groups[].links` | [`1–12 × object`](https://next.mdxui.dev/docs/reference/refusals#product-list.rail.groups.links) | yes |
| `sort` | [`0–4 × object`](https://next.mdxui.dev/docs/reference/refusals#product-list.sort) | no |
| `sort[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-list.sort.href) | yes |
| `sort[].label` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#product-list.sort.label) | yes |
| `sort[].on` | `boolean` | no |
| `view` | `"list" \| "cards"` | no |
| `views` | [`0–2 × object`](https://next.mdxui.dev/docs/reference/refusals#product-list.views) | no |
| `views[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-list.views.href) | yes |
| `views[].label` | [`string ≤16`](https://next.mdxui.dev/docs/reference/refusals#product-list.views.label) | yes |
| `views[].icon` | `icon or mark name (52)` | no |
| `views[].on` | `boolean` | no |
| `rows` | [`0–50 × object`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows) | yes |
| `rows[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows.href) | yes |
| `rows[].mark` | `icon or mark name (52)` | no |
| `rows[].name` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows.name) | yes |
| `rows[].summary` | [`string ≤120`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows.summary) | yes |
| `rows[].tag` | [`string ≤24`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows.tag) | no |
| `rows[].note` | [`string ≤32`](https://next.mdxui.dev/docs/reference/refusals#product-list.rows.note) | no |
| `pager` | `object` | no |
| `pager.prev` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-list.pager.prev) | no |
| `pager.next` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#product-list.pager.next) | no |
| `pager.page` | [`integer 1–10000`](https://next.mdxui.dev/docs/reference/refusals#product-list.pager.page) | yes |
| `pager.pages` | [`integer 1–10000`](https://next.mdxui.dev/docs/reference/refusals#product-list.pager.pages) | yes |
| `empty` | [`string ≤80`](https://next.mdxui.dev/docs/reference/refusals#product-list.empty) | no |

</details>

## Variants and counts

Two views, `list` and `cards`. A record names the view it renders and links to the other.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `article` and `directory-list` Templates. Seen on `pages/benchlist/home.json`, section 3.

  - Harbor tides: An API product lists its integrations, with one row inviting a new one.
  - Vanroster: A scheduling product lists the tools it connects to.
  - Ledgerhouse: A bookkeeping firm lists the bank feeds it reads.
  - Diffkeel: A developer tool lists the formats it diffs.
  - Benchlist: A directory lists the benches of one city, sorted, with pages.
  - Sidework: A weekly letter lists its series.

## Do and do not

  - Do: A summary that says what the listing does.
  - Don't: A summary that repeats the name tells the reader nothing to choose on.

  - Do: A name of one or two words.
  - Don't: A name written as a pitch runs past 32 characters and is refused.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Unnamed nav landmarks | 0 | 0 of 1 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The list sits in `main`. Sort, view and pager are each a `nav` with its own name.
- **Heading level** The title renders as an `h2`; the listings are a list, `ul`.
- **Focus order** Tab runs sort, view, each listing link, then the pager. The current sort and view carry `aria-current`.

## Related

  - [post-list](https://next.mdxui.dev/docs/sections/post-list): Use it for posts, not listings.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/product-list.md. Add a product-list section to my directory page: one linked row per listing, names of at most 32 characters and summaries of at most 120. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# Section shells (/docs/sections/shells)

> The shell of a section paints and paces its band: a ground, a pattern, an inset and a density, all from the Theme's own tokens.

The shell is the band around a Section type. It never positions content: it paints the band, sets its width and sets the room above and below. Every value is a Theme token, so one shell reads right in every brand.

## The `surface` field

`surface` paints the band: `paper`, `tint`, `plate` or `glass`. Leave it out and the page ground shows through. A plate re-tokens the ink, rule and accent families for everything inside it, so a solid button on a plate inverts on its own. Here is one hero on each, in its Business's Theme.

A code window sits well on a plate; a sticky nav needs a painted ground, such as glass, so content does not show through it.

## The `background` field

`background` lays a pattern behind the content: `none`, `dots`, `grain` or `glow`. Glow pours the Theme's own accent and field colors from the top of the band, over grain, so each brand's glow is its own.

No record in this build sets `dots` or `grain`, so no frame shows them here. Both are in the published shell rules: dots are a 24 px grid of faint points, grain a fine noise.

## Inset and density

`inset` sets the width: `contained` holds the content to the Theme's measure, `bleed` runs it edge to edge, and `article` and `listing` are the narrower reading measures. `density` sets the room above and below, by the band's role: `hero`, `section`, `compact`, `closing`, `footer`, `article`, `listing`, `access`, or `none` for a bar. The room is fluid, so a phone does not spend a screen on padding.

## Sticky, aside and id

`sticky` pins the band to the top, as a nav does. `aside` sends the band to the side column of a `split` frame; see [Composition](https://next.mdxui.dev/docs/sections/composition). `id` gives the band an address, such as `#pricing`, of at most 24 lowercase characters.



# statement (/docs/sections/statement)

> One claim on its own, set large, with one phrase in the accent.

Preview: every frame of statement is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a statement for the one sentence a reader should remember, set large between denser sections. It holds 140 characters of plain words. A phrase wrapped in `*asterisks*` sets in the accent; mark one.

Place it after proof, never first: a page opens on a hero. When the claim is a number, a `stats` band says it with its caption.

Write it as a claim a competitor could not sign. Read it aloud: if it needs a breath, it is a paragraph.

- [`stats`](https://next.mdxui.dev/docs/sections/stats): the claim is a number

## The record

```json title="pages/ledgerhouse/home.json, section 4"
{
  "kind": "band",
  "shell": { "inset": "contained", "density": "section", "surface": "tint" },
  "block": { "type": "statement", "text": "A close is a promise with a date on it. *Ledgerhouse keeps the date.*" }
}
```

## Smallest that parses

```json
{ "type": "statement", "text": "A close is a promise with a date on it. *Ledgerhouse keeps the date.*" }
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

| Prop | Type and bound | Required |
| --- | --- | --- |
| `text` | [`string ≤140`](https://next.mdxui.dev/docs/reference/refusals#statement.text) | yes |

## Variants and counts

One layout. The shell decides its weight: a tint or a plate sets it apart from paper sections.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `article` and `blog` Templates. Seen on `pages/ledgerhouse/home.json`, section 4.

  - Harbor tides: An API product states the one promise its tide windows keep.
  - Vanroster: A scheduling product states the cost of a crew sent to the wrong job.
  - Ledgerhouse: A bookkeeping firm states its close date as a promise, in the accent.
  - Diffkeel: A developer tool states what it refuses to let ship.
  - Benchlist: A directory states what a bench by the hour replaces.
  - Sidework: A weekly letter states who it is for, in one line.

## Do and do not

  - Do: One phrase in the accent, at the end, where the claim lands.
  - Don't: The accent on every word marks nothing, so the claim reads as one flat color.

  - Do: Two sentences that fit 140 characters.
  - Don't: A paragraph posing as a claim runs past 140 characters and is refused.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The statement is a paragraph in `main`. It adds no landmark.
- **Heading level** It renders a paragraph, not a heading, so a heading outline passes over it.
- **Focus order** Nothing in it takes focus.

## Related

  - [stats](https://next.mdxui.dev/docs/sections/stats): Use it for the claim is a number.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/statement.md. Add one statement section to pages/home.json for my Business: one claim of at most 140 characters, with at most one phrase in *asterisks* for the accent. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# stats (/docs/sections/stats)

> A band of three or four big numbers with captions, ruled between cells.

Preview: every frame of stats is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use stats for three or four figures a reader checks: a free allowance, a refresh interval, a count of routes. Each value holds six characters and each caption 72, and an optional head sits above the band.

Give product facts or plan terms, never customer counts or revenue. When the reader decides on labels and values rather than scanning numbers, use `facts`.

Write each value as the figure alone, with a short unit such as `6 min`, and let the caption say what it counts.

- [`facts`](https://next.mdxui.dev/docs/sections/facts): labels and values a reader decides on

## The record

```json title="pages/benchlist/home.json, section 2"
{
  "kind": "band",
  "shell": { "inset": "contained", "density": "compact" },
  "block": {
    "type": "stats",
    "items": [
      { "value": "10", "label": "Benches listed in Duluth" },
      { "value": "$9", "label": "Lowest hourly rate listed" },
      { "value": "24 h", "label": "Free cancellation before a booking" }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "stats",
  "items": [
    { "value": "10", "label": "Benches listed in Duluth" },
    { "value": "$9", "label": "Lowest hourly rate listed" },
    { "value": "24 h", "label": "Free cancellation before a booking" }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 1 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `items` | [`3–4 × object`](https://next.mdxui.dev/docs/reference/refusals#stats.items) | yes |

<details>
<summary>Show all 14 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#stats.head) | no |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#stats.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#stats.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#stats.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#stats.head.tag) | no |
| `head.layout` | `"split"` | no |
| `items` | [`3–4 × object`](https://next.mdxui.dev/docs/reference/refusals#stats.items) | yes |
| `items[].value` | [`string ≤6`](https://next.mdxui.dev/docs/reference/refusals#stats.items.value) | yes |
| `items[].label` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#stats.items.label) | yes |
| `items[].icon` | `icon or mark name (52)` | no |

</details>

## Variants and counts

Three or four figures. The schema refuses any other count.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `blog` and `directory-list` Templates. Seen on `pages/benchlist/home.json`, section 2.

  - Harbor tides: An API product counts its free calls, its days ahead and its update interval.
  - Vanroster: A scheduling product counts crews per plan and the minutes a change takes to reach a phone.
  - Ledgerhouse: A bookkeeping firm counts its close day and its fixed monthly price.
  - Diffkeel: A developer tool counts the formats it reads and the milliseconds a diff takes.
  - Benchlist: A directory counts its benches and its cities.
  - Sidework: A weekly letter counts its issues and its minutes to read.

## Do and do not

  - Do: Figures a reader can check against the product.
  - Don't: Words in the value slot read as a slogan, not a figure.

  - Do: Three figures on one row at every width.
  - Don't: Five figures are refused: the band holds three or four.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** Stats is a band in `main`. It adds no landmark.
- **Heading level** The band carries no heading unless it has a head, which renders an `h2`. Each value is bold text with its caption beside it.
- **Focus order** Nothing in it takes focus.

## Related

  - [facts](https://next.mdxui.dev/docs/sections/facts): Use it for labels and values a reader decides on.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/stats.md. Add a stats section to pages/home.json for my Business: three or four figures of at most 6 characters, each with a caption of at most 72. Use product facts or plan terms only. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# steps (/docs/sections/steps)

> Copy beside a numbered list of three to five steps.

Preview: every frame of steps is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use steps when order matters: install, configure, run. It holds three to five steps of 56 characters, numbered for you, beside a head, with up to two closing lines and an optional preview.

Each step starts with a verb. When the paragraphs run in no order, use `text-stack`.

Keep each step to one action. Put what a step needs, such as a key or a version, in the closing lines.

- [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack): paragraphs with no order

## The record

```json title="pages/harbor/home.json, section 9"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "steps",
    "head": { "eyebrow": "How it works", "title": "From berth to window." },
    "steps": ["Name the berth", "Give the draft", "Read the window", "Set an alert before it closes"]
  }
}
```

## Smallest that parses

```json
{
  "type": "steps",
  "head": { "eyebrow": "How it works", "title": "From berth to window." },
  "steps": ["Name the berth", "Give the draft", "Read the window"]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 2 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#steps.head) | yes |
| `steps` | [`3–5 × string ≤56`](https://next.mdxui.dev/docs/reference/refusals#steps.steps) | yes |

<details>
<summary>Show all 15 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#steps.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#steps.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#steps.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#steps.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#steps.head.tag) | no |
| `head.layout` | `"split"` | no |
| `more` | [`0–2 × string ≤96`](https://next.mdxui.dev/docs/reference/refusals#steps.more) | no |
| `steps` | [`3–5 × string ≤56`](https://next.mdxui.dev/docs/reference/refusals#steps.steps) | yes |
| `specimen` | `object` | no |
| `specimen.panel` | `"none" \| "field"` | no |
| `specimen.blocks` | [`1–3 × Section type (nested)`](https://next.mdxui.dev/docs/reference/refusals#steps.specimen.blocks) | yes |

</details>

## Variants and counts

Three designed counts, 3, 4 and 5. A preview can sit under the list.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article` and `contact` Templates. Seen on `pages/harbor/home.json`, section 9.

  - Harbor tides: An API product goes from berth to window in four steps.
  - Vanroster: A scheduling product goes from crew to route in four steps.
  - Ledgerhouse: A bookkeeping firm walks the monthly close in five steps.
  - Diffkeel: A developer tool goes from install to first diff in four steps.
  - Benchlist: A directory lists a bench in three steps.
  - Sidework: A weekly letter goes from subscribe to first issue in three steps.

## Do and do not

  - Do: Steps that start with a verb and run in order.
  - Don't: Features listed as steps: no step follows from the one before.

  - Do: Four steps, each a reader can do.
  - Don't: Six steps are refused: the list holds three to five.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** Steps sit in `main`. They add no landmark.
- **Heading level** The head title renders as an `h2`; the steps are an ordered list, `ol`, so a screen reader counts them.
- **Focus order** Nothing in the list takes focus; a preview copy control follows it.

## Related

  - [text-stack](https://next.mdxui.dev/docs/sections/text-stack): Use it for paragraphs with no order.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/steps.md. Add a steps section to pages/home.json: three to five steps of at most 56 characters, each starting with a verb, in the order a reader takes them. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# terminal (/docs/sections/terminal)

> The code window: dark in every Theme and scheme, plain or tabbed.

Preview: every frame of terminal is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a terminal for code a reader reads line by line: a config, a session, a response. It stays dark in every Theme and scheme. `plain` holds up to 32 lines of 100 characters and names a language for color; `tabs` holds up to four tabs of commands and output.

For one command to copy, use `command-row`. For a request beside its answer, use `api-call`.

Show real output, trimmed to what the claim needs. The title in the bar names the file or the moment, such as `window.ts`.

- [`command-row`](https://next.mdxui.dev/docs/sections/command-row): one command to copy
- [`api-call`](https://next.mdxui.dev/docs/sections/api-call): a request beside its answer

## The record

```json title="pages/diffkeel/home.json, section 3"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section", "surface": "plate" },
  "block": {
    "type": "terminal",
    "variant": "tabs",
    "title": "One diff, three places",
    "group": "where",
    "tabs": [
      {
        "label": "CLI",
        "lines": [
          { "cmd": "diffkeel diff prod", "space": "after" },
          { "out": "rendered prod from 3 files in 41 ms" },
          {
            "row": ["api.yaml", "timeout 30s to 5s"]
          },
          {
            "row": ["worker.yaml", "queue.concurrency 8 to 16"]
          },
          {
            "row": ["prod.env", "DB_PASSWORD changed, value masked"]
          },
          { "gap": "sm" },
          { "out": "3 changes, 1 secret, 0 reviews", "cursor": true }
        ]
      },
      {
        "label": "CI",
        "lines": [
          { "cmd": "diffkeel check --env prod --require-review", "space": "after" },
          { "out": "3 changes in prod need a review" },
          {
            "row": ["api.yaml", "timeout 30s to 5s"]
          },
          {
            "row": ["worker.yaml", "queue.concurrency 8 to 16"]
          },
          {
            "row": ["prod.env", "DB_PASSWORD changed, value masked"]
          },
          { "gap": "sm" },
          { "out": "exit 1: deploy stopped", "cursor": true }
        ]
      },
      {
        "label": "Config",
        "lines": [
          { "text": "# diffkeel.toml" },
          { "text": "[env.prod]" },
          { "text": "files = [\"base.yaml\", \"prod.yaml\", \"prod.env\"]" },
          { "text": "live  = \"./scripts/read-live-config.sh prod\"" },
          { "text": "mask  = [\"DB_PASSWORD\", \"API_TOKEN\"]" },
          { "text": "review = \"required\"" }
        ],
        "pre": true
      }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "terminal",
  "variant": "tabs",
  "title": "One diff, three places",
  "group": "where",
  "tabs": [
    {
      "label": "CLI",
      "lines": [
        { "cmd": "diffkeel diff prod" }
      ]
    }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 4 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `variant` | `"plain"` | yes |
| `lines` | [`1–32 × string ≤100`](https://next.mdxui.dev/docs/reference/refusals#terminal.lines) | yes |
| `group` | `string (pattern)` | yes |
| `tabs` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs) | yes |

<details>
<summary>Show all 17 fields</summary>

#### `variant: "plain"`

| Prop | Type and bound | Required |
| --- | --- | --- |
| `variant` | `"plain"` | yes |
| `title` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#terminal.title) | no |
| `lang` | `icon or mark name (44)` | no |
| `lines` | [`1–32 × string ≤100`](https://next.mdxui.dev/docs/reference/refusals#terminal.lines) | yes |
| `copy` | `boolean` | no |

#### `variant: "tabs"`

| Prop | Type and bound | Required |
| --- | --- | --- |
| `variant` | `"tabs"` | yes |
| `title` | [`string ≤48`](https://next.mdxui.dev/docs/reference/refusals#terminal.title) | no |
| `group` | `string (pattern)` | yes |
| `tabs` | [`1–4 × object`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs) | yes |
| `tabs[].label` | [`string ≤6`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs.label) | yes |
| `tabs[].lines` | [`1–24 × object \| object \| object \| object \| object`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs.lines) | yes |
| `tabs[].lines[].cmd` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs.lines.cmd) | yes |
| `tabs[].lines[].space` | `"after" \| "both"` | no |
| `tabs[].lines[].row` | [`[string ≤16, string ≤56]`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs.lines.row) | yes |
| `tabs[].lines[].out` | [`string ≤64`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs.lines.out) | yes |
| `tabs[].lines[].cursor` | `boolean` | no |
| `tabs[].lines[].gap` | `"sm" \| "lg"` | yes |
| `tabs[].lines[].text` | [`string ≤128`](https://next.mdxui.dev/docs/reference/refusals#terminal.tabs.lines.text) | yes |
| `tabs[].pre` | `boolean` | no |
| `copy` | `boolean` | no |

</details>

## Variants and counts

Two variants, `plain` and `tabs`. Color marks such as `@kw{…}` work only in a plain window with no language.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product` and `article` Templates. Seen on `pages/diffkeel/home.json`, section 3.

  - Harbor tides: An API product shows the answer for one draft as JSON.
  - Vanroster: A scheduling product shows the webhook a route change sends.
  - Ledgerhouse: A bookkeeping firm shows the export a client imports.
  - Diffkeel: A developer tool shows the same diff from the CLI, from CI and in the config.
  - Benchlist: A directory shows the listing record a host fills in.
  - Sidework: A weekly letter shows its feed address.

## Do and do not

  - Do: A window for several lines a reader reads.
  - Don't: One command in a window: a `command-row` gives it a copy control and a note.

  - Do: Lines short enough to read without scrolling.
  - Don't: A line past 100 characters is refused; break the command across lines.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Scroll regions a keyboard cannot reach | 0 | 3 of 3 | no |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The window sits in `main`. It adds no landmark.
- **Heading level** It carries no heading; its title is a label in the bar.
- **Focus order** The copy control takes focus. A window that scrolls sideways takes no focus, and tabs switch on click only, in 7.0.0-alpha.0: keep lines short and put what most readers need in the first tab.

## Related

  - [command-row](https://next.mdxui.dev/docs/sections/command-row): Use it for one command to copy.
  - [api-call](https://next.mdxui.dev/docs/sections/api-call): Use it for a request beside its answer.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/terminal.md. Add a terminal section to my page: a plain window with a title, a language and at most 32 lines of at most 100 characters. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# text-stack (/docs/sections/text-stack)

> Copy beside a column of ruled, titled paragraphs.

Preview: every frame of text-stack is listed in https://next.mdxui.dev/components/manifest.json

## When to use

Use a text stack for three to six short paragraphs that each need a title: where the data comes from, what a plan covers, how a firm works. Each holds a title of 28 characters and a line of 160.

`stack` runs them in one ruled column beside the head; `grid` sets them in a grid. When they run in order, use `steps`; when each answers a question, use `faq`.

Lead each paragraph with its point: the title names the topic and the line gives the fact.

- [`steps`](https://next.mdxui.dev/docs/sections/steps): the paragraphs run in order
- [`faq`](https://next.mdxui.dev/docs/sections/faq): each paragraph answers a question

## The record

```json title="pages/sidework/about.json, section 2"
{
  "kind": "section",
  "shell": { "inset": "contained", "density": "section" },
  "block": {
    "type": "text-stack",
    "head": { "eyebrow": "House rules", "title": "Four rules for every issue.", "lede": "They hold for every issue since the first." },
    "layout": "stack",
    "items": [
      { "title": "No sponsors", "text": "Paid readers fund the letter. No issue carries an advertisement." },
      { "title": "No affiliate links", "text": "A tool named in an issue earns Sidework nothing." },
      { "title": "Numbers worked", "text": "Every price and tax figure shows its arithmetic, so you can redo it with yours." },
      { "title": "Corrections on top", "text": "A mistake is corrected at the top of the issue, with the date it was fixed." }
    ]
  }
}
```

## Smallest that parses

```json
{
  "type": "text-stack",
  "head": { "eyebrow": "House rules", "title": "Four rules for every issue." },
  "items": [
    { "title": "No sponsors", "text": "Paid readers fund the letter. No issue carries an advertisement." },
    { "title": "No affiliate links", "text": "A tool named in an issue earns Sidework nothing." },
    { "title": "Numbers worked", "text": "Every price and tax figure shows its arithmetic, so you can redo it with yours." }
  ]
}
```

## Fields and bounds

From `@mdxui/site@7.0.0-alpha.0`. A count reads as `min–max × item`; a string bound is its maximum length in characters, and links its refusal.

The 2 fields a writer fills most:

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#text-stack.head) | yes |
| `items` | [`3–6 × object`](https://next.mdxui.dev/docs/reference/refusals#text-stack.items) | yes |

<details>
<summary>Show all 15 fields</summary>

| Prop | Type and bound | Required |
| --- | --- | --- |
| `head` | [`object`](https://next.mdxui.dev/docs/reference/refusals#text-stack.head) | yes |
| `head.eyebrow` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#text-stack.head.eyebrow) | yes |
| `head.title` | [`string ≤72`](https://next.mdxui.dev/docs/reference/refusals#text-stack.head.title) | no |
| `head.lede` | [`string ≤300`](https://next.mdxui.dev/docs/reference/refusals#text-stack.head.lede) | no |
| `head.max` | `string (pattern)` | no |
| `head.ledeMax` | `string (pattern)` | no |
| `head.balance` | `boolean` | no |
| `head.scale` | `"compact" \| "large"` | no |
| `head.tag` | [`string ≤8`](https://next.mdxui.dev/docs/reference/refusals#text-stack.head.tag) | no |
| `head.layout` | `"split"` | no |
| `layout` | `"stack" \| "grid"` | no |
| `items` | [`3–6 × object`](https://next.mdxui.dev/docs/reference/refusals#text-stack.items) | yes |
| `items[].title` | [`string ≤28`](https://next.mdxui.dev/docs/reference/refusals#text-stack.items.title) | yes |
| `items[].text` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#text-stack.items.text) | yes |
| `items[].href` | [`string ≤160`](https://next.mdxui.dev/docs/reference/refusals#text-stack.items.href) | no |

</details>

## Variants and counts

Two layouts, `stack` and `grid`, each from three to six items.

### One record in five Themes

## Shells

## In three Businesses

Carried by the `api-product`, `article`, `blog` and `directory-product` Templates. Seen on `pages/sidework/about.json`, section 2.

  - Harbor tides: An API product says where its depths, tides and datums come from.
  - Vanroster: A scheduling product says how it keeps crew data safe.
  - Ledgerhouse: A bookkeeping firm says what each service covers.
  - Diffkeel: A developer tool says what the install changes on a machine.
  - Benchlist: A directory says how benches are checked.
  - Sidework: A weekly letter says who writes it and how often.

## Do and do not

  - Do: Titles that name a topic: depth, tide, datum.
  - Don't: Titles numbered Step 1, 2, 3 ask for `steps`, which numbers them for you.

  - Do: Three paragraphs fill the column.
  - Don't: Two paragraphs are refused: the stack holds three to six.

## Accessibility

| Check, on the exemplar render | Limit | Now | Pass |
| --- | --- | --- | --- |
| Skipped heading levels | 0 | 0 | yes |
| Images and icons with no text alternative | 0 | 0 | yes |

None on this type: unnamed nav landmarks; scroll regions a keyboard cannot reach; copy controls that announce the result.

5 text pairs fall below AA across the 5 Themes. [Render checks](https://next.mdxui.dev/docs/maintainers/render-checks) name each pair.

- **Landmark** The stack sits in `main`. It adds no landmark.
- **Heading level** The head title renders as an `h2` and each item title as an `h3`.
- **Focus order** Only an item with a link takes focus; its title becomes the link.

## Related

  - [steps](https://next.mdxui.dev/docs/sections/steps): Use it for the paragraphs run in order.
  - [faq](https://next.mdxui.dev/docs/sections/faq): Use it for each paragraph answers a question.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/sections/text-stack.md. Add a text-stack section to my page: three to six paragraphs, each with a title of at most 28 characters and a line of at most 160. Run PageSchema.safeParse from @mdxui/site@7.0.0-alpha.0; when it refuses a field, shorten the content at that path.
```


# Benchlist (/docs/showcase/benchlist)

> Directory and marketplace: shared workshop benches by the hour, in directory.



## Pages

Every page is a live render of its record. Flip the Site to see each one under another Theme; the records do not change.

## Brand

A directory is many listings competing for one glance. Directory's monochrome Inter and no dividers let the benches carry the page, and it reads in light or dark.

## Built from

<details className="mx-sc-details">
<summary>The tally and the records, as text</summary>

16 Section types across 8 pages.

[`footer`](https://next.mdxui.dev/docs/sections/footer) ×8 · [`nav`](https://next.mdxui.dev/docs/sections/nav) ×8 · [`closing`](https://next.mdxui.dev/docs/sections/closing) ×4 · [`page-head`](https://next.mdxui.dev/docs/sections/page-head) ×4 · [`facts`](https://next.mdxui.dev/docs/sections/facts) ×2 · [`faq`](https://next.mdxui.dev/docs/sections/faq) ×2 · [`product-list`](https://next.mdxui.dev/docs/sections/product-list) ×2 · [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) ×2 · [`article`](https://next.mdxui.dev/docs/sections/article) ×1 · [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) ×1 · [`hero`](https://next.mdxui.dev/docs/sections/hero) ×1 · [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) ×1 · [`product-head`](https://next.mdxui.dev/docs/sections/product-head) ×1 · [`statement`](https://next.mdxui.dev/docs/sections/statement) ×1 · [`stats`](https://next.mdxui.dev/docs/sections/stats) ×1 · [`steps`](https://next.mdxui.dev/docs/sections/steps) ×1

| Page | Template | Sections | Record |
| --- | --- | --- | --- |
| [home](https://next.mdxui.dev/sites/benchlist/) | `directory-list` | 6 | [JSON](https://next.mdxui.dev/pages/benchlist/home.json) |
| [404](https://next.mdxui.dev/sites/benchlist/404) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/benchlist/404.json) |
| [about](https://next.mdxui.dev/sites/benchlist/about) | `article` | 6 | [JSON](https://next.mdxui.dev/pages/benchlist/about.json) |
| [list-a-bench](https://next.mdxui.dev/sites/benchlist/list-a-bench) | `contact` | 5 | [JSON](https://next.mdxui.dev/pages/benchlist/list-a-bench.json) |
| [terms](https://next.mdxui.dev/sites/benchlist/terms) | `article` | 3 | [JSON](https://next.mdxui.dev/pages/benchlist/terms.json) |
| [bench/kiln-room-4](https://next.mdxui.dev/sites/benchlist/bench/kiln-room-4) | `directory-product` | 7 | [JSON](https://next.mdxui.dev/pages/benchlist/bench/kiln-room-4.json) |
| [city/duluth](https://next.mdxui.dev/sites/benchlist/city/duluth) | `directory-list` | 5 | [JSON](https://next.mdxui.dev/pages/benchlist/city/duluth.json) |
| [list-a-bench/sent](https://next.mdxui.dev/sites/benchlist/list-a-bench/sent) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/benchlist/list-a-bench/sent.json) |

</details>

## How it was built

**The brief.** A directory and marketplace of shared workshop benches, booked by the hour. The listings are things, never people. The hero says it plainly: "A workbench near you, by the hour."

**The records.** One JSON record per page under `pages/benchlist/`: the home and `city/duluth` name `directory-list`, `bench/kiln-room-4` names `directory-product`, and listing a bench names `contact`.

**The Theme.** Every record names `"theme": "directory"`. Changing that line in each file rebrands the Site, which is what Flip Site shows under all five Themes.

**The 404 and the listing flow.** `404.json` leads back home. The list-a-bench form posts to its action, and `list-a-bench/sent.json` is the page an owner lands on. A static host answers no post, so on this host the form does not send.

## Use this Site



# Diffkeel (/docs/showcase/diffkeel)

> Developer tool: a CLI that diffs config before it deploys, in certificate.



## Pages

Every page is a live render of its record. Flip the Site to see each one under another Theme; the records do not change.

## Brand

Diffkeel's buyers read diffs all day. Teal on cool paper, IBM Plex and hatched rules look like the terminal they trust, and certificate emits a dark scheme for readers who keep one on.

## Built from

<details className="mx-sc-details">
<summary>The tally and the records, as text</summary>

22 Section types across 9 pages.

[`footer`](https://next.mdxui.dev/docs/sections/footer) ×9 · [`nav`](https://next.mdxui.dev/docs/sections/nav) ×9 · [`command-row`](https://next.mdxui.dev/docs/sections/command-row) ×3 · [`page-head`](https://next.mdxui.dev/docs/sections/page-head) ×3 · [`article`](https://next.mdxui.dev/docs/sections/article) ×2 · [`closing`](https://next.mdxui.dev/docs/sections/closing) ×2 · [`facts`](https://next.mdxui.dev/docs/sections/facts) ×2 · [`terminal`](https://next.mdxui.dev/docs/sections/terminal) ×2 · [`agent-prompt`](https://next.mdxui.dev/docs/sections/agent-prompt) ×1 · [`api-call`](https://next.mdxui.dev/docs/sections/api-call) ×1 · [`bento`](https://next.mdxui.dev/docs/sections/bento) ×1 · [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) ×1 · [`endpoints`](https://next.mdxui.dev/docs/sections/endpoints) ×1 · [`faq`](https://next.mdxui.dev/docs/sections/faq) ×1 · [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) ×1 · [`hero`](https://next.mdxui.dev/docs/sections/hero) ×1 · [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) ×1 · [`post-list`](https://next.mdxui.dev/docs/sections/post-list) ×1 · [`pricing`](https://next.mdxui.dev/docs/sections/pricing) ×1 · [`stats`](https://next.mdxui.dev/docs/sections/stats) ×1 · [`steps`](https://next.mdxui.dev/docs/sections/steps) ×1 · [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) ×1

| Page | Template | Sections | Record |
| --- | --- | --- | --- |
| [home](https://next.mdxui.dev/sites/diffkeel/) | `api-product` | 8 | [JSON](https://next.mdxui.dev/pages/diffkeel/home.json) |
| [404](https://next.mdxui.dev/sites/diffkeel/404) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/diffkeel/404.json) |
| [changelog](https://next.mdxui.dev/sites/diffkeel/changelog) | `blog` | 4 | [JSON](https://next.mdxui.dev/pages/diffkeel/changelog.json) |
| [contact](https://next.mdxui.dev/sites/diffkeel/contact) | `contact` | 4 | [JSON](https://next.mdxui.dev/pages/diffkeel/contact.json) |
| [install](https://next.mdxui.dev/sites/diffkeel/install) | `article` | 8 | [JSON](https://next.mdxui.dev/pages/diffkeel/install.json) |
| [pricing](https://next.mdxui.dev/sites/diffkeel/pricing) | `api-product` | 7 | [JSON](https://next.mdxui.dev/pages/diffkeel/pricing.json) |
| [changelog/0-9](https://next.mdxui.dev/sites/diffkeel/changelog/0-9) | `post` | 3 | [JSON](https://next.mdxui.dev/pages/diffkeel/changelog/0-9.json) |
| [contact/sent](https://next.mdxui.dev/sites/diffkeel/contact/sent) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/diffkeel/contact/sent.json) |
| [docs/first-diff](https://next.mdxui.dev/sites/diffkeel/docs/first-diff) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/diffkeel/docs/first-diff.json) |

</details>

## How it was built

**The brief.** A developer tool: a CLI that diffs config before it deploys, with install notes, a changelog and plans. The hero says what it does: "See the config change before it ships."

**The records.** One JSON record per page under `pages/diffkeel/`: install and the first-diff docs name `article`, the changelog and release 0.9 name `blog` and `post`, and pricing, contact and its sent page fill out the rest.

**The Theme.** Every record names `"theme": "certificate"`, the Theme these docs wear. Changing that line in each file rebrands the Site, which is what Flip Site shows.

**The 404 and the contact flow.** `404.json` leads back home. The contact form posts to its action, and `contact/sent.json` is the page a sender lands on. A static host answers no post, so on this host the form does not send.

## Use this Site



# Harbor tides (/docs/showcase/harbor)

> API product: tide windows per berth, in quaypoint.



## Pages

Every page is a live render of its record. Flip the Site to see each one under another Theme; the records do not change.

## Brand

Harbor sells numbers to people who plan around the water. Navy and signal orange read as a chart table, Space Grotesk keeps headings sturdy, and the plated plan marks the one most berths need.

## Built from

<details className="mx-sc-details">
<summary>The tally and the records, as text</summary>

24 Section types across 10 pages.

[`footer`](https://next.mdxui.dev/docs/sections/footer) ×10 · [`nav`](https://next.mdxui.dev/docs/sections/nav) ×10 · [`article`](https://next.mdxui.dev/docs/sections/article) ×2 · [`closing`](https://next.mdxui.dev/docs/sections/closing) ×2 · [`page-head`](https://next.mdxui.dev/docs/sections/page-head) ×2 · [`pricing`](https://next.mdxui.dev/docs/sections/pricing) ×2 · [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) ×2 · [`agent-prompt`](https://next.mdxui.dev/docs/sections/agent-prompt) ×1 · [`api-call`](https://next.mdxui.dev/docs/sections/api-call) ×1 · [`bento`](https://next.mdxui.dev/docs/sections/bento) ×1 · [`command-row`](https://next.mdxui.dev/docs/sections/command-row) ×1 · [`compare`](https://next.mdxui.dev/docs/sections/compare) ×1 · [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) ×1 · [`endpoints`](https://next.mdxui.dev/docs/sections/endpoints) ×1 · [`facts`](https://next.mdxui.dev/docs/sections/facts) ×1 · [`faq`](https://next.mdxui.dev/docs/sections/faq) ×1 · [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) ×1 · [`feature-split`](https://next.mdxui.dev/docs/sections/feature-split) ×1 · [`hero`](https://next.mdxui.dev/docs/sections/hero) ×1 · [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) ×1 · [`post-list`](https://next.mdxui.dev/docs/sections/post-list) ×1 · [`product-head`](https://next.mdxui.dev/docs/sections/product-head) ×1 · [`product-list`](https://next.mdxui.dev/docs/sections/product-list) ×1 · [`steps`](https://next.mdxui.dev/docs/sections/steps) ×1

| Page | Template | Sections | Record |
| --- | --- | --- | --- |
| [home](https://next.mdxui.dev/sites/harbor/) | `api-product` | 14 | [JSON](https://next.mdxui.dev/pages/harbor/home.json) |
| [404](https://next.mdxui.dev/sites/harbor/404) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/harbor/404.json) |
| [blog](https://next.mdxui.dev/sites/harbor/blog) | `blog` | 4 | [JSON](https://next.mdxui.dev/pages/harbor/blog.json) |
| [contact](https://next.mdxui.dev/sites/harbor/contact) | `contact` | 3 | [JSON](https://next.mdxui.dev/pages/harbor/contact.json) |
| [integrations](https://next.mdxui.dev/sites/harbor/integrations) | `directory-list` | 3 | [JSON](https://next.mdxui.dev/pages/harbor/integrations.json) |
| [pricing](https://next.mdxui.dev/sites/harbor/pricing) | `api-product` | 5 | [JSON](https://next.mdxui.dev/pages/harbor/pricing.json) |
| [terms](https://next.mdxui.dev/sites/harbor/terms) | `article` | 3 | [JSON](https://next.mdxui.dev/pages/harbor/terms.json) |
| [blog/tide-windows](https://next.mdxui.dev/sites/harbor/blog/tide-windows) | `post` | 3 | [JSON](https://next.mdxui.dev/pages/harbor/blog/tide-windows.json) |
| [contact/sent](https://next.mdxui.dev/sites/harbor/contact/sent) | `article` | 3 | [JSON](https://next.mdxui.dev/pages/harbor/contact/sent.json) |
| [integrations/chartplot](https://next.mdxui.dev/sites/harbor/integrations/chartplot) | `directory-product` | 5 | [JSON](https://next.mdxui.dev/pages/harbor/integrations/chartplot.json) |

</details>

## How it was built

**The brief.** An API product that sells tide windows per berth: a free plan, paid plans and a way to ask for a new berth. The hero says it in four words: "Every berth, every tide."

**The records.** One JSON record per page under `pages/harbor/`: the home and pricing name `api-product`, the integrations listing and one integration name `directory-list` and `directory-product`, and a blog, a post, terms, contact and its sent page fill out the rest.

**The Theme.** Every record names `"theme": "quaypoint"`. Changing that line in each file rebrands the Site, which is what Flip Site shows under all five Themes.

**The 404 and the contact flow.** `404.json` is a page head and a closing that leads back home. The form posts to `/contact/send`, and `contact/sent.json` is the page a sender lands on. A static host answers no post, so on this host the form does not send.

## Use this Site



# Showcase (/docs/showcase)

> Six worked Businesses built from records, each a live Site you can open, wear in another Theme and copy.

Six worked examples, not customers: each a whole Site rendered from records on every build.

Each worked Site is a folder of Page records under `pages/<site>/`: one Theme, a 404 and a contact or subscribe flow. Open one to see every page, flip it into another Theme, download its records or hand the folder to an agent. The names are invented, and so is every number on their pages.

## Templates

A Template names the kind of a page: a landing, a list of posts, one listing. The same seven Templates recur across all six Businesses, so a page that works for one Business is a starting record for the next.

[Every Template, with each page that names it →](https://next.mdxui.dev/docs/showcase/templates)


# Ledgerhouse (/docs/showcase/ledgerhouse)

> Professional services: a two-partner bookkeeping and tax firm, in vaultline.



## Pages

Every page is a live render of its record. Flip the Site to see each one under another Theme; the records do not change.

## Brand

A bookkeeping firm sells trust before it sells hours. Vaultline's serif on warm paper reads like a letter from a partner, and its plated offer sets the monthly close apart from a one-off return.

## Built from

<details className="mx-sc-details">
<summary>The tally and the records, as text</summary>

21 Section types across 9 pages.

[`footer`](https://next.mdxui.dev/docs/sections/footer) ×9 · [`nav`](https://next.mdxui.dev/docs/sections/nav) ×9 · [`closing`](https://next.mdxui.dev/docs/sections/closing) ×7 · [`page-head`](https://next.mdxui.dev/docs/sections/page-head) ×5 · [`facts`](https://next.mdxui.dev/docs/sections/facts) ×2 · [`steps`](https://next.mdxui.dev/docs/sections/steps) ×2 · [`article`](https://next.mdxui.dev/docs/sections/article) ×1 · [`bento`](https://next.mdxui.dev/docs/sections/bento) ×1 · [`compare`](https://next.mdxui.dev/docs/sections/compare) ×1 · [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) ×1 · [`faq`](https://next.mdxui.dev/docs/sections/faq) ×1 · [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) ×1 · [`feature-split`](https://next.mdxui.dev/docs/sections/feature-split) ×1 · [`hero`](https://next.mdxui.dev/docs/sections/hero) ×1 · [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) ×1 · [`pricing`](https://next.mdxui.dev/docs/sections/pricing) ×1 · [`product-list`](https://next.mdxui.dev/docs/sections/product-list) ×1 · [`statement`](https://next.mdxui.dev/docs/sections/statement) ×1 · [`stats`](https://next.mdxui.dev/docs/sections/stats) ×1 · [`terminal`](https://next.mdxui.dev/docs/sections/terminal) ×1 · [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) ×1

| Page | Template | Sections | Record |
| --- | --- | --- | --- |
| [home](https://next.mdxui.dev/sites/ledgerhouse/) | — | 8 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/home.json) |
| [404](https://next.mdxui.dev/sites/ledgerhouse/404) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/404.json) |
| [about](https://next.mdxui.dev/sites/ledgerhouse/about) | `article` | 6 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/about.json) |
| [intake](https://next.mdxui.dev/sites/ledgerhouse/intake) | `contact` | 4 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/intake.json) |
| [pricing](https://next.mdxui.dev/sites/ledgerhouse/pricing) | `api-product` | 6 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/pricing.json) |
| [services](https://next.mdxui.dev/sites/ledgerhouse/services) | `article` | 6 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/services.json) |
| [terms](https://next.mdxui.dev/sites/ledgerhouse/terms) | `article` | 3 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/terms.json) |
| [intake/sent](https://next.mdxui.dev/sites/ledgerhouse/intake/sent) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/intake/sent.json) |
| [services/monthly-close](https://next.mdxui.dev/sites/ledgerhouse/services/monthly-close) | `article` | 8 | [JSON](https://next.mdxui.dev/pages/ledgerhouse/services/monthly-close.json) |

</details>

## How it was built

**The brief.** A two-partner bookkeeping and tax firm that sells a monthly close and a yearly return. The hero promises one date: "Books closed by the fifth."

**The records.** One JSON record per page under `pages/ledgerhouse/`: the services, the monthly close, about and terms name `article`, pricing names `api-product`, and an eight-field intake names `contact`.

**The Theme.** Every record names `"theme": "vaultline"`, the Theme Sidework also wears. A Theme is the firm's choice, not its kind of business.

**The 404 and the intake flow.** `404.json` leads back home. The intake form posts to its action, and `intake/sent.json` is the page a new client lands on. A static host answers no post, so on this host the form does not send.

## Use this Site



# Sidework (/docs/showcase/sidework)

> Publication: a weekly letter for people running a Business on the side, in vaultline.



## Pages

Every page is a live render of its record. Flip the Site to see each one under another Theme; the records do not change.

## Brand

Sidework is read, not scanned. Vaultline's serif and warm paper suit a weekly letter, and the plated paid plan on the subscribe page is the one offer a reader needs. Ledgerhouse wears it too.

## Built from

<details className="mx-sc-details">
<summary>The tally and the records, as text</summary>

15 Section types across 8 pages.

[`footer`](https://next.mdxui.dev/docs/sections/footer) ×8 · [`nav`](https://next.mdxui.dev/docs/sections/nav) ×8 · [`closing`](https://next.mdxui.dev/docs/sections/closing) ×5 · [`page-head`](https://next.mdxui.dev/docs/sections/page-head) ×3 · [`article`](https://next.mdxui.dev/docs/sections/article) ×2 · [`post-list`](https://next.mdxui.dev/docs/sections/post-list) ×2 · [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) ×1 · [`facts`](https://next.mdxui.dev/docs/sections/facts) ×1 · [`faq`](https://next.mdxui.dev/docs/sections/faq) ×1 · [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) ×1 · [`hero`](https://next.mdxui.dev/docs/sections/hero) ×1 · [`pricing`](https://next.mdxui.dev/docs/sections/pricing) ×1 · [`statement`](https://next.mdxui.dev/docs/sections/statement) ×1 · [`stats`](https://next.mdxui.dev/docs/sections/stats) ×1 · [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) ×1

| Page | Template | Sections | Record |
| --- | --- | --- | --- |
| [home](https://next.mdxui.dev/sites/sidework/) | `blog` | 8 | [JSON](https://next.mdxui.dev/pages/sidework/home.json) |
| [404](https://next.mdxui.dev/sites/sidework/404) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/sidework/404.json) |
| [about](https://next.mdxui.dev/sites/sidework/about) | `article` | 5 | [JSON](https://next.mdxui.dev/pages/sidework/about.json) |
| [archive](https://next.mdxui.dev/sites/sidework/archive) | `blog` | 4 | [JSON](https://next.mdxui.dev/pages/sidework/archive.json) |
| [subscribe](https://next.mdxui.dev/sites/sidework/subscribe) | `contact` | 5 | [JSON](https://next.mdxui.dev/pages/sidework/subscribe.json) |
| [terms](https://next.mdxui.dev/sites/sidework/terms) | `article` | 3 | [JSON](https://next.mdxui.dev/pages/sidework/terms.json) |
| [issues/the-first-invoice](https://next.mdxui.dev/sites/sidework/issues/the-first-invoice) | `post` | 4 | [JSON](https://next.mdxui.dev/pages/sidework/issues/the-first-invoice.json) |
| [subscribe/sent](https://next.mdxui.dev/sites/sidework/subscribe/sent) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/sidework/subscribe/sent.json) |

</details>

## How it was built

**The brief.** A publication: a weekly letter for people running a Business on the side, free to read with a paid plan. The hero says it in one line: "One letter a week for the side business."

**The records.** One JSON record per page under `pages/sidework/`: the home and the archive name `blog`, each issue names `post`, about names `article`, and the subscribe page sets a free and a paid plan beside a one-field form.

**The Theme.** Every record names `"theme": "vaultline"`, the Theme Ledgerhouse also wears. Two Businesses can share a Theme; their records stay their own.

**The 404 and the subscribe flow.** `404.json` leads back home. The subscribe form posts to its action, and `subscribe/sent.json` is the page a new reader lands on. A static host answers no post, so on this host the form does not send.

## Use this Site



# api-product (/docs/showcase/templates/api-product)

> Say what a Business sells: hero, proof, features, plans and a closing, in the order a buyer reads them.



Use `api-product` for the pages that sell: a landing and a pricing page. The hero states the offer and its two actions, proof and features follow in the order a buyer asks, OfferTiles price it, and a closing repeats the one action that matters. Despite the name, it fits any Product or Service, not only an API.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "api-product"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of hero</summary>

</details>

<details className="mx-sc-details">
<summary>Every field of feature-grid</summary>

</details>

<details className="mx-sc-details">
<summary>Every field of pricing</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/api-product.md, then fetch https://next.mdxui.dev/pages/vanroster/home.json, a api-product page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# article (/docs/showcase/templates/article)

> Long reading under a page head: services, install notes, terms and the page after a form.



Use `article` for a page a reader reads rather than scans: services explained, install notes, terms, an about page, and the short page a form lands on. A `page-head` or the article's own head names it; the body stays inside the article Markdown subset.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "article"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of page-head</summary>

</details>

<details className="mx-sc-details">
<summary>Every field of article</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/article.md, then fetch https://next.mdxui.dev/pages/vanroster/security.json, a article page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# blog (/docs/showcase/templates/blog)

> A list of posts or letters, each with a tag, a dateline and a dek.



Use `blog` for any page that lists dated writing: a blog, a changelog, a letter archive. One `post-list` carries the posts, newest first, each linking to a `post` page. The list holds at most 24 posts; a longer archive pages across records.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "blog"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of post-list</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/blog.md, then fetch https://next.mdxui.dev/pages/vanroster/changelog.json, a blog page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# contact (/docs/showcase/templates/contact)

> A form, its fields and the note beside it, with a sent page to land on.



Use `contact` for any page whose job is a form: contact, intake, a listing submission. The `cta-form` holds one to eight fields and posts to its `action`; the page a sender lands on is its own record. A static host answers no post, so point the action at a handler the Business runs.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "contact"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of cta-form</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/contact.md, then fetch https://next.mdxui.dev/pages/vanroster/contact.json, a contact page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# directory-list (/docs/showcase/templates/directory-list)

> A listing of products or places, with search, sort and a pager.



Use `directory-list` for a page of things a directory lists: benches in a city, integrations of an API. One `product-list` carries up to 50 rows, with a rail of filters, sort links and a pager; each row links to its `directory-product` page.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "directory-list"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of product-list</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/directory-list.md, then fetch https://next.mdxui.dev/pages/benchlist/home.json, a directory-list page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# directory-product (/docs/showcase/templates/directory-product)

> One listing on the split frame: a product head, facts and plans.



Use `directory-product` for one thing a directory lists: a bench, a room, an integration, a plan. The product head names it and carries its actions, facts answer the questions a buyer compares on, and plans price it. A listing page links back to it from `directory-list`.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "directory-product"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of product-head</summary>

</details>

<details className="mx-sc-details">
<summary>Every field of facts</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/directory-product.md, then fetch https://next.mdxui.dev/pages/vanroster/product/dispatch.json, a directory-product page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# Templates (/docs/showcase/templates)

> The seven Templates, each shown live in the worked Sites that use it.

> A Template is reusable Content with variables, filled from Things in the graph and authored as MDX, rendering a Message, Document, or Page.
>
> startupbuilder.dev, [Template](https://startupbuilder.dev/business/nouns/template)

In mdxui, a Page record names its Template in `template`, one of seven values `PageSchema` accepts. Each Tile shows every worked page that names it, live, in its own Business's Theme.

**Variables and slot rules.**

The seven names are in 7.0.0-alpha.0; the rest of startupbuilder.dev's Template is not. `PageSchema` checks that `template` is one of the seven and checks no slot, so the Section types a kind of page carries are read from the records, as each Template page shows.

## Which Template



# post (/docs/showcase/templates/post)

> One post: a back link, a dateline, the body and share links.



Use `post` for one dated piece: a blog post, a release note, an issue of a letter. The `article` carries the back link to its `blog` page, the dateline, the body in the article Markdown subset, and share links where the Business wants them.

## Sections in order

**Slot rules.**

Required and optional slots are not in 7.0.0-alpha.0. `PageSchema` accepts `"template": "post"` and checks no slot; the order above is read from the records.

## Fields that matter

<details className="mx-sc-details">
<summary>Every field of article</summary>

</details>

## Starter record

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/showcase/templates/post.md, then fetch https://next.mdxui.dev/pages/vanroster/changelog/route-swaps.json, a post page that parses.
Run pnpm add @mdxui/site@7.0.0-alpha.0.
Rewrite its strings for my Business. Keep its Section types in their order; drop one only when my Business has nothing to say there.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it with renderPage and save the HTML file.
```

## Other Templates



# Vanroster (/docs/showcase/vanroster)

> B2B SaaS: scheduling for field-service crews, in callboard.



## Pages

Every page is a live render of its record. Flip the Site to see each one under another Theme; the records do not change.

## Brand

Crew scheduling sells to operations leads choosing in a crowded field. Violet and Bricolage Grotesque make the brand loud enough to remember, and the plated plan points every visitor at the crew plan.

## Built from

<details className="mx-sc-details">
<summary>The tally and the records, as text</summary>

25 Section types across 9 pages.

[`footer`](https://next.mdxui.dev/docs/sections/footer) ×9 · [`nav`](https://next.mdxui.dev/docs/sections/nav) ×9 · [`closing`](https://next.mdxui.dev/docs/sections/closing) ×4 · [`facts`](https://next.mdxui.dev/docs/sections/facts) ×3 · [`page-head`](https://next.mdxui.dev/docs/sections/page-head) ×3 · [`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) ×2 · [`agent-prompt`](https://next.mdxui.dev/docs/sections/agent-prompt) ×1 · [`api-call`](https://next.mdxui.dev/docs/sections/api-call) ×1 · [`article`](https://next.mdxui.dev/docs/sections/article) ×1 · [`bento`](https://next.mdxui.dev/docs/sections/bento) ×1 · [`command-row`](https://next.mdxui.dev/docs/sections/command-row) ×1 · [`compare`](https://next.mdxui.dev/docs/sections/compare) ×1 · [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) ×1 · [`endpoints`](https://next.mdxui.dev/docs/sections/endpoints) ×1 · [`faq`](https://next.mdxui.dev/docs/sections/faq) ×1 · [`feature-split`](https://next.mdxui.dev/docs/sections/feature-split) ×1 · [`hero`](https://next.mdxui.dev/docs/sections/hero) ×1 · [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) ×1 · [`post-list`](https://next.mdxui.dev/docs/sections/post-list) ×1 · [`pricing`](https://next.mdxui.dev/docs/sections/pricing) ×1 · [`product-head`](https://next.mdxui.dev/docs/sections/product-head) ×1 · [`stats`](https://next.mdxui.dev/docs/sections/stats) ×1 · [`steps`](https://next.mdxui.dev/docs/sections/steps) ×1 · [`terminal`](https://next.mdxui.dev/docs/sections/terminal) ×1 · [`text-stack`](https://next.mdxui.dev/docs/sections/text-stack) ×1

| Page | Template | Sections | Record |
| --- | --- | --- | --- |
| [home](https://next.mdxui.dev/sites/vanroster/) | `api-product` | 8 | [JSON](https://next.mdxui.dev/pages/vanroster/home.json) |
| [404](https://next.mdxui.dev/sites/vanroster/404) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/vanroster/404.json) |
| [changelog](https://next.mdxui.dev/sites/vanroster/changelog) | `blog` | 4 | [JSON](https://next.mdxui.dev/pages/vanroster/changelog.json) |
| [contact](https://next.mdxui.dev/sites/vanroster/contact) | `contact` | 4 | [JSON](https://next.mdxui.dev/pages/vanroster/contact.json) |
| [pricing](https://next.mdxui.dev/sites/vanroster/pricing) | `api-product` | 5 | [JSON](https://next.mdxui.dev/pages/vanroster/pricing.json) |
| [security](https://next.mdxui.dev/sites/vanroster/security) | `article` | 7 | [JSON](https://next.mdxui.dev/pages/vanroster/security.json) |
| [changelog/route-swaps](https://next.mdxui.dev/sites/vanroster/changelog/route-swaps) | `post` | 3 | [JSON](https://next.mdxui.dev/pages/vanroster/changelog/route-swaps.json) |
| [contact/sent](https://next.mdxui.dev/sites/vanroster/contact/sent) | `article` | 4 | [JSON](https://next.mdxui.dev/pages/vanroster/contact/sent.json) |
| [product/dispatch](https://next.mdxui.dev/sites/vanroster/product/dispatch) | `directory-product` | 10 | [JSON](https://next.mdxui.dev/pages/vanroster/product/dispatch.json) |

</details>

## How it was built

**The brief.** A B2B SaaS that schedules field-service crews, with a product page for dispatch and a pricing page. The hero says it in six words: "Every crew on the right job."

**The records.** One JSON record per page under `pages/vanroster/`: the home and pricing name `api-product`, `product/dispatch` names `directory-product`, the changelog and one entry name `blog` and `post`, and security, contact and its sent page fill out the rest.

**The Theme.** Every record names `"theme": "callboard"`. Changing that line in each file rebrands the Site, which is what Flip Site shows under all five Themes.

**The 404 and the contact flow.** `404.json` leads back home. The contact form posts to its action, and `contact/sent.json` is the page a sender lands on. A static host answers no post, so on this host the form does not send.

## Use this Site



# How mdxui fits a Business (/docs/start/business)

> Business, Brand and Theme; Site, Page and Section; Products and Services, Interfaces and renderings: what startupbuilder.dev defines, and what mdxui draws.

[startupbuilder.dev](https://startupbuilder.dev) defines the Nouns of a Business; mdxui draws the ones a customer sees. A Startup is one kind of Business, so everything here holds for any Business, and a Startup adds its own layer on top.

> A Startup is the smallest business that can be moved, promoted, or sold on its own, with its own Products, Offers, Customers, and P&L.
>
> startupbuilder.dev, [Startup](https://startupbuilder.dev/business/nouns/startup)

## Business, Brand, Theme

A Business trades under a Brand, and mdxui turns the Brand's look into a Theme.

> A Brand is a name, a voice, a logo, and a style under which a Startup makes Offers.
>
> startupbuilder.dev, [Brand](https://startupbuilder.dev/business/nouns/brand)

> A Theme is the design tokens of a Brand, its color, type, spacing, radius, and motion, that every Component reads when it renders.
>
> startupbuilder.dev, [Theme](https://startupbuilder.dev/business/nouns/theme)

An mdxui Theme carries those tokens plus four render policies: how sections divide, whether headings carry markers, how the featured plan stands out, and how icons sit. A record names its Theme in one field, `"theme"`. [The Theme contract](https://next.mdxui.dev/docs/themes/contract) lists every role.

## Site, Page, Section

> A Site is a website as a Thing: its Pages, navigation, and Brand, served on one or more Domains.
>
> startupbuilder.dev, [Site](https://startupbuilder.dev/business/nouns/site)

> A Page is an addressable page of a Site, of a named type such as pricing, about one Thing or each member of a Collection.
>
> startupbuilder.dev, [Page](https://startupbuilder.dev/business/nouns/page)

> A Component is a named block of a Page, such as a hero, a pricing table, or a form, filled from records through typed props.
>
> startupbuilder.dev, [Component](https://startupbuilder.dev/business/nouns/component)

| startupbuilder.dev | In an mdxui record | Drawn by |
| --- | --- | --- |
| Site | A folder of Page records under one Theme, with a 404 | [Ship a Site](https://next.mdxui.dev/docs/start/ship) |
| Page | One record: `theme`, `title`, `description`, `frame`, 3 to 20 `sections` | `renderPage` |
| Page type, such as pricing | `template`, one of 7 Templates | [Templates](https://next.mdxui.dev/docs/showcase/templates) |
| Component | One entry of `sections`: its `kind`, `shell` and `block` | One of 27 [Section types](https://next.mdxui.dev/docs/sections) |
| Brand | The wordmark or mark in `nav` and `footer`, and the Theme | [Themes](https://next.mdxui.dev/docs/themes) |

## Products and Services, Interfaces, renderings

> A Product is what a Customer gets from a Startup, with a promise the Customer can rely on.
>
> startupbuilder.dev, [Product](https://startupbuilder.dev/business/nouns/product)

> A Service is a Product that warrants an outcome, delivered by Agents and Humans under an Outcome Contract.
>
> startupbuilder.dev, [Service](https://startupbuilder.dev/business/nouns/service)

> An Interface is how a person or an Agent reaches a Product: an API, MCP server, CLI, SDK, Site, or App.
>
> startupbuilder.dev, [Interface](https://startupbuilder.dev/business/nouns/interface)

mdxui draws two Interfaces: the Site, which renders today one `renderPage` call per record (`site()` is Spec), and the App, which is [studied](https://next.mdxui.dev/docs/app) and has no package. One record has several renderings, one per reader:

| Rendering | Reader | Status |
| --- | --- | --- |
| HTML | People, in a browser | Alpha |
| JSON | Agents and tools | Alpha |
| Markdown | Agents that read text | Spec |
| Share image | Feeds and chat previews | Spec |
| Email | Inboxes | Spec |

## What stays with the Business

Offers, prices, Customers, Domains and the work behind a Service live in the Business's own records; mdxui shows them only as the words of a page. [startupbuilder.dev](https://startupbuilder.dev) is where a Business models them.


# Coming from earlier mdxui (/docs/start/from-earlier-mdxui)

> What retired from earlier mdxui (the Site wrapper, Card, Tier, UsageMeter, Storybook) and where each idea lives now.

Earlier mdxui described a Business as React components: a `<Startup>` wrapping a `<Site>` of `<Hero>` and `<Pricing>` elements. mdxui 7 keeps the idea, components for Businesses, and changes the material: a page is a record an agent writes, and hand-made Section types draw it.

## What retired, and where it lives now

| Earlier | Now | Why |
| --- | --- | --- |
| The `<Site>` wrapper | A folder of Page records under one Theme; [Ship a Site](https://next.mdxui.dev/docs/start/ship) builds it | Site is startupbuilder.dev's Noun, and a Site is data |
| `<Hero>`, `<Pricing>`, `<FAQ>` and their props | One entry in `sections`, drawn by one of 27 [Section types](https://next.mdxui.dev/docs/sections) | An agent writes words, never markup |
| `Card` | Tile, the item root of the contract | On startupbuilder.dev, `Card` names a payment credential |
| `Tier`, `PricingTier` | OfferTile; each plan in a [`pricing`](https://next.mdxui.dev/docs/sections/pricing) section | An Offer is the priced choice |
| `UsageMeter` | UsageGauge | A meter counts billable usage on startupbuilder.dev |
| Site types: marketing, docs, blog, directory, marketplace, API | Worked Businesses and [Templates](https://next.mdxui.dev/docs/showcase/templates) | Built and rendered, not described |
| Per-component examples for a SaaS, a dev tool, an agency | Every Section type page shows its type in three worked Businesses | Real records, rendered |
| App shell, Dashboard, Settings, API keys, Usage | [App studies](https://next.mdxui.dev/docs/app): 13 App types, studied | The App design is open; no App package exists |
| Business, Startup and Service declarations | [startupbuilder.dev](https://startupbuilder.dev), which owns those Nouns | One owner per definition |
| Storybook | Live previews on every Section type, Theme and guide page | Every preview is a render of the published package |
| `pnpm add mdxui` | `pnpm add @mdxui/site@7.0.0-alpha.0` | The bare name is an earlier, unrelated release |

## Claims that no longer hold

- **Open source under MIT.** No. `@mdxui/site` and `@mdxui/themes` 7.0.0-alpha.0 declare license `UNLICENSED`, and their source is closed while they are alpha.
- **Components that deploy infrastructure.** mdxui renders pages. It provisions no database, auth, billing or hosting; a Site ships on the host you choose.
- **Time to an MVP.** These docs count Section types, Themes and worked Businesses, which you can check, and make no promise of elapsed time.

## Moving a page across

1. List the sections the earlier page drew, top to bottom.
2. For each, pick the Section type on [Choosing a Section type](https://next.mdxui.dev/docs/sections/choosing).
3. Start from the worked page closest to yours in the [Showcase](https://next.mdxui.dev/docs/showcase) and rewrite its words.
4. Parse it. Each refusal names the field to shorten.


# Run a blog and changelog (/docs/start/guides/blog-and-changelog)

> A post list, posts with share links and copy, and a changelog, built like Sidework's letter and Diffkeel's release notes.

A blog is two Templates: [`blog`](https://next.mdxui.dev/docs/showcase/templates/blog), one list page, and [`post`](https://next.mdxui.dev/docs/showcase/templates/post), one record per post. A changelog is the same pair, with a release in each post. Sidework publishes a weekly letter this way, and Diffkeel its release notes.

## Prerequisites

- A Site's `nav` and `footer`, from [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page).

**File: pages/archive.json**

**File: pages/issues/the-first-invoice.json**

**File: pages/changelog.json**

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/sidework/issues/the-first-invoice.json

## List the posts

[`post-list`](https://next.mdxui.dev/docs/sections/post-list) opens on a head (eyebrow, a title of 64, a lede of 200) and holds 1 to 24 posts. The `read` label, 16 characters, is the word on each link.

## Write each entry

Each post in the list carries its address, a tag of 20, a date as `YYYY-MM-DD` with an optional reading time, a title of 80 and a dek of 360. For more than 24 posts, split the archive into pages.

## Write a post

A post is one [`article`](https://next.mdxui.dev/docs/sections/article) section between the nav and the footer. Its head takes a back link, a tag, a dateline, a title of 80 and a dek of 360. The body runs to 12,000 characters, and each fenced code block in it names one of the [highlight languages](https://next.mdxui.dev/docs/reference/languages), or the record is refused at that block's line.

## Add share and copy

`share` takes the post's address and title, a label of 16 characters, and one to five networks: reddit, x, linkedin, bluesky and hackernews. `copy: true` puts a copy button on every code block of the body.

## Run a changelog

Give each release its own post record, tagged with its version, and list them newest first with the same `post-list`. Diffkeel's changelog is a `blog` page; each release is a `post`.

## Result

The Result is a post as it ships. Flip the Theme chips to read the same article in another Brand's typefaces.

## Next steps

  - [article](https://next.mdxui.dev/docs/sections/article): Long reading, under every Theme.
  - [Inline grammar](https://next.mdxui.dev/docs/sections/inline-grammar): Emphasis, code and links inside a field.
  - [List a directory](https://next.mdxui.dev/docs/start/guides/directory): The other list a Business publishes.



# Contact flow and 404 (/docs/start/guides/contact-and-404)

> A form, its sent page and a 404 for any Site, built like Ledgerhouse's intake, and what a static host does with a form post.

Every Site needs three pages no visitor asks for by name: the form that takes an inquiry, the page that thanks them, and the page an unknown address lands on. Ledgerhouse, a two-partner bookkeeping firm, takes new clients through an eight-field intake this way.

## Prerequisites

- A Site's `nav` and `footer`, from [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page).
- Somewhere to receive a post, such as the Worker in [Ship a Site](https://next.mdxui.dev/docs/start/ship).

**File: pages/intake.json**

**File: pages/intake/sent.json**

**File: pages/404.json**

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/ledgerhouse/intake.json

## Ask for what you need

[`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) takes one to eight fields. Each has a lowercase `name`, a type of `text`, `email`, `select` or `textarea`, a label of 16 characters and a placeholder of 32; a select lists up to 12 options. The button label runs to 24, and a note under it to 80.

## Send the post somewhere that answers

The form renders `method="post"` to its `action`, with no script. A static host answers only GET and HEAD, so a post to a file is never received. Route the `action` to a function: on Cloudflare, `worker.ts` from [Ship a Site](https://next.mdxui.dev/docs/start/ship) forwards each field and answers with a redirect to the sent page. The worked Sites on these docs are static files, so their forms do not send.

## Thank them

The sent page is an [`article`](https://next.mdxui.dev/docs/showcase/templates/article) page: the nav, a [`page-head`](https://next.mdxui.dev/docs/sections/page-head) with a title of 64 and a lede of 200 that says what happens next, and the footer. Give it `meta.noindex`, so no search engine lists it.

## Catch every lost address

The 404 record is a `page-head` and a `closing` with a way back, between the nav and the footer. A Site without one does not build: `ship.ts` stops on a missing `404.json`, and the host serves the page with status 404.

## Result

The Result is the form under each Theme. Below, the 404 page of every worked Site, each in its own Brand.

## Next steps

  - [Ship a Site](https://next.mdxui.dev/docs/start/ship): The Worker that receives the post.
  - [cta-form](https://next.mdxui.dev/docs/sections/cta-form): One field to eight, under every Theme.
  - [contact](https://next.mdxui.dev/docs/showcase/templates/contact): Every worked contact page.



# List a directory (/docs/start/guides/directory)

> A listing page with a rail, sort and pager, and a page per listing with its facts and plans, built like Benchlist.

A directory is two Templates: [`directory-list`](https://next.mdxui.dev/docs/showcase/templates/directory-list), the rows a reader scans, and [`directory-product`](https://next.mdxui.dev/docs/showcase/templates/directory-product), the page each row opens. Benchlist lists shared workshop benches by the hour this way.

## Prerequisites

- A Site's `nav` and `footer`, from [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page).
- One record per listing, written from your own catalog of things: benches, rooms, integrations.

**File: pages/city/duluth.json**

**File: pages/bench/kiln-room-4.json**

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/benchlist/city/duluth.json

## List what you carry

[`product-list`](https://next.mdxui.dev/docs/sections/product-list) holds up to 50 rows a page. Each row links to its listing and carries a name of 32 characters, a summary of 120, a tag of 24 and a note of 32. `view` sets the rows as a `list` or as a grid of `cards`.

## Let readers narrow it

The rail holds up to four groups of links with counts, the sort up to four links, and the pager a previous and a next address. Every control is a link to another address, so each filter, order and page is its own record, and no script runs.

## Give each listing a page

[`product-head`](https://next.mdxui.dev/docs/sections/product-head) opens the listing: a name of 32, a summary of 120, up to nine chips and one or two actions.

## State its facts

[`facts`](https://next.mdxui.dev/docs/sections/facts) holds up to 16 rows, a label of 24 and a value of 80 each, for what a reader compares: size, hours, address, what is included.

## Add its plans

A listing that sells by the hour or the month ends on [`pricing`](https://next.mdxui.dev/docs/sections/pricing), as on [Build a pricing page](https://next.mdxui.dev/docs/start/guides/pricing-page).

## Result

The Result is the list page. Open the render: every row, sort and page link goes to another page of the same Site.

## Next steps

  - [product-list](https://next.mdxui.dev/docs/sections/product-list): List and grid views, under every Theme.
  - [Benchlist](https://next.mdxui.dev/docs/showcase/benchlist): Every page of the worked directory.
  - [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404): Let owners send in a listing.



# Guides (/docs/start/guides)

> Every task guide, by the page a Business needs next: a landing page, pricing, a blog, a directory, a contact flow or a rebrand.

Each guide builds one kind of page from a worked Business's real record, one section at a time, with the record beside the steps. Start with the [Quickstart](https://next.mdxui.dev/docs/start/quickstart); then take them in the order a Business publishes.

  - [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page): Nav to footer: the promise, the proof, the ask.
  - [Build a pricing page](https://next.mdxui.dev/docs/start/guides/pricing-page): Plans, a comparison and the questions.
  - [Run a blog and changelog](https://next.mdxui.dev/docs/start/guides/blog-and-changelog): A post list, posts, release notes.
  - [List a directory](https://next.mdxui.dev/docs/start/guides/directory): Rows, a rail, sort and pages; a page per listing.
  - [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404): A form, its sent page, and every 404.
  - [Rebrand a Site](https://next.mdxui.dev/docs/start/guides/rebrand): One field per record moves the whole Site.

| Guide | You leave with | Built from |
| --- | --- | --- |
| [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page) | A home record, nav to footer | Vanroster |
| [Build a pricing page](https://next.mdxui.dev/docs/start/guides/pricing-page) | Plans, a plan table and questions | Vanroster, Ledgerhouse |
| [Run a blog and changelog](https://next.mdxui.dev/docs/start/guides/blog-and-changelog) | A list page and one record per post | Sidework, Diffkeel |
| [List a directory](https://next.mdxui.dev/docs/start/guides/directory) | A list page and a page per listing | Benchlist |
| [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404) | A form, its sent page and a 404 | Ledgerhouse, every Site |
| [Rebrand a Site](https://next.mdxui.dev/docs/start/guides/rebrand) | Every record under a new Theme | Harbor tides |
| [Ship a Site](https://next.mdxui.dev/docs/start/ship) | The whole Site, live | Harbor tides |
| [Have your agent write a page](https://next.mdxui.dev/docs/agents/write-a-page) | The same pages, written by an agent | Any |


# Build a landing page (/docs/start/guides/landing-page)

> Write a landing page record from nav to footer, one section at a time, the way Vanroster's home is built.

A landing page says what a Business sells in the order a buyer reads it: who you are, the promise, the proof, what it does, the next step. It uses the [`api-product`](https://next.mdxui.dev/docs/showcase/templates/api-product) Template. Each step lights its section in Vanroster's record.

## Prerequisites

- The project from the [Quickstart](https://next.mdxui.dev/docs/start/quickstart), or [starter.zip](https://next.mdxui.dev/starter.zip), whose `pages/home.json` is the record these steps build.

**File: pages/home.json**

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/vanroster/home.json

## Name the Business

[`nav`](https://next.mdxui.dev/docs/sections/nav) holds the brand, a wordmark of up to 16 characters, a mark, or both. With `menu: "push"` it takes up to six links of 20 characters and one call to action; below its `collapse` width the links fold into a menu that runs no script.

## Make the promise

The [`hero`](https://next.mdxui.dev/docs/sections/hero) title runs to 64 characters and the lede to 260. Give it two actions at most, and up to four lines of fine print. `layout: "split"` sets up to three Section types beside the words, such as a terminal window or an API call.

## Show the proof

[`stats`](https://next.mdxui.dev/docs/sections/stats) holds three or four values of six characters, each with a label. State product facts or plan terms the reader can check: a trial length, a count of views, a step saved.

## Say what it does

[`feature-grid`](https://next.mdxui.dev/docs/sections/feature-grid) takes 2, 3, 4, 6 or 8 cells, the counts that fill their rows at every width. Each cell has a title of 40 characters and a text of 200; `cellHead` picks what tops it: an icon, a label, both, an index, or nothing.

## Ask once more

[`closing`](https://next.mdxui.dev/docs/sections/closing) repeats the call to action under a short head. It ends on up to two buttons or on one command line, never both.

## Close the page

[`footer`](https://next.mdxui.dev/docs/sections/footer) in `columns` or `areas` holds two or three link columns, and one of them is titled "For agents"; `layout: "row"` drops that rule. Two note lines of 96 characters end the page.

## Result

The record parses and renders as one page. Flip the Theme chips: the words stay, and the Brand changes around them.

## What a landing here does not draw

Images, video, a gallery, testimonials, a logo wall and a team page have no Section type in 7.0.0-alpha.0. [Choosing a Section type](https://next.mdxui.dev/docs/sections/choosing#not-drawn-in-700-alpha0) gives the stand-in for each.

## Next steps

  - [Build a pricing page](https://next.mdxui.dev/docs/start/guides/pricing-page): Plans, a comparison and the questions.
  - [Choose a Section type](https://next.mdxui.dev/docs/sections/choosing): A section for every job on the page.
  - [api-product](https://next.mdxui.dev/docs/showcase/templates/api-product): Every worked page built on it.



# Build a pricing page (/docs/start/guides/pricing-page)

> Plans as OfferTiles, a plan table and the pricing questions, built like the Vanroster and Ledgerhouse pricing pages.

A pricing page lets a buyer pick a plan without writing in. It runs three sections under the nav: the plans, a comparison, and the questions. Vanroster sells software and Ledgerhouse sells bookkeeping; one record shape serves both.

## Prerequisites

- A landing page record, from [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page). The pricing page shares its `nav` and `footer`.

**File: pages/pricing.json**

**File: pages/pricing.json**

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/vanroster/pricing.json

## Lay out the plans

[`pricing`](https://next.mdxui.dev/docs/sections/pricing) holds one to four plans, each an OfferTile: a name and a price of 16 characters, a note of 24, a line of 80, one to ten features of 56, and the label and address of its button. In the record the list is `tiers`.

## Feature one plan

Mark one plan `featured`, and name its badge in `featuredBadge`, 16 characters. With four plans, the fourth is a row under the other three and is never the featured one.

## Choose the layout

`layout: "cards"` sets each plan in its own box; `layout: "ruled"` sets the plans as columns between rules. Ledgerhouse sets its plans ruled. How the featured plan stands out is the Theme's `featured` policy: a plate in vaultline, quaypoint and callboard, a rule in certificate and directory.

## Compare them line by line

[`plan-table`](https://next.mdxui.dev/docs/sections/plan-table) takes up to six columns of 16 characters and eight rows, each cell 32 characters, with a foot line of 160. Put the plan names across the top and one limit per row.

## Answer the questions

[`faq`](https://next.mdxui.dev/docs/sections/faq) holds up to ten questions of 64 characters, each answer up to 420; or up to four titled groups of six. Never both. Answer what stops a purchase: the trial, the contract, what happens over a limit.

## Result

The Result is the SaaS page. Flip it to vaultline, then to directory, and watch the featured plan move from a plate to a rule.

## Next steps

  - [pricing](https://next.mdxui.dev/docs/sections/pricing): Every variant, under every Theme.
  - [Render policies](https://next.mdxui.dev/docs/themes/policies): The featured plan, dividers, markers and icons.
  - [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404): For the plan that needs a conversation.



# Products and Services as pages (/docs/start/guides/products-and-services)

> How a Product becomes a landing, a pricing page and a listing, and how a Service becomes an intake form, a sent page and terms, each one a record.

> A Product is what a Customer gets from a Startup, with a promise the Customer can rely on.
>
> startupbuilder.dev, [Product](https://startupbuilder.dev/business/nouns/product)

> An Offer is a Product, under a Brand, at a price, on terms, made by a Startup.
>
> startupbuilder.dev, [Offer](https://startupbuilder.dev/business/nouns/offer)

startupbuilder.dev defines the Product, the Service and their Offers. mdxui draws the pages a customer reads about them. A Business that sells a Product and one that sells a Service need different pages, and each page is one record.

## A Product: say it, price it, list it

Vanroster sells crew scheduling as software. Its Product reaches a customer through three pages.

| Page | Template | What it carries | Record |
| --- | --- | --- | --- |
| Landing | `api-product` | The promise, the proof, the features and the plans, in the order a buyer reads | [`pages/vanroster/home.json`](https://next.mdxui.dev/pages/vanroster/home.json) |
| Pricing | `api-product` | Plans as OfferTiles, a plan table and the pricing questions | [`pages/vanroster/pricing.json`](https://next.mdxui.dev/pages/vanroster/pricing.json) |
| Product page | `directory-product` | One feature as a listing: its head, facts, calls and endpoints | [`pages/vanroster/product/dispatch.json`](https://next.mdxui.dev/pages/vanroster/product/dispatch.json) |

The rendered page: https://next.mdxui.dev/sites/vanroster/pricing; its record: https://next.mdxui.dev/pages/vanroster/pricing.json

The pricing page's plans are Offers: a name, a price, terms and an action. Each is an OfferTile in [`pricing`](https://next.mdxui.dev/docs/sections/pricing), and the same plans line up feature by feature in [`plan-table`](https://next.mdxui.dev/docs/sections/plan-table).

## A Service: take the inquiry, set the terms

Ledgerhouse sells bookkeeping, done by two partners. A Service starts with a conversation, so its pages ask before they sell.

| Page | Template | What it carries | Record |
| --- | --- | --- | --- |
| Services | `article` | What the firm does, as a list of engagements | [`pages/ledgerhouse/services.json`](https://next.mdxui.dev/pages/ledgerhouse/services.json) |
| Intake | `contact` | An eight-field form and the steps that follow it | [`pages/ledgerhouse/intake.json`](https://next.mdxui.dev/pages/ledgerhouse/intake.json) |
| Sent | `article` | What happens next, after the form | [`pages/ledgerhouse/intake/sent.json`](https://next.mdxui.dev/pages/ledgerhouse/intake/sent.json) |
| Terms | `article` | The engagement terms, as a document | [`pages/ledgerhouse/terms.json`](https://next.mdxui.dev/pages/ledgerhouse/terms.json) |

The rendered page: https://next.mdxui.dev/sites/ledgerhouse/intake; its record: https://next.mdxui.dev/pages/ledgerhouse/intake.json

The intake is a [`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) of up to eight bounded fields. [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404) shows where its post goes.

## One record per page, one Theme per Business

Every page above is its own record, and every record of one Business names one Theme. A plan changed on the pricing page is changed there only; the [Product record](https://next.mdxui.dev/docs/components/product-record) is the Spec that gives every page one source for those facts.

## Next steps

  - [Build a pricing page](https://next.mdxui.dev/docs/start/guides/pricing-page): Plans as OfferTiles, a plan table and pricing questions.
  - [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404): A form, its sent page and the page for lost addresses.
  - [Templates](https://next.mdxui.dev/docs/showcase/templates): The seven page kinds, each in two or three Businesses.
  - [How mdxui fits a Business](https://next.mdxui.dev/docs/start/business): Business, Brand, Theme, Site, Page and Section.



# Use it in a React app (/docs/start/guides/react-app)

> Serve a rendered record from a Next.js or React Router route, set one section inside a React page, or attach one on the client.

An app keeps its own React, routes and styles. mdxui adds a page or one section as HTML: `renderPage` returns a whole document, and `renderBlock` returns one section. Every snippet below is a part of `react-app.ts`, which `pnpm check` runs against Harbor tides' records.

## Prerequisites

- An app on React 19, Next.js App Router or React Router, with `@mdxui/site@7.0.0-alpha.0` installed as in the [Quickstart](https://next.mdxui.dev/docs/start/quickstart).
- Records in `pages/`, such as the [Harbor tides records](https://next.mdxui.dev/sites/harbor/records.zip).

## Serve a whole page from a route

A rendered record is a complete document, so a route answers with it as `text/html`. In Next.js, export it as `GET` from `app/pricing/route.ts`; in React Router, export it as a resource route's `loader`.

```ts
import { readFile } from 'node:fs/promises';
import { PageSchema, renderPage } from '@mdxui/site';

/**
 * A route handler that answers with a rendered record. It is a plain
 * Request-to-Response function, so it drops into a Next.js App Router
 * `app/pricing/route.ts` as `GET`, a React Router resource route as `loader`,
 * or a Worker's `fetch`.
 */
export async function GET(): Promise<Response> {
  const record = JSON.parse(await readFile('pages/pricing.json', 'utf8'));
  const html = renderPage(PageSchema.parse(record));
  return new Response(html, { headers: { 'content-type': 'text/html; charset=utf-8' } });
}
```

The page keeps its own Theme and stylesheet; nothing from the app's CSS reaches it.

## Set one section inside a React page

A server component renders one section into a declarative shadow root. The section's styles stay inside the root, and the app's styles stay out. No script runs.

```ts
import { createElement } from 'react';
import { renderToString } from 'react-dom/server';
import { BlockSchema, baseCss, blocksCss, context, primitivesCss, renderBlock } from '@mdxui/site';
import { THEMES, type ThemeName } from '@mdxui/themes';

/**
 * One section inside a React page, as a server component: a declarative
 * shadow root keeps the section's styles in and the app's styles out, and
 * needs no script. In JSX: <Section block={block} theme="quaypoint" />.
 */
export function Section({ block, theme }: { block: unknown; theme: ThemeName }) {
  const { theme: t, css } = THEMES[theme];
  const html = renderBlock(BlockSchema.parse(block), context(t, 'paper', t.icons));
  const styles = `<style>${css().replaceAll(':root', ':host')}${baseCss}${primitivesCss}${blocksCss}</style>`;
  return createElement(
    'div',
    { className: 'mdxui-section' },
    createElement('template', { shadowrootmode: 'open', dangerouslySetInnerHTML: { __html: `${styles}${html}` } }),
  );
}
```

Use it as `<Section block={block} theme="quaypoint" />`. The block is any section's `block` from a record; `BlockSchema.parse` refuses one past its bounds at its path.

## Attach a section on the client

A client component that receives the section's HTML as a string attaches the shadow root itself, after hydration:

```ts
/**
 * In a client component, after hydration: attach the shadow root yourself,
 * from HTML your server rendered with renderBlock and sent as a string.
 */
export function attachSection(host: HTMLElement, html: string): void {
  const root = host.shadowRoot ?? host.attachShadow({ mode: 'open' });
  root.innerHTML = html;
}
```

Render the string on the server with `renderBlock`, as in the server component, and send it to the client as a prop.

## Next steps

  - [Ship a Site](https://next.mdxui.dev/docs/start/ship): Every record in pages/ as one Site, on Node, Vite, React Router or a Worker.
  - [Embed one section](https://next.mdxui.dev/docs/components/renderings/embed): renderBlock in a shadow root, in any page.



# Rebrand a Site in one line (/docs/start/guides/rebrand)

> Change the theme field in every record, check that each still parses, and compare every page of the Site under the old Theme and the new.

A record names its Theme in one field, `"theme"`. Change it in every record of a Site and the whole Site redraws in another Brand: color, typefaces, dividers, how the featured plan stands out. No word moves.

## Prerequisites

- A Site's records in `pages/`, all under one Theme. [Harbor tides](https://next.mdxui.dev/sites/harbor/records.zip) has ten.

**File: pages/home.json**

**File: rebrand.ts**

```ts
// node rebrand.ts directory: every record in pages/ moves to one Theme, and still parses.
const theme = process.argv[2] ?? 'directory';
if (!(THEME_NAMES as readonly string[]).includes(theme)) throw new Error(`${theme} is not one of ${THEME_NAMES.join(', ')}`);

let moved = 0;
for (const file of (await readdir('pages', { recursive: true })).filter((f) => f.endsWith('.json'))) {
  const record = JSON.parse(await readFile(`pages/${file}`, 'utf8'));
  if (record.theme === theme) continue;
  record.theme = theme;
  PageSchema.parse(record); // a Theme changes no bound, so a record that parsed still parses
  await writeFile(`pages/${file}`, `${JSON.stringify(record, null, 2)}\n`);
  moved++;
}
console.log(`${moved} records now wear ${theme}`);
```

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/harbor/pricing.json

## Pick the Theme

The field takes one of five: `certificate`, `vaultline`, `quaypoint`, `callboard` or `directory`. Each [Theme](https://next.mdxui.dev/docs/themes) is a Brand's tokens plus four render policies. To wear your own Brand, [write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme).

## Change one line in every record

A Site wears one Theme, so change every record at once. Run `node rebrand.ts directory`; it sets the field, parses each record and writes it back. A Theme changes no bound, so a record that parsed still parses.

## Compare before you ship

These docs render every page of every worked Site under all five Themes. Flip the chips on the Result, or flip the whole Site below, before you commit a Brand. Check the pages where the policies show most: pricing for the featured plan, long pages for the dividers.

## Result

Every record names the new Theme and parses, and every page renders in one Brand. Build it with [Ship a Site](https://next.mdxui.dev/docs/start/ship).

## Next steps

  - [Themes](https://next.mdxui.dev/docs/themes): All five, side by side.
  - [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme): Your Brand, under every record.
  - [Ship a Site](https://next.mdxui.dev/docs/start/ship): Build the rebranded Site.



# Introduction (/docs/start)

> mdxui renders a Business's pages from records its agent writes, in the Business's own brand, and the design holds whatever the agent writes.

A page is a JSON record: the words, the plans, the questions. `@mdxui/site` lays it out from 27 Section types designed by hand, and a Theme from `@mdxui/themes` dresses it in the Business's Brand. Below, one worked Business's home record under three Themes; not one word differs between them.

## Who it is for

| You are | You use mdxui to | Start at |
| --- | --- | --- |
| A founder | Put every page a Business needs in front of customers, written by your agent, in your Brand | [Showcase](https://next.mdxui.dev/docs/showcase) |
| A developer | Build those records into a Site on your own stack, with a 404 and a contact flow | [Quickstart](https://next.mdxui.dev/docs/start/quickstart) |
| An agent | Write records that parse, and fix each refusal at the path it names | [For agents](https://next.mdxui.dev/docs/agents) |

## Four ideas

1. **Your Business, not a component kit.** Six worked Businesses, from a B2B SaaS to a publication, each built as real pages. Find the one closest to yours and copy its records.
2. **Your agent writes words, never markup.** The record holds no HTML, class names or CSS, so an agent can write it, diff it and fix it, and cannot move the layout.
3. **Your brand is one line.** Change `"theme"` and every page redraws in another Brand's tokens and render policies.
4. **Long copy never breaks the layout.** Every field has a maximum the design was drawn for, such as 64 characters for a hero title, so whatever the agent writes, the page keeps its shape. [Why the design holds](https://next.mdxui.dev/docs/sections/bounds) shows how.

## What ships

| Part | Status | Read |
| --- | --- | --- |
| `@mdxui/site@7.0.0-alpha.0`: the page schema, `renderPage` and 27 Section types | Alpha, on npm | [Packages](https://next.mdxui.dev/docs/start/packages) |
| `@mdxui/themes@7.0.0-alpha.0`: the Theme contract and 5 Themes | Alpha, on npm | [Themes](https://next.mdxui.dev/docs/themes) |
| HTML and JSON renderings of every record | Alpha | [Renderings](https://next.mdxui.dev/docs/components/renderings) |
| Markdown, share image and email renderings | Spec | [Renderings](https://next.mdxui.dev/docs/components/renderings) |
| `site()`: a whole Site in one call | Spec | [Ship a Site](https://next.mdxui.dev/docs/start/ship) |
| App, View and Dashboard | Study: 13 App types, no package | [Apps](https://next.mdxui.dev/docs/app) |

Both packages are unlicensed alpha releases, and their source is closed while they are alpha. Every schema, bound and render they produce is shown on these docs. The bare `mdxui` name on npm is an older, unrelated line, despite its higher version number.

## Where the definitions live

[startupbuilder.dev](https://startupbuilder.dev) defines the Business-side Nouns: [Site](https://startupbuilder.dev/business/nouns/site), [Page](https://startupbuilder.dev/business/nouns/page), [Brand](https://startupbuilder.dev/business/nouns/brand), [Theme](https://startupbuilder.dev/business/nouns/theme) and [Component](https://startupbuilder.dev/business/nouns/component). These docs show how mdxui draws each one; [How mdxui fits a Business](https://next.mdxui.dev/docs/start/business) maps them.

## Next

  - [Quickstart](https://next.mdxui.dev/docs/start/quickstart): One record, two Themes, made yours.
  - [Showcase](https://next.mdxui.dev/docs/showcase): Find the Business closest to yours and copy its records.
  - [Guides](https://next.mdxui.dev/docs/start/guides): A landing page, pricing, a blog, a directory, a contact flow.
  - [For agents](https://next.mdxui.dev/docs/agents): The prompt, the four fetches and the fix loop.



# Packages and versions (/docs/start/packages)

> The two published packages, the exact version to pin, and the three npm names that install something else.

Two packages make up mdxui 7: `@mdxui/site` renders a record, and `@mdxui/themes` holds the Themes it renders under. Both are at `7.0.0-alpha.0`.

## Install the pinned pair

```bash
pnpm add @mdxui/site@7.0.0-alpha.0
```

`@mdxui/site` depends on `@mdxui/themes` at exactly its own version, so one install brings both. To import `@mdxui/themes` yourself, as [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme) does, add it at that same version:

```bash
pnpm add @mdxui/themes@7.0.0-alpha.0
```

## Names that install something else

| Never install | What it installs | Why it breaks |
| --- | --- | --- |
| `mdxui` | `7.0.0-alpha.1`, from an earlier, unrelated line | Types and schemas only, with no renderer; it predates the records these docs describe |
| `@mdxui/app` | `6.0.1`, from the 6 line | The App renderer of these docs is unpublished; App types are [studies](https://next.mdxui.dev/docs/app) |
| `@mdxui/themes` with no version | `6.3.0`, the `latest` tag of the 6 line | A second, older copy beside the one `@mdxui/site` pins |

## Why the exact version

The packages are alpha, and an alpha can tighten or loosen any bound. A record that parses under one alpha may be refused under the next, at parse, by path, before anything renders. Pin the exact version, and run `PageSchema.safeParse` on every record in CI; [Have your agent write a page](https://next.mdxui.dev/docs/agents/write-a-page) shows the check. Read [Release notes](https://next.mdxui.dev/docs/reference/changelog) before you move the pin.

## What each package holds

| Package | Holds | dist-tags |
| --- | --- | --- |
| `@mdxui/site` | The page schema, `renderPage`, the composer, the section shells, the document, and every Section type with its CSS | `latest` and `alpha`: `7.0.0-alpha.0` |
| `@mdxui/themes` | The Theme contract, `compileTheme`, `resolveTokens` and the 5 Themes | `alpha`: `7.0.0-alpha.0`; `latest`: `6.3.0` |

| Package | Installed here | Depends on |
| --- | --- | --- |
| `@mdxui/site` | `7.0.0-alpha.0` | `@iconify-json/lucide@1.2.131`, `@iconify-json/simple-icons@1.2.95`, `@mdxui/themes@7.0.0-alpha.0`, `lucide-static@1.26.0`, `simple-icons@16.27.0`, `zod@4.6.2` |
| `@mdxui/themes` | `7.0.0-alpha.0` | nothing |

Both declare Node.js `>=22`.

The guides run their TypeScript files directly, which needs Node.js 22.18 or later.

## License and source

Both packages declare `license: UNLICENSED`. The npm tarballs hold the built JavaScript and the type declarations; the source is closed while the packages are alpha.

`UNLICENSED` grants no license, and no terms of use are published for the alpha. Evaluate 7.0.0-alpha.0; before you ship it in a product, wait for a published license. Every export is listed in [@mdxui/site exports](https://next.mdxui.dev/docs/reference/site-exports) and [@mdxui/themes exports](https://next.mdxui.dev/docs/reference/themes-exports).


# Pages are data (/docs/start/pages-are-data)

> A page is one JSON record of words and choices, never markup. What that buys an agent, and the four layers that turn it into HTML.

A page is one JSON record that `PageSchema` accepts or refuses, and `renderPage` turns it into one HTML document. The record holds content only: no markup, no class names, no CSS. Open the Record tab to read the same page as data:

The rendered page: https://next.mdxui.dev/sites/harbor/; its record: https://next.mdxui.dev/pages/harbor/home.json

## What a record buys an agent

| An agent writing markup | An agent writing a record |
| --- | --- |
| Redraws the layout on every edit | Changes words; the layout is the Section type's |
| Drifts from the brand page by page | Every page wears the one Theme it names |
| Produces a diff of tags and classes to review | Produces a JSON diff of the words that changed |
| Breaks the layout with a long headline | Is refused at the field, with its maximum, before anything renders |

## The smallest record

```json title="25 lines; PageSchema.parse accepts it"
{
  "theme": "quaypoint",
  "title": "Harbor tides",
  "description": "Tide tables for every berth.",
  "frame": "none",
  "sections": [
    {
      "kind": "hero", "shell": { "inset": "contained", "density": "hero" },
      "block": {
        "type": "hero", "layout": "centered", "stack": 560,
        "title": "Every berth, every tide.",
        "lede": "One call returns the tide table for any berth.",
        "actions": [], "fine": []
      }
    },
    {
      "kind": "band", "shell": { "inset": "contained", "density": "section" },
      "block": { "type": "statement", "text": "A tide table is a *promise*." }
    },
    {
      "kind": "section", "shell": { "inset": "contained", "density": "section" },
      "block": { "type": "command-row", "command": "npm i @example/harbor-tides" }
    }
  ]
}
```

| Field | Says |
| --- | --- |
| `theme` | Which bundled Theme the page wears |
| `frame` | The frame around every section: `none`, one ruled `sheet`, or a `split` with an aside |
| `sections` | Three to twenty sections, in page order |
| `kind` | What the section is to its neighbors; it picks the landmark and the divider |
| `shell.inset`, `shell.density` | The section's width and its vertical pace |
| `block.type` | The Section type that lays the content out |
| `stack` | The width in pixels below which the hero's actions stack |

## Four layers

Block is the renderer's word for a Section type's code; these docs say Section type everywhere else. Each layer owns one thing and never reaches into another.

| Layer | Holds | Never knows |
| --- | --- | --- |
| Block | One Section type's layout: one root element, colors by role | What is painted behind it, its neighbors, the Theme, the page |
| Shell | What is painted behind and between: `surface`, `background`, inset, density, stickiness, the frame | What the content says |
| Theme | Tokens and [policies](https://next.mdxui.dev/docs/themes/policies), compiled to custom properties | Which page it dresses |
| Composition | The record: Theme, frame and sections | Markup and CSS |

## The rules the layers keep

| Rule | It prevents |
| --- | --- |
| No model writes markup or CSS; a Section type is drawn once by hand | A page that re-guesses its design on every edit |
| A token never changes layout; a layout change is a variant | A Theme that breaks a page it never saw |
| Painted behind content is shell; positioning content is block | Two layers fighting over one box |
| A Section type never knows its neighbors; the composer derives each divider | A divider right between two sections and wrong between two others |
| Every string is bounded | A headline three times the length the design was drawn for |

## Edit with the schema

`PageSchema.toJSONSchema()` writes every bound as `maxLength`, `minItems` and `maxItems`, the schema this site serves at `/schema.json`:

```ts
import { PageSchema } from '@mdxui/site';

const schema = PageSchema.toJSONSchema();
```

A record may open with a `$schema` key naming that address; `PageSchema` strips unknown keys as it parses.

startupbuilder.dev defines the [Page](https://startupbuilder.dev/business/nouns/page); the record is how mdxui holds one. [Page](https://next.mdxui.dev/docs/components/page) maps each part, and [How mdxui fits a Business](https://next.mdxui.dev/docs/start/business) places it in a Business.


# Quickstart (/docs/start/quickstart)

> Render a worked Business's home page from one JSON record under two Themes, make it yours, and ship it.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/start/quickstart.md and https://next.mdxui.dev/llms.txt.
Download https://next.mdxui.dev/starter.zip and unzip it. Run pnpm install, then pnpm render.
Rewrite the strings of pages/home.json for my Business. Keep the Section types that fit.
Parse it with PageSchema.safeParse. When it refuses, shorten the content at the path it names, never the bound.
Render it under its own Theme and one more, and show me both HTML files.
```

Copy a five-line prompt: your agent downloads the starter, rewrites the record for your Business, fixes each refusal at its path and renders it under two Themes.

You start from Vanroster, a worked B2B SaaS on these docs, and leave with its home page as two HTML files. Or take the finished files:

[Download starter.zip](https://next.mdxui.dev/starter.zip): `pages/home.json`, `render.ts` and a `package.json`.

## Prerequisites

- Node.js 22.18 or later, which runs `render.ts` with no build step.
- An empty directory that is not inside another pnpm project. Mark it as an ES module first:

```bash
pnpm init && npm pkg set type=module
```

The starter download above already holds a `package.json` with `"type": "module"`; with it, run `pnpm install && pnpm render` and skip to step 3.

**File: install**

```bash
pnpm add @mdxui/site@7.0.0-alpha.0
```

**File: pages/home.json**

```json
{
  "$schema": "https://next.mdxui.dev/schema.json",
  "theme": "callboard",
  "frame": "none",
  "template": "api-product",
  "title": "Vanroster: every crew on the right job",
  "description": "Crew scheduling for field-service teams. Vanroster matches each job to a crew with the skills, the van and the shortest drive.",
  "sections": [
    {
      "kind": "nav",
      "shell": { "inset": "bleed", "density": "none", "surface": "glass", "sticky": true },
      "block": {
        "type": "nav",
        "menu": "push",
        "collapse": 880,
        "brand": { "href": "/", "text": "Vanroster", "mark": "radar" },
        "links": [
          ["/product/dispatch", "Dispatch"],
          ["/pricing", "Pricing"],
          ["/changelog", "Changelog"],
          ["/security", "Security"]
        ],
        "cta": { "href": "/contact", "label": "Book a walkthrough" }
      }
    },
    {
      "kind": "hero",
      "shell": { "inset": "contained", "density": "hero", "background": "glow" },
      "block": {
        "type": "hero",
        "layout": "split",
        "stack": 640,
        "title": "Every crew on the right job.",
        "lede": "Vanroster matches each job to a crew with the right skills, the right van and the shortest drive. Move a job on the board, and every crew phone follows.",
        "actions": [
          { "href": "/contact", "label": "Book a walkthrough", "kind": "solid" },
          { "href": "/pricing", "label": "See the plans", "kind": "ghost" }
        ],
        "fine": ["14-day trial, no payment details", "Office users free on every plan"],
        "specimen": {
          "panel": "field",
          "blocks": [
            {
              "type": "terminal",
              "variant": "plain",
              "title": "Board · Tue 13 Oct · 07:42",
              "lines": [
                "@dim{CREW  VAN   JOB                 WINDOW        DRIVE}",
                "A-1   V-12  Boiler service      08:00-10:00   14 min",
                "A-1   V-12  Heat pump install   10:30-13:00    9 min",
                "@dim{B-2   V-07  Out today: 2 jobs moved}",
                "C-3   V-03  Panel upgrade       08:00-11:00   22 min",
                "C-3   V-03  @acc{Boiler service}  ←B2 11:30-12:30    @pass{6 min}",
                "D-4   V-15  @acc{Gas leak check}  ←B2 13:00-14:00   @pass{11 min}",
                "D-4   V-15  Water heater swap   14:30-16:30   18 min",
                "",
                "@pass{2 customers texted a new window}"
              ]
            }
          ]
        }
      }
    },
    {
      "kind": "band",
      "shell": { "inset": "contained", "density": "compact" },
      "block": {
        "type": "stats",
        "items": [
          { "value": "400", "label": "Crews on one board, on every plan", "icon": "layout-grid" },
          { "value": "12", "label": "Skills a job can require, from gas to height", "icon": "badge-check" },
          { "value": "30 min", "label": "Arrival window texted to each customer", "icon": "clock" }
        ]
      }
    },
    {
      "kind": "section",
      "shell": { "inset": "contained", "density": "section" },
      "block": {
        "type": "feature-grid",
        "cellHead": "icon",
        "head": {
          "eyebrow": "The board",
          "title": "One board runs the whole day.",
          "lede": "Office staff plan on the board. Crews work from one ordered list on their phones."
        },
        "items": [
          {
            "icon": "map-pin",
            "title": "Drive time, not distance",
            "text": "Jobs are ordered by the drive between them, from road times at the hour of the job."
          },
          {
            "icon": "badge-check",
            "title": "Skills before speed",
            "text": "A gas job reaches only a crew with a gas licence on file and in date."
          },
          {
            "icon": "refresh-cw",
            "title": "Swaps in one drag",
            "text": "Drag a job to another crew. Both crew phones update before the drag ends."
          },
          {
            "icon": "bell",
            "title": "Customers told once",
            "text": "Each customer gets one text with a 30-minute window, and one when the van leaves."
          },
          {
            "icon": "clock",
            "title": "Overtime flagged",
            "text": "A day that keeps a crew past 10 hours turns amber before anyone assigns it."
          },
          {
            "icon": "shield-check",
            "title": "Every change logged",
            "text": "Who moved which job, when and why, kept for up to 7 years."
          }
        ]
      }
    },
    {
      "kind": "section",
      "shell": { "inset": "contained", "density": "section", "surface": "tint" },
      "block": {
        "type": "feature-split",
        "head": { "eyebrow": "A sick call at 07:40", "title": "Re-plan the day in one move." },
        "items": [
          { "icon": "x", "title": "Mark the crew out", "text": "One tap clears the crew and lists every job it held that day." },
          { "icon": "radar", "title": "Accept the re-plan", "text": "Each job goes to the nearest crew that holds every skill it needs." },
          { "icon": "message-square", "title": "Tell the customers", "text": "Each changed window goes out as one text, with the new time." }
        ],
        "specimen": {
          "blocks": [
            {
              "type": "terminal",
              "variant": "plain",
              "title": "Text to the customer · 07:43",
              "lines": [
                "Your boiler service today moved to 11:30-12:30.",
                "Crew C-3 is coming in van V-03.",
                "",
                "@dim{A second text arrives when the van leaves.}",
                "@dim{Reply 1 to keep the time, 2 to pick another day.}"
              ]
            }
          ]
        }
      }
    },
    {
      "kind": "section",
      "shell": { "inset": "contained", "density": "section" },
      "block": {
        "type": "compare",
        "head": { "eyebrow": "Against the whiteboard", "title": "A board that moves with the day." },
        "cons": {
          "label": "Whiteboard and calls",
          "items": ["Jobs assigned from memory", "Licences checked by phone", "Customers call to ask", "Swaps lost by noon"]
        },
        "pros": {
          "label": "Vanroster",
          "items": ["Jobs matched to skills", "Licences checked on assign", "Customers get a window", "Every swap on record"]
        }
      }
    },
    {
      "kind": "closing",
      "shell": { "inset": "contained", "density": "closing", "surface": "plate" },
      "block": {
        "type": "closing",
        "layout": "split",
        "head": {
          "eyebrow": "14-day trial",
          "title": "Plan tomorrow on Vanroster.",
          "lede": "Import crews and jobs from three spreadsheets. The first board is ready the same afternoon."
        },
        "specimen": {
          "blocks": [
            {
              "type": "terminal",
              "variant": "plain",
              "title": "Import · 3 files",
              "lines": [
                "crews.csv    14 crews, 14 vans, 2 depots",
                "skills.csv   38 licences, @acc{3 expire this year}",
                "jobs.csv     212 jobs over the next 10 days",
                "",
                "@pass{Board ready: 212 jobs on 14 crews}"
              ]
            }
          ]
        },
        "actions": [
          { "href": "/contact", "label": "Book a walkthrough", "kind": "solid" },
          { "href": "/product/dispatch", "label": "Tour Dispatch", "kind": "ghost" }
        ]
      }
    },
    {
      "kind": "footer",
      "shell": { "inset": "contained", "density": "footer" },
      "block": {
        "type": "footer",
        "layout": "areas",
        "brand": { "href": "/", "text": "Vanroster", "mark": "radar" },
        "blurb": "Crew scheduling for field-service teams: heating, electrical, plumbing, cleaning and grounds.",
        "columns": [
          {
            "title": "Product",
            "links": [
              ["/product/dispatch", "Dispatch"],
              ["/pricing", "Pricing"],
              ["/changelog", "Changelog"]
            ]
          },
          {
            "title": "Company",
            "links": [
              ["/security", "Security"],
              ["/contact", "Contact"]
            ]
          },
          {
            "title": "For agents",
            "links": [
              ["/product/dispatch", "The Dispatch API"],
              ["/records.zip", "Site records (.zip)"]
            ]
          }
        ],
        "cta": { "href": "/contact", "label": "Book a walkthrough", "icon": "arrow-right" },
        "note": ["Vanroster is a worked example on mdxui.dev, not a customer.", "Rendered by @mdxui/site. Forms here do not send."]
      }
    }
  ]
}
```

**File: render.ts**

```ts
// Renders each record in pages/ twice: under its own Theme, and under ALSO.
// A string over its bound stops the run and names the field.
import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
import { PageSchema, renderPage } from '@mdxui/site';

// certificate, vaultline, quaypoint, callboard or directory
const ALSO = 'vaultline';

const pages = [];
for (const file of (await readdir('pages')).filter((f) => f.endsWith('.json'))) {
  const json = JSON.parse(await readFile(`pages/${file}`, 'utf8'));
  const result = PageSchema.safeParse(json);
  if (!result.success) {
    for (const { path, message } of result.error.issues) {
      console.error(`pages/${file}: ${path.join('.')}: ${message}`);
    }
    process.exit(1);
  }
  pages.push({ name: file.replace(/\.json$/, ''), page: result.data });
}

await mkdir('out', { recursive: true });
for (const { name, page } of pages) {
  await writeFile(`out/${name}.html`, renderPage(page));
  await writeFile(`out/${name}.${ALSO}.html`, renderPage(page, { theme: ALSO }));
  console.log(`out/${name}.html  ${page.theme}`);
  console.log(`out/${name}.${ALSO}.html  ${ALSO}`);
}
```

**File: Result**
The record as this site renders it, under each Theme</span>}>
The result, as this site renders it: https://next.mdxui.dev/pages/vanroster/home.json

## Install

Install `@mdxui/site` at its exact version. It brings `@mdxui/themes` at the same version, so you name one package.

The bare `mdxui` package shows a higher version, `7.0.0-alpha.1` from May 2026, but it is an older, unrelated line. Install `@mdxui/site@7.0.0-alpha.0`; [Packages and versions](https://next.mdxui.dev/docs/start/packages) lists every name to avoid.

## Write the record

Copy Vanroster's home record into `pages/home.json`. It runs from the nav to the footer, and it parses as it stands.

## Render it under two Themes

Save `render.ts` and run `node render.ts`. `renderPage` returns one HTML document per record: once under the record's own `theme`, and once under the Theme in `ALSO`.

```text title="node render.ts"
out/home.html  callboard
out/home.vaultline.html  vaultline
```

The words are the same in both files. The color, typefaces, dividers and plan styling come from the Theme.

## Make it yours

Set `theme` to the Theme your Brand wears, and rewrite the hero `title` as your Business's promise: 64 characters fit, and the `lede` under it takes 260. Run `node render.ts` again and open `out/home.html`.

Long copy never breaks the layout. If the schema says no, the run names the field, such as `sections.1.block.title`, and writes nothing; shorten the content at that path. [Refusals](https://next.mdxui.dev/docs/reference/refusals#hero.title) lists every bound.

## Result

`out/home.html` is Vanroster's home page in your words. The Result tab renders the same record on this site: pick a Theme chip to see it in each of the five.

## Ship it

Your page is one HTML file that any static host serves. [Ship a Site](https://next.mdxui.dev/docs/start/ship) turns a folder of records into a whole Site with a 404, on Node, Vite, React Router or a Worker.

## Next steps

  - [Ship a Site](https://next.mdxui.dev/docs/start/ship): A folder of records as one live Site with a 404.
  - [Build a landing page](https://next.mdxui.dev/docs/start/guides/landing-page): Every section of the home page, nav to footer.
  - [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme): Your Brand's tokens and policies, under every record.
  - [Have your agent write a page](https://next.mdxui.dev/docs/agents/write-a-page): The same loop, with an agent writing the record.



# Ship a Site (/docs/start/ship)

> Turn a folder of records into one live Site with its 404 page and a contact flow, from a Node script, Vite, React Router or a Cloudflare Worker.

**Using an agent? Paste this prompt**

```text
Read https://next.mdxui.dev/docs/start/ship.md.
Run pnpm add @mdxui/site@7.0.0-alpha.0, then save ship.ts, site.ts and write-a-theme.ts as the page shows them.
Put every record of my Site in pages/, with home.json, 404.json and one Theme for every record.
Run node ship.ts. Fix each refusal at its path by shortening the content.
Deploy dist/ and confirm an unknown address answers 404 with my 404 page.
```

Copy a five-line prompt: your agent saves the files for the Node script target, builds your records into `dist/` and checks the 404.

Pick where the Site ships. For pages inside an existing React or Next.js app, see [Use it in a React app](https://next.mdxui.dev/docs/start/guides/react-app). Every target below runs in this site's checks, on published exports only, and each file pane shows the whole file, imports included.

**Spec: site().**

`site` builds a whole Site in one call: every record under one Theme, the 404, `sitemap.xml` and `robots.txt`. It is not in `@mdxui/site@7.0.0-alpha.0`; each target below does its work in one file.

## Prerequisites

- Node.js 22.18 or later, and `@mdxui/site` installed as in the [Quickstart](https://next.mdxui.dev/docs/start/quickstart).
- Records in `pages/`: `home.json`, a `404.json`, and one Theme across all of them. The 10 records of [Harbor tides](https://next.mdxui.dev/sites/harbor/records.zip) are a whole Site to start from; the zip unzips to `pages/`.
- Or take every file of the Node script target at once: [ship-starter.zip](https://next.mdxui.dev/ship-starter.zip) holds `package.json`, `ship.ts` and Harbor tides' `pages/`. Run `pnpm install && node ship.ts`.

**File: ship.ts**

```ts
import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
import { dirname } from 'node:path';
import { PageSchema, renderPage, type Page } from '@mdxui/site';

const origin = 'https://harbor-tides.example'; // the Site's origin, for sitemap.xml

// Every record in pages/: home.json is /, contact/sent.json is /contact/sent.
const pages: { path: string; page: Page }[] = [];
for (const file of (await readdir('pages', { recursive: true })).filter((f) => f.endsWith('.json'))) {
  const page = PageSchema.parse(JSON.parse(await readFile(`pages/${file}`, 'utf8')));
  pages.push({ path: file === 'home.json' ? '/' : `/${file.replace(/\.json$/, '')}`, page });
}
pages.sort((a, b) => a.path.localeCompare(b.path));
```

**File: records.ts**

```ts
import { readFile, readdir } from 'node:fs/promises';
import { join } from 'node:path';
import { PageSchema, type Page } from '@mdxui/site';

/** Every record under `dir`, parsed, with its address: home.json is /, contact/sent.json is /contact/sent. */
export async function readRecords(dir = 'pages'): Promise<{ path: string; page: Page }[]> {
  const out: { path: string; page: Page }[] = [];
  for (const file of (await readdir(dir, { recursive: true })).filter((f) => f.endsWith('.json')).sort()) {
    const result = PageSchema.safeParse(JSON.parse(await readFile(join(dir, file), 'utf8')));
    if (!result.success) {
      const [{ path, message }] = result.error.issues;
      throw new Error(`${dir}/${file}: ${path.join('.')}: ${message}`);
    }
    out.push({ path: file === 'home.json' ? '/' : `/${file.replace(/\.json$/, '')}`, page: result.data });
  }
  return out;
}

/** The file a static host serves for an address: / is index.html, /pricing is pricing.html. */
export const fileFor = (path: string) => (path === '/' ? 'index.html' : `${path.slice(1)}.html`);
```

**File: ship.ts · whole**

```ts
// A Site renders whole or not at all: a 404 page, and one Theme for every Page.
if (!pages.some((p) => p.path === '/404')) throw new Error('pages/404.json is missing: a Site has a 404 page');
const themes = new Set(pages.map((p) => p.page.theme));
if (themes.size > 1) throw new Error(`the records name ${themes.size} Themes, ${[...themes].join(' and ')}: a Site has one`);
```

**File: ship.ts · write**

```ts
const write = async (file: string, text: string) => {
  await mkdir(dirname(file), { recursive: true });
  await writeFile(file, text);
  console.log(file);
};
for (const { path, page } of pages) await write(`dist${path === '/' ? '/index' : path}.html`, renderPage(page));

// Every page a search engine may list: not the 404, and no record marked noindex.
const listed = pages.filter((p) => p.path !== '/404' && !p.page.meta?.noindex);
await write(
  'dist/sitemap.xml',
  `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${listed.map((p) => `  <url><loc>${origin}${p.path}</loc></url>`).join('\n')}\n</urlset>\n`,
);
await write('dist/robots.txt', `User-agent: *\nAllow: /\nSitemap: ${origin}/sitemap.xml\n`);
```

**File: vite-plugin.ts**

```ts
import { mkdir, writeFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { renderPage } from '@mdxui/site';
import type { Plugin, ResolvedConfig } from 'vite';
import { fileFor, readRecords } from './records.ts';

/**
 * Every record in pages/ as a page of a Vite project: rendered on each request
 * under `vite dev`, so an edit to a record shows on reload, and written into
 * the build's outDir by `vite build`.
 */
export function mdxuiPages({ dir = 'pages' } = {}): Plugin {
  let config: ResolvedConfig;
  return {
    name: 'mdxui-pages',
    configResolved(resolved) {
      config = resolved;
    },
    configureServer(server) {
      server.middlewares.use(async (req, res, next) => {
        const path = new URL(req.url ?? '/', 'http://dev').pathname.replace(/(.)\/$/, '$1');
        try {
          const hit = (await readRecords(join(config.root, dir))).find((r) => r.path === path);
          if (!hit) return next();
          res.setHeader('content-type', 'text/html; charset=utf-8');
          res.end(renderPage(hit.page));
        } catch (error) {
          next(error); // a refused record answers with its path and bound
        }
      });
    },
    async writeBundle(_options, bundle) {
      const out = resolve(config.root, config.build.outDir);
      for (const { path, page } of await readRecords(join(config.root, dir))) {
        const file = fileFor(path);
        if (file in bundle) throw new Error(`${file} is already in the build: give the record or the entry another address`);
        await mkdir(dirname(join(out, file)), { recursive: true });
        await writeFile(join(out, file), renderPage(page));
      }
    },
  };
}
```

**File: react-router.ts**

```ts
import { access, mkdir, writeFile } from 'node:fs/promises';
import { dirname, join } from 'node:path';
import { renderPage } from '@mdxui/site';
import { readRecords } from './records.ts';

/**
 * Run after `react-router build`: every record in pages/ becomes a file in the
 * prerendered client build, beside the routes React Router wrote. A record
 * never replaces a prerendered route; the landing record takes index.html,
 * the address React Router gives its SPA fallback when / is not prerendered.
 */
export async function renderInto(client = 'build/client', dir = 'pages'): Promise<string[]> {
  const written: string[] = [];
  for (const { path, page } of await readRecords(dir)) {
    const file = path === '/' ? 'index.html' : `${path.slice(1)}/index.html`;
    const taken = await access(join(client, file)).then(() => true, () => false);
    if (taken && path !== '/') throw new Error(`${file} is a prerendered route: give the record or the route another address`);
    await mkdir(dirname(join(client, file)), { recursive: true });
    await writeFile(join(client, file), renderPage(page));
    written.push(file);
  }
  return written;
}

if (process.argv[1] === import.meta.filename) console.log((await renderInto()).join('\n'));
```

**File: wrangler.jsonc**

```jsonc
{
  "name": "harbor-site",
  "compatibility_date": "2026-10-01",
  "main": "worker.ts",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page",
    "html_handling": "auto-trailing-slash",
    "run_worker_first": ["/contact/send"]
  },
  "vars": { "CONTACT": "https://forms.harbor-tides.example/inbox" }
}
```

**File: worker.ts**

```ts
// Runs only for POST /contact/send (wrangler.jsonc, assets.run_worker_first); every other path is a file in dist/.
export default {
  async fetch(request: Request, env: { CONTACT: string }): Promise<Response> {
    if (request.method !== 'POST') return new Response('Method Not Allowed', { status: 405, headers: { allow: 'POST' } });
    const form = await request.formData();
    // Forward the form, field for field, to the Site's contact address.
    const sent = await fetch(env.CONTACT, { method: 'POST', body: form });
    if (!sent.ok) return new Response('The message was not sent. Try again.', { status: 502 });
    return Response.redirect(new URL('/contact/sent', request.url), 303);
  },
};
```

**File: Result**

The result, as this site renders it: https://next.mdxui.dev/pages/harbor/404.json

## Read every record

Each file in `pages/` is parsed and given its address: `contact/sent.json` is `/contact/sent`. A record that does not parse stops the run at its path.

## Build whole or not at all

Before it writes a file, `ship.ts` stops on a missing 404 page or a second Theme. Without `pages/404.json`, then with one record under `directory`:

```text
Error: pages/404.json is missing: a Site has a 404 page
Error: the records name 2 Themes, quaypoint and directory: a Site has one
```

## Render every page

`node ship.ts` writes each page, then `sitemap.xml` and `robots.txt`. Run on the Harbor tides records:

```text
dist/index.html
dist/404.html
dist/blog.html
dist/blog/tide-windows.html
dist/contact.html
dist/contact/sent.html
dist/integrations.html
dist/integrations/chartplot.html
dist/pricing.html
dist/terms.html
dist/sitemap.xml
dist/robots.txt
```

10 pages, then `sitemap.xml`, which lists 8 of them:

```xml title="dist/sitemap.xml"
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url><loc>https://harbor-tides.example/</loc></url>
  <url><loc>https://harbor-tides.example/blog</loc></url>
  <url><loc>https://harbor-tides.example/blog/tide-windows</loc></url>
  <url><loc>https://harbor-tides.example/contact</loc></url>
  <url><loc>https://harbor-tides.example/integrations</loc></url>
  <url><loc>https://harbor-tides.example/integrations/chartplot</loc></url>
  <url><loc>https://harbor-tides.example/pricing</loc></url>
  <url><loc>https://harbor-tides.example/terms</loc></url>
</urlset>
```

Add `mdxuiPages()` to `plugins` in `vite.config.ts`. `vite dev` renders a record on each request, so an edit shows on reload, and `vite build` writes every page beside your entry. A record never takes the address of a file your entry builds.

Run `node react-router.ts` after `react-router build`. Every record joins the prerendered client build; a record never replaces a prerendered route. These docs ship their worked Sites this way.

To render under your own Theme, swap `renderPage` for `render` from [site.ts](https://next.mdxui.dev/docs/themes/write-a-theme).

## Serve it, 404 included

Upload the output to a static host whose not-found page is `404.html`. On Cloudflare, `wrangler.jsonc` sets `not_found_handling`, so any unknown address answers 404 with that page, and runs the Worker only for `/contact/send`. Deploy with `pnpm wrangler deploy`.

## Receive the contact form

[`cta-form`](https://next.mdxui.dev/docs/sections/cta-form) posts, and a static host answers only GET. `worker.ts` takes the post, forwards the fields to `CONTACT` and redirects to the sent page:

```text
POST /contact/send
  forwards POST https://forms.harbor-tides.example/inbox: name, email, topic, message
  answers 303 See Other, location: /contact/sent
```

The worked Sites on these docs are served as static files, so their forms do not send.

## Result

Every record is a page at its address, and any other address answers 404 with your 404 page. The Harbor tides records ship the same way, at [/sites/harbor/](https://next.mdxui.dev/sites/harbor/).

## Next steps

  - [Contact flow and 404](https://next.mdxui.dev/docs/start/guides/contact-and-404): The form, its sent page and every 404.
  - [Site](https://next.mdxui.dev/docs/components/site): Each part of a Site, and what builds it.
  - [Rebrand a Site](https://next.mdxui.dev/docs/start/guides/rebrand): One line moves every page to another Theme.



# callboard (/docs/themes/callboard)

> Violet, Bricolage Grotesque and DM Mono. Best for B2B SaaS with a loud brand.



**Best for.** B2B SaaS with a loud brand, events and venues. House paper, stage black, a violet wash light and poster lettering in Bricolage Grotesque.

## Swatches

From `resolveTokens(THEMES.callboard.theme)` in `@mdxui/themes@7.0.0-alpha.0`.

| Role | Light |
| --- | --- |
| `paper` | `#F6F5F8` |
| `panel` | `#FFFFFF` |
| `ink` | `#16121F` |
| `ink-soft` | `#332B42` |
| `rule` | `#DAD6E2` |
| `rule-soft` | `#E7E4ED` |
| `accent` | `#6D28D9` |
| `accent-ink` | `#FFFFFF` |
| `plate` | `#17121F` |
| `plate-ink` | `#F5F3F8` |
| `plate-rule` | `#342B44` |
| `pass` | `#15803D` |
| `warn` | `#B45309` |
| `fail` | `#B91C1C` |

## Typefaces

| Role | Typeface |
| --- | --- |
| Display | Bricolage Grotesque |
| Text | Instrument Sans |
| Mono | DM Mono |

The head lines load Bricolage Grotesque, Instrument Sans and DM Mono.

## Policies

Four policies change the markup a page renders. Each pair below holds the tokens still and changes the markup.

| Policy | Value |
| --- | --- |
| Dividers | `rule`, after article `none` |
| Markers | off |
| Featured plan | `plate` |
| Icons | `inline` |
| Scheme | `light`, light only |

### Dividers

### Markers

### Featured plan

### Icons

## Schemes

## Worn by

## Same page, other Themes

## Use it



# certificate (/docs/themes/certificate)

> Teal on cool paper, IBM Plex, hatched rules, light and dark. Best for developer tools and API products.



**Best for.** Developer tools and API products whose proof is a test or a measurement. Lab paper, one engineering superfamily, hatched dividers, and a dark palette that follows the reader.

## Swatches

From `resolveTokens(THEMES.certificate.theme)` in `@mdxui/themes@7.0.0-alpha.0`, with the dark palette the Theme emits.

| Role | Light | Dark |
| --- | --- | --- |
| `paper` | `oklch(0.930 0.004 175)` | `oklch(0.185 0.014 210)` |
| `panel` | `oklch(0.968 0.003 175)` | `oklch(0.225 0.016 212)` |
| `ink` | `oklch(0.205 0.021 210)` | `oklch(0.930 0.010 185)` |
| `ink-soft` | `oklch(0.445 0.018 200)` | `oklch(0.680 0.016 195)` |
| `rule` | `oklch(0.845 0.008 190)` | `oklch(0.320 0.016 212)` |
| `rule-soft` | `oklch(0.890 0.006 190)` | `oklch(0.270 0.014 212)` |
| `accent` | `oklch(0.470 0.110 185)` | `oklch(0.760 0.128 178)` |
| `accent-ink` | `oklch(0.992 0.006 180)` | `oklch(0.185 0.014 210)` |
| `plate` | `oklch(0.128 0.022 222)` | `oklch(0.128 0.022 222)` |
| `plate-ink` | `oklch(0.910 0.014 190)` | `oklch(0.910 0.014 190)` |
| `plate-rule` | `oklch(0.280 0.020 220)` | `oklch(0.280 0.020 220)` |
| `pass` | `oklch(0.500 0.135 158)` | `oklch(0.760 0.145 160)` |
| `warn` | `oklch(0.545 0.130 70)` | `oklch(0.790 0.140 70)` |
| `fail` | `oklch(0.545 0.195 27)` | `oklch(0.700 0.180 27)` |

## Typefaces

| Role | Typeface |
| --- | --- |
| Display | IBM Plex Sans |
| Text | IBM Plex Sans |
| Mono | IBM Plex Mono |

The head lines load IBM Plex Sans and IBM Plex Mono.

## Policies

Four policies change the markup a page renders. Each pair below holds the tokens still and changes the markup.

| Policy | Value |
| --- | --- |
| Dividers | `hatch`, after hero `hatch`, around band `rule`, closing `rule` |
| Markers | on |
| Featured plan | `rule` |
| Icons | `inline` |
| Scheme | `auto`, light and dark |

### Dividers

### Markers

### Featured plan

### Icons

## Schemes

## Worn by

## Same page, other Themes

## Use it



# The Theme contract (/docs/themes/contract)

> The 21 core roles every Theme sets, the derived roles that default through var(), the invariant roles, the plate remap, and what compileTheme refuses.

[startupbuilder.dev defines the Theme](https://startupbuilder.dev/business/nouns/theme): "A Theme is the design tokens of a Brand, its color, type, spacing, radius, and motion, that every Component reads when it renders." mdxui adds five [policies](https://next.mdxui.dev/docs/themes/policies) and compiles the tokens to CSS custom properties.

## Three kinds of role

A role names a use, not a look: `ink-lede` is the color a lede is set in, whatever that color is. Every Section type reads roles and never a literal color, typeface or size.

| Kind | A Theme | Example |
| --- | --- | --- |
| Core | Sets every one, in `light` or `invariant` | `paper`, `ink`, `accent` |
| Derived | May override any; each defaults to a core role through `var()` | `ink-lede` defaults to the secondary ink |
| Invariant | Declares once and never redefines for dark | certificate's `plate` family |

From `@mdxui/themes@7.0.0-alpha.0`: 21 core roles, which every Theme sets, and 325 derived roles, each with a default.

`paper`, `panel`, `ink`, `ink-soft`, `rule`, `rule-soft`, `accent`, `accent-ink`, `pass`, `fail`, `warn`, `plate`, `plate-ink`, `plate-rule`, `sans`, `mono`, `text`, `lh`, `shell-max`, `shell-inset`, `shell-d-section`

## Core roles

Each square is one role under one Theme, as `resolveTokens` returns it. Hover for the value; click to copy the custom property. Dark shows the palette a Theme emits, so the three light-only Themes keep their light values.

## Derived roles

A Theme that sets only the core roles renders: every derived role falls back through `var()` to a core role. A richer Theme overrides the families its design needs. The bars count how many roles of each family a Theme sets itself.

[`@mdxui/themes` exports](https://next.mdxui.dev/docs/reference/themes-exports#roles) lists every derived role with its default.

## Invariant roles

An invariant role is declared once and never redefined for dark. `compileTheme` refuses a Theme that names one in `dark`. certificate keeps its plate and its scrim invariant, so a code window is the same dark plate in both schemes.

## On a plate

A plate section re-tokens its subtree: a Section type on a plate reads `--ink` and gets the plate's ink. `PLATE_REMAP` names each pair, so one Section type renders on paper and on a plate with no second set of styles.

## The Theme object

```ts
interface Theme {
  name: string;
  light: Record<string, string>; // the full light palette, every core role included
  dark?: Record<string, string>; // only what changes for dark
  invariant?: Record<string, string>; // declared once, never redefined for dark
  dividers: DividerPolicy;
  markers: boolean;
  featured: 'rule' | 'plate';
  icons: 'inline' | 'image';
  scheme?: 'auto' | 'light';
}
```

## Compiling

`compileTheme(theme)` checks a Theme against the contract and returns its custom properties for `:root`. It refuses a Theme missing a core role and names every missing one. For a Theme that sets only `paper`:

```text
theme "fieldnote" is missing core roles: panel, ink, ink-soft, rule, rule-soft, accent, accent-ink, pass, fail, warn, plate, plate-ink, plate-rule, sans, mono, text, lh, shell-max, shell-inset, shell-d-section
```

`resolveTokens(theme)` returns the light palette with every `var()` chain followed to its value, for wherever a role is needed as a literal. The [playground](https://next.mdxui.dev/docs/themes/playground) runs both on every edit.

## Prior definitions

| Prior | Definition | Disposition |
| --- | --- | --- |
| startupbuilder.dev Theme | The design tokens of a Brand, its color, type, spacing, radius, and motion | Adopted word for word. The 5 policies are the mdxui addition. Its `css` property, extra CSS after the tokens, has no counterpart: no page carries its own CSS. |
| `@mdxui/themes` contract | Role and value pairs compiled to CSS custom properties | Kept as the rendering view of the same Noun |
| Legacy mdxui `theme` prop | `light`, `dark` or `system` on a Site wrapper | Superseded by the `scheme` policy and the dark palette |


# Dark mode (/docs/themes/dark-mode)

> Light is the full palette on :root. Dark redefines only the roles that change, under the reader's prefers-color-scheme.

## What each Theme emits

| Theme | Dark palette | `scheme` | Document `color-scheme` |
| --- | --- | --- | --- |
| `certificate` | yes | `auto` | `light dark` |
| `vaultline` | no | `auto` | `light` |
| `quaypoint` | yes | `light` | `light` |
| `callboard` | yes | `light` | `light` |
| `directory` | yes | `auto` | `light dark` |

- **certificate** and **directory** emit dark. The page follows the reader's scheme.
- **quaypoint** and **callboard** declare a dark palette and set `scheme: 'light'`. `compileTheme` checks the palette and emits none of it.
- **vaultline** declares no dark palette. Its page is light in every scheme.

## See it

Pick a Theme. Where it emits dark, the toggle swaps between its two real renders: the dark one is the build's twin with the Theme's own dark media query switched on. Where it does not, the page shows the declared palette as values and draws no dark render.

## The rules

- No color gets its only definition inside the dark media query. Every role has a light value first.
- An invariant role is declared once and never redefined for dark. `compileTheme` refuses one that appears in `dark`. The code window is dark in both schemes.
- `scheme: 'light'` keeps the dark palette declared and checked, and emits none of it. Changing that one word to `auto` turns dark mode on.
- The document's `color-scheme` is `light dark` when the Theme emits a dark palette, and `light` otherwise.

## Previews on these docs

Every preview on these docs follows the same rule. The scheme control is on only for certificate and directory, and it swaps to the dark twin; for the other three it stays off, with "Light only by this Theme's policy". No preview inverts a light render.


# directory (/docs/themes/directory)

> Monochrome Inter with no dividers, light and dark. Best for directories and listings.



**Best for.** Directories, listings and marketplaces, and the docs beside a landing. Monochrome, Inter for everything, no dividers, light and dark.

## Swatches

From `resolveTokens(THEMES.directory.theme)` in `@mdxui/themes@7.0.0-alpha.0`, with the dark palette the Theme emits.

| Role | Light | Dark |
| --- | --- | --- |
| `paper` | `#FFFFFF` | `#0A0A0A` |
| `panel` | `#FAFAFA` | `#111111` |
| `ink` | `#171717` | `#EDEDED` |
| `ink-soft` | `#404040` | `#D4D4D4` |
| `rule` | `#E5E5E5` | `#262626` |
| `rule-soft` | `#EBEBEB` | `#1F1F1F` |
| `accent` | `#171717` | `#EDEDED` |
| `accent-ink` | `#FFFFFF` | `#0A0A0A` |
| `plate` | `#0A0A0A` | `#FFFFFF` |
| `plate-ink` | `#EDEDED` | `#171717` |
| `plate-rule` | `#262626` | `#E5E5E5` |
| `pass` | `#15803D` | `#4ADE80` |
| `warn` | `#B45309` | `#FBBF24` |
| `fail` | `#B91C1C` | `#F87171` |

## Typefaces

| Role | Typeface |
| --- | --- |
| Display | Inter |
| Text | Inter |
| Mono | JetBrains Mono |

The head lines load Inter and JetBrains Mono.

## Policies

Four policies change the markup a page renders. Each pair below holds the tokens still and changes the markup.

| Policy | Value |
| --- | --- |
| Dividers | `none` |
| Markers | off |
| Featured plan | `rule` |
| Icons | `inline` |
| Scheme | `auto`, light and dark |

### Dividers

### Markers

### Featured plan

### Icons

## Schemes

## Worn by

## Same page, other Themes

## Use it



# Theming the docs (/docs/themes/docs)

> Dress a Fumadocs site in a Business's Theme: each Fumadocs color reads one resolved role, light and dark. These docs wear certificate this way.

These docs and the landing share one paper, one ink and one accent: certificate's, read through `resolveTokens`. No color in the chrome is typed by hand.

## Prerequisites

- A Fumadocs site, such as one from `create-fumadocs-app`.
- `@mdxui/themes` at the pinned version, as on [Packages and versions](https://next.mdxui.dev/docs/start/packages).

## Steps

1. Map each Fumadocs color to one role. Saved as `docs-theme.ts`:

   ```ts
   // Each Fumadocs color, read from one Theme role. A value in brackets is mixed from two roles.
   const MAP: Record<string, string> = {
     background: '[panel 55% paper]',
     foreground: 'ink',
     card: '[accent-ink 55% panel]',
     'card-foreground': 'ink',
     popover: '[accent-ink 55% panel]',
     'popover-foreground': 'ink',
     muted: 'panel',
     'muted-foreground': 'ink-soft',
     secondary: 'panel',
     'secondary-foreground': 'ink',
     accent: '[accent 8% panel]',
     'accent-foreground': 'ink',
     border: 'rule',
     primary: 'accent',
     'primary-foreground': 'accent-ink',
     ring: 'accent',
   };
   // In dark, the paper is the darkest ground, so a raised panel is the panel role itself.
   const DARK: Record<string, string> = { card: 'panel', popover: 'panel' };
   // The roles the docs' own components paint with: rules, the hatch, the plates code sits on, the status colors and the code roles.
   const EXTRA = ['rule-soft', 'hatch', 'plate', 'plate-ink', 'plate-ink-soft', 'plate-rule', 'plate-accent', 'pass', 'warn', 'fail', 'code-ink', 'code-comment', 'code-string', 'code-keyword'];
   ```

2. Resolve the roles to literals and write the stylesheet. A Theme under `scheme: 'light'` writes no `.dark` block:

   ```ts
   const { theme } = THEMES.certificate;
   const light = resolveTokens(theme);
   // The dark palette redefines only what changes; resolving it again lets every derived role follow.
   const dark = theme.dark && theme.scheme !== 'light' ? resolveTokens({ ...theme, light: { ...theme.light, ...theme.dark } }) : undefined;

   const value = (roles: Record<string, string>, role: string) => {
     const mix = role.match(/^\[(\S+) (\d+)% (\S+)\]$/);
     return mix ? `color-mix(in oklab, ${roles[mix[1]]} ${mix[2]}%, ${roles[mix[3]]})` : roles[role];
   };
   const block = (selector: string, roles: Record<string, string>, over: Record<string, string> = {}) =>
     `${selector} {\n${[
       ...Object.entries({ ...MAP, ...over }).map(([fd, role]) => `  --color-fd-${fd}: ${value(roles, role)};`),
       ...EXTRA.map((role) => `  --mx-${role}: ${roles[role]};`),
     ].join('\n')}\n}`;

   const radii = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', '4xl'].map((r) => `  --radius-${r}: ${light['radius-control']};`).join('\n');
   const css = [
     block(':root', light),
     dark ? block('.dark', dark, DARK) : '',
     `:root {\n  --font-sans: ${light.sans};\n  --font-mono: ${light.mono};\n${radii}\n}`,
   ]
     .filter(Boolean)
     .join('\n\n');
   await writeFile('docs-theme.css', `${css}\n`);
   ```

3. Run it, and import `docs-theme.css` after the Fumadocs preset in the site's global CSS. This site imports the same file after the preset:

   ```css
   @import 'fumadocs-ui/css/preset.css';
   @import './docs-theme.css';
   ```

4. Serve every page as Markdown. Fumadocs' `llms()` renders a page as Markdown, and `MarkdownCopyButton` puts the copy control under each title. This site serves each page at its address plus `.md`.

## Result

For `certificate`, the Theme this site's landing and docs wear. The generator writes the same file into this site's styles, and the check fails if the two drift:

```css title="docs-theme.css, 32 variables"
:root {
  --color-fd-background: color-mix(in oklab, oklch(0.968 0.003 175) 55%, oklch(0.930 0.004 175));
  --color-fd-foreground: oklch(0.205 0.021 210);
  --color-fd-card: color-mix(in oklab, oklch(0.992 0.006 180) 55%, oklch(0.968 0.003 175));
  --color-fd-card-foreground: oklch(0.205 0.021 210);
  --color-fd-popover: color-mix(in oklab, oklch(0.992 0.006 180) 55%, oklch(0.968 0.003 175));
  --color-fd-popover-foreground: oklch(0.205 0.021 210);
  --color-fd-muted: oklch(0.968 0.003 175);
  --color-fd-muted-foreground: oklch(0.445 0.018 200);
  --color-fd-secondary: oklch(0.968 0.003 175);
  --color-fd-secondary-foreground: oklch(0.205 0.021 210);
  --color-fd-accent: color-mix(in oklab, oklch(0.470 0.110 185) 8%, oklch(0.968 0.003 175));
  --color-fd-accent-foreground: oklch(0.205 0.021 210);
  --color-fd-border: oklch(0.845 0.008 190);
  --color-fd-primary: oklch(0.470 0.110 185);
  --color-fd-primary-foreground: oklch(0.992 0.006 180);
  --color-fd-ring: oklch(0.470 0.110 185);
  --mx-rule-soft: oklch(0.890 0.006 190);
  --mx-hatch: oklch(0.205 0.021 210 / 0.16);
  --mx-plate: oklch(0.128 0.022 222);
  --mx-plate-ink: oklch(0.910 0.014 190);
  --mx-plate-ink-soft: oklch(0.680 0.016 195);
  --mx-plate-rule: oklch(0.280 0.020 220);
  --mx-plate-accent: oklch(0.800 0.130 175);
  --mx-pass: oklch(0.500 0.135 158);
  --mx-warn: oklch(0.545 0.130 70);
  --mx-fail: oklch(0.545 0.195 27);
  --mx-code-ink: oklch(0.910 0.014 190);
  --mx-code-comment: oklch(0.680 0.016 195);
  --mx-code-string: oklch(0.800 0.130 175);
  --mx-code-keyword: oklch(0.800 0.130 175);
}

.dark {
  --color-fd-background: color-mix(in oklab, oklch(0.225 0.016 212) 55%, oklch(0.185 0.014 210));
  --color-fd-foreground: oklch(0.930 0.010 185);
  --color-fd-card: oklch(0.225 0.016 212);
  --color-fd-card-foreground: oklch(0.930 0.010 185);
  --color-fd-popover: oklch(0.225 0.016 212);
  --color-fd-popover-foreground: oklch(0.930 0.010 185);
  --color-fd-muted: oklch(0.225 0.016 212);
  --color-fd-muted-foreground: oklch(0.680 0.016 195);
  --color-fd-secondary: oklch(0.225 0.016 212);
  --color-fd-secondary-foreground: oklch(0.930 0.010 185);
  --color-fd-accent: color-mix(in oklab, oklch(0.760 0.128 178) 8%, oklch(0.225 0.016 212));
  --color-fd-accent-foreground: oklch(0.930 0.010 185);
  --color-fd-border: oklch(0.320 0.016 212);
  --color-fd-primary: oklch(0.760 0.128 178);
  --color-fd-primary-foreground: oklch(0.185 0.014 210);
  --color-fd-ring: oklch(0.760 0.128 178);
  --mx-rule-soft: oklch(0.270 0.014 212);
  --mx-hatch: oklch(0.930 0.010 185 / 0.13);
  --mx-plate: oklch(0.128 0.022 222);
  --mx-plate-ink: oklch(0.910 0.014 190);
  --mx-plate-ink-soft: oklch(0.680 0.016 195);
  --mx-plate-rule: oklch(0.280 0.020 220);
  --mx-plate-accent: oklch(0.800 0.130 175);
  --mx-pass: oklch(0.760 0.145 160);
  --mx-warn: oklch(0.790 0.140 70);
  --mx-fail: oklch(0.700 0.180 27);
  --mx-code-ink: oklch(0.910 0.014 190);
  --mx-code-comment: oklch(0.680 0.016 195);
  --mx-code-string: oklch(0.800 0.130 175);
  --mx-code-keyword: oklch(0.800 0.130 175);
}

:root {
  --font-sans: 'IBM Plex Sans', system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
  --font-mono: 'IBM Plex Mono', ui-monospace, 'SF Mono', 'Cascadia Mono', Menlo, Consolas, monospace;
  --radius-xs: 0;
  --radius-sm: 0;
  --radius-md: 0;
  --radius-lg: 0;
  --radius-xl: 0;
  --radius-2xl: 0;
  --radius-3xl: 0;
  --radius-4xl: 0;
}
```

## Try it on these docs

The generator also writes one scope per other bundled Theme, `[data-docs-theme="<name>"]`, from the same roles. Wear one here, and the chrome redraws in its paper, ink, accent and typefaces:

## Next steps

- [The Theme contract](https://next.mdxui.dev/docs/themes/contract): every role the map can read.
- [Renderings](https://next.mdxui.dev/docs/components/renderings): the Markdown of a Page record.


# Theme gallery (/docs/themes)

> Five Themes ship in @mdxui/themes. Each Tile is the same Business in that Theme: pick one, or set two side by side.

> A Theme is the design tokens of a Brand, its color, type, spacing, radius, and motion, that every Component reads when it renders.
>
> startupbuilder.dev, [Theme](https://startupbuilder.dev/business/nouns/theme)

In mdxui a Theme is a Brand's tokens plus its render policies. A record names one in `"theme"`, and every page of the Site redraws in it.

## Compare two

The same record under two Themes, one over the other. Drag the divider across the page.

## At a glance

## How a Theme works

  - [The Theme contract](https://next.mdxui.dev/docs/themes/contract): The 21 core roles, the derived and invariant roles, and the plate remap.
  - [Render policies](https://next.mdxui.dev/docs/themes/policies): Dividers, markers, featured and icons, each as two renders.
  - [Typefaces](https://next.mdxui.dev/docs/themes/typefaces): Each Theme's display, text and mono typefaces, and the lines that load them.
  - [Dark mode](https://next.mdxui.dev/docs/themes/dark-mode): Which Themes emit dark, and which only declare it.

## Make one

  - [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme): Start from a bundled Theme and render any record under yours.
  - [Theme your docs](https://next.mdxui.dev/docs/themes/docs): Dress a Fumadocs site in the same roles, as these docs do.
  - [Theme playground](https://next.mdxui.dev/docs/themes/playground): Edit tokens over a live render and copy the Theme object.



# Theme playground (/docs/themes/playground)

> Spec: written ahead of the package. Not in the published packages: renderWithTheme

> Edit paper, ink, accent, rule and plate over a real render with the published compileTheme, then copy the Theme object.

**What is written ahead.**

Every edit runs the published `compileTheme` in your browser. The frame is a page rendered at build under the Theme you start from, and the edit replaces its token stylesheet. Rendering a whole page under a Theme of your own in one call, `renderWithTheme`, is the unpublished part.

## How it runs

- The first edit loads `@mdxui/themes`, at most 17 KB gzipped, and runs `compileTheme` on your draft.
- The output replaces the frame's `<style data-theme>`, which the build wraps around the render's own `compileTheme` string. Nothing else in the frame changes.
- A field `compileTheme` refuses shows its message in place. Clear a color to see the refusal for a missing core role.
- Dividers, markers, featured and icons change markup, so they come from the Theme you start from. [Policies](https://next.mdxui.dev/docs/themes/policies) shows each as two renders.
- The contrast readouts are WCAG 2 ratios of the draft's resolved roles.

## Next steps

- Paste the Theme object into `write-a-theme.ts` and [render a record under it](https://next.mdxui.dev/docs/themes/write-a-theme).
- Read [the Theme contract](https://next.mdxui.dev/docs/themes/contract) for every role the draft can set.


# Policies (/docs/themes/policies)

> The four choices a design makes once, stated as data beside its tokens: dividers, markers, the featured plan and icon delivery, each shown as two renders.

## The 4 policies

| Policy | Values | What it decides |
| --- | --- | --- |
| `dividers` | a divider policy | What falls between two sections: `none`, `rule`, `rule-contained` or `hatch` |
| `markers` | `true`, `false` | Whether a small accent square sits before each eyebrow and fine-print item |
| `featured` | `rule`, `plate` | How the featured plan in `pricing` stands apart: an inset rule and a stamp, or a plate with a chip |
| `icons` | `inline`, `image` | Whether an icon is inline SVG in the text's color, or an image with its color resolved from the Theme |

Each changes the markup a page renders, so it takes effect when the page renders.

## Beside them: the scheme

`scheme` is a property of the Theme's tokens, not a policy: `auto` follows the reader's color scheme, and `light` renders the light palette in every scheme. It changes only the stylesheet, never the markup.

## Reading a pair

Each pair below wears one Theme's tokens. The left frame is a section rendered under that Theme. The right frame is the same section rendered under the bundled Theme whose policies differ most narrowly, with the left Theme's `compileTheme` output in place of its own. Pick the Theme whose tokens both frames wear; the caption names any other policy the two differ in.

## Dividers

A section never declares its own dividers. The composer chooses each one from the pair of sections it sits between, under the Theme's divider policy:

| Field | Chooses by |
| --- | --- |
| `default` | Any pair no other field matches |
| `after` | The earlier section's kind; it wins over every other field |
| `afterSurface` | The earlier section's shell `surface` |
| `around` | Either neighbor's kind |
| `withinPlate` | Two plate sections in a row |

The `quaypoint` policy rules every pair, sets nothing after an article or a plate section, and draws a contained rule between two plates:

```json
{ "default": "rule", "after": { "article": "none" }, "afterSurface": { "plate": "none" }, "withinPlate": "rule-contained" }
```

## Markers

certificate is the one bundled Theme with markers on: an accent square before each eyebrow and fine-print item.

## Featured plan

`plate` sets the featured plan on the plate with a chip; `rule` keeps it on paper with an inset accent rule and a stamp.

## Icon delivery

A Theme chooses one delivery for every icon. Under `image`, the render context resolves each icon's role to the Theme's literal value on the background it sits on. The two deliveries rasterize a few pixels apart.

## Scheme

`scheme` has no dark-only value. A design that is dark in every scheme puts its dark palette in `light` and declares no `dark`. See [Dark mode](https://next.mdxui.dev/docs/themes/dark-mode).


# quaypoint (/docs/themes/quaypoint)

> Navy and signal orange, set in Space Grotesk. Best for API products and infrastructure.



**Best for.** API and data products, and anything sold as readings. Chart paper, harbor navy and a signal-orange accent, with Space Grotesk as instrument lettering.

## Swatches

From `resolveTokens(THEMES.quaypoint.theme)` in `@mdxui/themes@7.0.0-alpha.0`.

| Role | Light |
| --- | --- |
| `paper` | `#F4F6F8` |
| `panel` | `#FFFFFF` |
| `ink` | `#0F1B2A` |
| `ink-soft` | `#2C3B4D` |
| `rule` | `#D3DBE2` |
| `rule-soft` | `#E3E9EE` |
| `accent` | `#C2410C` |
| `accent-ink` | `#FFFFFF` |
| `plate` | `#0B1F33` |
| `plate-ink` | `#F1F5F9` |
| `plate-rule` | `#24384D` |
| `pass` | `#0F766E` |
| `warn` | `#B45309` |
| `fail` | `#B91C1C` |

## Typefaces

| Role | Typeface |
| --- | --- |
| Display | Space Grotesk |
| Text | Inter |
| Mono | JetBrains Mono |

The head lines load Space Grotesk, Inter and JetBrains Mono.

## Policies

Four policies change the markup a page renders. Each pair below holds the tokens still and changes the markup.

| Policy | Value |
| --- | --- |
| Dividers | `rule`, after article `none` |
| Markers | off |
| Featured plan | `plate` |
| Icons | `inline` |
| Scheme | `light`, light only |

### Dividers

### Markers

### Featured plan

### Icons

## Schemes

## Worn by

## Same page, other Themes

## Use it



# Typefaces (/docs/themes/typefaces)

> Each Theme sets its display, text and mono typefaces in three roles, and its head lines load them from Google Fonts with display=swap.

## Three roles

A Theme names its typefaces in three roles, and every Section type reads the role, never a family:

| Role | Sets | Falls back to |
| --- | --- | --- |
| `display` | Headlines, the hero title, plan prices | `sans`, when a Theme names no display typeface |
| `sans` | Body text, controls, navigation | the system stack in the role's value |
| `mono` | Code, commands, eyebrows, fine print | the system monospace stack |

`sans` and `mono` are core roles; `display` is derived. certificate and directory name no display typeface, so their headlines set in their `sans`.

## Every Theme

Each specimen sets its lines in the Theme's own typefaces, loaded by the Theme's own head lines. Under each sit the lines themselves, as `THEMES.<name>.head` holds them.

## Shared typefaces

Seven of the ten families serve one Theme each. IBM Plex Mono, Inter and JetBrains Mono serve two.

## How a render loads them

`renderPage` writes the Theme's `head` lines into the page's `<head>`: the browser color, then a preconnect to both Google Fonts hosts, then one stylesheet for every family. Each stylesheet asks for `display=swap`, so the system stack paints first and nothing waits on a font.

A Theme of your own carries its own `head`, as [Write a Theme](https://next.mdxui.dev/docs/themes/write-a-theme) shows. To serve the files from your own host, replace the stylesheet line with `@font-face` rules; the roles do not change.


# vaultline (/docs/themes/vaultline)

> An editorial serif on warm paper, with plated offers. Best for firms and publications.



**Best for.** Firms and publications that sell trust through reading: a practice, a weekly letter, a report. An editorial serif on warm paper, with plated offers, light in every scheme.

## Swatches

From `resolveTokens(THEMES.vaultline.theme)` in `@mdxui/themes@7.0.0-alpha.0`.

| Role | Light |
| --- | --- |
| `paper` | `#F2F0E9` |
| `panel` | `#FBFAF6` |
| `ink` | `#16150F` |
| `ink-soft` | `#3B382F` |
| `rule` | `#DAD6C9` |
| `rule-soft` | `#E6E2D8` |
| `accent` | `#1E4D36` |
| `accent-ink` | `#F2F0E9` |
| `plate` | `#16150F` |
| `plate-ink` | `#F2F0E9` |
| `plate-rule` | `#34322A` |
| `pass` | `#2F7A54` |
| `warn` | `#E0B44A` |
| `fail` | `#E0876F` |

## Typefaces

| Role | Typeface |
| --- | --- |
| Display | Newsreader |
| Text | Public Sans |
| Mono | IBM Plex Mono |

The head lines load Newsreader, Public Sans and IBM Plex Mono.

## Policies

Four policies change the markup a page renders. Each pair below holds the tokens still and changes the markup.

| Policy | Value |
| --- | --- |
| Dividers | `rule`, after article `none` |
| Markers | off |
| Featured plan | `plate` |
| Icons | `image` |
| Scheme | `auto`, light only |

### Dividers

### Markers

### Featured plan

### Icons

## Schemes

## Worn by

## Same page, other Themes

## Use it



# Write a Theme (/docs/themes/write-a-theme)

> Write a Theme for one Business from a bundled Theme, its core roles, two typefaces and the policies, then render any record under it.

Steps 1 to 7 are the parts of `write-a-theme.ts`, in order, imports first; step 8 adds `site.ts` beside it. Both whole files are under [The whole files](#the-whole-files), and [theme-starter.zip](https://next.mdxui.dev/theme-starter.zip) holds them with a `package.json`: run `pnpm install && node write-a-theme.ts`.

**The limit.**

`renderPage` takes a Theme by name, and only the 5 bundled names. A Theme of your own renders through `compileTheme`, `renderBlock`, `compose` and `document`, the exports `site.ts` calls. Under a bundled Theme, that path returns what `renderPage` returns, byte for byte.

## Prerequisites

- The [quickstart](https://next.mdxui.dev/docs/start/quickstart) runs in your project.
- `@mdxui/themes` at the pinned version:

  ```bash
  pnpm add @mdxui/themes@7.0.0-alpha.0
  ```

- The Brand's colors, a text typeface and a mono typeface.

## Steps

1. In `write-a-theme.ts`, import what the file uses and start from the bundled Theme closest to the Brand:

   ```ts
   import { writeFile } from 'node:fs/promises';
   import { PageSchema } from '@mdxui/site';
   import { THEMES, compileTheme, type Theme } from '@mdxui/themes';
   import { render, type ThemeEntry } from './site.ts';

   const base = THEMES.quaypoint.theme;
   ```

2. Set the core roles the Brand changes. Check each text role against the background it sits on: body text needs a contrast ratio of at least 4.5:1.

   ```ts
   const light: Record<string, string> = { ...base.light, accent: '#0b7285', 'accent-ink': '#ffffff' };
   ```

3. Set the typefaces in the `sans`, `display` and `mono` roles. `display` sets every heading: leave it out and the headings keep the base Theme's display typeface, which your `<head>` does not load.

   ```ts
   // Display sets the headings: name it, or it keeps the base Theme's display typeface, which head does not load.
   light.sans = "'Atkinson Hyperlegible Next', system-ui, sans-serif";
   light.display = "'Atkinson Hyperlegible Next', system-ui, sans-serif";
   light.mono = "'Martian Mono', ui-monospace, monospace";
   ```

4. Choose the [policies](https://next.mdxui.dev/docs/themes/policies):

   ```ts
   const policies = { dividers: { default: 'rule' }, markers: false, featured: 'rule', icons: 'inline' } satisfies Partial<Theme>;
   ```

5. Redefine for [dark](https://next.mdxui.dev/docs/themes/dark-mode) only the roles that change:

   ```ts
   const dark = { ...base.dark, accent: '#66d9e8', 'accent-ink': '#0b1f24' };
   ```

6. Compile it. `compileTheme` throws on a missing core role and names each one:

   ```ts
   const theme: Theme = { ...base, ...policies, name: 'fieldnote', light, dark, scheme: 'auto' };
   const tokens = compileTheme(theme); // throws on a missing core role, naming each one
   ```

7. Write the `<head>` tags that load the typefaces and set the browser color, check that they load every typeface the roles name, then export the Theme in the shape `THEMES` holds each bundled one:

   ```ts
   const head = [
     '<meta name="theme-color" content="#f6f7f4">',
     '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible+Next:wght@400;600;700&family=Martian+Mono&display=swap">',
   ].join('\n');

   // Every typeface the Theme names is one its head loads; a missing one falls back to the system's.
   for (const role of ['sans', 'display', 'mono']) {
     const family = light[role].split(',')[0].trim().replace(/^'|'$/g, '');
     if (!head.includes(`family=${family.replaceAll(' ', '+')}`)) throw new Error(`fieldnote: --${role} names ${family}, which head does not load`);
   }

   // The shape THEMES holds each bundled Theme in: the Theme, its CSS and its <head> tags.
   export const fieldnote: ThemeEntry = { theme, css: () => tokens, head };
   ```

8. Render a record under `fieldnote`. Save this as `site.ts`: `render` runs `renderBlock`, `compose` and `document` with your Theme in place of a bundled one, and writes the `<head>` tags a record's `meta` adds.

   ```ts
   import { baseCss, blocksCss, compose, context, document, esc, primitivesCss, renderBlock, renderPage, shellCss, type Page } from '@mdxui/site';
   import { THEMES, type Theme } from '@mdxui/themes';

   /** A Theme in the shape `THEMES` holds each bundled one: the Theme, its CSS, and the <head> tags that load its typefaces. */
   export interface ThemeEntry {
     theme: Theme;
     css: () => string;
     head: string;
   }

   /** One Page under any Theme: the record's own bundled Theme by default, or yours. */
   export function render(page: Page, entry: ThemeEntry = THEMES[page.theme]): string {
     const { theme, css, head } = entry;
     const sections = page.sections.map((s) => ({
       kind: s.kind,
       shell: s.shell,
       html: renderBlock(s.block, context(theme, s.shell.surface ?? 'paper', theme.icons)),
     }));
     return document({
       title: page.title,
       description: page.description,
       colorScheme: theme.dark && theme.scheme !== 'light' ? 'light dark' : 'light',
       jsonLd: page.jsonLd ?? [],
       head: [head, ...metaTags(page)].join('\n'),
       css: `${css()}${baseCss}${primitivesCss}${shellCss}${blocksCss}`,
       body: compose({ frame: page.frame, sections, dividers: theme.dividers }),
     });
   }

   /** The <head> tags a record's `meta` adds, in the order `renderPage` writes them. */
   function metaTags({ meta = {} }: Page): string[] {
     const tags: string[] = [];
     if (meta.canonical) tags.push(`<link rel="canonical" href="${esc(meta.canonical)}">`);
     if (meta.noindex) tags.push('<meta name="robots" content="noindex">');
     if (meta.type) tags.push(`<meta property="og:type" content="${meta.type}">`);
     if (meta.icon) tags.push(`<link rel="icon" href="${esc(meta.icon)}" type="image/svg+xml">`);
     if (meta.iconFallback) tags.push(`<link rel="alternate icon" href="${esc(meta.iconFallback)}" sizes="32x32">`);
     if (meta.appleTouchIcon) tags.push(`<link rel="apple-touch-icon" href="${esc(meta.appleTouchIcon)}">`);
     if (meta.image) {
       const { url, width, height } = meta.image;
       tags.push(
         `<meta property="og:image" content="${esc(url)}">`,
         `<meta property="og:image:width" content="${width}">`,
         `<meta property="og:image:height" content="${height}">`,
         '<meta name="twitter:card" content="summary_large_image">',
         `<meta name="twitter:image" content="${esc(url)}">`,
       );
     }
     return tags;
   }

   // Under the record's own Theme, `render` returns what `renderPage` returns, byte for byte.
   export function sameAsRenderPage(page: Page): boolean {
     return render(page) === renderPage(page);
   }
   ```

   The record still names `quaypoint`, because `theme` takes only the 5 bundled names: a record names the Theme yours starts from, and `render` draws it under yours.

   ```ts
   // The record names `quaypoint`, the bundled Theme yours starts from: `theme` takes only the 5 bundled names.
   const brand = { href: '/', text: 'Fieldnote', mark: 'file-text' as const };
   const page = PageSchema.parse({
     theme: 'quaypoint',
     title: 'Fieldnote: notes from every site visit',
     description: 'Site-visit notes for building inspectors, filed from a phone.',
     frame: 'none',
     sections: [
       { kind: 'nav', shell: { inset: 'contained', density: 'none' }, block: { type: 'nav', menu: 'none', brand, links: [['#on-site', 'On site'], ['#sign-off', 'Sign-off']] } },
       { kind: 'hero', shell: { inset: 'contained', density: 'hero' }, block: { type: 'hero', layout: 'centered', stack: 560, title: 'Notes from every site visit.', lede: 'Inspectors file each visit from a phone: photos named by room, defects by code, and a report the owner signs the same day.', actions: [{ href: '#on-site', label: 'See it on site', kind: 'solid' }, { href: '#sign-off', label: 'How sign-off works', kind: 'ghost' }], fine: ['Works offline on site'] } },
       { kind: 'band', shell: { inset: 'contained', density: 'compact' }, block: { type: 'stats', items: [{ value: '1', label: 'Report per visit' }, { value: '12', label: 'Defect codes built in' }, { value: '0', label: 'Forms to retype' }] } },
       { kind: 'section', shell: { id: 'on-site', inset: 'contained', density: 'section' }, block: { type: 'feature-grid', cellHead: 'icon', head: { eyebrow: 'On site', title: 'File it before you leave the driveway.' }, items: [{ icon: 'layout-grid', title: 'Rooms', text: 'Each photo lands under the room it was taken in.' }, { icon: 'list', title: 'Codes', text: 'Each defect carries its code and its fix.' }, { icon: 'badge-check', title: 'Sign-off', text: 'The owner signs the report on the inspector’s phone.' }] } },
       { kind: 'band', shell: { id: 'sign-off', inset: 'contained', density: 'section' }, block: { type: 'statement', text: 'A report is a *promise*.' } },
       { kind: 'section', shell: { inset: 'contained', density: 'section' }, block: { type: 'command-row', command: 'npm i @example/fieldnote', note: 'An illustrative package name' } },
       { kind: 'footer', shell: { inset: 'contained', density: 'footer' }, block: { type: 'footer', layout: 'row', brand, columns: [{ title: 'Fieldnote', links: [['#on-site', 'On site'], ['#sign-off', 'Sign-off']] }], note: ['Fieldnote is an example on mdxui.dev, not a product.', 'Rendered under the fieldnote Theme.'] } },
     ],
   });
   await writeFile('fieldnote-theme.html', render(page, fieldnote));
   ```

9. Ship it. [Ship a Site](https://next.mdxui.dev/docs/start/ship) passes `fieldnote` to `render`, so every record in `pages/` renders under your Theme.

## Result

`fieldnote-theme.html`: a seven-section page, nav to footer, under `fieldnote`. Every Section type reads the new roles, the headings set in the Theme's own display typeface, and the page carries no CSS of its own.

Under each record's own Theme, `render` returns what `renderPage` returns, byte for byte, on 54 of 54 living records.

## The whole files

```ts
// #region start
import { writeFile } from 'node:fs/promises';
import { PageSchema } from '@mdxui/site';
import { THEMES, compileTheme, type Theme } from '@mdxui/themes';
import { render, type ThemeEntry } from './site.ts';

const base = THEMES.quaypoint.theme;
// #endregion

// #region roles
const light: Record<string, string> = { ...base.light, accent: '#0b7285', 'accent-ink': '#ffffff' };
// #endregion

// #region typefaces
// Display sets the headings: name it, or it keeps the base Theme's display typeface, which head does not load.
light.sans = "'Atkinson Hyperlegible Next', system-ui, sans-serif";
light.display = "'Atkinson Hyperlegible Next', system-ui, sans-serif";
light.mono = "'Martian Mono', ui-monospace, monospace";
// #endregion

// #region policies
const policies = { dividers: { default: 'rule' }, markers: false, featured: 'rule', icons: 'inline' } satisfies Partial<Theme>;
// #endregion

// #region dark
const dark = { ...base.dark, accent: '#66d9e8', 'accent-ink': '#0b1f24' };
// #endregion

// #region compile
const theme: Theme = { ...base, ...policies, name: 'fieldnote', light, dark, scheme: 'auto' };
const tokens = compileTheme(theme); // throws on a missing core role, naming each one
// #endregion

// #region head
const head = [
  '<meta name="theme-color" content="#f6f7f4">',
  '<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible+Next:wght@400;600;700&family=Martian+Mono&display=swap">',
].join('\n');

// Every typeface the Theme names is one its head loads; a missing one falls back to the system's.
for (const role of ['sans', 'display', 'mono']) {
  const family = light[role].split(',')[0].trim().replace(/^'|'$/g, '');
  if (!head.includes(`family=${family.replaceAll(' ', '+')}`)) throw new Error(`fieldnote: --${role} names ${family}, which head does not load`);
}

// The shape THEMES holds each bundled Theme in: the Theme, its CSS and its <head> tags.
export const fieldnote: ThemeEntry = { theme, css: () => tokens, head };
// #endregion

// #region result
// The record names `quaypoint`, the bundled Theme yours starts from: `theme` takes only the 5 bundled names.
const brand = { href: '/', text: 'Fieldnote', mark: 'file-text' as const };
const page = PageSchema.parse({
  theme: 'quaypoint',
  title: 'Fieldnote: notes from every site visit',
  description: 'Site-visit notes for building inspectors, filed from a phone.',
  frame: 'none',
  sections: [
    { kind: 'nav', shell: { inset: 'contained', density: 'none' }, block: { type: 'nav', menu: 'none', brand, links: [['#on-site', 'On site'], ['#sign-off', 'Sign-off']] } },
    { kind: 'hero', shell: { inset: 'contained', density: 'hero' }, block: { type: 'hero', layout: 'centered', stack: 560, title: 'Notes from every site visit.', lede: 'Inspectors file each visit from a phone: photos named by room, defects by code, and a report the owner signs the same day.', actions: [{ href: '#on-site', label: 'See it on site', kind: 'solid' }, { href: '#sign-off', label: 'How sign-off works', kind: 'ghost' }], fine: ['Works offline on site'] } },
    { kind: 'band', shell: { inset: 'contained', density: 'compact' }, block: { type: 'stats', items: [{ value: '1', label: 'Report per visit' }, { value: '12', label: 'Defect codes built in' }, { value: '0', label: 'Forms to retype' }] } },
    { kind: 'section', shell: { id: 'on-site', inset: 'contained', density: 'section' }, block: { type: 'feature-grid', cellHead: 'icon', head: { eyebrow: 'On site', title: 'File it before you leave the driveway.' }, items: [{ icon: 'layout-grid', title: 'Rooms', text: 'Each photo lands under the room it was taken in.' }, { icon: 'list', title: 'Codes', text: 'Each defect carries its code and its fix.' }, { icon: 'badge-check', title: 'Sign-off', text: 'The owner signs the report on the inspector’s phone.' }] } },
    { kind: 'band', shell: { id: 'sign-off', inset: 'contained', density: 'section' }, block: { type: 'statement', text: 'A report is a *promise*.' } },
    { kind: 'section', shell: { inset: 'contained', density: 'section' }, block: { type: 'command-row', command: 'npm i @example/fieldnote', note: 'An illustrative package name' } },
    { kind: 'footer', shell: { inset: 'contained', density: 'footer' }, block: { type: 'footer', layout: 'row', brand, columns: [{ title: 'Fieldnote', links: [['#on-site', 'On site'], ['#sign-off', 'Sign-off']] }], note: ['Fieldnote is an example on mdxui.dev, not a product.', 'Rendered under the fieldnote Theme.'] } },
  ],
});
await writeFile('fieldnote-theme.html', render(page, fieldnote));
// #endregion
```

`site.ts` is the file in step 8, whole.

## Next steps

- [Ship a Site](https://next.mdxui.dev/docs/start/ship) under `fieldnote`.
- Compare it with the [bundled Themes](https://next.mdxui.dev/docs/themes).
- [Theme the docs](https://next.mdxui.dev/docs/themes/docs) in the same roles.
- Try roles over a live render in the [playground](https://next.mdxui.dev/docs/themes/playground).