@threadlabs/looma-docs 0.0.0-stage → 0.52.0

package/docs/fonts.mjs

@@ -0,0 +1,73 @@
+/** A focused searchable Google Fonts collection; system fonts never require a request. */
+export const googleFonts = Object.fromEntries([
+  ['Inter', 'sans-serif'], ['Roboto', 'sans-serif'], ['Open Sans', 'sans-serif'],
+  ['Source Sans 3', 'sans-serif'], ['Lato', 'sans-serif'], ['Nunito Sans', 'sans-serif'],
+  ['DM Sans', 'sans-serif'], ['Manrope', 'sans-serif'], ['Work Sans', 'sans-serif'],
+  ['IBM Plex Sans', 'sans-serif'], ['Public Sans', 'sans-serif'], ['Atkinson Hyperlegible', 'sans-serif'],
+  ['Outfit', 'sans-serif'], ['Fraunces', 'serif'], ['Merriweather', 'serif'], ['Lora', 'serif'],
+  ['Source Serif 4', 'serif'], ['Newsreader', 'serif'], ['Libre Baskerville', 'serif'], ['Crimson Pro', 'serif'],
+  ['EB Garamond', 'serif'], ['Playfair Display', 'serif'], ['Roboto Mono', 'monospace'],
+  ['IBM Plex Mono', 'monospace'], ['JetBrains Mono', 'monospace'], ['Fira Code', 'monospace'],
+].map(([family, category]) => [family, { family, category, weights: ['Lato', 'Atkinson Hyperlegible', 'Libre Baskerville'].includes(family) ? '400;700' : '400;500;600;700' }]));
+
+export const systemFont = 'system-ui, sans-serif';
+export const googleFontStack = family => `"${family}", ${googleFonts[family].category}`;
+export function googleFontURL(fonts = {}) {
+  const families = [...new Set(Object.values(fonts))].sort();
+  if (!families.length) return '';
+  return 'https://fonts.googleapis.com/css2?' + families.map(family => {
+    if (!Object.hasOwn(googleFonts, family)) throw new Error('Choose a supported Google font.');
+    return 'family=' + encodeURIComponent(family).replaceAll('%20', '+') + ':wght@' + googleFonts[family].weights;
+  }).join('&') + '&display=swap';
+}
+
+/** Load and confirm actual faces before reporting a selected font as ready. */
+const fontLoads = new WeakMap();
+export async function loadGoogleFonts(document, fonts) {
+  const url = googleFontURL(fonts);
+  let link = document.head.querySelector('link[data-looma-google-fonts]');
+  if (!url) { fontLoads.get(link)?.cancel(); link?.remove(); return; }
+  if (link?.href !== url) {
+    fontLoads.get(link)?.cancel(); link?.remove(); link = document.createElement('link');
+    link.rel = 'stylesheet'; link.dataset.loomaGoogleFonts = '';
+    let cancel;
+    const loaded = new Promise((resolve, reject) => {
+      cancel = () => resolve(false);
+      link.onload = () => resolve(true); link.onerror = () => reject(new Error('The Google font could not load. Check your connection or select the system font.'));
+    });
+    fontLoads.set(link, { loaded, cancel }); link.href = url; document.head.append(link);
+  }
+  if (await fontLoads.get(link)?.loaded === false) return;
+  for (const family of new Set(Object.values(fonts))) {
+    const faces = await document.fonts.load(`400 16px "${family}"`);
+    if (!faces.length) throw new Error(`${family} is unavailable; the fallback is currently displayed.`);
+  }
+}
+
+/** Request only a font name's glyphs; selected fonts use the unrestricted stylesheet above. */
+export function googleFontPreviewURL(family) {
+  if (!Object.hasOwn(googleFonts, family)) throw new Error('Choose a supported Google font.');
+  return 'https://fonts.googleapis.com/css2?family=' + encodeURIComponent(family).replaceAll('%20', '+') + ':wght@400&display=swap&text=' + encodeURIComponent(family);
+}
+
+const previewLoads = new WeakMap();
+/** Isolate subset faces under aliases so document typography always uses full selected fonts. */
+export function loadGoogleFontPreview(document, family) {
+  let loads = previewLoads.get(document);
+  if (!loads) { loads = new Map(); previewLoads.set(document, loads); }
+  if (!loads.has(family)) {
+    const loaded = (async () => {
+      const response = await document.defaultView.fetch(googleFontPreviewURL(family));
+      if (!response.ok) throw new Error('Font preview unavailable.');
+      const source = (await response.text()).match(/src\s*:\s*([^;]+);/)?.[1];
+      if (!source) throw new Error('Font preview unavailable.');
+      const alias = `Looma Font Preview ${family}`;
+      const face = new document.defaultView.FontFace(alias, source, { weight: '400', style: 'normal', display: 'swap' });
+      await face.load(); document.fonts.add(face);
+      return alias;
+    })();
+    loads.set(family, loaded);
+    loaded.catch(() => { if (loads.get(family) === loaded) loads.delete(family); });
+  }
+  return loads.get(family);
+}

package/docs/framework-examples.d.mts

@@ -0,0 +1,9 @@
+import type { TypeNode } from '@nextwebwg/html-next';
+
+export type Framework = 'html-next' | 'vue' | 'react' | 'preact' | 'svelte' | 'angular';
+export interface FrameworkExample { language: 'html' | 'vue' | 'tsx' | 'svelte' | 'text'; code: string; notice?: string; }
+export const frameworkLabels: Readonly<Record<Framework, string>>;
+export function frameworkExamples(
+  example: { markup: string; frameworks?: Partial<Record<Framework, FrameworkExample>> },
+  components: readonly { tag: string; package: string; root?: string; resource?: string; importSource?: string; attributes?: readonly { name: string; property?: string; type?: string; valueType?: TypeNode }[] }[],
+): Record<Framework, FrameworkExample>;

package/docs/framework-examples.mjs

@@ -0,0 +1,225 @@
+import { camel, componentName, exampleInvocations, nativeBooleans } from './example-invocations.mjs';
+
+const escapeHtml = value => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const indent = depth => '  '.repeat(depth);
+const textValue = node => node.preserve ? node.value : node.value.replace(/[\t\n\r\f ]+/g, ' ');
+const formattingSpace = node => node?.kind === 'text' && !node.preserve && /^[\t\n\r\f ]*$/.test(node.value);
+const key = (value, quote = JSON.stringify) => /^[a-zA-Z_$][\w$]*$/.test(value) ? value : quote(value);
+const singleQuoted = value => `'${JSON.stringify(value).slice(1, -1).replaceAll('\\"', '"').replaceAll("'", "\\'")}'`;
+const kebab = value => value.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`);
+const jsx = target => target === 'react' || target === 'preact';
+const voidElements = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const reactAttributes = { class: 'className', for: 'htmlFor', readonly: 'readOnly', tabindex: 'tabIndex', autofocus: 'autoFocus', maxlength: 'maxLength', minlength: 'minLength', colspan: 'colSpan', rowspan: 'rowSpan', srcset: 'srcSet', crossorigin: 'crossOrigin', spellcheck: 'spellCheck', contenteditable: 'contentEditable', allowfullscreen: 'allowFullScreen', formnovalidate: 'formNoValidate', novalidate: 'noValidate', playsinline: 'playsInline' };
+const numericAttributes = new Set(['cols', 'rows', 'size', 'span', 'rowSpan', 'colSpan', 'tabIndex', 'maxLength', 'minLength', 'start']);
+const inlineElements = new Set('a abbr b bdi bdo br button cite code del em i img input ins kbd label mark q s samp small span strong sub sup time u var wbr'.split(' '));
+const reserved = new Set('await break case catch class const continue debugger default delete do else enum export extends false finally for function if implements import in instanceof interface let new null package private protected public return static super switch this throw true try typeof var void while with yield arguments eval'.split(' '));
+
+export const frameworkLabels = { 'html-next': 'HTML Next', vue: 'Vue', react: 'React', preact: 'Preact', svelte: 'Svelte', angular: 'Angular' };
+
+function vueExpression(value) {
+  if (typeof value === 'string') return singleQuoted(value);
+  if (Array.isArray(value)) return `[${value.map(vueExpression).join(', ')}]`;
+  if (value && typeof value === 'object') {
+    const fields = Object.entries(value).map(([name, item]) => `${key(name, singleQuoted)}: ${vueExpression(item)}`);
+    return fields.length ? `{ ${fields.join(', ')} }` : '{}';
+  }
+  return JSON.stringify(value);
+}
+
+// Derive block layout from the tree. Mixed text and inline adjacency stay together.
+function layout(nodes, owner) {
+  const structural = nodes.some(node => node.kind === 'slot' || node.kind === 'element' && (node.component || !inlineElements.has(node.tag)));
+  const labels = nodes.filter(node => node.kind === 'text' && !formattingSpace(node));
+  const namedSlot = node => node.kind === 'element' && node.attributes.some(attribute => attribute.name === 'slot' && attribute.value);
+  const slottedLabel = owner?.tag.includes('-') && labels.length === 1 && !labels[0].preserve
+    && nodes.some(namedSlot) && nodes.every(node => node.kind !== 'element' || namedSlot(node));
+  const multiline = slottedLabel || structural
+    && !nodes.some(node => node.kind === 'text' && !formattingSpace(node));
+  if (!multiline) return { multiline, nodes };
+  const displayed = nodes.filter(node => !formattingSpace(node)).map(node => {
+    if (!slottedLabel || node.kind !== 'text') return node;
+    return { ...node, value: node.value.replace(/^[\t\n\r\f ]+|[\t\n\r\f ]+$/g, '') };
+  });
+  return { multiline, nodes: displayed };
+}
+
+function text(node, target) {
+  const value = textValue(node);
+  if (target === 'html-next') return escapeHtml(value);
+  if (jsx(target)) {
+    if (node.preserve || /[\n\r\t]/.test(node.value)) {
+      return `{${JSON.stringify(value)}}`;
+    }
+    return escapeHtml(value).replace(/[{}]/g, char => `{${JSON.stringify(char)}}`);
+  }
+  const escaped = escapeHtml(value);
+  if (target === 'angular') return escaped.replaceAll('{', '&#123;').replaceAll('}', '&#125;').replaceAll('@', '&#64;');
+  return target === 'svelte' ? escaped.replaceAll('{', "{'{'}") : escaped.replaceAll('{', '&#123;');
+}
+
+function attribute(value, target, component) {
+  let name = value.property;
+  let data = value.value;
+  if (target === 'html-next') return data === true || data === '' ? name : `${name}="${escapeHtml(data)}"`;
+  if (jsx(target)) {
+    name = reactAttributes[name] ?? name;
+    if (name === 'style') {
+      data = Object.fromEntries(String(data).split(';').filter(part => part.includes(':')).map(part => {
+        const at = part.indexOf(':');
+        const property = part.slice(0, at).trim();
+        return [property.startsWith('--') ? property : camel(property), part.slice(at + 1).trim()];
+      }));
+    } else if (!component && numericAttributes.has(name) && /^[-+]?\d+$/.test(data)) data = Number(data);
+    if (data === true) return name;
+    return typeof data === 'string' ? `${name}="${escapeHtml(data)}"` : `${name}={${JSON.stringify(data)}}`;
+  }
+  if (target === 'angular') {
+    if (component?.attributes?.some(prop => (prop.property ?? prop.name) === name)) return `[${name}]="${escapeHtml(vueExpression(data))}"`;
+    if (data === true) return name;
+    return `${value.name}="${escapeHtml(data)}"`;
+  }
+  if (target === 'svelte') {
+    if (data === true) return name;
+    return typeof data === 'string' ? `${name}="${escapeHtml(data).replaceAll('{', '&#123;')}"` : `${name}={${JSON.stringify(data)}}`;
+  }
+  name = component ? kebab(name) : value.name;
+  if (data === true && nativeBooleans.has(name) && !component) return name;
+  return typeof data === 'string' ? `${name}="${escapeHtml(data).replaceAll('{', '&#123;')}"` : `:${name}="${escapeHtml(vueExpression(data))}"`;
+}
+
+function snippetBindings(model) {
+  const taken = new Set([...reserved, ...model.components.map(component => componentName(component.tag))]);
+  const bindings = new Map();
+  function visit(nodes) {
+    for (const node of nodes) {
+      if (node.kind === 'slot') {
+        let base = camel(node.name.replace(/[^\w$-]/g, '-')).replace(/-/g, '');
+        if (!/^[a-zA-Z_$]/.test(base)) base = `slot${base}`;
+        if (reserved.has(base)) base += 'Content';
+        let name = base;
+        if (taken.has(name)) {
+          const owner = componentName(node.owner.tag).replace(/^Ui/, '');
+          base = owner[0].toLowerCase() + owner.slice(1) + base[0].toUpperCase() + base.slice(1);
+          name = base;
+          for (let index = 2; taken.has(name); index++) name = `${base}${index}`;
+        }
+        taken.add(name);
+        bindings.set(node, name);
+      }
+      if (node.children) visit(node.children);
+    }
+  }
+  visit(model.nodes);
+  return bindings;
+}
+
+/** Print the public invocation API, keeping framework-specific syntax out of the parsed model. */
+function printer(model, target) {
+  const bindings = ['svelte', 'angular'].includes(target) ? snippetBindings(model) : new Map();
+
+  function sequence(nodes, depth, forceLines = false, owner) {
+    const arranged = layout(nodes, owner);
+    const content = arranged.nodes.map(node => (arranged.multiline ? indent(depth) : '') + render(node, depth)).join(arranged.multiline ? '\n' : '');
+    return (forceLines && !arranged.multiline ? indent(depth) : '') + content;
+  }
+
+  function reactValue(nodes, depth) {
+    const content = [...nodes];
+    const boundaryIndentation = node => formattingSpace(node) && /[\n\r]/.test(node.value);
+    while (boundaryIndentation(content[0])) content.shift();
+    while (boundaryIndentation(content.at(-1))) content.pop();
+    const arranged = layout(content);
+    if (!arranged.nodes.length) return 'null';
+    if (arranged.nodes.length === 1) {
+      const node = arranged.nodes[0];
+      if (node.kind === 'text') return JSON.stringify(textValue(node));
+      if (node.kind === 'comment') return `null /*${node.value}*/`;
+      return render(node, depth);
+    }
+    return arranged.multiline
+      ? `<>\n${sequence(content, depth + 1)}\n${indent(depth)}</>`
+      : `<>${sequence(content, depth)}</>`;
+  }
+
+  function render(node, depth) {
+    if (node.kind === 'text') return text(node, target);
+    if (node.kind === 'comment') return jsx(target) ? `{/*${node.value}*/}` : `<!--${node.value}-->`;
+    if (node.kind === 'slot' && target === 'angular') {
+      return `<ng-container ngProjectAs="[slot='${node.name}']">\n${sequence(node.children, depth + 1, true)}\n${indent(depth)}</ng-container>`;
+    }
+    if (node.kind === 'slot') {
+      return `<template #${node.name}>\n${sequence(node.children, depth + 1, true)}\n${indent(depth)}</template>`;
+    }
+    const structural = target === 'angular' && node.component?.angularHost === 'ng-template';
+    const declared = value => node.component.attributes?.some(prop => (prop.property ?? prop.name) === value.property);
+    const attrs = node.attributes.filter(value => !structural || declared(value)).map(value => attribute(value, target, node.component));
+    if (structural) {
+      const forwarded = node.attributes.filter(value => !declared(value));
+      if (forwarded.length) attrs.push(`[hnAttributes]="${escapeHtml(`{ ${forwarded.map(value => `${key(value.name, singleQuoted)}: ${vueExpression(value.value)}`).join(', ')} }`)}"`);
+    }
+    if (node.slots.length && target === 'svelte') {
+      attrs.push(`slots={{ ${node.slots.map(slot => slot.name === bindings.get(slot) ? slot.name : `${key(slot.name)}: ${bindings.get(slot)}`).join(', ')} }}`);
+    }
+    if (node.slots.length && jsx(target)) {
+      attrs.push(`slots={{\n${node.slots.map(slot => `${indent(depth + 2)}${key(slot.name)}: ${reactValue(slot.children, depth + 2)},`).join('\n')}\n${indent(depth + 1)}}}`);
+    }
+    let tag = node.tag;
+    let templates = '';
+    if (target === 'angular' && node.component) {
+      tag = node.component.angularHost ?? node.component.root;
+      if (!tag) throw new Error(`Missing Angular native host for ${node.component.tag}.`);
+      attrs.unshift(node.component.tag);
+      if (tag === 'ng-template' && node.slots.length) {
+        templates = node.slots.map(slot => `<ng-template #${bindings.get(slot)}>\n${sequence(slot.children, depth + 1, true)}\n${indent(depth)}</ng-template>\n${indent(depth)}`).join('');
+        attrs.push(`[slots]="${escapeHtml(`{ ${node.slots.map(slot => `${key(slot.name, singleQuoted)}: ${bindings.get(slot)}`).join(', ')} }`)}"`);
+      }
+    }
+    const wrapped = attrs.length > 0;
+    const start = wrapped ? `<${tag}\n${attrs.map(value => indent(depth + 1) + value).join('\n')}\n${indent(depth)}` : `<${tag}`;
+    const children = target === 'vue' || target === 'angular' && tag !== 'ng-template' ? node.children : node.children.filter(child => child.kind !== 'slot');
+    const owner = target === 'html-next' ? node : undefined;
+    const arranged = layout(children, owner);
+    if (!arranged.nodes.length && target !== 'angular' && (node.component || jsx(target))) return `${start}${wrapped ? '' : ' '}/>`;
+    if (voidElements.has(tag)) return templates + `${start}>`;
+    const content = sequence(children, depth + 1, false, owner);
+    return arranged.multiline
+      ? `${templates}${start}>\n${content}\n${indent(depth)}</${tag}>`
+      : `${templates}${start}>${content}</${tag}>`;
+  }
+
+  function body(depth) {
+    const arranged = layout(model.nodes);
+    if (jsx(target)) return reactValue(model.nodes, depth);
+    return (arranged.multiline ? '' : indent(depth)) + sequence(model.nodes, depth);
+  }
+
+  return {
+    body,
+    snippets: () => [...bindings].map(([slot, name]) => `{#snippet ${name}()}\n${sequence(slot.children, 1, true)}\n{/snippet}`).join('\n\n'),
+  };
+}
+
+/** Present invocations using the public APIs produced by each Vite framework target. */
+export function frameworkExamples(example, components) {
+  const model = exampleInvocations(example.markup, components);
+  const importSource = component => component.importSource ?? component.package;
+  const imports = [...new Set(model.components.map(importSource))].map(owner => {
+    const names = model.components.filter(component => importSource(component) === owner).map(component => componentName(component.tag)).sort();
+    const line = `import { ${names.join(', ')} } from ${JSON.stringify(owner)};`;
+    return line.length <= 100 ? line : `import {\n${names.map(name => `  ${name},`).join('\n')}\n} from ${JSON.stringify(owner)};`;
+  }).join('\n');
+  const links = model.components.map(component => `<link\n  rel="component"\n  href="${escapeHtml(component.resource ?? `${component.package}/components/${component.tag}/${component.tag}.html`)}"\n>`).join('\n');
+  const html = printer(exampleInvocations(example.markup, []), 'html-next').body(0);
+  const codes = { 'html-next': { language: 'html', code: [links, html].filter(Boolean).join('\n\n') } };
+  for (const target of ['vue', 'react', 'preact', 'svelte']) {
+    const output = printer(model, target);
+    const script = imports ? `<script${target === 'vue' ? ' setup' : ''}>\n${imports.split('\n').map(line => '  ' + line).join('\n')}\n</script>\n\n` : '';
+    codes[target] = jsx(target)
+      ? { language: 'tsx', code: `${target === 'preact' ? '/** @jsxImportSource preact */\n' : ''}${imports ? imports + '\n\n' : ''}export default function Example() {\n  return ${output.body(1)};\n}` }
+      : { language: target, code: script + (target === 'vue' ? `<template>\n${output.body(1)}\n</template>` : [output.snippets(), output.body(0)].filter(Boolean).join('\n\n')) };
+  }
+  const angular = printer(model, 'angular');
+  const template = angular.body(2).replaceAll('\\', '\\\\').replaceAll('`', '\\`').replaceAll('${', '\\${');
+  codes.angular = { language: 'typescript', code: `import { Component } from "@angular/core";\n${imports ? imports + '\n' : ''}\n@Component({\n  selector: "example-view",\n  standalone: true,\n  imports: [${model.components.map(component => componentName(component.tag)).join(', ')}],\n  template: \`\n${template}\n  \`,\n})\nexport default class Example {}` };
+  return { ...codes, ...example.frameworks };
+}

package/docs/guides/01.theme-your-system.md

@@ -0,0 +1,64 @@
+---
+title: Theme your system
+order: 1
+---
+
+<div data-looma-guide>
+
+# Theme your system
+
+Open **Customize** in your local docs site. You can try a starting theme, refine its shared decisions, and see the result on real components.
+
+## Choose a starting point
+
+Pick a starting theme in the summary bar. Each choice sets a coordinated identity across color, typography, shape, spacing, material, and motion.
+
+- **Minimal** keeps neutral colors and restrained depth.
+- **Gold** combines warm actions with rounded, polished surfaces.
+- **Bookish** pairs wine and coral accents with reading-focused type.
+- **Editorial** uses flat ink-and-paper surfaces and serif headings.
+- **Night** uses cool accents and glass material.
+- **Garden** brings forest, clay, and gold together with soft corners.
+
+## Refine one family at a time
+
+Open a summary on the overview to edit that subject. Choose **Overview** to return.
+
+::: table
+
+- Editor: Palette
+  Try: Change your brand seeds, then compare light and dark specimens.
+
+- Editor: Typography
+  Try: Choose a body font and a heading font. Check a heading beside a form label.
+
+- Editor: Size & spacing
+  Try: Adjust control roominess and spacing while comparing the size ladder.
+
+- Editor: Material & light
+  Try: Move the light source and compare matte and polished surfaces.
+
+- Editor: Motion
+  Try: Replay the motion study and open the example popover.
+
+:::
+
+Edits apply immediately. Use **Undo**, **Redo**, or **Reset** in the summary bar as you explore. [Theme decisions](/theme-decisions/) explains the detailed controls and derivation rules.
+
+## Check your own components
+
+Choose **Browse components** to find an example in your discovered catalog. Preview your common forms, navigation, and content alongside one another. [Add your components](/add-your-components/) shows how to include your own definitions and examples.
+
+![Fellowship UI with the same component definitions in a dark theme.](./assets/fellowship-dark.png)
+
+Every generated theme includes light and dark palettes. Use the appearance button to compare both. In your application, leave `data-theme` off the document root to follow the system, or set it to `light` or `dark` for a fixed mode.
+
+## Save and continue
+
+Open **Export & save**. On your local site, saving updates the configured JSON recipe and CSS. A static site offers downloads. Import a recipe to continue editing it later.
+
+Load the CSS after Looma's styles in your application. Re-save your recipe after a Looma upgrade to pick up updated derivation rules. Keep handwritten overrides in their own file.
+
+[Next: add your components](/add-your-components/)
+
+</div>

package/docs/guides/02.add-your-components.md

@@ -0,0 +1,96 @@
+---
+title: Add your components
+order: 2
+---
+
+<div data-looma-guide>
+
+# Add your components
+
+Build your design-system components in HTML Next. Their definitions, description attributes, modules and HTML examples are the source for the generated documentation and customizer cards. Use Looma’s public semantic properties to make your components respond to the same theme.
+
+1. Create a directory for your HTML Next component resources, such as `app/components`.
+2. Opt that directory into `components` in `looma.docs.json`, with your package's name.
+3. Put `docs.json` and an `examples/` directory beside each resource, as shown below.
+4. Run `looma-docs dev`. Your components appear beside Looma's in the reference,
+   search and customizer example picker. Resources under registered directories
+   are rediscovered when the local server rebuilds.
+
+## Register a discovery root
+
+The configuration can combine your name, authored guides and discovery roots:
+
+```json
+{
+  "title": "The Fellowship",
+  "base": "/",
+  "outDir": ".looma/site",
+  "content": "docs",
+  "theme": { "recipe": "looma.theme.json", "css": "looma.theme.css" },
+  "components": [{ "directory": "app/components", "packageName": "fellowship-ui" }],
+  "overrides": ["styles/design-system-overrides.css"]
+}
+```
+
+`content` and `overrides` are optional. Create files you configure before building. Markdown guidance supplements the generated reference; it cannot replace an API page. Relative component and asset dependencies keep their original project locations, and code examples remain literal. Local web fonts referenced by override CSS are embedded in the documentation's theme stylesheet so isolated examples render the same fonts on static hosts. Google font selections travel in the generated CSS import. Load custom or self-hosted faces in the consuming application; their stacks only select families.
+
+## Write a component
+
+A resource can use any valid HTML Next component tag:
+
+```html
+<template component="office-status">
+  <defs>
+    <prop name="label" type="string" default="Ready">The team's current status.</prop>
+  </defs>
+  <p>{$label}<slot></slot></p>
+</template>
+```
+
+## Describe it in the catalog
+
+Place a `docs.json` beside it to join a shared category:
+
+```json
+{
+  "title": "Office status",
+  "summary": "The office’s current status.",
+  "description": "A status for the Fellowship office.",
+  "group": "display"
+}
+```
+
+An optional `summary` supplies the short card text; `description` supplies the full reference introduction. Cards use `description` when no summary is authored.
+
+Looma's category IDs are listed in its published catalog. Components without a category appear in **Project components**. A discovery root can declare additional `groups` as `{ "id": "…", "label": "…" }` entries. The top-level `categories` mapping explicitly maps category IDs when combining catalogs.
+
+A component card should demonstrate its defining feature, including a non-default configuration when that makes the behavior clear. A feature demonstration does not require changing the component’s default.
+
+## Add a live example
+
+Put authored examples in an `examples/` directory beside the resource. Each `.html` example starts with a metadata comment:
+
+```html
+<!--
+title: Ready for second breakfast
+description: Sam has finished the morning checklist.
+-->
+<office-status label="Ready for second breakfast"></office-status>
+```
+
+The first example also appears in the component directory, so keep it representative at a narrow card width. Full variations belong in the later reference examples. Optional `.behavior.js` or `.behavior.ts` companions export a default setup function receiving the example root; return a cleanup function when needed. Select controls through example-local data attributes: generated IDs and their label, trigger and command references are namespaced for each instance. Add `preview: resizable` to expose the shared card's width control, or `preview: stretch` when the sample needs the available inline width, such as percentage-based loading placeholders. Framework-specific `.snippet.html` and `.vue` companions provide literal source views.
+
+Discovery reads definitions and descriptions without executing their controllers. New resources under a selected root appear after the local server rebuilds. External components keep their own contracts and supported token hooks; discovery does not make arbitrary components respond to Looma's tokens.
+
+Author components and documentation examples in HTML Next. Vue, React, Preact and Svelte applications compile those definitions with the HTML Next Vite plugin or converter; framework conversion belongs in the consuming application. See the [loading guide](https://threadlabs.studio/looma/getting-started/) for framework setup, imports and styles.
+
+
+## Combine installed catalogs
+
+A library can publish the versioned catalog shape exposed by `@threadlabs/looma/docs/catalog.json`. Add package exports or relative JSON files under `catalogs` in the configuration. Component identities are package-qualified; duplicate tags, conflicting categories and missing compound parents fail with ownership information instead of silently replacing a component.
+
+Use the `@threadlabs/looma-docs` entrypoint for programmatic discovery, catalog merging, theme validation, and build/dev/preview integration. Its TypeScript definitions describe the configuration and catalog interfaces. The browser card renderer, catalog data and compiled example companions ship in the package.
+
+[Next: publish your system](/publish-your-system/)
+
+</div>

package/docs/guides/03.publish-your-system.md

@@ -0,0 +1,71 @@
+---
+title: Publish your system
+order: 3
+---
+
+<div data-looma-guide>
+
+# Publish your system
+
+Give your documentation its own name, then build a static site for your team.
+
+## Name and brand the site
+
+`looma-docs init --title "Fellowship UI"` sets your site's name. To rename an
+existing local documentation site, edit `title` in `looma.docs.json`; the local
+server rebuilds the header, generated landing page and page titles with that
+name. You do not need to fork Looma or change component imports.
+
+You can also supply your logo and navigation:
+
+```json
+{
+  "title": "Fellowship UI",
+  "logo": {
+    "light": "/assets/fellowship-light.svg",
+    "dark": "/assets/fellowship-dark.svg"
+  },
+  "nav": [{ "label": "Our application", "href": "https://example.com" }]
+}
+```
+
+Merge these fields into your existing configuration. Serve the logo URLs from
+your application's public assets, such as `public/assets/`. Leave `logo` unset
+for a text-only brand. To author your own introduction, set `content` to your
+Markdown directory and add its `index.md`; it replaces the generated landing
+page without replacing component reference pages.
+
+The site name is yours. Component ownership stays accurate: built-in cards
+still identify `@threadlabs/looma`, while your discovered components identify
+the `packageName` you configure below. That is package attribution, not the
+name of your design system. Shared CSS and recipe filenames are configured
+under `theme`; changing a site title does not require renaming those files.
+
+A navigation link with `"position": "start"` appears before the generated component and
+editor sections. Other links keep their order after those sections:
+
+```json
+{ "nav": [{ "label": "Get started", "href": "/getting-started/", "position": "start" }] }
+```
+
+For documentation-site Markdown syntax and publishing options, see the
+[Markupress documentation](https://threadlabs-studio.github.io/markupress/).
+
+## Build and preview
+
+```sh
+pnpm exec looma-docs build
+pnpm exec looma-docs preview
+```
+
+`build` writes a static MarkupKit site to `outDir`, which defaults to `.looma/site`. Deploy that directory to your static host. `preview` serves the built files. All commands accept `--root`; `dev` and `preview` also accept `--port`.
+
+## Save your theme
+
+Commit `looma.docs.json`, the theme recipe, and the generated CSS with your components. Add `.looma/` to your ignore file. Keep handwritten CSS in a separate overrides file so saving a theme preserves it.
+
+The local editor writes only the configured recipe and CSS inside the project. It rejects symlink paths, generated or dependency directories, cross-origin save requests and stale file revisions. A competing edit leaves your unsaved preview in place; reload and reconcile it before saving again. Examples are pre-rendered directly in the documentation page and share its styles and HTML Next runtime. Project component roots and example companions are trusted application code, so opt in only to sources you would run in your application. Example IDs and their label, trigger and command relationships are namespaced per specimen; companions can select stable authored hooks such as data-example-id. Width controls resize the inline stage; viewport media queries follow the documentation window.
+
+The writer stages complete files, serializes saves with a project lock, and rolls back the recipe if replacing the CSS fails. If a process stops during a save or build, close the old editor before removing its `.looma/theme-write.lock` or `.looma/docs-build.lock`; restart and save the loaded recipe to regenerate a consistent pair. Change the server base, output directory or theme-file paths by restarting `dev`.
+
+</div>