Easy to read. Safe to edit.
A docs theme for people and agents, built on Mizzen.
Quick start · Documentation · Contributing · Mizzen
A docs theme for people and agents, built on Mizzen: layouts, chrome, components, design tokens, and styles. The engine reads it only by listing the folders below; adding a unit never edits a shared index file.
- Easy to read. An editorial layout with a sidebar, table of contents, and search that works for people and for agents.
- Safe to edit. Every visual decision is a design token, and a component is a folder, so a change stays in one place.
- Accessible. Tested against WCAG 2.2 AA, with a keyboard gate, a contrast gate, and an RTL gate.
- Right-to-left ready. Direction, language, and mirrored icons are handled for RTL languages.
Check out Mizzen next to it (../mizzen) and run npm ci in both; the tests and the docs site build with it.
The theme may import type from @velella/mizzen/contracts, by package name and never by relative path, and imports nothing else from the engine. Preact is a peer dependency, with jsx: react-jsx and jsxImportSource: preact in tsconfig.json.
| Folder | One unit is | Guide |
|---|---|---|
layouts/ |
<name>.ts |
layouts/README.md |
chrome/ |
<name>/ |
chrome/README.md |
components/ |
<name>/ |
components/README.md |
tokens/ |
<group>.json |
tokens/README.md |
styles/ |
<name>.css |
styles/README.md |
starters/ |
<name>/ |
starters/README.md |
npm testnpm run typechecknpm run tokenswritesstyles/tokens.cssfromtokens/*.json;tokens:checkfails when it is stale.npx mizzen init my-site --theme node_modules/@velella/lateen --starter docsstarts a site from one of the three starters instarters/;--listnames them.
A page picks a layout with layout in its front matter, or gets one from defaults in the site config. mizzen build uses doc when neither sets one.
| Layout | What it renders |
|---|---|
base |
The document shell: <head>, skip link, theme script, and slots for the header, sidebar, main column, aside, and footer. The other layouts build on it; a page does not name it. |
doc |
The docs page: header, sidebar, breadcrumb, article, table of contents, pager, and page footer. Front matter status, since, and replaced_by add the page-status banner. |
home |
The docs home: a hero, action buttons, and section cards from hero, actions, and sections in front matter. home: { style: showpiece } composes it from the showpiece sections instead. |
not-found |
The 404 page, with base-aware home and documentation-search links that work without JavaScript. |
versions |
The versions index: a page's versions from site.data.docsVersions or the versions front matter key, each row linked to the same page when it exists and marked with Latest, Deprecated, or Dev in text. |
record |
One data record: title, summary, facts, status, body sections, history, calendar, and its source position. |
list |
A collection index as a table, cards, or a dated list, with groups, counts, pagination, and an empty note. |
post |
A blog post in the docs shell; the engine also writes the archive, one page per author, and a feed. |
api-reference, api-reference-index |
One OpenAPI operation, and the reference index, from a pinned document. |
gallery |
A collection as a card grid with facet filters, a sort choice, and an optional "add yours" card. |
guide |
A task page with a summary bar, status, reading time, and related guides. |
embedded |
A chrome-free view of one record for an iframe, with a full-page link, no script, and noindex. |
Each layout is layouts/<name>.ts; the rules for adding one are in layouts/README.md.
Components are the pieces pages use inside their content. Each unit is its folder under components/; the table groups them by what a page uses them for.
| Component | What it does | Reference |
|---|---|---|
| Data views | timeline, compare, data-explorer, dated-list, charts, gallery, record-history, stale-notice, add-to-calendar, and related guides. |
Timeline, Compare, Data explorer, Dated list, Charts, Gallery, Record history, Stale notice, Add to calendar |
| Status and evidence | status and status-legend, trust-panel, drift-banner, tested-chip, status-banner, and the accessibility, performance, and WCAG reports. |
Status, Trust panel, Drift banner, Tested chip, Reports |
| Commands and install | install-tabs, os-tabs, cli-demo, terminal, and output-block, all plain text that copies without JavaScript. |
CLI demo, Terminal, OS tabs, Output block |
| Code and diffs | code and code annotations, code-tabs, mermaid, diff-block, and version badges and diffs. |
Code, Code tabs, Mermaid, Diff block |
| Embeds and media | embed, embed-code, figure, and video. |
Embed, Embed code, Figure, Video |
| Glossary and terms | glossary lists every term, and an inline term opens its definition in place. |
Glossary |
| Page tools and prose | callout, cards, link-card, details, steps, tabs, table, key-value, file-tree, tags, kbd, badge, reading-time, changelog-entry, and variables-form. |
Callout, Cards, Steps, Key-value list, Tabs, Variables form |
| Showpiece home | hero, backdrop, motif, stat-strip, feature-grid, frame, cta-band, and preset-preview. |
Showpiece |
The component reference lists every unit with its syntax, every option, and a live example.
Every visual decision is a design token, defined once and read from CSS. tokens/names.json freezes the names; one file per group (color.json, type.json, space.json, and the rest) sets the values. Run npm run tokens after editing a group: it writes styles/tokens.css, which npm test keeps current. Never edit that CSS by hand, and never put a raw color, length, or duration in a unit's stylesheet; use var(--color-accent), var(--space-4), and the other token variables.
A site does not edit a token file. It sets an accent colour, a neutral tint, its own fonts, a corner radius, and a density under theme.options.brand, or picks a shipped theme.options.preset; Lateen derives every dependent token at build time, corrects a colour that cannot reach its contrast, and writes the values into the page. The full list, the contrast rule, and what stays fixed are in site/brand-options.md, and the shipped starting points are in site/presets.md.
The rest of theme.options is the theme's as well. Lateen reads these blocks:
theme:
options:
announcement:
id: v0-4
text: Mizzen 0.4 is out.
href: /changelog/
editPage:
headingLinks: true
logo:
light: /assets/logo.svg
dark: /assets/logo-dark.svg
footer:
copyright: © 2026 Example
license: MIT
links:
- title: Source
url: https://github.com/example/site
gallery:
addCard:
label: Add your project
link: /gallery/new/
pageAgent:
providers:
- title: Claude
url: "https://claude.ai/new?q=Read+{markdown}"
feedback:
endpoint: https://feedback.example.com/vote| Option | What it changes |
|---|---|
announcement.id, announcement.text, announcement.href |
A dismissible bar above the header. text is required; the bar renders nothing without it. href links the text; http, https, mailto, and root-relative paths are shown. Dismissal is remembered per id. |
editPage.headingLinks |
true adds a per-heading "suggest an edit" issue link under the "Edit this page" link; absent or any other value leaves it out. |
logo.light, logo.dark |
The header mark. A root-relative path gets the site's base; an absolute URL is used as written. With both, the header swaps them with the theme; with one, it shows that one in both modes. |
footer.copyright, footer.license |
The two lines of the site footer. |
footer.links[] |
Footer links with title and url; only http, https, mailto, and root-relative paths are shown. |
gallery.addCard |
The site's own card at the end of a gallery: a label and a link. The card keeps the record cards' shape and gets the site's base; a blank label or an unsafe link renders nothing, and the option itself is optional. |
pageAgent.providers[] |
The "Use with an agent" menu. Each provider has a title and a url; {markdown}, {url}, and {title} are filled per page. Without the block the menu offers Claude, ChatGPT, and Cursor. |
feedback.endpoint |
The address the "Was this page helpful?" buttons POST {url, helpful} to. Without the block the feedback widget renders nothing. |
favicon.ico, favicon.svg, favicon.apple |
The icon links, each a path from the site root. |
installTabs.managers[] |
The package managers the install tabs offer, each with a name and a command; {package} becomes the package name. |
network.switcher, network.footer, network.position |
Show or hide the project switcher and network footer, and place the switcher in the header or above the footer. |
reportIssue |
The report-an-issue link for this site's tracker: false turns it off; an url template, labels, template, and titlePrefix customise the new issue. The link falls back to repository.url. |
sourceMode.editor |
A URL template that opens a block in a local editor; it needs {path} and may use {line} and {column}. |
status.values |
The site's map from a data value to a tone, a label (one string or one per language), and the legend's description. An unmapped value shows as written in the neutral tone. |
glossary.collection, glossary.page |
The data collection with term, definition, and aliases, and the page that carries ::glossary (one address per language allowed). |
A site cannot add a component without changing the theme or its fork: components are theme units, not content files. Adding one never edits a shared index file, because the registry discovers components/<name>/ by listing the folder.
- Make
components/<name>/, using lowercase kebab-case. The folder name is the component's name and the directive an author writes. - Add
index.tswith the Preact component written withh(), never JSX, and a default export typed by the engine's component contract. The props arrive as strings from the directive's attributes, and the directive's body arrives as rendered HTML. - Add
style.cssonly when the component has styles. Read tokens withvar(--…), use logical properties, and name classes after the component: the root is<name>, its parts add a suffix such as<name>-title. - Add
client.tsonly when the component needs the browser. It is an island: it ships only on pages that use the component, and every control it enhances startshiddenso the page still reads without JavaScript. - Add
test/component-<name>.test.tsbeside the other component tests. Test the rendered element, each variant, escaping, and the source position. - Run
npm run typecheckandnpm test. The registry finds the new folder, and an unknown directive or a missing default export becomes a diagnostic naming the file.
The full rules for a unit are in components/README.md.
src/index.ts: exports the theme manifest (nameandfolders) and nothing else.test/:*.test.tsfiles fornode --test.
Bug reports, fixes, and docs improvements are welcome. See CONTRIBUTING.md to get started.
MIT.
Lateen is part of Velella. Set the sail. Let the docs carry.