Shared documentation rules across all Naykel projects. Project-specific skills extend this one — apply both, with the project skill taking precedence where they conflict.
Review Workflow
- Mark every new heading with
(review)until its content is confirmed. - When you update a section carrying
(review), ask whether that section is complete. - On confirmation: remove the
(review)tag and update the project status file. - Remove
(wip)from the nav entry once the doc's structure is agreed, even if some sections still carry(review). - Leave
(review)on any headings that are still unresolved. - When all
(review)tags are gone from a doc, it is considered complete. - When closing documentation work, call out which headings or docs still carry
(review)tags.
Common Rules
- One doc, one job. If a page explains the mental model AND lists all properties AND shows a quickstart, split it.
- Code-first. Add prose only when behaviour is non-obvious or context is needed.
Document Structure
- Every doc starts with a title and a short lead.
- Write the lead as
<p class="lead">...</p>. - The lead should say what the page covers and what the reader gets from it.
- Keep it concrete and free of filler.
- Do not add a separate
## Introductionsection.
Nav Management
- When starting work on a doc not yet in the nav, add it in its real category
with
(wip)suffixed to the name so it is accessible during development. - Keep nav labels and sections minimal. Add structure back only as docs are reviewed and agreed.
Rule Files
Read the relevant rule file before responding — do not rely on summaries alone.
Component Docs → rules/component-docs.md
- Single-component pages
- Multi-component pages
- Variants and component families