ktui-theming

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KtUI Theming

KtUI 主题定制

Use this skill when working with KtUI theming—colors, dark mode, and custom appearance. KtUI uses CSS variables and a background/foreground convention; prefer these over inventing custom classes.

当你处理KtUI主题相关工作（颜色、暗色模式、自定义外观）时，可使用本技能。KtUI采用CSS变量以及背景/前景命名约定；请优先使用这些约定，而非自定义类。

Convention

命名约定

Background/foreground: KtUI follows a Shadcn-inspired convention. Background colors omit the
```
-background
```
suffix (e.g.
```
bg-primary
```
uses
```
var(--primary)
```
). Foreground colors use
```
-foreground
```
(e.g.
```
text-primary-foreground
```
).
Semantic classes: Use KtUI semantic utilities (e.g.
```
bg-background
```
,
```
text-foreground
```
,
```
bg-primary
```
,
```
text-card
```
,
```
kt-btn
```
,
```
kt-card
```
) so theming stays consistent.

背景/前景： KtUI遵循Shadcn风格的命名约定。背景色省略
```
-background
```
后缀（例如
```
bg-primary
```
使用
```
var(--primary)
```
）。前景色使用
```
-foreground
```
后缀（例如
```
text-primary-foreground
```
）。
语义类： 使用KtUI语义工具类（例如
```
bg-background
```
、
```
text-foreground
```
、
```
bg-primary
```
、
```
text-card
```
、
```
kt-btn
```
、
```
kt-card
```
），确保主题一致性。

Key CSS variables

核心CSS变量

Define or override in your Tailwind entry (e.g.

style.css

). KtUI expects at least:

Surfaces:

--background

--foreground

;

--card

--card-foreground

;

--popover

--popover-foreground

Brand:

--primary

--primary-foreground

;

--secondary

--secondary-foreground

Muted / accent:

--muted

--muted-foreground

;

--accent

--accent-foreground

Destructive:
```
--destructive
```
,
```
--destructive-foreground
```
.
Borders and inputs:
```
--border
```
,
```
--input
```
,
```
--ring
```
.
Radius:
```
--radius
```
(e.g.
```
0.5rem
```
).

Use

oklch()

or any valid CSS color. Example:

css

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(14.1% 0.005 285.823);
  --primary: oklch(62.3% 0.214 259.815);
  --primary-foreground: oklch(1 0 0);
  --radius: 0.5rem;
}

在你的Tailwind入口文件（例如

style.css

）中定义或覆盖这些变量。KtUI至少需要以下变量：

界面表层：

--background

、

--foreground

；

--card

、

--card-foreground

；

--popover

、

--popover-foreground

。

品牌色：

--primary

、

--primary-foreground

；

--secondary

、

--secondary-foreground

。

弱化/强调色：

--muted

、

--muted-foreground

；

--accent

、

--accent-foreground

。

警示色：
```
--destructive
```
、
```
--destructive-foreground
```
。
边框与输入框：
```
--border
```
、
```
--input
```
、
```
--ring
```
。
圆角：
```
--radius
```
（例如
```
0.5rem
```
）。

可使用

oklch()

或任何有效的CSS颜色格式。示例：

css

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(14.1% 0.005 285.823);
  --primary: oklch(62.3% 0.214 259.815);
  --primary-foreground: oklch(1 0 0);
  --radius: 0.5rem;
}

Dark mode

暗色模式

Variables: Override the same variables under a
```
.dark
```
scope (or your dark-mode class). KtUI docs use
```
.dark
```
for dark theme.
Tailwind: Add the dark variant, e.g.
```
@custom-variant dark (&:is(.dark *));
```
in your Tailwind entry so utilities like
```
dark:bg-background
```
work.
Theme switch: Use the KTThemeSwitch component or toggle the
```
.dark
```
class on
```
<html>
```
(or a wrapper) to switch between light and dark variables.

变量覆盖： 在
```
.dark
```
作用域（或你使用的暗色模式类）下覆盖相同的变量。KtUI官方文档使用
```
.dark
```
类来实现暗色主题。
Tailwind配置： 在你的Tailwind入口文件中添加暗色变体，例如
```
@custom-variant dark (&:is(.dark *));
```
，这样
```
dark:bg-background
```
这类工具类才能正常工作。
主题切换： 使用KTThemeSwitch组件，或在
```
<html>
```
（或某个父容器）上切换
```
.dark
```
类，实现明暗变量的切换。

Documentation

官方文档

Theming: ktui.io/docs/theming
Dark mode: ktui.io/docs/dark-mode
Installation (variables setup): ktui.io/docs/installation

Prefer the official variable list and examples from these pages over guessing variable names or values.

主题定制： ktui.io/docs/theming
暗色模式： ktui.io/docs/dark-mode
安装（变量设置）：ktui.io/docs/installation

请优先参考这些页面中的官方变量列表和示例，而非自行猜测变量名称或取值。