write-component-jsdocs
/write-component-jsdocs
Guide for writing JSDoc comments on vapor-ui components and their props. Use when adding, reviewing, or fixing JSDoc on component tsx files or css.ts variant files. Covers where to place comments based on component pattern — standalone, compound root, compound sub-part, primitive vs combined part — language and format rules, and a checklist for review. Triggers on requests like add jsdocs, write component docs, document props, jsdoc 작성, or when reviewing a component documentation completeness.
- Author
- goorm-dev ↗
- Repository
- vapor-ui ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Guide for writing JSDoc comments on vapor-ui components and their props. Use when adding, reviewing, or fixing JSDoc on component tsx files or css.ts variant files. Covers where to place comments based on component pattern — standalone, compound root, compound sub-part, primitive vs combined part — language and format rules, and a checklist for review. Triggers on requests like add jsdocs, write component docs, document props, jsdoc 작성, or when reviewing a component documentation completeness.
Arguments
/write-component-jsdocs ComponentName — the PascalCase component name to document (e.g. Button, Dialog, Avatar). Required. When provided, locate
Original author description
Guide for writing JSDoc comments on vapor-ui components and their props. Use when adding, reviewing, or fixing JSDoc on component tsx files or css.ts variant files. Covers where to place comments based on component pattern — standalone, compound root, compound sub-part, primitive vs combined part — language and format rules, and a checklist for review. Triggers on requests like add jsdocs, write component docs, document props, jsdoc 작성, or when reviewing a component documentation completeness.
How it works
- Core rules
- Where to write
- Component summary rules
- Prop description rules
- Review checklist
SKILL.md preview
---
name: write-component-jsdocs
description: Guide for writing JSDoc comments on vapor-ui components and their props. Use when adding, reviewing, or fixing JSDoc on component tsx files or css.ts variant files. Covers where to place comments based on component pattern — standalone, compound root, compound sub-part, primitive vs combined part — language and format rules, and a checklist for review. Triggers on requests like add jsdocs, write component docs, document props, jsdoc 작성, or when reviewing a component documentation completeness.
argument-hint: ComponentName — the PascalCase component name to document (e.g. Button, Dialog, Avatar). Required. When provided, locate the component under packages/core/src/components/{kebab-case-name}/ and apply this guide to those files only.
---
# JSDoc Component Guide
JSDoc in vapor-ui is **user-facing UI**, not internal code comments. Write it for developers who encounter the component for the first time via documentation sites (Storybook Autodocs, etc.).
## Core rules
- **Language**: English only. No Korean in JSDoc blocks.
- **Format**: Put `/**` on its own line and start the text on the next line. Never write a one-line `/** ... */` block, and don't add an empty ` *` line before the text.
- **Placement**: Write the component summary directly above the `export const X = forwardRef(...)` statement — the extractor reads the JSDoc on that statement. Write individual prop descriptions inside the Props interface/type, not on the component.
## Where to write
Placement depends on the component pattern. See [references/guide.md](references/guide.md) for detailed patterns and examples.
| Target | File | Location |
| ----------------- | -------------------- | ----------------------------------------------------- |
| Component summary | `{component}.tsx` | Above `export const X = forwardRef(...)` |
| Individual props | `{component}.tsx` | Inside the `interface` or namespace `Props` |
| Variant groups | `{component}.css.ts` | On each variant key object inside `componentRecipe()` |
**Do NOT write JSDoc on:**
- Individual variant values (`sm`, `md`, `primary`, `fill`, etc.) — the variant key description is sufficient
- `export type XxxVariants` — tooling derives this from the recipe automatically
### Pattern quick-reference
- **Standalone** — no JSDoc on namespace `Props` itself; write variant group docs in `componentRecipe()` in `.css.ts`
- **Compound Root** (custom props via `interface`) — write on the `interface`, namespace wraps it
- **Compound Root with context** (`Assign<…, Context>` pattern) — write only on custom props
- **Compound sub-part** (`Omit<…, keyof Context>` pattern) — write only on remaining props
## Component summary rules
1. One single line — no line breaks inside the summary
2. User perspective: what it is → when to use it
3. No internal terms (`memoized`, `wrapper`, `token-based`, etc.)
4. End with the rendered HTML element using backticks around the tag: "Renders a `<button>` element." or "Doesn't render its own HTML element.".
5. **Primitive vs combined part** — a `XxxPrimitive` part describes the part itself. A part that assembles primitives (e.g. `Tooltip.Popup` over `PortalPrimitive`, `PositionerPrimitive`, `PopupPrimitive`) starts with "Combines `A`, `B`, and `C` into a single part.", then names the `xxxElement` props that replace each piece (if it has any), then the rendered element. See [references/guide.md](references/guide.md#primitive-vs-combined-parts).
## Prop description rules
1. Don't repeat the prop name or its type
2. Describe side effects and interactions with other props
3. For numeric props: include unit and valid range
4. For event handlers: specify the exact trigger condition, not just "handler"
5. Put a default in code, not in JSDoc. The docs table reads `defaultValue` from code: the component's destructuring defaults, a literal written before the props spread, then the `defaultVariants` of the recipe that declares the variant. For a Base UI prop vapor-ui passes through untouched, it falls back to Base UI's own `@default` (see `scripts/docs-extractor/README.md` "Default values"). Never write inline `Default:` text; it stays in the description and repeats the table. Write an `@default` tag only when the extractor can't read the default from code, such as a prop forwarded to another vapor-ui component. A vapor-ui `@default` is dropped from the description and not read as a default, so it shows only in editor hover.
6. `children` — say what goes in the slot, with an example ("Content shown inside the badge, such as a label or count."). For a function child, describe its arguments. Never write just "Children of the component" or restate `ReactNode`.
7. Inherited Base UI props with no description (e.g. `children`, `onClick`) — re-declare the prop in the part's Props `interface` with the Base UI type (`children?: BaseMenu.Trigger.Props['children']`) and write the JSDoc there. The extractor prefers vapor-ui's own declaration. Turn `export type Props = …` into `export interface Props extends … {}` when needed.
8. Repeated props (`size`, `invalid`, `portalElement`, …) — start from the shared phrase in [references/guide.md](references/guide.md#shared-phrases) and add only what differs for that component.
## Review checklist
See the full checklist in [references/guide.md](references/guide.md#checklist).
**Quick checklist:**
- [ ] All JSDoc in English
- [ ] `/**` on its own line, text starts on the next line, no one-line `/** */` blocks
- [ ] Summary is one line, complete sentence, HTML element in backticks (e.g. `` `<button>` ``)
- [ ] Combined parts start with "Combines …" and name their `xxxElement` props
- [ ] No prop name repetition in descriptions
- [ ] `children` says what goes in the slot
- [ ] Event handlers describe exact trigger condition
- [ ] Numeric props include unit and range
- [ ] Shared props (`size`, `invalid`, …) follow the shared phrases
- [ ] No JSDoc on individual variant values (`sm`, `md`, `fill`, `primary`, etc.)
- [ ] No JSDoc on `export type XxxVariants`
- [ ] No inline `Default:` text; `@default` only where the extractor can't read the default from code
Files in this package (2)
- SKILL.md 6 KB
- references/guide.md 17 KB
Versions
The database has no other skills named write-component-jsdocs.
Database snapshot: 13.11.2026 · package version 47496fe3c634 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 96jsdocs
Public API JSDoc. Use when authoring or reviewing Effect API documentation, refining a module's documentation, or fixing documentation related diagnostics. - 100documentation
In-code documentation, folder READMEs, code comments. Use when: "document this", "add JSDoc", "write a README", "explain this code", or writing README.md/JSDoc. - 100maintain-jsdocs
Maintain JSDoc on exported declarations so the generated API reference has zero coverage gaps. Use when: (1) filling or improving JSDoc for exports, (2) running whole-repo or targeted JSDoc maintenance, (3) making gen-api-docs report zero gaps. - 95jsdoc-guide
JSDoc writing rules for AI-powered documentation generation. Use when writing JSDoc, documenting functions, or adding code comments. - 100tonic-ui-types
Use this skill when adding JSDoc type definitions to React components in Tonic UI. Triggers include "add type definitions", "add JSDoc types", "document component props", or when creating new components that need type annotations. - 100jsdoc-comment-generator
Generate jsdoc comment generator operations. Auto-activating skill for Technical Documentation. Triggers on: jsdoc comment generator, jsdoc comment generator Part of the Technical Documentation skill category. Use when working with jsdoc comment generator functionality. Trigger…