FRD: createComponentDocs Coverage

Field	Value
ID	FRD-040
Owner	David Holmes
Status	Draft
Priority	P1 — Developer Experience
Size	L (Refactor)
Target Release	v2.0.0
Last Updated	2026-05-26

Document Summary

Achieve 100% coverage of createComponentDocs across every story file in the design system. Every *.stories.tsx file must call createComponentDocs with meaningful values for summary, whenToUse, whenNotToUse, and accessibility fields. The pnpm run dx:audit command must report zero violations for missing or empty documentation fields.

Introduction

Overview

createComponentDocs (defined in src/lib/storybook-docs.ts) is the canonical way to attach structured documentation metadata to a Storybook story. It powers the docs page summary, “When to use” / “When not to use” guidance, accessibility notes, and the LLM MCP contract. Today, many story files either do not call createComponentDocs at all or call it with empty/placeholder values, leaving developers without the guidance they need to choose and use components correctly.

Goals

Every *.stories.tsx file calls createComponentDocs in its meta configuration.
The summary field contains a concise 1-2 sentence description of the component’s purpose.
The whenToUse field describes at least two concrete scenarios where the component is appropriate.
The whenNotToUse field describes at least one scenario where a different component is a better choice.
The accessibility field documents keyboard behavior, ARIA roles, and screen reader expectations.
pnpm run dx:audit enforces all of the above with zero tolerance.

Non-Goals

Rewriting component implementations or APIs.
Adding new components.
Changing the createComponentDocs function signature (unless a field is missing).
Migrating to a different documentation framework.

Scope

In Scope

Item	Description
Story file audit	Identify every `*.stories.tsx` file missing `createComponentDocs` or with empty required fields
Documentation authoring	Write `summary`, `whenToUse`, `whenNotToUse`, and `accessibility` content for each component
Audit script rules	Add detection for missing `createComponentDocs` call and empty required fields to `scripts/checks/audit-story-dx.mjs`
CI enforcement	`pnpm run dx:audit` blocks merge on missing documentation

Out of Scope

Item	Reason
Optional `createComponentDocs` fields	Fields like `dummyData`, `motion`, `courtRules` are domain-specific and not universally required
MDX documentation pages	MDX pages are authored separately and not governed by `createComponentDocs`
Component visual changes	This is a documentation-only effort

Users and Pain Points

User	Pain Point
Application developer	Opens a component docs page and sees no usage guidance — unclear when to use vs. alternatives
Application developer	No accessibility notes — must read source code to understand keyboard and screen reader behavior
Design system maintainer	Inconsistent documentation quality across components
LLM agent (MCP consumer)	Missing `summary` and `whenToUse` fields degrade the quality of LLM-generated integration code

Definitions

Term	Definition
createComponentDocs	Factory function in `src/lib/storybook-docs.ts` that generates Storybook `parameters.docs` configuration
Required fields	`summary`, `whenToUse`, `whenNotToUse`, `accessibility` — must be non-empty strings
LLM MCP contract	Structured metadata emitted by `createComponentDocs` for consumption by LLM tool-use agents

Current State

createComponentDocs exists and is used by some story files (observed in widgets like user-menu.stories.tsx, activity-feed-widget.stories.tsx, global-search-bar.stories.tsx).
Many UI component stories in src/components/ui/ do not use createComponentDocs at all.
The dx:audit script checks some documentation aspects but does not enforce the presence of all four required fields.
There is no inventory of coverage percentage.

Proposed Solution

Phase 1: Inventory

Extend scripts/checks/audit-story-dx.mjs to report on createComponentDocs coverage:

Detect story files that do not import or call createComponentDocs.
Detect calls where summary, whenToUse, whenNotToUse, or accessibility is missing or empty.
Produce a coverage report with counts and percentages.

Phase 2: Author documentation

For each non-compliant story file:

Read the component source to understand its purpose, API, and accessibility behavior.
Write a summary (1-2 sentences describing what the component does and when it is useful).
Write whenToUse (2+ concrete scenarios as a markdown list).
Write whenNotToUse (1+ scenarios with recommended alternatives).
Write accessibility (keyboard interactions, ARIA roles, screen reader announcements).
Add the createComponentDocs call to the story meta’s parameters.

Phase 3: Enforce in CI

Remove any --warn-only exception for documentation coverage rules. Ensure pnpm run dx:audit exits non-zero on any missing documentation.

Requirements

ID	Requirement	Priority
REQ-01	Every `*.stories.tsx` file must call `createComponentDocs`	Must
REQ-02	`summary` field must be a non-empty string of at least 20 characters	Must
REQ-03	`whenToUse` field must be a non-empty string	Must
REQ-04	`whenNotToUse` field must be a non-empty string	Must
REQ-05	`accessibility` field must be a non-empty string	Must
REQ-06	`pnpm run dx:audit` must detect and report all violations	Must
REQ-07	Optional fields (`dummyData`, `motion`, etc.) should be filled when applicable	Should

Functional Requirements

ID	Description	Acceptance
FR-01	Audit script detects story files without `createComponentDocs`	Lists all non-compliant files
FR-02	Audit script detects empty required fields	Lists file, field name, and current value
FR-03	Audit script reports coverage percentage	Outputs `X/Y stories compliant (Z%)`
FR-04	Each component’s docs page shows summary, when to use, when not to use, and accessibility sections	Visual verification on 10 sample components

Non-Functional Requirements

ID	Description	Target
NFR-01	Audit script execution time	Under 10 seconds
NFR-02	Documentation accuracy	Every `summary` and `whenToUse` must be reviewed by a human for correctness
NFR-03	Consistency	Documentation follows a consistent voice and format across all components

API/Interface Requirements

Interface	Requirement
`createComponentDocs`	No API changes required; existing signature supports all required fields
`scripts/checks/audit-story-dx.mjs`	New rules: `missing-component-docs`, `empty-summary`, `empty-when-to-use`, `empty-when-not-to-use`, `empty-accessibility`

Accessibility Requirements

ID	Requirement
A11Y-01	Every component’s `accessibility` field must document keyboard interactions (Tab, Enter, Escape, Arrow keys as applicable)
A11Y-02	Every component’s `accessibility` field must document ARIA roles and properties used
A11Y-03	Every component’s `accessibility` field must document screen reader announcements and live region behavior where applicable

Content and Documentation Requirements

ID	Requirement
DOC-01	Create a style guide for writing `createComponentDocs` fields (tone, length, format)
DOC-02	Add `createComponentDocs` requirement to the “How to Write a Story” guide
DOC-03	Document the new audit rules in the `scripts/checks/audit-story-dx.mjs` JSDoc header

Dependencies

Dependency	Type	Risk
`src/lib/storybook-docs.ts`	Internal	Function signature must remain stable during the documentation push
`scripts/checks/audit-story-dx.mjs`	Internal	Must be extended before bulk authoring begins
Component source code	Internal	Documentation accuracy depends on reading current implementation

Risks and Tradeoffs

Risk	Impact	Mitigation
Large number of story files (~150+)	Slow delivery	Batch by component directory; prioritize high-usage components first
Documentation may become stale as APIs evolve	Inaccurate guidance	CI audit catches empty fields; PR reviewers check accuracy on component changes
Subjective quality of documentation content	Inconsistency	Publish a style guide before bulk authoring; review a sample set for calibration
LLM-authored documentation may have inaccuracies	Misleading guidance	Human review required for every batch

Open Questions

#	Question	Status
1	Should `accessibility` be required for purely decorative components (Divider, Skeleton)?	Open
2	Should we require `relatedComponents` as a fifth required field?	Open
3	What minimum character count should be enforced for `whenToUse` and `whenNotToUse`?	Open

Acceptance Criteria

pnpm run dx:audit reports zero violations for createComponentDocs coverage.
Every *.stories.tsx file imports and calls createComponentDocs.
Every summary field is a non-empty, accurate description (20+ characters).
Every whenToUse field lists at least two concrete use cases.
Every whenNotToUse field lists at least one alternative with rationale.
Every accessibility field documents keyboard behavior and ARIA usage.
CI pipeline blocks merge on any new missing-documentation violation.

LLM Handoff Instructions

When an LLM agent picks up this FRD:

Run pnpm run dx:audit to get the current list of non-compliant story files.
Read src/lib/storybook-docs.ts to understand the createComponentDocs API and its field semantics.
For each non-compliant story file, read the corresponding component .tsx file to understand its purpose, props, and accessibility behavior.
Write documentation following these guidelines:
- summary: “A [component type] that [what it does]. Use it to [primary use case].”
- whenToUse: Markdown list of 2+ scenarios with brief explanations.
- whenNotToUse: Markdown list of 1+ scenarios with recommended alternatives.
- accessibility: Document keyboard interactions, ARIA roles, and screen reader behavior.
After fixing a batch, run pnpm run dx:audit and pnpm typecheck to verify.
Do not modify component implementations — only story files and the audit script.

Decision Log

Date	Decision	Rationale
2026-05-26	Require four fields: summary, whenToUse, whenNotToUse, accessibility	These four provide the minimum useful documentation for component selection and integration
2026-05-26	Extend existing audit script rather than a separate linter	Single tool for all DX audit rules reduces CI complexity

Document History

Date	Version	Author	Changes
2026-05-26	0.1	David Holmes	Initial draft