Theming

No component writes values directly. Components read only token variables. The tokens live in one file, components/arc/foundation.css.

Light values are in :root, and dark values are in :root[data-theme="dark"] and :root.dark. So you can turn dark mode on with <html data-theme="dark">, or with <html class="dark"> as shadcn does. With neither, it follows the operating system's dark mode setting.

Some tokens have no value of their own. They are computed from other tokens. So changing only --accent and --accent-foreground also changes buttons, switches, checkboxes and the first chart series.

Components and blocks read token names such as --accent and --surface. New screens and new themes use these names too.

The seasonal themes change colour, motion, some icons, some sounds and the heading font.

• Heading font: Halloween uses Jejudoldam, Seollal uses Binggrae II, Chuseok uses Griun Oksooni handwriting and Christmas uses Nexon Maplestory. They apply to headings (display) only; body text stays Pretendard. A theme points at an alias such as "Halloween Display", and @font-face in app/globals.css connects the alias to the real file, so swapping a font means changing only that src. In an installed project, load a font under the same name yourself. Use the font files exactly as received and check each font's own license (public/fonts/season/SEASON-FONTS.txt).
• Sounds: only the five roles click, success, error, notify and confirm change; every other role keeps its default sound. The sounds are synthesized by scripts/gen-season-sounds.ts, so there is no license to carry. pnpm sounds:season rebuilds them, and to use them in an installed project, copy public/sounds/<theme name>/ along with the theme.
• The themes page shows each heading font, the icons a theme changes and a "Hear the sounds" button.

base holds only the reference values for type, corners and shadows. It holds no colour tokens. The token defaults are in foundation.css, so any token a theme leaves out keeps that value.

On the themes page you can see each theme drawn on a button, input, badge, switch and card. The previews follow the site's light and dark switch. The "Theme preview" on item pages changes the demo the same way.

A theme is a registry:theme item, so instead of files it adds CSS rules to your global stylesheet.

npx shadcn@latest add https://dsui.vercel.app/r/halloween.json

The CLI writes the parent theme base first, then halloween, into your global stylesheet (such as app/globals.css). Each theme adds only the values it changes.

The selectors are the same as in foundation.css. At equal specificity the later rule wins, so import foundation.css at the very top of your global stylesheet. Then the theme rules come after it and override the defaults.

@import "../components/arc/foundation.css";
@import "tailwindcss";
/* … CLI가 테마 규칙을 이 아래에 써 넣어요 … */

Dark mode gets the theme's dark values whether you turn it on with <html data-theme="dark"> or <html class="dark">.

A theme's type, corners and shadows (typography, shape, elevation) are CSS variables too, so they go into the same rules. Icons, sounds and motion can't be moved into CSS, so they stay only in the theme JSON's meta.themeRoles. See "Icons, sounds and motion are called by role" below and pass them to ThemeAssetsProvider.

The quickest way is to set the tokens again in your own global stylesheet. Written after foundation.css, they override it. Computed tokens (--accent-subtle, --control-on and others) follow without being listed.

:root {
  --accent: oklch(58% .17 165);
  --accent-foreground: oklch(100% 0 0);
  --radius-control: .75rem;
}

:root[data-theme="dark"],
:root.dark {
  --accent: oklch(72% .15 165);
  --accent-foreground: oklch(20% .04 165);
}

When you change the accent, always check its contrast with --accent-foreground. Text on the accent needs at least 4.5:1 to be readable. For corners, change only the three steps --radius-control (buttons, inputs), --radius-panel (cards, panels) and --radius-surface (large surfaces), and leave the pill shape --radius-pill as it is.

A dsui theme is defined by one file, registry/theme/<name>/item.json. In the repository, these commands create a starter file.

npm run theme:new forest
npm run theme:new forest --extends base

The name and summary placeholders, extends, and the main light and dark tokens (surfaces, text, lines, accent, highlight, controls) are filled in with the foundation defaults. If a theme with the same name exists, it stops instead of overwriting it. Inheritance goes one level deep, so --extends accepts only a theme without a parent. After changing values, validate with pnpm gen and check contrast with pnpm test.

Pick a parent and list only what you want to change.

{
  "slug": "my-theme",
  "type": "theme",
  "title": { "ko": "내 테마", "en": "My theme" },
  "summary": { "ko": "초록 강조색과 작은 모서리의 테마" },
  "extends": "base",
  "tokens": {
    "light": { "--accent": "oklch(58% .14 160)", "--accent-foreground": "oklch(100% 0 0)" },
    "dark": { "--accent": "oklch(78% .13 160)", "--accent-foreground": "oklch(20% .04 160)" }
  },
  "sounds": { "click": "tick-001" },
  "motion": { "duration": { "fast": 0.2 } },
  "typography": { "family": { "display": "'Pretendard Variable', sans-serif" } },
  "shape": { "control": "8px", "panel": "14px" },
  "elevation": { "floating": "0 24px 60px oklch(0% 0 0 / .12)" }
}

This list is every token a theme can use (lib/theme/arc-tokens.ts). Validation filters out any other name.

Tests check text and background contrast for every theme. Text on the accent (--accent-foreground), body text (--foreground) and secondary text (--text-secondary) on surfaces, and text on the highlight need 4.5:1. The mark on an active control (--control-glyph) needs at least 3:1. To match --control-on to the accent in dark mode, you can point at other tokens, such as "--control-on": "var(--accent)" and "--control-glyph": "var(--accent-foreground)".

Inheritance happens one role at a time. Change a single icon and the rest come from the parent. Type, corner and shadow values go into the stylesheet as they are, so they don't accept ;, braces, backslashes, comments or url().

Adding a theme to the dsui registry happens inside the repository. If your team needs its own theme, ask the devs7udio studio.

Components don't pick icon files or sound files directly. They call a role name, and the current theme decides what to use.

import { UiIcon } from "@/components/arc/theme";
import { playUiSound } from "@/components/arc/sound";

<UiIcon iconRole="close" size={16} aria-hidden="true" />;
playUiSound("click");

A theme's icons, sounds, motion, type, corners and shadows are applied with ThemeAssetsProvider. One per page is enough.

import { ThemeAssetsProvider } from "@/components/arc/theme";

const assets = {
  sounds: { click: "tick-001" },
  shape: { control: "8px", panel: "14px" },
};

<ThemeAssetsProvider assets={assets}>{children}</ThemeAssetsProvider>;

An installed project doesn't merge with the parent theme. Pass an object that already includes the inherited values. The installed theme JSON's meta.themeRoles holds the values that theme uses. The CLI already added type, corners and shadows as CSS, so you can pass only icons, sounds and motion to the provider.

• The CLI can't add icons, sounds or motion. shadcn has no slot for them, so they stay only in meta.themeRoles. They apply only when you pass them to ThemeAssetsProvider yourself.
• Layers that float above the page don't follow the preview theme. Dialogs, menus and toasts are drawn in body, outside the preview area's theme (data-dsui-theme, the demo's data-theme). In an installed project they go under :root, so this is not a problem.
• Names overlap with the shadcn init variables. The :root that shadcn init creates also has --background, --foreground, --accent, --accent-foreground and --border. That block comes after foundation.css, so without a theme the light accent becomes shadcn's grey. Installing a theme overrides them with the theme's values. Without a theme, delete those five lines.
• Motion values held by modules change late. If you switch themes while a page is open, some transitions that captured their values on first load change on the next load.
• Springs have no CSS variables. Durations and curves change through CSS variables right away, but springs exist only in scripts.
• Sample icons in blocks stay the same. A theme changes only the 34 shared interface icons.
• Themes don't ship font files. You can use only font names the page already loads with @font-face.
• Turning sound on and the volume are the user's choice. Themes don't change them.
• A token editor and theme export are in the works.

The seasonal themes also draw their own illustrations. An illustration is a list of shapes, written under illustrations in item.json; any of the 17 a theme does not draw is the base picture in the theme's colours. Christmas has a tree and a wreath, Chuseok a harvest moon and hills, Halloween pumpkins and ghosts, Seollal a striped fan and patchwork squares.