jalco-writing-component-docs - SKILL.md Agent Skill

name: jalco-writing-component-docs description: Write and review jalco ui component documentation with consistent structure, concise descriptions, realistic examples, and registry-aligned metadata. Use when creating new component docs, updating existing docs, reviewing doc quality, or syncing registry-backed component copy.

jal-co/ui Component Docs Skill

Use this skill when creating, editing, or reviewing component documentation in jalco ui.

Canonical reference

The single source of truth for docs page structure, section order, and formatting rules is:

.pi/references/docs-component-format-spec.md

The agent MUST read it before writing or updating any component docs. This skill provides workflow guidance and review steps, not a parallel format definition.

Required reading before changes

.pi/references/docs-component-format-spec.md — page anatomy, section order, writing rules
AGENTS.md — project conventions, quality bar, comment style
.pi/skills/jalco-shadcn-registry/SKILL.md — for registry-backed items

The agent MUST also inspect:

similar component docs already in the repo
the source component and its example/demo files
any related registry metadata

What this skill covers

writing new component docs
revising existing component docs
reviewing docs for clarity and consistency
writing or refining descriptions
keeping registry-backed descriptions in sync

Workflow

Read .pi/references/docs-component-format-spec.md and this skill.
Inspect similar docs pages in app/docs/components/.
Review the component source, public API, and demo files.
Create or update the page using ComponentDocsPage from components/docs/component-docs-page.tsx.
Supply: title, description, registryName, sourceFiles, preview, usage.
Add Examples, API Reference, Notes, or When to use sections as children — only when justified.
Sync description and naming with registry.json and lib/docs.ts.
Ensure a catalog card preview exists at components/docs/previews/<registry-name>.tsx with key variants.
Ensure the sidebar nav entry exists in lib/docs.ts with badge: "New" and badgeAdded set for new components.
Run pnpm previews:generate if the card preview file was created or renamed.
Ensure screenshots exist at public/previews/<name>-dark.png and <name>-light.png.
Review using the checklist in .pi/references/docs-component-format-spec.md.

Quick rules

These are the rules most frequently needed during docs work. For full details, see the format spec.

Descriptions

MUST be one sentence, capability-first
MUST NOT start with "A", "An", or "A React component for..."
MUST NOT contain subjective adjectives
MUST match across: page metadata, ComponentDocsPage props, registry.json

Usage section

MUST include import and minimal usage snippets via CodeLine
Server/client rendering context MUST go here, not in Notes
The first example SHOULD be minimal — layer complexity in Examples

Examples

MUST use VariantGrid with labeled items
MUST group by meaning: Variants, Sizes, Languages, etc.
MUST NOT call everything a variant
SHOULD use realistic content

Notes

MUST contain only caveats, limitations, and external service behavior
MUST NOT include architecture decisions, feature highlights, or rendering context
SHOULD be brief

Bundled exports

MUST use installNote to explain the relationship
MUST set bundledIn on the nav item in lib/docs.ts

Review checklist

Use the checklist in .pi/references/docs-component-format-spec.md before shipping any docs page.

Key things to verify:

Page uses ComponentDocsPage
Description matches across all surfaces
Preview is realistic
Usage includes runtime context
Examples are labeled correctly
Notes contains only caveats
Sidebar entry is correct (title, order, bundledIn)
Catalog card preview exists at components/docs/previews/<registry-name>.tsx