Installation + AI Skills

CodedVisuals is compatible with any shadcn/ui + React + Tailwind CSS project out of the box. Compositions use the same design tokens shadcn/ui already defines, so they inherit your theme and dark mode with no extra configuration.

Compositions rely on two packages: Motion, which powers the animations, and lucide-react, the icon set they draw from. Most shadcn/ui projects already include them both, but some are configured to use a different icon library, so it is worth confirming.

Two ways to install

There are two ways to bring a composition into your project. Pick the one that matches how you work:

1. Use the shadcn CLI (recommended). The CLI pulls the composition file and installs its dependencies for you. If you work with an AI agent, the AI skill builds on this same path.
2. Copy the source by hand. You paste a composition's code yourself and install the two packages once.

1. Add with the CLI (recommended)

This is the fastest route, and there is nothing to install up front.

Step 1. Connect the registry (one time). Compositions live in the private CodedVisuals registry. Issue a token and add the registry to your components.json by following the Registry guide. You only do this once per project.

Step 2. Add a composition. Run the add command with the composition you want:

npx shadcn@latest add @codedvisuals/charts-line

The command pulls in both the composition file and its packages (Motion and lucide-react), installing them the first time if they are missing.

Step 3. Use it. Import the composition and drop it into your page. Head to Usage for the further details.

Recommended with AI: add the AI skill

If you use an AI coding agent (Claude Code, Cursor, Codex, and others), add the CodedVisuals skill on top of the registry you just set up. The skill installs compositions through that same registry, so the agent knows the full catalog, every composition's props and defaults, and how to add one. Then just ask, for example "add visuals to my features grid section" or "drop in a line chart in the first feature of my bento grid", and it picks and wires them up for you.

Install the skill:

npx skills add pixelcave/skills --skill codedvisuals

This uses the skills CLI and needs only npx, nothing to install globally. Add -g to make the skill available in every project instead of just the current one.

Keep it current. When a new update is released, run the following command to update the skill (if the update fails for some reason, just re-add it like you did the first time and it will be updated):

npx skills update pixelcave/skills --skill codedvisuals

2. Copy the source by hand

If you prefer to paste a composition's code yourself, install the dependencies once and you are set for every composition after that.

Step 1. Install the dependencies. Add the two packages compositions rely on:

npm install motion lucide-react

Using a different package manager? pnpm add motion lucide-react or yarn add motion lucide-react work the same way.

Step 2. Confirm you have lucide-react. Compositions import their icons from lucide-react, which is shadcn/ui's default icon library, so most projects already have it. Some shadcn/ui setups use a different library instead (for example Radix Icons, via "iconLibrary": "radix" in components.json). If yours does, lucide-react will not be installed, so add it with the command above. You can keep your own icon library everywhere else: compositions only need lucide-react for the icons inside them.

Step 3. Copy a composition and use it. With Motion and lucide-react in place, head to Usage to copy a composition's source into your project and customize it.

Requirements

• React 18 or newer
• Tailwind CSS v4
• TypeScript
• shadcn/ui tokens defined in your stylesheet (the standard :root and .dark variables)
• Motion and lucide-react (installed above)

Not using shadcn/ui? Follow the Manual setup guide to add the few pieces compositions rely on.