ncdai-writing-component-docs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Writing component documentation

Guide for writing concise, consistent component documentation for this project's registry. Covers MDX doc structure, description writing, Features sections, Composition sections, Credits sections, and References sections.

## Key files

- Component docs: `src/features/doc/content/components/{component-name}.mdx`
- Registry items: `src/registry/components/_registry.ts`
- Description must be kept in sync between both files.
- The doc's category (`components`) is derived from the `components/` subfolder, not declared in frontmatter.

## MDX document structure

Component docs follow this section order. Only include sections that are relevant. Headings use sentence-case (capitalize only the first word and proper nouns); the fixed section names below already follow this, and any custom heading must too.

```
---
title: Component Name
description: One concise sentence about what the component does.
image: https://assets.chanhdai.com/images/blog/{component-name}.webp
createdAt: YYYY-MM-DD
updatedAt: YYYY-MM-DD
---

<ComponentPreview name="{component-name}-demo" />

## Features            (optional -- skip if component is self-explanatory)

## Installation

## Usage

## Composition         (optional -- only for compound/composable components)

## API reference       (optional)

## Examples            (optional)

## Credits             (optional -- for inspiration/original sources)

## References          (optional -- for technical reading and implementation details)
```

## Writing descriptions

The `description` field appears in MDX frontmatter AND the registry item. Both must match.

### Rules

1. One short sentence -- focus on WHAT the component does, not HOW it is built.
2. Start with a verb or noun. Never start with "A", "An", or "A React component for...".
3. Drop implementation details like "built with Motion" or "using Tailwind CSS".
4. Keep it under ~80 characters when possible.

### Good examples

```
Toggle between system, light, and dark themes in Next.js apps.
Animated text that cycles through items with a smooth flip transition.
Interactive slider inspired by the classic iPhone "slide to unlock" gesture.
Scrolling marquee to showcase user testimonials.
Display install commands with package manager switcher and copy button.
Copy text to clipboard with visual feedback and animation.
```

### Bad examples

```
A React component for managing user consent for cookies and tracking in Next.js applications.
  --> Too long, starts with "A React component for..."

Animated text component that cycles through items with a smooth flip transition built with Motion for React.
  --> "component" is redundant, "built with Motion for React" is implementation detail

A sleek, interactive slider inspired by the classic iPhone OS "slide to unlock" gesture.
  --> Starts with "A sleek", subjective adjective
```

## Writing Features sections

### When to include

Add `## Features` when the component has non-obvious capabilities that the title, description, and preview alone cannot convey. Examples: multi-mode support, special interactions, keyboard navigation, persistence, composability.

### When to skip

Skip `## Features` when the component is self-explanatory through its title + description + preview + usage. Examples: Theme Switcher, Shimmering Text, Apple Hello Effect.

### Rules

1. Use exactly `## Features` as the heading (not "About", not "Overview").
2. Write 2-4 bullet points, one line each.
3. Start each bullet with the capability, not filler words.
4. End each bullet with a period.
5. No emoji.
6. Do not repeat information already in Installation, Usage, or API reference.
7. Describe WHAT the user gets, not HOW it is implemented. Do not name libraries, framework APIs, hooks, or internal data flow. A technical detail is worth keeping only when rephrased as a user-facing benefit (for example "caches results for a day" instead of "uses `unstable_cache` with `revalidate: 86400`").
8. Do not put attribution here. "Built on X" or "inspired by Y" belongs in `## Credits`; links that explain how something works belong in `## References`.

### Good example

```markdown
## Features

- Content fades in and out smoothly as you scroll.
- Supports both vertical and horizontal scrolling.
```

### Bad example

```markdown
## About

The Scroll Fade Effect component is built on top of CSS animation-timeline.

- 📱 Smooth scrolling fade effect
- 🎨 Customizable with Tailwind CSS
- ⚡️ Easy installation via shadcn CLI
```

From Vishwajeetsrk/Myraa, MIT.

More from Vishwajeetsrk/Myraa