luciano-stefano-meloclaps/platform-argentum / .agents/skills/building-components
building-components
VerifiedGuide for building modern, accessible, and composable UI components. Use when building new components, implementing accessibility, creating composable APIs, setting up design tokens, publishing to npm/registry, or writing component documentation.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.1 KB |
| references/accessibility.mdx | markdown | 18.4 KB |
| references/as-child.mdx | markdown | 7.0 KB |
| references/composition.mdx | markdown | 7.1 KB |
| references/data-attributes.mdx | markdown | 11.7 KB |
| references/definitions.mdx | markdown | 10.4 KB |
| references/design-tokens.mdx | markdown | 2.2 KB |
| references/docs.mdx | markdown | 6.2 KB |
| references/marketplaces.mdx | markdown | 5.8 KB |
| references/npm.mdx | markdown | 5.3 KB |
| references/polymorphism.mdx | markdown | 13.6 KB |
| references/principles.mdx | markdown | 4.1 KB |
| references/registry.mdx | markdown | 6.4 KB |
| references/state.mdx | markdown | 3.2 KB |
| references/styling.mdx | markdown | 8.8 KB |
| references/types.mdx | markdown | 5.7 KB |
references/docs.mdx
View on GitHub---
title: Docs
description: How to document your components.
type: guide
summary: Essential documentation sections for components including demos, installation, API reference, accessibility notes, and changelog.
prerequisites:
- /composition
related:
- /registry
- /npm
- /marketplaces
---
Good documentation is essential for making your components accessible and easy to use. This guide outlines the key elements every component documentation page should include.
## Documentation Framework
To scale your documentation, you can use a documentation framework. There are many options available depending on your projects' language and project needs. Popular options include:
- [Fumadocs](https://fumadocs.dev/) - Fast, feature-rich documentation framework for Next.js
- [Nextra](https://nextra.site/) - Markdown-based documentation with built-in search and theming
- [Content Collections](https://content-collections.dev/) - Type-safe content management for documentation
- [Docusaurus](https://docusaurus.io/) - Feature-rich documentation sites with versioning support
- [VitePress](https://vitepress.dev/) - Vue-powered static site generator optimized for documentation
Preferably, your framework choice should support syntax highlighting, custom components and be generally well designed.
## Essential Documentation Sections
### Overview
Start with a brief introduction explaining what the component does and when to use it.
### Demo, Source Code, and Preview
For a great first impression for developers, you should include a demo that shows the component in action, as well as the code used to create the demo.
If you're using an open source [Registry](/registry), you can also include a preview of the source code that is used to create the component.
Use code blocks with syntax highlighting and copy-to-clipboard functionality. Consider using tabbed interfaces to switch between these views without cluttering the page.
### Installation
Include a clear instruction on how to install the component. Preferably this should be a single command you can copy and paste into your terminal.
If you're building on shadcn/ui, you can use the [shadcn CLI](https://ui.shadcn.com/docs/cli) to install the component e.g.
```package-install
npx shadcn@latest add <your-component-url>
```
If you're publishing to a [Marketplace](/marketplaces), you can use the marketplace's CLI to install the component e.g.
```package-install
npx shadcn@latest add https://21st.dev/r/<your-author>/<your-component>
```
If you're not using shadcn/ui but you are building a [Registry](/registry), you could build your own CLI to install the component, e.g.
```package-install
npx your-registry-cli@latest add <your-component-url>
```
Lastly, if you're publishing to npm, you can use the npm CLI to install the component e.g.
```package-install
npm install <your-component-name>
```
<Callout>
To show multiple installation options like we've done above, you can use
something like Fumadocs' [`package-install`
syntax](https://fumadocs.dev/docs/headless/mdx/install).
</Callout>
### Features
List the key features of your component to help users quickly understand its capabilities and advantages. For example:
- **Customizable** – Easily adjust styles, sizes, and behavior to fit your needs.
- **Accessible by default** – Follows best practices for keyboard navigation, ARIA roles, and screen reader support.
- **Composable** – Designed to work seamlessly with other components and patterns.
- **Type-safe** – Ships with comprehensive TypeScript types for maximum safety and autocomplete.
- **Theming support** – Integrates with your design tokens or theme system.
- **Lightweight** – Minimal dependencies and optimized for performance.
- **SSR/SSG ready** – Works with server-side and static rendering frameworks.
- **Well-documented** – Includes clear usage examples and API reference.
Tailor this list to your specific component. Highlight what makes it unique or especially useful for developers.
### Examples
Demonstrate the component's flexibility with practical examples:
- **Variants** - Different visual styles or sizes available
- **States** - Loading, disabled, error, or success states
- **Advanced Usage** - Complex scenarios and edge cases
- **Composition** - How the component works with other components
- **Responsive Behavior** - How it adapts to different screen sizes
Each example should include both the rendered output and the corresponding code.
### Props and API Reference
Document all available props, methods, and configuration options. Consider grouping related props together and highlighting commonly used ones. For each prop, include:
- **Name** - The prop identifier
- **Type** - TypeScript type definition
- **Default** - Default value if not specified
- **Required** - Whether the prop is mandatory
- **Description** - What the prop does and when to use it
<Callout>
If you're using Fumadocs, you might consider using [Auto Type
Table](https://fumadocs.dev/docs/ui/components/auto-type-table) to ensure
accuracy and reduce maintenance burden.
</Callout>
### Accessibility
Document how your component supports accessibility features:
- Keyboard navigation patterns
- ARIA attributes and roles
- Screen reader support
- Focus management
- Color contrast considerations
### Changelog and Versioning
It can be useful to maintain a changelog on each component documentation page covering:
- Version numbers following semantic versioning
- New features and enhancements
- Bug fixes
- Breaking changes
- Migration guides for major version updates
Help users understand what changed between versions and how to upgrade safely. Include code examples showing before/after patterns for breaking changes.
<Callout>
If your syntax highlighting framework supports it (like Shiki), you might want
to use a [diff transformer
notation](https://shiki.style/packages/transformers#transformernotationdiff)
to show the changes between versions.
</Callout>
## Best Practices
- Keep documentation up-to-date with code changes
- Use real-world examples that solve actual problems
- Include common pitfalls and troubleshooting tips
- Provide performance considerations when relevant
- Link to related components and patterns
- Make all code examples runnable and tested
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |