# mdxui

> A page is bounded JSON, rendered by hand-made Section types under a Theme per business. A record over its bound fails to parse, and the fix is shorter content.

startupbuilder.dev defines the Page. mdxui draws it.

## Start

- Install: `pnpm add @mdxui/site@7.0.0-alpha.0`. It pins `@mdxui/themes` 7.0.0-alpha.0; the `latest` tag of `@mdxui/themes` is the 6 line, so install the pinned pair.
- Starter record: https://next.mdxui.dev/pages/home.json, the landing as JSON. It parses; rewrite its strings and keep the Section types that fit.
- Schema: https://next.mdxui.dev/schema.json, the output of `PageSchema.toJSONSchema()`.

## Calls

- `PageSchema.safeParse(page)`: on refusal, each issue carries its `path` and its bound, such as `path: ['sections', 1, 'block', 'title']` and `maximum: 64`.
- `PageSchema.toJSONSchema()`: every bound as `maxLength`, `minItems` and `maxItems`, for a tool definition or structured output.
- `renderPage(page, { theme })`: one HTML document with one stylesheet.
- Themes: `certificate`, `vaultline`, `quaypoint`, `callboard`, `directory`.

The rule: when a string is over its bound, shorten the content, never the bound.

## Docs

- [Pages for Businesses, not pixels.](/docs): Render a page from a record, wear it in a Business's Theme, and hand the next one to your agent.
- Start
  - [Introduction](/docs/start): mdxui renders a bounded JSON record as a page under any Theme.
  - [Quickstart](/docs/start/quickstart): Install @mdxui/site, render one Page record under two Themes, and read one refusal.
  - [Ship a Site](/docs/start/ship): Build every record in pages/ into one Site under one Theme, with its 404 page, sitemap and robots file, then serve it from Cloudflare.
  - [Packages and versions](/docs/start/packages): The published mdxui packages, what each holds, and their npm versions and dist-tags.
  - **Concepts**
  - [How mdxui fits a Business](/docs/start/business): Business, Brand and Theme; Site, Page and Section; Products and Services, Interfaces and renderings, as startupbuilder.dev defines them.
  - [Pages are data](/docs/start/pages-are-data): A page is one bounded JSON record, rendered through four layers: Block, Shell, Theme and Composition. No record holds markup or CSS.
  - [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.
  - **Guides**
  - Guides
    - [Guides](/docs/start/guides): Every task guide, by what you are building: a landing page, pricing, a blog, a directory, a contact flow or a rebrand.
    - [Build a landing page](/docs/start/guides/landing-page): A landing page from nav to footer, built like Crewplan home: hero, proof, features, plans and a closing.
    - [Build a pricing page](/docs/start/guides/pricing-page): Plans as OfferTiles, a plan table and the pricing questions, built like the Crewplan and Ledgerhouse pricing pages.
    - [Run a blog and changelog](/docs/start/guides/blog-and-changelog): A post list, posts with share and copy-link, and a changelog, built like Sidework and Diffkeel.
    - [List a directory](/docs/start/guides/directory): A listing with a rail, sort and pager, and a listing page with facts and plans, built like Benchlist.
    - [Contact flow and 404](/docs/start/guides/contact-and-404): A form, its sent page and the 404, and how a static host treats a form post.
    - [Rebrand a Site in one line](/docs/start/guides/rebrand): Change the theme field in each record and compare the cross-renders of every page.
- Showcase
  - [Showcase](/docs/showcase): Six worked Businesses built from records, each a live Site you can open, wear in another Theme and copy.
  - **Worked Sites**
  - [Crewplan](/docs/showcase/crewplan): B2B SaaS: scheduling for field-service crews, in callboard.
  - [Ledgerhouse](/docs/showcase/ledgerhouse): Professional services: a two-partner bookkeeping and tax firm, in vaultline.
  - [Diffkeel](/docs/showcase/diffkeel): Developer tool: a CLI that diffs config before it deploys, in certificate.
  - [Benchlist](/docs/showcase/benchlist): Directory and marketplace: shared workshop benches by the hour, in directory.
  - [Sidework](/docs/showcase/sidework): Publication: a weekly letter for people running a Business on the side, in vaultline.
  - [Harbor tides](/docs/showcase/harbor): API product: tide windows per berth, in quaypoint.
  - **Templates**
  - Templates
    - [Templates](/docs/showcase/templates): The seven Templates, each shown live in the worked Sites that use it.
    - [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.
    - [blog](/docs/showcase/templates/blog): A post list that publishes on a schedule, with a head and ruled rows.
    - [post](/docs/showcase/templates/post): One long article with its share bar and copy-link control.
    - [article](/docs/showcase/templates/article): Terms, privacy and policy pages that read like documents.
    - [contact](/docs/showcase/templates/contact): A bounded form and the page that thanks the sender.
    - [directory-list](/docs/showcase/templates/directory-list): A sortable list of listings with a rail and a pager, up to 50 rows a page.
    - [directory-product](/docs/showcase/templates/directory-product): One listing on the split frame: a product head, its facts and its plans.
- Sections
  - [Gallery](/docs/sections): Every Section type a living page holds, each rendered alone as one section of that page.
  - [Choosing a Section type](/docs/sections/choosing): A Section type is one layout, drawn once by hand, that a section names in its block type.
  - **How sections work**
  - [Anatomy of a page](/docs/sections/anatomy): A page holds sections; each section has a kind, a shell and one Section type, drawn once.
  - [Section shells](/docs/sections/shells): One section on paper, tint, plate and glass; with dots, grain and glow; inset and density.
  - [Composition and dividers](/docs/sections/composition): How kinds compose, the divider each Theme draws between bands, and the none, sheet and split frames.
  - [Bounds and counts](/docs/sections/bounds): Every string has a maximum length and every list a designed count, and a record over its bound fails to parse.
  - [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.
  - **Navigation**
  - [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.
  - [footer](/docs/sections/footer): The foot of a page: brand and blurb, link columns and a ruled note row.
  - **Heroes**
  - [hero](/docs/sections/hero): The opening of a page: headline, lede, actions, fine print and an optional preview window.
  - [statement](/docs/sections/statement): One claim on its own, set large, with one phrase in the accent.
  - [page-head](/docs/sections/page-head): A plain page heading: a title and one line, with no actions.
  - **Proof**
  - [stats](/docs/sections/stats): A band of three or four big numbers with captions, ruled between cells.
  - [facts](/docs/sections/facts): Labels and values a buyer decides on, as one ruled list.
  - **Features**
  - [feature-grid](/docs/sections/feature-grid): A section head over a hairline grid of two, three, four, six or eight cells.
  - [feature-split](/docs/sections/feature-split): Copy with exactly three features beside one preview window.
  - [bento](/docs/sections/bento): Two to four panels, each a claim with its own preview, laid out from their count.
  - [compare](/docs/sections/compare): Two columns side by side: what the old way costs and what this one gives.
  - [steps](/docs/sections/steps): Copy beside a numbered list of three to five steps.
  - [text-stack](/docs/sections/text-stack): Copy beside a column of ruled, titled paragraphs.
  - **Code and prompts**
  - [terminal](/docs/sections/terminal): The code window: dark in every Theme and scheme, plain or tabbed.
  - [command-row](/docs/sections/command-row): One command to copy, with a note beneath it.
  - [api-call](/docs/sections/api-call): One API call beside its answer, a JSON response or an event stream.
  - [endpoints](/docs/sections/endpoints): An API at a glance: one ruled row per route, with its method, path and job.
  - [agent-prompt](/docs/sections/agent-prompt): The prompt a reader pastes into a coding agent, copied in one action.
  - **Offer**
  - [pricing](/docs/sections/pricing): One to four plans under a section head, one of them featured.
  - [plan-table](/docs/sections/plan-table): Plans as one ruled comparison table: a row per plan, a column per fact.
  - **Questions and calls**
  - [faq](/docs/sections/faq): A heading beside questions that open in place, every one closed at first.
  - [closing](/docs/sections/closing): The final call of a page: a head, then buttons or one command, never both.
  - [cta-form](/docs/sections/cta-form): Copy beside a short form: a plain post, answered with no script.
  - **Reading**
  - [article](/docs/sections/article): A reading page: an optional head and share bar, then the body as prose.
  - [post-list](/docs/sections/post-list): A blog index: a head, then the posts as ruled rows.
  - **Directory**
  - [product-head](/docs/sections/product-head): A listing page header in a directory: mark, name, one sentence, category and tags.
  - [product-list](/docs/sections/product-list): A directory list: one linked row per listing, as a list or as Tiles.
- Themes
  - [Theme gallery](/docs/themes): The 5 Themes in @mdxui/themes, each rendering the same record, and what each one suits.
  - **Themes**
  - [certificate](/docs/themes/certificate): Teal on cool paper, IBM Plex, hatched rules, light and dark. Best for developer tools and API products.
  - [vaultline](/docs/themes/vaultline): An editorial serif on warm paper, with plated offers. Best for firms and publications.
  - [quaypoint](/docs/themes/quaypoint): Navy and signal orange, set in Space Grotesk. Best for API products and infrastructure.
  - [callboard](/docs/themes/callboard): Violet, Bricolage Grotesque and DM Mono. Best for B2B SaaS with a loud brand.
  - [directory](/docs/themes/directory): Monochrome Inter with no dividers, light and dark. Best for directories and listings.
  - **How a Theme works**
  - [The Theme contract](/docs/themes/contract): The 21 core roles every Theme sets, the derived and invariant roles, and what compileTheme refuses.
  - [Policies](/docs/themes/policies): The 5 choices a design makes once, stated as data beside its tokens: dividers, markers, featured plan, icon delivery and scheme.
  - [Typefaces](/docs/themes/typefaces): Each Theme sets its display, text and mono typefaces, and its head lines load them.
  - [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.
  - **Make one**
  - [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.
  - [Theming the docs](/docs/themes/docs): A Business's Fumadocs site wears its Theme: each Fumadocs color reads one Theme role, light and dark, and every page is also Markdown.
  - [Theme playground](/docs/themes/playground): Edit paper, ink, accent, rule and plate over a real render with the published compileTheme, then copy the Theme object.
- Components
  - [Component](/docs/components): A Component is the root of the contract: startupbuilder.dev defines each one, and mdxui documents how it renders and which export draws it.
  - [Site](/docs/components/site): One origin's Pages, header, footer and required pages, rendered under one Theme.
  - [Page](/docs/components/page): A Page is one record: its Theme, an optional template, its frame, its head metadata and three to twenty sections.
  - [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.
  - [Template](/docs/components/template): A Template names one kind of page: the slots it holds in order, which Section type fills each, which are required and how many.
  - [Brand and Theme](/docs/components/brand-and-theme): startupbuilder.dev defines the Brand and the Theme; mdxui draws a Theme as tokens plus four render policies.
  - [The Product record](/docs/components/product-record): One bounded record dresses a product's landing, docs, emails, share image and directory entry.
  - [Interface](/docs/components/interface): A Site and an App are each an Interface of a Business; a rendering is one output format of a record.
  - Renderings
    - [Renderings](/docs/components/renderings): One Page record, five renderings: HTML for people, JSON and Markdown for agents, a share image and an email.
    - [How rendering works](/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.
    - [JSON](/docs/components/renderings/json): The record served beside each page, the page schema and the schema of each Section type.
    - [Embedding](/docs/components/renderings/embed): One rendered section inside another site's page, isolated in a declarative shadow root, with no script.
    - [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.
    - [Markdown](/docs/components/renderings/markdown): A page as Markdown, for agents that read text.
    - [Share image](/docs/components/renderings/share-image): A 1200 by 630 share image drawn from the product record.
    - [Email](/docs/components/renderings/email): Six kinds of mail drawn from the product record, in the Business Theme.
- Agents
  - [For agents](/docs/agents): An agent writes the record, never the markup, and shortens each field the schema refuses.
  - [Prompts](/docs/agents/prompts): One copyable prompt per task: a new page, a new Site, a rebrand and a fix for each refusal.
  - [llms.txt](/docs/agents/llms-txt): What llms.txt and llms-full.txt hold: instructions first, then the docs index.
  - [Markdown and JSON twins](/docs/agents/twins): Every docs page as Markdown at its .md address, and every rendered record as JSON.
  - [schema.json](/docs/agents/schema): The page schema, each Section type schema, and the refinements JSON Schema cannot carry.
  - [catalog.json](/docs/agents/catalog): The machine index of Section types, Themes, Templates, frames and docs addresses.
  - [Have your agent write a page](/docs/agents/write-a-page): Prompt, record, safeParse, fix at the path, render; then the same check in CI.
- Reference
  - [Reference](/docs/reference): Every export, field, bound, refusal and closed set of the published packages.
  - [Page fields and bounds](/docs/reference/page-schema): Every Page, section and shell field: its type, its bounds, its default and the anchor of its refusal.
  - [@mdxui/site exports](/docs/reference/site-exports): Every runtime export of @mdxui/site: its kind, what it does and its signature.
  - [@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.
  - [Refusals](/docs/reference/refusals): Every refusal PageSchema returns, by path, with its bound and the fix.
  - [Closed sets](/docs/reference/closed-sets): Every value an enum field accepts: icon names, brand marks, highlighter languages and each smaller set, by field.
  - [Icons](/docs/reference/icons): The Lucide glyphs and brand marks a record may name, each drawn.
  - [Highlight languages](/docs/reference/languages): The languages and aliases the code windows highlight, each with a sample line.
  - **Words and releases**
  - [Glossary](/docs/reference/glossary): One meaning per term: startupbuilder.dev terms quoted and linked, mdxui terms marked provisional.
  - [Release notes](/docs/reference/changelog): What each publish of @mdxui/site and @mdxui/themes changed, from 7.0.0-alpha.0.

## Optional

- App, View and Dashboard stubs
  - [App](/docs/components/app): The abstract App: views over a data contract, wearing the same Theme as the Site.
  - [View](/docs/components/view): The abstract View: an arrangement of Components bound to records.
  - [Dashboard](/docs/components/dashboard): The abstract Dashboard: one unified view of a scope.
- Apps
  - [App types](/docs/app): The thirteen kinds of App a Business ships, told apart by the sides they serve and the work they carry, with a study of each.
  - [Developer portal](/docs/app/developer-portal): App study: where a Customer's developers, payers and agents get a key, make a first call, fix failed calls and read their own analytics.
  - [Party portal](/docs/app/service-portal): App study: where a party with rights in a Business's work, such as a buyer, borrower or claimant, sees its own projection and acts on its turn.
  - [Worklist](/docs/app/worklist): App study: where any Worker, human or agent, inside or outside the Business, takes the Tasks routed to it and closes each with evidence.
  - [Operating review](/docs/app/operating-review): App study: where a Business steers itself by its Goals and numbers, on a cadence that ends in a Decision.
  - [Admin](/docs/app/admin): App study: the back office where a Business's own people and agents find any Thing, read its history and act on it through named Verbs.
  - [Agent console](/docs/app/agent-console): App study: where a Business that runs or sells an agent, and the Customer who hires it, govern it as a team member whose trust is earned.
  - [Directory](/docs/app/directory): App study: a public catalog of other parties, with the listed party's account and the operator's review queues behind it.
  - [SaaS workspace](/docs/app/saas-workspace): App study: a system of record a tenant Business rents, where its people and agents keep and move their own records.
  - [Marketplace](/docs/app/marketplace): App study: the exchange for a Business that brokers between buyers and Suppliers: matching, liquidity, trust, disputes and the money split.
  - [Delivery and dispatch console](/docs/app/delivery-console): App study: where a Business's staff dispatch demand into work, digital or physical, and see every item by state and by who acts next.
  - [Booking](/docs/app/booking): App study: where a Business that sells time turns perishable capacity into attended, paid visits under policies that carry money.
  - [Storefront](/docs/app/storefront): App study: everything after the cart for a Business that sells goods or digital products, from checkout to returns and disputes.
  - [Disclosure room](/docs/app/disclosure-room): App study: where a Business releases sealed, period-bound numbers and documents to the investors, boards, lenders, buyers and regulators outside it.
  - [What every App needs](/docs/app/every-app): The thirteen App types read together: the mechanisms they share, what stays specific, and what any App definition must be able to say.