# Installation

> How to add components and blocks to your project from the registry URLs.

- URL: https://dsui.vercel.app/en/docs/installation

## Before you start

- **A React app:** the dsui site is built with React 19 and Next.js. The components are client components that use `"use client"`.
- **A bundler that reads CSS Modules:** components are styled with CSS Modules (`*.module.css`) and token variables, not Tailwind classes. You don't need Tailwind. Any setup that supports CSS Modules works, such as Next.js or Vite.
- **The shadcn CLI:** install with `npx shadcn@latest add`. If your project has no `components.json`, the CLI may ask to create one first.

You don't need to install npm packages yourself. The registry lists the packages each item needs, and the CLI installs them too.

| Package | Used by |
| --- | --- |
| `motion` | Movement in almost every component and block |
| `@hugeicons/react`, `@hugeicons/core-free-icons` | Components with icons and the shared theme files |
| `@radix-ui/react-*` | Some components, such as dialogs, dropdown menus, popovers, tooltips and tabs |

## Install one component

Put the item name in the URL. The "Install" section on each item page has the same command, ready to copy.

```bash
npx shadcn@latest add https://dsui.vercel.app/r/button.json
```

The CLI also fetches the other items this one depends on. For the button, that is the shared foundation `arc-foundation` and the sound effects `arc-sound`. Items with icons also bring in `arc-theme`. Blocks install the components they use as well.

```bash
npx shadcn@latest add https://dsui.vercel.app/r/hero-section.json
```

## Where files go

| Item | Location |
| --- | --- |
| Components | `components/arc/<name>/` |
| Blocks | `components/arc/blocks/<name>/` |
| Shared foundation (`arc-foundation`) | `components/arc/foundation.css`, `components/arc/motion-tokens.ts`, `components/arc/lib/`, `components/arc/LICENSE` |
| Theme roles (`arc-theme`) | `components/arc/theme/` |
| Sound effects (`arc-sound`) | `components/arc/sound/` |
| devs7udio items | `components/devs7udio/<name>/` |

Files import each other with relative paths. If you change the folder structure, update the import paths too.

## Import the token file

Import `foundation.css` once in your global stylesheet. It holds every colour, corner, shadow and motion variable the components read.

```css
@import "../components/arc/foundation.css";
```

Adjust the path to where your global stylesheet lives. The example above imports it from `app/globals.css`. Put it at the very top, so the rules of a [theme](/en/docs/theming) you install later come after it and override the defaults.

## Use Next.js Link and Image

Components that draw links and images use a plain `<a>` and `<img>` by default. That way they work outside Next.js too. To use Next.js `Link` and `Image`, wrap your app once in `ArcProvider`.

```tsx
import Link from "next/link";
import Image from "next/image";
import { ArcProvider } from "@/components/arc/lib/arc-provider";

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ArcProvider link={Link} image={Image}>
      {children}
    </ArcProvider>
  );
}
```

`ArcProvider` is a client component, so it's easiest to wrap it in a separate providers file like the one above.

## Fonts

The tokens look for Pretendard Variable first for body and display text. If it's missing, they use system fonts (`Apple SD Gothic Neo`, `Noto Sans KR` and others). Font files are not in the registry. For the same look, load Pretendard Variable yourself.

```css
@font-face {
  font-family: "Pretendard Variable";
  font-style: normal;
  font-weight: 45 930;
  font-display: swap;
  src: url("/fonts/PretendardVariable.woff2") format("woff2-variations");
}
```

Pretendard uses the SIL OFL licence, so you can ship it with your app.

## Dark mode

Add `data-theme="dark"` or `class="dark"` to `<html>` to switch to the dark tokens. With neither, it follows the operating system setting. `data-theme="light"` or `class="light"` locks it to light.

```tsx
<html lang="ko" data-theme="dark">
```

If you already use a tool that adds a `.dark` class, such as next-themes, leave it as it is.

## Install by name

To install with a short name instead of a URL, register the registry namespace in `components.json`.

```json
{
  "registries": {
    "@devs7udio": "https://dsui.vercel.app/r/{name}.json"
  }
}
```

After that, install like this.

```bash
npx shadcn@latest add @devs7udio/button
```

You can also register it with the CLI.

```bash
npx shadcn@latest registry add @devs7udio=https://dsui.vercel.app/r/{name}.json
```

## Registry URLs

| URL | Contents |
| --- | --- |
| `/r/registry.json` | The full list of installable items. There are 133 right now. |
| `/r/<name>.json` | One item. The name matches its page URL (`/items/<name>`). |
| `/r/arc-foundation.json` | Tokens, motion presets, shared utilities and the licence. Every item depends on it. |
| `/r/arc-theme.json` | Role icons (`UiIcon`), the theme provider and motion roles. |
| `/r/arc-sound.json` | The sound engine and 11 sound effects. |

Every URL starts with `https://dsui.vercel.app`.

## Troubleshooting

- **I get a 404.** Check the name. A registry name is the last part of the item page URL and uses only lowercase English letters and hyphens. Items listed under "Items you can't install" below also return 404.
- **It says the package versions don't match.** The registry lists ranges such as `motion@^14.2.0`. If you already use another major version, the CLI or your package manager may warn you. The items are built for React 19.
- **I don't see colours or corners.** Check that you imported `foundation.css`. Import it once, and preferably before other global styles.
- **The button is grey.** The `--background`, `--foreground`, `--accent`, `--accent-foreground` and `--border` that `shadcn init` added to `:root` override the same names in `foundation.css`. Delete those five lines or install a [theme](/en/docs/theming).
- **Components have no styles at all.** If a new Next.js project's `next.config.ts` has a `"*.css"` rule (`@tailwindcss/turbopack`, `as: "*.css"`), CSS Modules are read as plain CSS and the class names come out empty. Narrow the rule's key to `"globals.css"`.
- **Photos and logos in blocks are broken.** The sample images live in the dsui site's `/public/media` and `/public/block-logos` and are not shipped through the registry. Replace the sample data in blocks such as `blog-grid`, `hero-section`, `logo-marquee` and `page-header`, and in `components/arc/lib/media.ts`, with your own images.

## Items you can't install

Most earlier devs7udio items are not shipped through the registry. They depend on the demo kit or on paths used only inside the site, so they don't work in other projects. Their "Install" section shows this note instead of a command, and you can still read the source for reference.

The devs7udio items you can install now are the themes [base](/en/themes#base), [halloween](/en/themes#halloween), [seollal](/en/themes#seollal), [chuseok](/en/themes#chuseok) and [christmas](/en/themes#christmas). The other 9 components, 3 blocks, 1 element, and the motion and animation items can't be installed.