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:

{
  "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:

<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:

{
  "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:

<!--
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 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