Documentation standards
Maintain examples, public API references, and guidance from shared sources.
Page structure
Start with the component's purpose and one realistic working example. Follow with minimal usage, focused examples, API reference, behavior and accessibility, and relevant design guidance. Keep related components linked where the choice matters. Scale the length to the component: a separator needs less explanation than a data grid.
Use sentence case for headings and exact exported names in code. Explain state ownership and callback behavior. Describe what ships today. Keep internal Figma reconciliation, implementation history, test reports, and unresolved design questions in the repository's decision archive.
Working examples
Author complete starter examples in packages/pathfinder/documentation/examples/<component>/. Register their IDs in manifest.json and run pnpm --filter @commenda/pathfinder generate:examples. Their source is formatted and used by the rendered preview, Code tab, and Markdown reference. Source generation rejects private fixture imports. Existing navigation and field examples also generate source from their React implementations.
Focused usage snippets may omit application orchestration when the page explains it; they must be labeled as snippets. Never silently substitute another example's code. Missing example IDs fail the documentation build.
Keep stress switches, adversarial data, and test reset controls in Storybook. Documentation examples teach a specific capability. Simulated network operations must say they are simulated. Use subdued explanatory text and a separate action row for necessary demo controls.
API reference
pnpm --filter @commenda/pathfinder-docs generate:api extracts component-owned props from public TypeScript exports. lib/api-notes.json owns the written behavior/default guidance. Update those notes when behavior changes. Conditional requirements depend on modes, controlled state, or label configurations; the published type is authoritative for legal combinations. Native and library-inherited props remain defined by the exported type.
Use ApiReference for generated component APIs and ordinary Markdown tables for comparison or design guidance. Keep types readable: long types expand on demand. Do not invent defaults from TypeScript optionality.
Navigation and links
lib/documentation-catalog.json owns component categories and Figma links. Run pnpm --filter @commenda/pathfinder-docs generate:navigation after changes. Generated metadata supplies Fumadocs navigation without runtime regrouping. Keep existing page URLs stable.
AI reference
The MDX transformer exports examples and API tables as Markdown without replacing their live HTML components. Human and AI docs share the same source. The index is available at llms.txt, with a full reference. Stable design-rule IDs stay with their relevant component; internal conflict history lives in the repository archive.
Verification
Run Pathfinder lint, tests, and types; regenerate/check examples, navigation, and API data; build Fumadocs and Storybook. Check source links, rendered tables, keyboard tabs, copy behavior, narrow screens, and accessibility. Review a simple, stateful, and complex page. Test evidence records the browser and limits of coverage.
Object props and unions
Use one prop per row, with separate Type and Behavior columns. Do not group independent props or combine prose and type signatures in a single cell.
The generated API reference links object props to field disclosures. Each shape lists its fields and requirements; excluded fields describe mutually exclusive alternatives. Use the exported TypeScript declarations for the complete signature; do not repeat a type-alias name in a definition disclosure. Native/third-party types remain opaque; the generator only expands package-owned objects, to three levels. Document array element models and deeper recursive structures explicitly on the owning component page, as Dropdown does.
Add prose examples for meaningful choices. For example, labelConfig={{ optionalLabel: 'Optional' }} and labelConfig={{ help: 'Use the legal entity name' }} are alternatives; do not combine them. Never invent an exported type name for an anonymous object. Defaults come from reviewed behavior notes, not TypeScript optionality.
Source formatting
Follow Formatting and linting for spacing, imports, generators, and editor setup. Run pnpm pathfinder:format before the documentation verification commands.