Requirements Catalog Overview

The requirements catalog is the project’s single source of truth for what must, should, or may be built. Every verifiable obligation or recommendation is captured as a structured record in src/core/config/requirements.catalog.ts. Documentation references requirements — not the reverse (REQ-00122).

Who this is for

• Implementors tracing work items back to canonical requirements
• Developers modifying requirements or integrating the requirements browser into docs

What the catalog contains

The catalog holds approximately 207 canonical requirements. Each requirement defines a single normative statement along with metadata for classification, lifecycle tracking, and cross-referencing. The file is TypeScript, typed against the CanonicalRequirement interface in requirements.schema.ts, so schema violations are caught at compile time.

Requirement structure

Every requirement record contains the following fields:

Field	Purpose
id	Stable canonical identifier (REQ-XXXXX). IDs are sequential and never reused, even after retirement.
scope	Breadth of applicability: global (project-wide), system (subsystem), or topic (single topic area).
scopeKey	Bucket category (e.g., rendering, design-system, component-system). Required when scope is global or system; omitted for topic.
classification	Kind of requirement: functional, non-functional, architectural, validation, documentation, governance, or security.
level	Normative strength: required, recommended, or optional.
ownerTopic	Primary topic responsible for the requirement (e.g., accessibility, design-tokens, layout-structure).
relatedTopics	Optional. Additional topics materially impacted by the requirement.
status	Current lifecycle position (see below).
statement	The normative requirement text — the single sentence that defines the obligation.
rationale	Why the requirement exists.
appliesTo	Optional. Array of DOC-XXXXX IDs linking the requirement to relevant documentation pages.
tags	Optional. Descriptive tags for filtering and grouping.
dependsOn	Optional. Other requirement IDs that must be satisfied first.
relatedRequirements	Optional. Associated requirements for informational cross-linking.
notes	Optional. Non-normative implementation hints or context.

Lifecycle statuses

Requirements move through a defined lifecycle. The statuses, in typical progression order:

1. idea — Captured but not yet evaluated.
2. evaluating — Under active review; feasibility or priority being assessed.
3. accepted — Approved for implementation but not yet scheduled.
4. planned — Scheduled in a work package with a defined scope.
5. in-progress — Active development underway.
6. implemented — Code shipped and acceptance criteria met.
7. enforced — Implemented and verified by automated validation (lint, test, CI).
8. normative — Permanently active policy, scope boundary, or intrinsic constraint. Always in force; never deliverable as a discrete work item.

Terminal and exceptional statuses:

• deferred — Approved but postponed to a future milestone.
• rejected — Evaluated and decided against; will not be implemented.
• deprecated — Was once implemented but is being phased out.
• retired — Fully removed; kept in the catalog for historical record.

Note: Status changes require project owner approval (REQ-00138). Never modify a requirement’s status without explicit sign-off.

Using the requirements browser

Navigate to /theme-docs/requirements/ for the filterable index page. The browser supports filtering by:

• Status — Show only requirements in a specific lifecycle state.
• Classification — Filter by functional, architectural, validation, etc.
• Level — Filter by required, recommended, or optional.
• Owner topic — Show requirements owned by a specific topic area.
• Scope — Filter by global, system, or topic scope.
• appliesTo — Filter to requirements linked to a specific documentation page.

URL state is shareable — copy the filtered URL to share a specific view with others.

Click any requirement ID to see its full detail page at /theme-docs/requirements/REQ-XXXXX/.

Requirements-to-docs linkage

The appliesTo field on each requirement connects it to the documentation pages where it is most relevant. Documentation pages automatically display their linked requirements when showRequirements is enabled in frontmatter (the default for docs).

The linkage direction is requirement-controlled: the requirement declares which docs it applies to, and doc pages look up requirements by matching their own docId. This keeps the requirements catalog as the single point of maintenance for cross-references.

Adding or modifying requirements

Requirements are defined in TypeScript using the CanonicalRequirement type exported from requirements.schema.ts. To add a new requirement:

1. Determine the next sequential ID (REQ-XXXXX with zero-padded 5-digit number).
2. Define all required fields: id, scope, classification, level, ownerTopic, status, statement, and rationale.
3. Add optional fields (appliesTo, tags, dependsOn, relatedRequirements, notes) as appropriate.
4. Place the new entry in the requirements array in requirements.catalog.ts.

Status changes and new requirements both require project owner approval before committing.