Getting Started

Initium gives your shadcn project a shared design direction, installable styles, production-ready blocks, and agent skills that help AI tools build with the same constraints your team uses.

This guide is the shortest path from an existing app to a working Initium setup.

What You Need

• A React, Next.js, or compatible app that can use shadcn.
• shadcn initialized in the project.
• Access to the Initium app: the Style Builder, the Strategy Builder, and the Blocks browser.
• An INITIUM_LICENSE_KEY if you want to install pro blocks or the Initium skill pack.

If your app does not have shadcn yet, start with Registry Setup.

Free And Pro Access

Free registry items can be installed without a license key. Pro items return an authorization error until your project has INITIUM_LICENSE_KEY available.

1. Initialize shadcn

If your project already has components.json, shadcn is already initialized. If not, initialize it first:

npx shadcn@latest init

Choose settings that match your app. Initium is installed through the shadcn registry system, so shadcn must be working before you install Initium items.

2. Add The Initium Registry

Add the Initium registry namespace to your project's components.json:

{
  "registries": {
    "@initium": {
      "url": "https://app.initium.sh/r/styles/{style}/{name}.json",
      "headers": {
        "Authorization": "Bearer ${INITIUM_LICENSE_KEY}"
      }
    }
  }
}

Keep the authorization header even if you start with free items. Free installs still work, and pro installs will work once the license key is available.

The {style} placeholder is filled in by the shadcn CLI from your project's style setting. Initium components are built on Base UI, and projects on a base-* style (the default for new shadcn projects) receive them directly. Projects on a radix-* or legacy style receive the Radix build of the registry, which is maintained for existing customers but no longer receives new blocks.

3. Install Your Style

For a custom style, open the Style Builder, choose your colors, fonts, type scale, radius scale, buttons, and forms, then copy the generated shadcn install command.

The command uses a generated registry URL:

npx shadcn@latest add "https://app.initium.sh/r/preset?code=..."

You can also install the base Initium style utilities:

npx shadcn@latest add @initium/initium-styles

Install styles before blocks so classes such as wrapper, tagline, paragraph, heading-xl, and heading-lg are available. Rich text article blocks additionally install the @initium/typeset stylesheet as a dependency; import it after Tailwind in your global CSS (@import "./typeset.css";).

4. Export Your AI Assets

From the Style Builder, export DESIGN.md. From the Strategy Builder, export STRATEGY.md.

Place both files in your project root while you work:

DESIGN.md
STRATEGY.md

You do not have to commit these files. Treat them as working files that your AI tool can read before generating or revising UI.

5. Install The Initium Skill Pack

If you have a license key, install the Initium skill pack:

npx shadcn@latest add @initium/initium-agent

This installs the skill into:

.agents/skills/initium/

Use the skill when your AI tool supports project skills. If it does not, tell the tool to read .agents/skills/initium/SKILL.md.

6. Install Blocks

Install blocks through the same registry namespace:

npx shadcn@latest add @initium/hero-section-1

Use the Blocks browser to choose the exact block name. Pro blocks require INITIUM_LICENSE_KEY.

7. Start A Chat With Your AI Tool

Start by telling your AI tool what to read:

Read DESIGN.md and STRATEGY.md from the project root.
Follow the installed Initium skill if available.
Use Initium blocks for major sections and keep the installed style preset intact.

Then ask for a specific page or section. The more specific your target audience, offer, proof, and conversion goal are, the better the result will be.

Package Manager Notes

Examples use npx shadcn@latest. If your project prefers another package manager, use the matching shadcn runner:

pnpm dlx shadcn@latest add @initium/hero-section-1
yarn dlx shadcn@latest add @initium/hero-section-1
bunx --bun shadcn@latest add @initium/hero-section-1