AgentSkillsCN

component-building

组件构建指南，用于打造高质量、无障碍且可组合的注册表组件。在涉及组件构建、新增或构建区块、新区块、注册表组件的任务时触发。在src/registry/中工作时使用此功能。

SKILL.md
--- frontmatter
name: component-building
description: Component building guidelines for creating high-quality, accessible, and composable registry components. Triggers on tasks involving building a component, adding or building a block, new block, registry component. Use when working in src/registry/.
license: MIT
metadata:
  author: shadcraft
  version: "1.0.0"

Component Building Guidelines

Comprehensive component authoring guide for building registry components that follow shadcn/ui patterns, emphasizing composition, accessibility, type safety, and maintainability.

When to Apply

Reference these guidelines when:

  • •Creating new components in src/registry/
  • •Building blocks that compose shadcn/ui primitives
  • •Reviewing component code for patterns and best practices
  • •Refactoring existing registry components

Rule Categories

CategoryDescriptionFile
CompositionComponent composition patternscomposition.md
AccessibilityInclusive, usable componentsaccessibility.md
State ManagementControlled/uncontrolled patternsstate-management.md
Design TokensSemantic theming architecturedesign-tokens.md
Styling PatternsTailwind CSS and class managementstyling-patterns.md
TypeScript PatternsType-safe, flexible componentstypescript-patterns.md
PolymorphismThe as prop patternpolymorphism.md
asChild PatternRadix Slot compositionas-child-pattern.md
Data AttributesState and structure via data-*data-attributes.md
DocumentationComponent docs standardscomponent-documentation.md

Quick Reference

Core Principles

  1. •Default to shadcn/ui + Radix primitives - Don't rebuild what exists
  2. •Composition over configuration - Split into focused parts (Root, Trigger, Content)
  3. •Semantic HTML first - Use appropriate elements, add ARIA only when needed
  4. •Single element wrapping - Each component wraps one element for composability
  5. •Extend native attributes - Use React.ComponentProps<'element'> patterns
  6. •Data attributes for state - Use data-state, data-slot instead of prop explosion
  7. •Semantic tokens - Never hardcode colors; use design tokens

Naming Conventions

Follow established patterns from shadcn/ui and Radix UI:

  • •Root, Trigger, Content - For interactive compositions
  • •Header, Body, Footer - For structural layouts
  • •Title, Description - For text content areas

Key Patterns

  • •Controlled + Uncontrolled: Support both via useControllableState
  • •asChild + Slot: Merge props onto child elements without wrapper DOM
  • •CVA: Use Class Variance Authority for variant-heavy components
  • •cn(): Merge classes with Tailwind conflict resolution

How to Use

Read individual rule files for detailed explanations and examples:

code
rules/composition.md
rules/accessibility.md
rules/typescript-patterns.md

Each rule file contains:

  • •DO patterns with references to components.build guides
  • •DON'T anti-patterns to avoid
  • •Links to source documentation

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md