The Source of Truth: Authoring Component Documentation

In the Espalier system, we do not write documentation files manually for our components. Instead, we utilize JSDoc comments within our Lit Element source files to generate a Custom Elements Manifest (CEM). This manifest acts as the "Source of Truth" for the entire design system, driving our static site, IDE autocomplete, and eventual design-tool integrations.

By authoring documentation alongside the implementation, we eliminate the risk of "Documentation Drift" and ensure that our API is always self-describing.

The Anatomy of a Component Comment

Every Espalier component must begin with a block comment (/**... */) placed immediately above the class definition. This comment should use Markdown to describe the component's purpose and include specific tags that the CEM analyzer can parse.

/**
 * A versatile button component that supports various visual 
 * variants and reactive states.
 * 
 * @tag esp-button
 * @summary Primary action trigger for user interfaces.
 */
@customElement('esp-button')
export class EspalierButton extends LitElement {... }

Supported Documentation Tags

To create a defensible and helpful API, you must document the following interactive surface areas using these standard tags:

1. Properties and Attributes

• @prop {type} name - description: Documents a JavaScript property.
• @attr {type} name - description: Documents an HTML attribute.
• @default value: Specifies the initial value.

2. Composition and Slots

• @slot - description: Documents the default, unnamed slot.
• @slot name - description: Documents a named slot (e.g., prefix or suffix).

3. Events and Interactivity

• @fires event-name - description: Documents a custom event dispatched by the component. This allows consumers to know exactly which listeners to attach.

4. Styling API (Shadow DOM)

• @cssprop --variable-name - description: Documents a CSS Custom Property that can be used to theme the component.
• @csspart part-name - description: Documents a Shadow Part that can be styled via the ::part() pseudo-element.

Markdown in JSDoc

The descriptions within your tags are parsed as Markdown. You are encouraged to use:

• Bold and Italics for emphasis.
• In-line `code` for variable names.
• Unordered lists for complex requirements.

Challenge the Assumption: "Type Definitions are Documentation"

A common assumption in modern development is that TypeScript interfaces are enough to document a component. We challenge this. A type definition (like string) tells a developer what the data is, but it doesn't explain Why it exists, When to use it, or How it affects the UI.

For a defensible architecture, every public member must have a human-readable description in Markdown.

Strategic Impact: The Manifest Ecosystem

Authoring documentation via JSDoc tags unlocks the "Manifest Ecosystem":

• IDE Support: Developers using VS Code get "hover docs" and autocomplete for your component's attributes and CSS properties.
• Automated READMEs: We can generate consistent GitHub documentation directly from the source code.
• Figma Connectivity: The manifest can be used to map code properties to Figma components, creating true parity between design and engineering.