Contributing

Create registry/components/<slug>.tsx. This file ships to other people's projects, so it may only import from react, its declared npm dependencies, and @/lib/utils.

"use client"

import * as React from "react"

import { cn } from "@/lib/utils"

export interface GlowCardProps extends React.ComponentPropsWithoutRef<"div"> {
  intensity?: number
}

export function GlowCard({ intensity = 1, className, ...props }: GlowCardProps) {
  return (
    <div
      className={cn("border border-border bg-card p-5", className)}
      {...props}
    />
  )
}

The house rules:

• Theme through tokens. No dark: variants — see dark mode for why.
• Colour is welcome, but only through the --info / --positive / --caution / --critical families. No literal colours and nothing from Tailwind's built-in palette — see theming.
• Elevation comes from the --elevation-* steps, reached as shadow-xs through shadow-lg. Do not invent a shadow, and do not use a gradient as one.
• Round through rounded-soft-sm, rounded-soft and rounded-soft-lg rather than the plain scale, so a project that retunes its own radii does not resize your component.
• Never let colour be the only carrier of state: pair it with a glyph and a label.
• Accept and merge className through cn, always last.
• Export the props interface.
• Animate transform and opacity only, and handle prefers-reduced-motion.
• Mark "use client" only if the component genuinely needs state, refs, effects or browser APIs.

Create components/previews/<slug>-preview.tsx with a default export. This one never leaves the site, so it may import anything.

"use client"

import { GlowCard } from "@/registry/components/glow-card"

export default function GlowCardPreview() {
  return <GlowCard className="max-w-sm">Preview content</GlowCard>
}

Register it so it code-splits. The map holds render functions, not component types — previews is a Record<string, () => ReactNode>, and renderPreview(slug) calls the entry:

const GlowCardPreview = dynamic(() => import("./glow-card-preview"))

export const previews: Record<string, () => ReactNode> = {
  "glow-card": () => <GlowCardPreview />,
}

Storing a function rather than a component keeps the preview frame from instantiating a value it received at runtime, and leaves the entry free to pass props or wrap the demo in a stage. A slug with no entry renders an explicit empty state rather than failing.

Add one entry to lib/registry/components.ts. This is the single source of truth: the component page, catalog card, search index, sidebar link, registry item and AI prompt are all projected from it.

defineComponent({
  name: "GlowCard",
  slug: "glow-card",
  title: "Glow Card",
  description: "A card with a soft animated glow.",
  overview: "Two to four sentences. Reused on the page and in the AI prompt.",
  category: "Cards",
  tags: ["card", "surface"],
  status: "new",
  featured: false,
  dependencies: [],
  registryDependencies: ["utils"],
  files: [uiFile("glow-card")],
  accessibility: ["Decorative layers are aria-hidden and pointer-events-none."],
  keyboard: [],
  props: [
    {
      name: "GlowCard",
      props: [
        {
          name: "intensity",
          type: "number",
          defaultValue: "1",
          description: "Glow strength.",
        },
      ],
    },
  ],
  usage: `import { GlowCard } from "@/components/joinui/glow-card"

export function Example() {
  return <GlowCard>Content</GlowCard>
}`,
  customization: [],
  related: [],
  since: "2026-08-02",
})

installCommand is derived by defineComponent — never write it by hand. related takes slugs of other components and is validated, so leave it empty until the components it would point at exist.

pnpm registry:validate
pnpm registry:build
pnpm check

Validation fails loudly if the file does not exist, the preview is not registered, related points at an unknown slug, the slug is not kebab-case, or the description is longer than 160 characters.

Create content/docs/<slug>.mdx. No frontmatter — the title and description live in the navigation.

{
  title: "Guides",
  items: [
    item("my-page", "My page", "One-line description for search and metadata."),
  ],
}

That entry drives the sidebar, breadcrumbs, previous/next links, the search index, the sitemap and generateStaticParams.