---

name: write-demos description: > Write demo HTML files for custom elements that work with cem serve. Use when the user asks to "write a demo", "create a demo", "add a demo", "demo file", "demo page", or mentions "cem serve demos". tools: Read, Glob, Grep, generate_html

Write Element Demos

Critical: Demos Are Partials

Never include <!DOCTYPE>, <html>, <head>, or <body>. The dev server wraps partials with its own document shell, import maps, and live reload. Adding document structure breaks rendering.

Workflow

1. Gather Context

Read the element's manifest data (cem://element/{tagName} and sub-resources) and check .config/cem.yaml for:

• generate.demoDiscovery — fileGlob determines where demos live; urlPattern captures path segments with :param; urlTemplate builds served URLs from those params (supports alias, slug, lower, upper template functions). Example: elements/rh-card/demo/sizes.html with urlTemplate: /elements/{{.tag | alias}}/demo/{{.demo}}/ serves at /elements/card/demo/sizes/. Index demos become the directory root.
• serve.urlRewrites (if present) — maps served URLs back to filesystem paths when they differ (e.g., /elements/card/... to /elements/rh-card/...). Most projects don't need this. Check if configured, and set up if asked.
• serve.importMap — bare specifiers need to be in dependencies or the import map config

2. Write Demos

Place files where fileGlob expects them (typically elements/my-el/demo/).

Index demo — simplest possible usage, no metadata needed:

<script type="module">
  import '../my-button.js';
</script>

<my-button>Click Me</my-button>

Feature demos — one feature per file, with metadata:

<meta itemprop="name"
      content="With Icon">
<meta itemprop="description"
      content="Button with a leading icon in the icon slot">

<script type="module">
  import '../my-button.js';
  import '../../my-icon/my-icon.js';
</script>

<my-button variant="primary">
  <my-icon slot="icon"
           name="check"></my-icon>
  Save Changes
</my-button>

Multi-element demos — use demo-for to associate with specific elements:

<meta itemprop="demo-for"
      content="my-button my-icon">

3. Validate

Call validate_html on the demo content, then verify:

• No document shell tags
• Script imports resolve (relative paths from demo file to source)
• <meta> tags use itemprop, not name or property

Common Mistakes

| Mistake | Fix | |---------|-----| | Adding <!DOCTYPE> / <html> | Demos are partials | | <meta name="description"> | <meta itemprop="description"> | | Absolute import paths | Relative from demo file to source | | Importing from devDependencies | Move to dependencies | | External CSS/JS links | Inline styles and scripts | | Everything in one file | One feature per demo | | Missing type="module" | Always <script type="module"> |

Guidelines

• Index is minimal: default demo should be copy-paste simple
• Self-contained: inline all CSS and JS
• One feature per file: variants, states, features get separate demos
• Use generate_html: produce valid element markup via the MCP tool