The guide — Loami

Your first document

Loami documents default to compact Geist typography, blue accents and tight spacing. Use tabs so the finding, explanation and evidence stay close together.

Download the report starter, or paste this into an HTML file. Open it in a browser.

<!doctype html>
<html lang="en" data-theme="dark">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>My first Loami</title>
<script defer src="https://loami.dev/v0.1.3/loami.js"></script>
<main>
  <h1>Room for a thought.</h1>
  <p>Ordinary HTML, with a little more life.</p>
  <button data-loam-action="export">Save offline HTML</button>
</main>

For the compact document shell, put class="loam-document" on body, a header.loam-document-heading inside main, and your sections in loam-tabs.loam-pages. Use div.loam-grid for explanation beside evidence. Start from the downloadable report for the complete structure. Put raw data and methods in separate tabs; phones flow naturally and long panels scroll without clipping. No install or build step. The core runtime has no browser dependencies; Anatomy figures load their own optional bundles. Basic headings, prose, tables, code, images, blockquotes, figures and details are styled automatically. Import Loami into standalone documents: its base styles affect the page, so it is not a drop-in reset for an existing application.

Small components, readable source

Put JSON in a separate script outside the component. Give it an id, then reference it. Reuse the same data across as many components as you need.

<script type="application/json" id="sales">
[{"month":"Jan","value":24},{"month":"Feb","value":38}]
</script>

<loam-chart data-source="sales" type="bar"
  x="month" y="value" title="Sales by month"></loam-chart>

<loam-table data-source="sales" searchable
  page-size="10" title="Sales"></loam-table>

Charts support bar, line, area and donut. They include an accessible description and an expandable data table. Values must be finite numbers; donuts require non-negative values and a positive total. Empty data gets an empty state. Aggregate large datasets before charting.

Tables sort when you select a column heading. Add searchable to filter. CSV export includes the filtered rows across all pages. CSV formula prefixes are escaped for safer spreadsheet opening.

Linked controls

<loam-range name="factor" label="Multiplier"
  min="0.5" max="2" step="0.1" value="1"></loam-range>
<p>Current factor: <span loam-bind="factor">1</span></p>
<loam-chart data-source="sales" type="line"
  x="month" y="value" multiplier="factor"></loam-chart>

For custom logic, use Loami.set('factor', 1.5), read Loami.state.factor, or listen for loam:input on document. Its detail is {name, value}. Call Loami.refresh() after replacing source JSON. Data sources must remain in the document.

Tabs

<loam-tabs label="Report sections">
  <section label="Summary"><p>The main findings.</p></section>
  <section label="Method"><p>How we got here.</p></section>
</loam-tabs>

Arrow keys, Home and End move between tabs. Tab takes focus into the selected panel.

The file carries its mood

Set data-theme="light", dark, sepia, forest or auto on html. Auto follows the system unless the visitor has saved a preference on that origin. An explicit document theme wins over local preferences.

<select data-loam-theme aria-label="Document theme">
  <option value="light">Light</option>
  <option value="dark">Dark</option>
  <option value="sepia">Sepia</option>
  <option value="forest">Forest</option>
  <option value="auto">System</option>
</select>

Override a few tokens in your own style block to make a custom theme. Use a selector with at least the same specificity as the built-in theme. Set foreground and background colors as a pair.

:root[data-theme="light"] {
  --loam-bg: #fffefb;
  --loam-surface: #f2f0e9;
  --loam-text: #292d29;
  --loam-muted: #61685f;
  --loam-line: #d9dfd7;
  --loam-accent: #38684c;
  --loam-on-accent: #ffffff;
  --loam-font: Geist, Arial, sans-serif;
  --loam-width: 1100px;
  --loam-size: 14px;
  --loam-leading: 1.5;
}

Other tokens: --loam-ui, --loam-radius, --loam-chart-2, --loam-chart-3. Use Loami.setTheme('dark') from JavaScript. Check text contrast when customizing.

<button data-loam-action="export">Save offline HTML</button>
<button data-loam-action="print">Print or save PDF</button>

// Return source without downloading:
const html = await Loami.exportHTML({ download: false });

Export embeds Loami’s code, your source data, the selected theme and current range values. Tables reset their sort/filter/page state, and tabs return to the first panel. Print styles expand tab panels; interactive controls don’t appear in the printed result.

Custom external images, fonts, scripts, modules, stylesheets, fetched data and iframes are not inlined. For a completely offline document, keep those assets inline or bundle them first. All JSON data travels in the file, including rows currently hidden by a filter.

Custom interactions need source code that initializes itself when the file opens. Attached event listeners are not serialized. Use this pattern:

function init() { /* wire your figure controls once */ }
if (document.readyState === 'loading') {
  document.addEventListener('DOMContentLoaded', init, { once: true });
} else { init(); }

HTML is executable content. Share trusted code; recipients should open files from sources they trust. Loami supplies no accounts, remote saving or collaboration backend.

A home for Anatomy figures

Try a real working figure with one tag:

<loam-anatomy figure="watch"></loam-anatomy>

Open the live watch document. Switch themes, wind the crown, and export it offline. Available figures: watch, message-queue, lru-cache. Theme changes and reopened exports reset the figure’s model. Anatomy MIT license.

Anatomy is a separate skill by Ryan that creates interactive explanatory machines. Loami includes three official Anatomy figures as optional bundles: watch, message-queue, and lru-cache. Ryan’s original figure code and MIT attribution are preserved. The core runtime loads only the figures you use, and offline export embeds those bundles.

<loam-figure>
  <!-- Your generated framework-free SVG / canvas / HTML here. -->
</loam-figure>

The wrapper maps Anatomy’s shared card, paper, text, strong, muted, accent, line and basic surface tokens to Loami. More detailed material shading stays under the figure’s control. Hardcoded colors and inline custom-property values override this bridge; update those in the generated figure. Preserve its model, painter’s order, keyboard controls, accessible descriptions and reduced motion behavior.

Use this prompt with both skills available:

Use Anatomy to explain a queue as an interactive machine. Output framework-free SVG and browser-ready JavaScript inside a Loami HTML document. Use the Loami light and dark theme tokens through loam-figure. Keep the simulation and readout on one model. Keep assets and scripts inline so the exported file works offline.

Anatomy’s TypeScript must be compiled to JavaScript. React components need a build or conversion; they won’t execute just by pasting them into HTML. External Anatomy custom-element modules also need bundling for offline use.

Open a small custom-figure example. This demonstrates the integration boundary; it is not generated by Anatomy and does not claim Anatomy’s illustration quality.

Connect a coding agent

For a project setup your agent can carry out, copy the setup prompt from the homepage. It installs the skill and adds a future document preference to the project’s CLAUDE.md or AGENTS.md, while preserving existing instructions. Read the complete setup steps.

Download the Loami skill and unzip it so loam-html/SKILL.md sits inside your project’s .claude/skills/ directory, or Codex’s .agents/skills/. You can also read the complete text reference directly.

claude mcp add --transport http loami \
  https://loami.dev/mcp

The public, read-only Streamable HTTP MCP server exposes get_documentation, list_components, get_example and create_document, plus a loam://docs resource. It returns documentation and HTML source; it does not execute code, store documents, call AI models or publish anything.

Other clients can connect to that URL as a remote HTTP MCP server. Their configuration formats and supported transports vary.