Contributing a Component

This guide walks through the full process of adding a new component to Prisma UI, from writing the component file to publishing its documentation and registry entry. It also covers what to do when you are only updating an existing component.

Using AI? There is a skill in .claude/skills/add-component/ that guides an AI agent through this entire workflow. Load it with any agent that supports skills.

Prisma UI lives in src/prisma/ of an Astro site. The docs are Starlight pages and the registry JSON is generated from the component sources at build time.

Component conventions

Follow these rules in every component:

Imports: Inside the library, import from @/prisma/ui/<name> and @/prisma/lib/utils. The registry rewrites them to @/components/ui/<name> and @/lib/utils for installs
Class merging: Always use cn() for conditional/merged class names
Semantic colors: Use design tokens (bg-primary, text-muted-foreground), never raw values like bg-blue-500
Spacing: Use flex with gap-*, never space-x-* or space-y-*
Variants: Use class-variance-authority (cva) when the component has multiple visual options
Hooks: Import directly — import { useState } from 'react', never React.useState
Return types: Component functions always return React.ReactNode
Client directive: Add "use client" if the component uses hooks, event handlers, or browser APIs
No framework APIs: Components install into any React project, so use plain <img> and <a>, never next/image or next/link
Animations: Keep keyframe animations in src/prisma/ui/style.css, not inline or in separate CSS files
Default animation props: When a component accepts transition or variants props (Framer Motion), provide sensible defaults so it works out of the box — users can override them, but should never be forced to pass them

Adding a new component

Follow these steps in order. Each step builds on the previous one.

1. Check shadcn availability

Before writing any new UI component, verify if shadcn/ui already provides it:

npx shadcn@latest view <component-name>

If shadcn has the component → use it as-is, or wrap it (see below)
If shadcn has something similar → extend it via a wrapper
If nothing exists → create from scratch following the conventions above

When extending a shadcn component, create a wrapper file instead of editing the base. For example, card-hover-effect.tsx instead of modifying card.tsx.

2. Create the component file

Add the component source at:

src/prisma/ui/<component-name>.tsx

Follow the component conventions listed above and use existing components as reference. Shared keyframes and [data-variant] properties go in src/prisma/ui/style.css, imported by the component as import './style.css'.

3. Create the documentation page

Create the page at:

src/content/docs/components/<component-name>.mdx

The page must follow this exact order:

Frontmatter — title and description
Imports — the component, ComponentPreview, Install, and any demo files
Short description — one paragraph (the title is rendered from the frontmatter, no # Title)
## Installation — <Install registryUrl='/components/<name>.json' />
## Import — single code block with the import statement
--- separator
## Usage / variant sections — each with a <ComponentPreview> above its code block
## Props — props table at the very end

ComponentPreview rules

Every non-import code block must have a <ComponentPreview> above it showing the rendered result
Preview blocks should contain only the component — no extra explanation, no wrapping layout
When a component needs images, use Lorem Picsum with a plain <img>. Vary dimensions slightly between items for different images
When icons or third-party imports are needed, split them into a separate code block before the usage block

Interactive demos

React in MDX renders as static HTML. Move a preview into its own file at src/prisma/demos/<component-name>/<n>.tsx and render it with client:visible when it:

is interactive (hooks, event handlers, motion, pointer effects)
uses compound tags such as <FlipCard.Front>, or props that take JSX such as front={<Card />} (these need the demo file even when static; leave out client:visible then)

import Demo1 from '@/prisma/demos/<component-name>/1';

<ComponentPreview>
  <Demo1 client:visible />
</ComponentPreview>

Open astro.config.mjs and add the page to the right group of the Starlight sidebar:

{
  label: 'Cards',
  items: [
    // ... existing entries
    'components/<component-name>',
  ],
},

Add a new group if the component belongs to a new category.

5. Add the registry entry

Open src/prisma/registry.ts and add an entry to COMPONENTS:

{
  name: '<component-name>',
  dependencies: ['motion'],           // every npm package the files import
  registryDependencies: ['card'],     // shadcn items it builds on
  files: ['<component-name>.tsx', 'style.css'],
},

That is all: /components/<component-name>.json and one JSON per shadcn style are generated from the source, in development and on every build. The <Install> block on the page works as soon as the entry exists.

The sitemap and the search index pick up the new page automatically.

Updating an existing component

When you are only changing an existing component — fixing a bug, adding a variant, adjusting styles — the scope is smaller:

Edit the component file at src/prisma/ui/<component-name>.tsx (and its per-style variants in src/prisma/ui/styles/ for style-aware components).
Update the documentation if any props, variants, or behavior changed.
Update the registry entry in src/prisma/registry.ts if the component’s dependencies or files changed. The JSON itself regenerates on its own.