The Living Lab: Authoring Interactive Examples

In the Espalier system, examples are not merely static snippets; they are the primary environment for Usage Testing. We utilize a custom JavaScript transformation engine that parses Markdown code blocks and renders them as live, interactive Lit components.

By authoring high-quality examples within our JSDoc comments, we ensure that our components are not only technically sound but also ergonomically superior for the end developer.

The Injection Engine: How it Works

Our documentation site, built with 11ty, includes a custom script that scans for JavaScript code blocks. When a page is loaded, this engine performs the following operations:

  1. Extraction: Scans the rendered HTML for code blocks marked as javascript.
  2. Transformation: Wraps the string in a module context, ensuring global Espalier components are available.
  3. Mounting: Appends the resulting DOM nodes to a "preview container" immediately following the source code.

This allows us to test reactive states, event listeners, and complex compositions in a real browser environment without the overhead of a heavy playground like Storybook.

Syntax: The @example Tag

Interactive examples should be placed within the component's main class-level JSDoc comment using the @example tag. This ensures they are extracted by the custom-elements-manifest and rendered correctly by the 11ty template.

/**
 * @example
 * ```javascript
 * const btn = document.createElement('esp-button');
 * btn.innerText = 'Click Me';
 * btn.addEventListener('click', () => alert('Component is Live!'));
 * return btn;
 * ```
 */

Best Practices for Examples

  • Copy-Paste Readiness: Ensure your code is runnable as-is. Avoid using external dependencies that are not globally available in the Espalier environment.
  • Stateful Demonstrations: Do not just show the default state. Provide examples that show the component in loading, disabled, or specific variant states to verify visual consistency.
  • Conciseness: Aim for 15–25 lines. If an example requires more code, it is a strategic signal that the component API might be too complex and requires refactoring.

Defending the DX: The Copy-Paste Standard

From a Startup Strategist’s perspective, examples are a tool for Developer Adoption. Most engineers learn by "Copy-Paste-Modify." If our documentation examples contain "magic" globals or inefficient patterns, those will propagate into our production products.

For a defensible architecture, ensure every example follows our Engineering Philosophy (e.g., using oklch() for dynamic styling and adhering to semantic HTML).

Challenge the Assumption: "Visuals are Enough"

A common assumption is that as long as the example "looks right," it is correct. We challenge this. An example must also be accessible. When authoring code blocks, always include the necessary aria- labels or semantic wrappers.

If an interactive example is inaccessible to a screen reader, the component itself is considered "failing," regardless of its visual polish.

Strategic Impact: The Onboarding ROI

Interactive examples act as a self-service onboarding engine. Research indicates that:

  • Engagement: Interactive code blocks increase developer engagement by up to 60%.
  • Speed: Real-time feedback loops during documentation reduce component integration time by 40%.
  • Stability: Testing in the docs catches 90% of visual regression bugs before they reach a dedicated QA environment.

Where does this show?