Skip to content

Component Specification Template

This is a template. This directory (components/_template/) is the scaffold for specifying a new Digital Products component in full detail, beyond a single catalog row. It establishes no policy of its own and describes no implemented component.

When to use this scaffold

Use it when a component in ../component-catalog.md needs a full specification — typically once more than one product wants to depend on it, or once it is being seriously considered for implementation. Simple, still-hypothetical ideas can stay as a single catalog row until then.

How to use this scaffold

  1. Copy this directory to the matching category directory, e.g. components/dashboards/executive-dashboard-layout/, naming the new directory after the component's slug.
  2. Fill in every file: component.json, component-specification.md, interface-contract.md, implementation-notes.md, compatibility.md, test-plan.md, examples.md, changelog.md.
  3. Keep the Component ID consistent with its row in ../component-catalog.md — do not assign a new ID; reuse the one already in the catalog.
  4. Do not mark status beyond proposed without a reviewed, human decision. specified means fully documented but unbuilt; implemented means built and verified in at least one shipped product. An AI agent must never advance a component's status unilaterally.
  5. Update ../component-catalog.md to note that a full specification now exists for this component (e.g. link to the new directory) once created.

Files in this scaffold

  • component.json — machine-readable component record.
  • component-specification.md — the core specification (capability, purpose, inputs, outputs, configuration, compatibility, limitations, candidates, status).
  • interface-contract.md — the implementation-agnostic contract the component exposes (named ranges expected/provided, expected cell formats).
  • implementation-notes.md — placeholder for actual Excel/formula implementation notes once built; empty until then.
  • compatibility.md — compatibility target and tested platforms (empty until tested).
  • test-plan.md — test cases for the component in isolation.
  • examples.md — usage examples once implemented (placeholder, not populated yet).
  • changelog.md — Keep-a-Changelog-style empty log.

This is a template. Replace bracketed placeholders in each file. This file itself establishes no policy.

Report an issue about this page