| name | readme-docs |
| version | 1.0.0 |
| description | Write README.md files for hyperfrontend libraries and sub-modules. Use when creating library documentation, writing sub-module READMEs, documenting API tables, adding quick start guides, or reviewing README structure compliance. |
README Docs
Create README.md files—library root for consumers, sub-module for maintainers.
Reference Locations
| Item | Path |
|---|
| Library README | libs/<name>/README.md |
| Sub-module README | libs/<name>/src/<module>/README.md |
| Library ESLint | lib-readme-structure |
| Submodule ESLint | docs-site-secondary-entries |
| Submodule README | lib-pkg-secondary-entry-readme |
Document Types
| Type | Location | Audience | Focus |
|---|
| Library README | libs/<name>/README.md | Consumers | Value prop, install, quick start |
| Sub-module README | libs/<name>/src/<mod>/README.md | Consumers | Intent, design, examples — NO API list |
The sub-module page renders this README plus an auto-generated scoped API reference. Manual API tables would duplicate the rendered ref.
Library README Structure
Required sections (in order):
## What is @hyperfrontend/<name>?
### Key Features### Architecture Highlights
## Why Use @hyperfrontend/<name>?## Installation## Quick Start## API Overview## Compatibility
Required badges:
[](...)
[](...)
[](...)
[](...)
[](...)
[](...)
[](...)
[](...)
[](...)
Required links:
• 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/<name>/)
• 👉 See [**roadmap**](https://github.com/AndrewRedican/hyperfrontend/blob/main/roadmap/<name>/)
Sub-Module README Structure
Required (the floor):
# moduleName
One-sentence statement of what this module does and why it exists.
Optional sections — add when the module's complexity warrants them:
| Section | When to add |
|---|
## Overview | Multi-step pipelines, mermaid diagrams |
## Usage | Composition examples beyond a single signature |
## Configuration | User-facing config knobs that need explanation |
| Semantic tables | Taxonomies, decision rules, behavior contracts |
| Mermaid diagram | Data flow, state machines, dependency relations |
## Design | Trade-offs, invariants, "why this and not that" |
Do NOT include:
## API table listing exports (the page renders this automatically below your README).- "Key Interfaces" code blocks duplicating typedoc-extractable types.
- Installation, npm install commands (consumer-facing — belongs in library README).
Validation
npx nx lint <project>
| Rule | Enforces |
|---|
lib-readme-structure | Library-root README sections, badges, links |
docs-site-secondary-entries | Every secondary entrypoint has a page.tsx + sidebar nav |
lib-pkg-secondary-entry-readme | Every secondary entrypoint has a README with H1 (matching basename) + description |
docs-site-library-docs | Every library README has a corresponding docs-site page |
Checklist
Library README:
Sub-module README:
