tapforce-shadcn-svelte

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tapforce-shadcn-svelte

This skill provides comprehensive guidance for setting up and using the shadcn-svelte library in Svelte projects. It covers installation, configuration, component usage, theming, and best practices.

本技能为在Svelte项目中搭建和使用shadcn-svelte库提供全面指导，涵盖安装、配置、组件使用、主题设置及最佳实践。

Requirements

要求

Project must be based on SvelteKit framework version 2.0 or higher
Project must use Svelte 5.0 or higher
Project should use TailwindCSS (recommended)

项目必须基于2.0或更高版本的SvelteKit框架
项目必须使用5.0或更高版本的Svelte
建议项目使用TailwindCSS

Resources

资源

Available Components

可用组件

Check Project Installation

检查项目安装情况

You must check if shadcn-svelte is already installed in the project. To check, look for the

components.json

file in the project root directory.

bash

undefined

你需要检查项目中是否已安装shadcn-svelte。可通过查看项目根目录下是否存在

components.json

文件来确认。

bash

undefined

Check if components.json exists

检查components.json是否存在

ls -la components.json


If the file exists, shadcn-svelte is already configured in the project.

ls -la components.json


若该文件存在，则说明项目中已配置shadcn-svelte。

Installation

安装步骤

Prerequisites

前置条件

Project requires SvelteKit ^2 and TailwindCSS ^4 ready before initializing shadcn-svelte.

项目在初始化shadcn-svelte前，需已配置好SvelteKit ^2和TailwindCSS ^4。

Initialize shadcn-svelte

初始化shadcn-svelte

bash

pnpm dlx shadcn-svelte@latest init

The

@latest

tag indicates installing the latest version. For adding components by command, you need to get the real version from

package.json

and use it in the command.

bash

pnpm dlx shadcn-svelte@latest init

@latest

标签表示安装最新版本。若要通过命令添加组件，你需要从

package.json

中获取实际版本并在命令中使用。

Configure components.json

配置components.json

You will be asked a few questions to configure

components.json

Which base color would you like to use? › Slate
Where is your global CSS file? (this file will be overwritten) › src/routes/layout.css
Configure the import alias for lib: › $lib
Configure the import alias for components: › $lib/components
Configure the import alias for utils: › $lib/utils
Configure the import alias for hooks: › $lib/hooks
Configure the import alias for ui: › $lib/components/ui

系统会询问几个问题以配置

components.json

：

你想要使用哪种基础颜色？› Slate
你的全局CSS文件路径是什么？（该文件将被覆盖）› src/routes/layout.css
配置lib的导入别名：› $lib
配置components的导入别名：› $lib/components
配置utils的导入别名：› $lib/utils
配置hooks的导入别名：› $lib/hooks
配置ui的导入别名：› $lib/components/ui

Setup Path Aliases (if needed)

设置路径别名（如有需要）

If you are not using the default alias

$lib

, you'll need to update your

svelte.config.js

file to include those aliases:

javascript

const config = {
  // ... other config
  kit: {
    // ... other config
    alias: {
      "@/*": "./path/to/lib/*",
    },
  },
};

若你未使用默认别名

$lib

，则需要更新

svelte.config.js

文件以添加这些别名：

javascript

const config = {
  // ... 其他配置
  kit: {
    // ... 其他配置
    alias: {
      "@/*": "./path/to/lib/*",
    },
  },
};

CLI Usage

CLI使用方法

Initialize Project

初始化项目

bash

pnpm dlx shadcn-svelte@latest init

Options:

```
-c, --cwd <path>
```
: the working directory (default: the current directory)
```
-o, --overwrite
```
: overwrite existing files (default: false)
```
--no-deps
```
: disable adding & installing dependencies
```
--skip-preflight
```
: ignore preflight checks and continue (default: false)
```
--base-color <name>
```
: the base color for the components (choices: "slate", "gray", "zinc", "neutral", "stone")
```
--css <path>
```
: path to the global CSS file
```
--components-alias <path>
```
: import alias for components
```
--lib-alias <path>
```
: import alias for lib
```
--utils-alias <path>
```
: import alias for utils
```
--hooks-alias <path>
```
: import alias for hooks
```
--ui-alias <path>
```
: import alias for ui
```
--proxy <proxy>
```
: fetch items from registry using a proxy

bash

pnpm dlx shadcn-svelte@latest init

选项：

```
-c, --cwd <path>
```
：工作目录（默认：当前目录）
```
-o, --overwrite
```
：覆盖现有文件（默认：false）
```
--no-deps
```
：禁用依赖的添加与安装
```
--skip-preflight
```
：忽略预检检查并继续（默认：false）
```
--base-color <name>
```
：组件的基础颜色（可选值："slate", "gray", "zinc", "neutral", "stone"）
```
--css <path>
```
：全局CSS文件路径
```
--components-alias <path>
```
：组件的导入别名
```
--lib-alias <path>
```
：lib的导入别名
```
--utils-alias <path>
```
：utils的导入别名
```
--hooks-alias <path>
```
：hooks的导入别名
```
--ui-alias <path>
```
：ui的导入别名
```
--proxy <proxy>
```
：通过代理从注册表获取资源

Add Components

添加组件

bash

pnpm dlx shadcn-svelte@latest add [component]

Example:

bash

pnpm dlx shadcn-svelte@latest add button

Options:

```
-c, --cwd <path>
```
: the working directory (default: the current directory)
```
--no-deps
```
: skips adding & installing package dependencies
```
--skip-preflight
```
: ignore preflight checks and continue (default: false)
```
-a, --all
```
: install all components to your project (default: false)
```
-y, --yes
```
: skip confirmation prompt (default: false)
```
-o, --overwrite
```
: overwrite existing files (default: false)
```
--proxy <proxy>
```
: fetch components from registry using a proxy

bash

pnpm dlx shadcn-svelte@latest add [component]

示例：

bash

pnpm dlx shadcn-svelte@latest add button

选项：

```
-c, --cwd <path>
```
：工作目录（默认：当前目录）
```
--no-deps
```
：跳过依赖包的添加与安装
```
--skip-preflight
```
：忽略预检检查并继续（默认：false）
```
-a, --all
```
：将所有组件安装到你的项目中（默认：false）
```
-y, --yes
```
：跳过确认提示（默认：false）
```
-o, --overwrite
```
：覆盖现有文件（默认：false）
```
--proxy <proxy>
```
：通过代理从注册表获取组件

Import and Use Components

导入并使用组件

After adding a component, you can import it like this:

svelte

<script lang="ts">
  import { Button } from "$lib/components/ui/button";
</script>

<Button>Click me</Button>

Import Guidelines:

Always use destructuring imports from the component's own folder:
```
import { Button } from "$lib/components/ui/button"
```

Import sub-components together from their parent:

import { Card, CardHeader, CardTitle } from "$lib/components/ui/card"

Never use namespace imports for simple components:

import * as Button from "$lib/components/ui/button"

Use direct component paths without
```
/index.js
```
suffix

添加组件后，你可以这样导入：

svelte

<script lang="ts">
  import { Button } from "$lib/components/ui/button";
</script>

<Button>Click me</Button>

导入指南：

始终从组件自身的文件夹使用解构导入：
```
import { Button } from "$lib/components/ui/button"
```

从父组件一起导入子组件：

import { Card, CardHeader, CardTitle } from "$lib/components/ui/card"

对于简单组件，切勿使用命名空间导入：
```
import * as Button from "$lib/components/ui/button"
```
使用不带
```
/index.js
```
后缀的直接组件路径

Theming

主题设置

CSS Variables Convention

CSS变量约定

shadcn-svelte uses a simple background and foreground convention for colors. The background variable is used for the background color of the component and the foreground variable is used for the text color.

For example, given these CSS variables:

css

--primary: oklch(0.208 0.042 265.755);
--primary-foreground: oklch(0.984 0.003 247.858);

The background color will be

var(--primary)

and the foreground color will be

var(--primary-foreground)

html

<div class="bg-primary text-primary-foreground">Hello</div>

shadcn-svelte对颜色采用简单的背景色和前景色约定。背景变量用于组件的背景颜色，前景变量用于文本颜色。

例如，给定以下CSS变量：

css

--primary: oklch(0.208 0.042 265.755);
--primary-foreground: oklch(0.984 0.003 247.858);

背景颜色将使用

var(--primary)

，前景颜色将使用

var(--primary-foreground)

：

html

<div class="bg-primary text-primary-foreground">Hello</div>

Generated CSS Structure

生成的CSS结构

The

init

command generates the full CSS structure in your global CSS file. The exact oklch values depend on the chosen base color (slate, gray, zinc, neutral, stone). The generated file includes:

TailwindCSS import and tw-animate-css animation library
Dark mode custom variant:
```
@custom-variant dark (&:is(.dark *))
```
:root
CSS variables for light mode colors
.dark
CSS variables for dark mode colors
@theme inline
block mapping CSS variables to TailwindCSS v4 utilities
@layer base
block for default border and background styles

init

命令会在你的全局CSS文件中生成完整的CSS结构。具体的oklch值取决于所选的基础颜色（slate、gray、zinc、neutral、stone）。生成的文件包括：

TailwindCSS导入和tw-animate-css动画库
深色模式自定义变体：
```
@custom-variant dark (&:is(.dark *))
```
:root
CSS变量：用于浅色模式颜色
.dark
CSS变量：用于深色模式颜色
@theme inline
块：将CSS变量映射到TailwindCSS v4工具类
@layer base
块：用于默认边框和背景样式

Available CSS Variables

可用的CSS变量

The following variables are available (values shown are for the slate base color):

Variable	Purpose
`--background` / `--foreground`	Page background and text
`--card` / `--card-foreground`	Card component colors
`--popover` / `--popover-foreground`	Popover/dropdown colors
`--primary` / `--primary-foreground`	Primary action colors
`--secondary` / `--secondary-foreground`	Secondary action colors
`--muted` / `--muted-foreground`	Muted/subtle content
`--accent` / `--accent-foreground`	Accent/highlight colors
`--destructive`	Destructive action color
`--border`	Border color
`--input`	Input border color
`--ring`	Focus ring color
`--chart-1` through `--chart-5`	Chart colors
`--sidebar-*`	Sidebar-specific variants
`--radius`	Base border radius

以下变量可用（显示的值为slate基础色的示例）：

变量	用途
`--background` / `--foreground`	页面背景和文本
`--card` / `--card-foreground`	卡片组件颜色
`--popover` / `--popover-foreground`	弹出层/下拉菜单颜色
`--primary` / `--primary-foreground`	主操作颜色
`--secondary` / `--secondary-foreground`	次要操作颜色
`--muted` / `--muted-foreground`	弱化/次要内容颜色
`--accent` / `--accent-foreground`	强调/高亮颜色
`--destructive`	危险操作颜色
`--border`	边框颜色
`--input`	输入框边框颜色
`--ring`	聚焦环颜色
`--chart-1` 至 `--chart-5`	图表颜色
`--sidebar-*`	侧边栏专用变体
`--radius`	基础边框圆角

TailwindCSS v4 Theme Mapping

TailwindCSS v4主题映射

The init command also generates a

@theme inline

block required by TailwindCSS v4 to map CSS variables to Tailwind utility classes (e.g.,

bg-primary

text-foreground

border-border

css

@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... maps all CSS variables to Tailwind color utilities */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

init命令还会生成一个

@theme inline

块，这是TailwindCSS v4将CSS变量映射到Tailwind工具类（如

bg-primary

、

text-foreground

、

border-border

）所必需的：

css

@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... 将所有CSS变量映射到Tailwind颜色工具类 */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

Dark Mode

深色模式

Install mode-watcher

安装mode-watcher

bash

pnpm i mode-watcher

bash

pnpm i mode-watcher

Add the ModeWatcher Component

添加ModeWatcher组件

Import the ModeWatcher component and use it in your root layout:

svelte

<script lang="ts">
  import { ModeWatcher } from "mode-watcher";
  let { children } = $props();
</script>

<ModeWatcher />
{@render children?.()}

导入ModeWatcher组件并在根布局中使用：

svelte

<script lang="ts">
  import { ModeWatcher } from "mode-watcher";
  let { children } = $props();
</script>

<ModeWatcher />
{@render children?.()}

Add a Mode Toggle

添加模式切换按钮

Simple Toggle Button

简单切换按钮

svelte

<script lang="ts">
  import SunIcon from "@lucide/svelte/icons/sun";
  import MoonIcon from "@lucide/svelte/icons/moon";
  import { toggleMode } from "mode-watcher";
  import { Button } from "$lib/components/ui/button";
</script>

<Button onclick={toggleMode} variant="outline" size="icon">
  <SunIcon class="h-[1.2rem] w-[1.2rem] scale-100 rotate-0 !transition-all dark:scale-0 dark:-rotate-90" />
  <MoonIcon class="absolute h-[1.2rem] w-[1.2rem] scale-0 rotate-90 !transition-all dark:scale-100 dark:rotate-0" />
  <span class="sr-only">Toggle theme</span>
</Button>

svelte

<script lang="ts">
  import SunIcon from "@lucide/svelte/icons/sun";
  import MoonIcon from "@lucide/svelte/icons/moon";
  import { toggleMode } from "mode-watcher";
  import { Button } from "$lib/components/ui/button";
</script>

<Button onclick={toggleMode} variant="outline" size="icon">
  <SunIcon class="h-[1.2rem] w-[1.2rem] scale-100 rotate-0 !transition-all dark:scale-0 dark:-rotate-90" />
  <MoonIcon class="absolute h-[1.2rem] w-[1.2rem] scale-0 rotate-90 !transition-all dark:scale-100 dark:rotate-0" />
  <span class="sr-only">切换主题</span>
</Button>

Dropdown Menu Toggle

下拉菜单切换按钮

svelte

<script lang="ts">
  import SunIcon from "@lucide/svelte/icons/sun";
  import MoonIcon from "@lucide/svelte/icons/moon";
  import { resetMode, setMode } from "mode-watcher";
  import { 
    DropdownMenu,
    DropdownMenuContent,
    DropdownMenuItem,
    DropdownMenuTrigger
  } from "$lib/components/ui/dropdown-menu";
  import { buttonVariants } from "$lib/components/ui/button";
</script>

<DropdownMenu>
  <DropdownMenuTrigger class={buttonVariants({ variant: "outline", size: "icon" })}>
    <SunIcon class="h-[1.2rem] w-[1.2rem] scale-100 rotate-0 !transition-all dark:scale-0 dark:-rotate-90" />
    <MoonIcon class="absolute h-[1.2rem] w-[1.2rem] scale-0 rotate-90 !transition-all dark:scale-100 dark:rotate-0" />
    <span class="sr-only">Toggle theme</span>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuItem onclick={() => setMode("light")}>Light</DropdownMenuItem>
    <DropdownMenuItem onclick={() => setMode("dark")}>Dark</DropdownMenuItem>
    <DropdownMenuItem onclick={() => resetMode()}>System</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

svelte

<script lang="ts">
  import SunIcon from "@lucide/svelte/icons/sun";
  import MoonIcon from "@lucide/svelte/icons/moon";
  import { resetMode, setMode } from "mode-watcher";
  import { 
    DropdownMenu,
    DropdownMenuContent,
    DropdownMenuItem,
    DropdownMenuTrigger
  } from "$lib/components/ui/dropdown-menu";
  import { buttonVariants } from "$lib/components/ui/button";
</script>

<DropdownMenu>
  <DropdownMenuTrigger class={buttonVariants({ variant: "outline", size: "icon" })}>
    <SunIcon class="h-[1.2rem] w-[1.2rem] scale-100 rotate-0 !transition-all dark:scale-0 dark:-rotate-90" />
    <MoonIcon class="absolute h-[1.2rem] w-[1.2rem] scale-0 rotate-90 !transition-all dark:scale-100 dark:rotate-0" />
    <span class="sr-only">切换主题</span>
  </DropdownMenuTrigger>
  <DropdownMenuContent align="end">
    <DropdownMenuItem onclick={() => setMode("light")}>浅色</DropdownMenuItem>
    <DropdownMenuItem onclick={() => setMode("dark")}>深色</DropdownMenuItem>
    <DropdownMenuItem onclick={() => resetMode()}>跟随系统</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

Rules

规则

This skill includes the following rules:

本技能包含以下规则：

[Component Maintenance]

[组件维护]

Rule: component-maintenance
Description: Guidelines for maintaining shadcn components to ensure future update compatibility

规则: component-maintenance
描述: 维护shadcn组件以确保未来更新兼容性的指南

[Component Usage Best Practices]

[组件使用最佳实践]

Rule: component-usage
Description: Best practices for using shadcn components effectively with their options

规则: component-usage
描述: 有效使用shadcn组件及其选项的最佳实践

[Component Imports]

[组件导入]

Rule: component-imports
Description: Best practices for importing shadcn-svelte components using folder paths for maximum compatibility

规则: component-imports
描述: 使用文件夹路径导入shadcn-svelte组件以实现最大兼容性的最佳实践

[CLI Usage]

[CLI使用]

Rule: cli-usage
Description: Always use CLI commands for installation, initialization, and adding components - never manually create config files

规则: cli-usage
描述: 始终使用CLI命令进行安装、初始化和添加组件 - 切勿手动创建配置文件