API Documentation via Custom Elements Manifest (CEM)

[rmenner]

Summary

This document outlines the Auro Design System's migration from Web Component Analyzer (WCA) to Custom Elements Manifest (CEM) as our core documentation generation strategy. This change addresses two critical WCA limitations: inheritance handling gaps and incompatibility with modern package delivery that excludes un-compiled source code. The migration maintains existing API documentation format while enabling future tooling integrations.

Background & Problem Statement

Previous Approach: Web Component Analyzer (WCA)

The Auro Design System previously relied on Web Component Analyzer (WCA) for generating API documentation. While WCA initially served our needs, two critical limitations became increasingly problematic as our component library evolved in complexity and our build/distribution strategy modernized.

Why We Had to Switch

Critical Limitation: Inheritance Support

WCA could not process inherited properties, methods, or attributes from parent classes. This meant that:

• Components extending base classes would have incomplete documentation
• Developers couldn't see the full API surface of components
• Documentation was misleading and incomplete for complex component hierarchies
• Manual documentation maintenance was required to fill gaps

Additionally, as the Auro Design System shifted to a more modern package delivery approach, we no longer shipped un-compiled source code. The old WCA tool could gather JSDoc information because it previously existed in the published packages, but this change in our build and distribution strategy meant WCA could no longer access the necessary source information for proper analysis.

Solution: Custom Elements Manifest (CEM)

What is CEM?

Custom Elements Manifest is a standardized file format for describing custom elements, developed by the web components community. It provides a machine-readable schema that captures the complete API surface of web components, including:

• Properties and attributes
• Methods and events
• CSS custom properties and parts
• Inheritance relationships
• TypeScript types

Key Benefits

1. Industry Standard: Widely adopted format with strong ecosystem support
2. Rich Metadata: Captures comprehensive component information including TypeScript types
3. Tooling Ecosystem: Extensive plugin architecture and community tools
4. Future-Proof: Designed for integration with IDEs, Storybook, framework wrappers, and other tooling

Problems Solved

• ✅ Inheritance Documentation: Addresses WCA's inheritance limitation
• ✅ Modern Package Compatibility: Works with compiled-only packages

Technical Implementation

Core Technology Stack

• Analyzer: @custom-elements-manifest/analyzer - Generates custom-elements.json files from source code
• Custom Tooling: Built custom documentation generator to maintain existing API.md format

Architecture Overview

Source Code (TypeScript/LitElement)
        ↓
@custom-elements-manifest/analyzer
        ↓
custom-elements.json
        ↓
Custom Documentation Generator
        ↓
api.md (existing format)

Implementation Scope

• Coverage: All Auro Design System family of components
• Output Format: Maintains existing api.md structure and formatting
• Compatibility: Preserves current documentation workflow and file locations

Level of Effort

Initial Implementation

• Timeline: ~1 sprint of engineering effort
• Breakdown:
  • Research and tool evaluation: 1-2 days
  • CEM analyzer integration: 1-2 days
  • Custom documentation generator development: 3-4 days
  • Testing and validation: 1 day

Key Implementation Challenges

1. Format Compatibility: No existing CEM tooling produced output matching our established API.md format
2. Solution: Built custom documentation generator to transform CEM data into our preferred format
3. Validation: Ensured output maintains visual and structural consistency with existing documentation

Future Opportunities

Planned Integrations

With CEM as our foundation, we can leverage the rich ecosystem for:

1. Storybook Integration: Automatic knobs and documentation generation
2. IDE Support: Enhanced autocomplete, hover documentation, and type checking
3. Framework Wrappers: Automated React, Svelte, and other framework component generation
4. Linting: Component usage validation in templates
5. Testing: API surface change detection and breaking change prevention

Ecosystem Benefits

• Editor Support: VS Code, IntelliJ, and other IDEs can provide rich custom element support
• Documentation Tooling: Integration with documentation sites and API viewers
• Framework Integration: Simplified wrapper generation for React, Svelte, Vue, etc.
• Cataloging: Potential inclusion in custom elements catalogs and registries

Success Metrics

Primary Success Criteria

• ✅ Format Consistency: Maintains existing api.md format
• ✅ Inheritance Completeness: Inherited members now documented
• ✅ Zero Regression: No loss of existing documentation features

Validation Approach

1. Side-by-side Comparison: Compare new CEM-generated docs with WCA-generated docs
2. Inheritance Verification: Manually verify inherited members are properly documented
3. Format Validation: Ensure markdown structure and styling remain consistent

Technical Details

Custom Elements Manifest Schema

CEM generates a standardized JSON schema containing:

{
  "schemaVersion": "2.1.0",
  "readme": "README.md",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/component.ts",
      "declarations": [
        {
          "kind": "class",
          "name": "ComponentName",
          "tagName": "auro-component",
          "customElement": true,
          "members": [...],
          "attributes": [...],
          "events": [...],
          "superclass": {...}
        }
      ]
    }
  ]
}

Integration Points

• Build Process: CEM analysis integrated into component build pipeline
• Documentation Generation: Custom tooling transforms CEM data to markdown

Conclusion

The migration to Custom Elements Manifest addresses both WCA limitations outlined in our problem statement: inheritance documentation gaps and modern package delivery compatibility.

With minimal implementation effort (1 sprint), we've resolved both documentation issues and established a foundation for enhanced developer experience across the web components ecosystem.

The investment in CEM provides immediate value through complete documentation generation and long-term value through ecosystem compatibility and future integration opportunities.

References

• Custom Elements Manifest Specification
• CEM Documentation Site
• @custom-elements-manifest/analyzer
• Previous Tool: Web Component Analyzer