Installation

Prerequisites

Step 1: Initialize shadcn

If you haven't already set up shadcn in your project, run the init command. This creates a components.json configuration file and sets up your project structure.

npx shadcn@latest init

Step 2: Add the shadszn registry

Open your components.json file and add the shadszn registry URL. This tells the shadcn CLI where to fetch shadszn/ui components from.

// Just add the "registries" block to your existing components.json
{
  "registries": {
    "@shadszn": "https://design.szns.dev/r/{name}.json"
  }
}

Step 3: Install the SZNS theme

The SZNS theme provides all the CSS variables, color tokens, and glass-morphism utilities that components depend on. Install it first.

npx shadcn@latest add @shadszn/szns-theme

This adds the theme CSS variables to your globals.css file, including dark mode (default) and light mode (Springboard) tokens.

Step 4: Install components

Now you can install any component from the registry. Components are added directly to your codebase so you own the code and can customize it freely.

# Install individual components
npx shadcn@latest add @shadszn/button
npx shadcn@latest add @shadszn/card

# Install multiple components at once
npx shadcn@latest add @shadszn/button @shadszn/card @shadszn/input @shadszn/dialog

# Install page blocks (dashboard, login, data grid, etc.)
npx shadcn@latest add @shadszn/dashboard-layout

Block components

Page blocks like dashboard-layout, login-page, and data-grid install multiple files: a page file into src/app/ and helper components into src/components/. All cross-file imports use the @/ alias so they resolve correctly in your project.

# After installing a block, you'll see files like:
src/app/dashboard/page.tsx      # Page route
src/components/stat-card.tsx    # Helper component (imported via @/components/stat-card)

Tailwind configuration

shadszn/ui uses Tailwind CSS v4 with CSS-first configuration. The theme is defined entirely through CSS variables in your globals.css file using @theme inline blocks. No tailwind.config.ts file is required for theming.

Make sure your postcss.config.mjs includes the Tailwind plugin:

/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default config;