components

Components

How components are added, shaped, styled, and organized. This skill owns authoring and styling rules; what components exist and what they look like is the design contract's concern, not this skill's.

The flow: shadcn first

1. Check shadcn before writing anything. Primitives use shadcn, which uses Radix primitives underneath. Adding a new component starts with a check of the shadcn library: if it exists there, import it with the CLI (pnpm dlx shadcn@latest add <name>), then reformat it to the house shape below and re-theme it with the project's design tokens.
2. Custom components use the identical shape. If shadcn doesn't have it (or the design calls for something bespoke), author it from scratch in exactly the same format; the only difference is there's nothing to import.

The file shape

1. Every component follows this example skeleton:

   import { forwardRef, type HTMLAttributes } from 'react'
   import { cn, cva, VariantProps } from '@/utils/theme'
   
   const styles = {
     root: cva('…', { variants: { … }, defaultVariants: { … } })
   }
   
   type ExampleRef = HTMLDivElement
   type ExampleProps = HTMLAttributes<ExampleRef> & VariantProps<typeof styles.root>
   
   const Example = forwardRef<ExampleRef, ExampleProps>((props, ref) => {
     // props
     const { className, ...rest } = props
   
     // hooks
   
     // render vars
   
     // jsx
     return <div ref={ref} className={cn(styles.root({ className }))} {...rest}></div>
   })
   Example.displayName = 'Example'
   
   export { Example }
   export type { ExampleProps, ExampleRef }
   

   Order within the file: CVA styles/constants on top → types (XxxRef, XxxProps) → component. Order within the function body, each under its comment: props destructure → hooks → render vars → jsx (composed with cn()).

2. Named exports only: the component plus its Props and Ref types; displayName set on forwardRef components. No default exports.