Component Specification Standard¶
This standard defines the required structure for any reusable component specification — a piece that exists to be reused across products or within a product, rather than sold independently (see the definition of "component" in docs/company/terminology.md).
Required sections¶
- Component ID — a stable identifier, kebab-case, scoped to the venture or product that owns it (see
docs/standards/naming-standard.md). - Capability — a one- or two-sentence statement of what this component does.
- Purpose — why the component exists as a separate, reusable piece rather than being built once inline.
- Inputs — what the component takes in (data, configuration, user interaction, upstream dependency).
- Outputs — what the component produces or returns.
- Configuration — any options or parameters that change the component's behavior across different consumers.
- Compatibility target — what environment(s), platform(s), or product type(s) the component is built to work within (e.g., "web app using [framework]," "Excel 2016 and later without macros").
- Known limitations — constraints, edge cases, or deliberately unsupported scenarios.
- Candidate products/consumers — which products currently use, or are expected to use, this component.
- Status — one of:
proposed,specified,in-development,tested,reusable,deprecated.
Status values¶
proposed— the component has been identified as potentially useful but is not yet specified in detail.specified— this specification is complete enough to build from, but the component does not exist yet.in-development— actively being built.tested— built and verified against its specification, but not yet confirmed reusable across more than one consumer.reusable— in active use by two or more consumers (or explicitly confirmed reusable even if only one consumer exists so far), and stable.deprecated— no longer recommended for new use; existing consumers should plan to migrate off it.
Placement¶
A component specification lives wherever it is actually reused: inside the owning product's directory if it is product-specific, inside a venture's shared area if reused across that venture's products, or in a company-wide shared location only where genuine cross-venture reuse is expected (which, per docs/architecture/company-venture-product-model.md, is expected to be uncommon given that ventures may use entirely different technology stacks).
Front matter¶
Every component specification uses the standard document metadata front matter (see docs/governance/document-metadata-standard.md), with document_type: specification.