Using components with AI

Every component page has a Copy prompt button. It puts a complete, structured brief on your clipboard — ready to paste into Cursor, Claude Code, Codex, or any other coding agent.

Why not just paste the code

Pasting a component into an agent gives it the what but none of the constraints. It does not know which dependencies to install, where the file belongs, that your project uses a cn utility, that the component must not introduce dark: variants, or that it should leave the rest of your codebase alone.

The generated prompt carries all of that, so the agent's first attempt is usually the correct one.

What the prompt contains

Shape of the output

Placeholders below stand in for the component you copied it from; the real prompt has the name, the target path and the props filled in.

Add the <ComponentName> component to my existing Next.js application.

Project stack:
- Next.js (App Router)
- React 19 with Server Components
- TypeScript in strict mode
- Tailwind CSS v4 with CSS-variable design tokens
- shadcn/ui conventions (open code, `cn` utility, `components.json`)

Requirements:
- Install all required dependencies: <packages>.
- Place the component at components/joinui/<component>.tsx.
- Use the project's existing `cn` utility from `@/lib/utils` and its existing
  design tokens (background, foreground, card, muted, border, primary, accent,
  destructive, radius, plus the component colour families info, positive,
  caution and critical — each with a `-soft` tint and a `-foreground`, as in
  `bg-info-soft text-info`). Round corners with the `rounded-soft-sm` /
  `rounded-soft` / `rounded-soft-lg` scale. Do not introduce new hard-coded
  colours, and do not reach for Tailwind's built-in palette (`gray-500`,
  `red-600`) — the tokens are warm neutrals and low-chroma hues, so those land
  next to but not on the system.
- Preserve dark mode support. The component must theme through CSS variables
  only — do not add `dark:` variants, so it keeps working inside a forced-theme
  preview.
- Preserve keyboard navigation and every ARIA attribute in the implementation
  below.
- Respect `prefers-reduced-motion: reduce`.
- Keep TypeScript strict mode passing. Export the prop types.
- Mark the file `"use client"` only if the implementation below does.
- Do not modify unrelated files.
- Do not replace existing project configuration unless it is genuinely required.
- Return a summary of created and modified files.

Component behavior:
…

Supported props:
- <prop>: <type> — default: <value>. …

Accessibility requirements:
- …

Keyboard interactions:
- …

Animation requirements:
- Animate compositor-friendly properties (transform, opacity) only. …

Integration notes:
- Category: <category>
- Registry item: https://ui.join-way.com/r/<component>.json
- Equivalent CLI install: pnpm dlx shadcn@latest add @joinui/<component>

Implementation:

File: components/joinui/<component>.tsx

```tsx
"use client"
…
```

That line is doing more work than it looks. The design system is token-driven: the neutrals carry a deliberate trace of warmth, emphasis in the chrome is ink rather than an accent, and the colour a component is allowed lives in four named families at low chroma. An agent reaching for gray-500 — a pure neutral — or red-600 — a saturated one — lands next to but not on those values, which is the single most common way an edit ends up visibly off. Naming the tokens explicitly is what keeps it on-system.

How it is generated

The prompt is assembled on the server from the component's metadata plus the real file on disk — never from a hand-written copy:

export function buildComponentPrompt({ component, sources }: BuildPromptOptions) {
  if (component.prompt) return component.prompt
  // …projects metadata + source into the template
}

Two consequences worth naming:

1. The prompt cannot describe a prop that does not exist. Props, dependencies and accessibility notes come from the same records that render the props table on the page.
2. The source is never stale. It is read from registry/components/ at build time, so it matches what the CLI installs, byte for byte.

Overriding the prompt

Some components need instructions the template cannot infer — a migration note, a warning about a conflicting library. Set prompt on the metadata and it replaces the generated text entirely:

defineComponent({
  name: "GlowCard",
  slug: "glow-card",
  // …
  prompt: `Add the GlowCard component…

Extra context this component needs.`,
})

Use it sparingly. A hand-written prompt is one more thing that can drift from the implementation, which is exactly what the generated path avoids.

Working with agents

pnpm tsc --noEmit && pnpm lint

Prefer the CLI when you can

If the agent has terminal access, installing is faster and less error-prone than writing the file from a prompt:

$pnpm dlx shadcn@latest add @joinui/<component>

The prompt says as much — it ends with the equivalent CLI command and tells the agent to prefer it when the project already uses shadcn. Reach for Copy prompt when the agent cannot run commands, when you want the component adapted rather than copied verbatim, or when you are working somewhere the registry is not reachable.

Machine-readable metadata

Agents that can fetch URLs do not need the clipboard at all. Every registry item is self-describing JSON:

curl https://ui.join-way.com/r/<component>.json

It carries the title, description, dependencies, registryDependencies, target path, full source, and a meta block with status and release date. The index at /r/registry.json lists every component, which is enough for an agent to discover the catalog on its own.