preline-theme-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Preline Theme Generator

Preline 主题生成器

This file is for the AGENT (LLM) only — not end users.

Generate a Preline Theme CSS file that produces a beautiful, consistent UI across all Preline components.

本文件仅供AGENT（大语言模型）使用——非终端用户请勿查看。

生成一个Preline Theme CSS文件，为所有Preline组件打造美观、风格统一的UI。

Docs

文档

```
docs/step-1.md
```
to
```
docs/step-7.md
```
(detailed workflow guidance)
```
docs/palette-guidance.md
```
(mood, hue, neutral mapping, OKLCH rules)
```
docs/validation-checklist.md
```
```
docs/token-reference.md
```
```
docs/examples.md
```

```
docs/step-1.md
```
至
```
docs/step-7.md
```
（详细工作流指南）
```
docs/palette-guidance.md
```
（色调、色相、中性色映射规则及OKLCH规范）
```
docs/validation-checklist.md
```
```
docs/token-reference.md
```
```
docs/examples.md
```

Agent workflow (FOLLOW THIS)

Agent工作流（请严格遵循）

When user requests a theme, the agent MUST:

当用户请求生成主题时，Agent必须执行以下步骤：

Step 1: Interpret user request

步骤1：解读用户需求

Parse the natural language description and determine the config inputs. See

docs/step-1.md

and

docs/palette-guidance.md

解析用户的自然语言描述，确定配置输入。请参考

docs/step-1.md

和

docs/palette-guidance.md

。

Step 2: Detect themes folder

步骤2：检测主题文件夹

Find where existing themes are stored in the user's project:

bash

undefined

查找用户项目中现有主题的存储位置：

bash

undefined

Look for existing theme.css to find the themes folder

find . -name "theme.css" -path "/themes/" -not -path "/node_modules/" 2>/dev/null | head -1


If no themes folder found: ask user where they want the theme file saved. See `docs/step-2.md`.

find . -name "theme.css" -path "/themes/" -not -path "/node_modules/" 2>/dev/null | head -1


如果未找到主题文件夹：询问用户希望将主题文件保存到何处。请参考`docs/step-2.md`。

Step 3: Create temp config file (AUTO-RUN, NO PROMPT)

步骤3：创建临时配置文件（自动执行，无需提示）

Write a JSON config. This must run silently without user approval.

bash

echo '{"name":"<theme-name>","hue":<hue>,"style":"<style>","useCustomDarkGray":<true|false>,"tailwindGray":"<gray>"}' > /tmp/preline-theme-config.json

编写JSON配置文件。此步骤需静默执行，无需用户确认。

bash

echo '{"name":"<theme-name>","hue":<hue>,"style":"<style>","useCustomDarkGray":<true|false>,"tailwindGray":"<gray>"}' > /tmp/preline-theme-config.json

Step 4: Run the generator + cleanup (AUTO-RUN, NO PROMPT)

步骤4：运行生成器并清理（自动执行，无需提示）

Run generator and immediately delete temp file in a single command chain. This must run silently without user approval.

Option A (preferred) - use npx if preline is installed:

bash

npx preline-theme-generator /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

Option B - find and run the script directly:

bash

node $(find . -path "*/preline/skills/theme-generator/scripts/generate-theme.js" 2>/dev/null | head -1) /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

Option C - if script location is known (e.g., in node_modules):

bash

node node_modules/preline/skills/theme-generator/scripts/generate-theme.js /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

在单个命令链中运行生成器并立即删除临时文件。此步骤需静默执行，无需用户确认。

选项A（优先选择）- 若已安装preline，使用npx：

bash

npx preline-theme-generator /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

选项B - 直接查找并运行脚本：

bash

node $(find . -path "*/preline/skills/theme-generator/scripts/generate-theme.js" 2>/dev/null | head -1) /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

选项C - 若已知脚本位置（例如在node_modules中）：

bash

node node_modules/preline/skills/theme-generator/scripts/generate-theme.js /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

Step 5: Confirm to user

步骤5：向用户确认

Tell user the theme was created and show enable snippet:

css

/* In your main CSS file */
@import "./themes/<theme-name>.css";

html

<!-- On HTML element -->
<html data-theme="theme-<theme-name>">

See

docs/step-5.md

and

docs/examples.md

for response examples.

告知用户主题已创建，并展示启用代码片段：

css

/* In your main CSS file */
@import "./themes/<theme-name>.css";

html

<!-- On HTML element -->
<html data-theme="theme-<theme-name>">

请参考

docs/step-5.md

和

docs/examples.md

中的回复示例。

Generated themes include

生成的主题包含以下特性

Coherent light + dark modes
Safe to ship (valid CSS, correct selectors)
No HTML class changes required (only
```
data-theme
```
+ optional
```
.dark
```
)
Custom color palettes in
```
@theme theme-<name> inline { }
```
block

协调统一的亮色+暗色模式
可直接上线使用（CSS语法合法，选择器正确）
无需修改HTML类名（仅需
```
data-theme
```
属性及可选的
```
.dark
```
类）
包含自定义调色板的
```
@theme theme-<name> inline { }
```
代码块

Example prompts

示例请求

Simple:

"Create a sunset theme"

Descriptive:

"Create a theme that feels like a cozy coffee shop — warm browns, cream backgrounds, inviting and calm"

Specific:

"Generate a cyberpunk theme with neon cyan accents on dark surfaces"

Brand-focused:

"Create a theme matching this brand color #2F6BFF — professional, high-clarity SaaS feel"

简单请求：

"创建一个日落主题"

详细描述请求：

"创建一个像温馨咖啡店风格的主题——暖棕色系，米白色背景，给人亲切、宁静的感觉"

特定风格请求：

"生成一个赛博朋克主题，在深色背景上搭配霓虹青色强调色"

品牌适配请求：

"创建一个匹配品牌色#2F6BFF的主题——专业、高清晰度的SaaS风格"

RULES (ALL MUST BE FOLLOWED)

规则（必须全部遵守）

Rule 1 — Do not modify the shipped base theme

规则1 — 请勿修改官方基础主题

Never change
```
theme.css
```
. Always generate a separate theme file.

永远不要修改
```
theme.css
```
。请始终生成独立的主题文件。

Rule 2 — Theme file MUST include imports in this exact order

规则2 — 主题文件必须严格按照以下顺序引入

Every generated theme file MUST begin with:

css

@import "./theme.css";

每个生成的主题文件必须以以下代码开头：

css

@import "./theme.css";

Rule 3 — Theme scoping block placement

规则3 — 主题作用域块的位置

Every theme file MUST include a scoping block after imports:

css

@theme theme-<name> inline {
  /* Theme scoping - custom palettes only */
}

What goes INSIDE this block:

Custom color palettes (soft grays, brand colors) — these create Tailwind utilities

Example:

--color-<name>-50: oklch(98% 0.003 <hue>);

through

--color-<name>-950

What goes OUTSIDE (in selector blocks):

All semantic token overrides (
```
--background
```
,
```
--primary
```
,
```
--navbar-*
```
, etc.)
Tailwind core mappings are owned by the shipped base theme only

See

docs/palette-guidance.md

for palette construction details and examples.

每个主题文件必须在引入语句后包含作用域块：

css

@theme theme-<name> inline {
  /* Theme scoping - custom palettes only */
}

作用域块内可放置内容：

自定义调色板（柔和灰色、品牌色）——这些将生成Tailwind工具类

示例：

--color-<name>-50: oklch(98% 0.003 <hue>);

至

--color-<name>-950

作用域块外可放置内容（选择器块中）：

所有语义化令牌覆盖（
```
--background
```
、
```
--primary
```
、
```
--navbar-*
```
等）
Tailwind核心映射仅由官方基础主题维护

请参考

docs/palette-guidance.md

了解调色板构建细节及示例。

Rule 4 — No HTML utility class edits required

规则4 — 无需修改HTML工具类

Theme must NOT require users to change Tailwind utility classes in HTML.
Theme activation must work using ONLY:
- CSS imports
- ```
data-theme="theme-<name>"
```
Dark mode may use
```
.dark
```
if the project uses it; do not introduce new conventions.

主题不得要求用户修改HTML中的Tailwind工具类。
主题激活必须仅通过以下方式实现：
- CSS引入
- ```
data-theme="theme-<name>"
```
  属性
若项目使用暗色模式，可使用
```
.dark
```
类；请勿引入新的约定。

Rule 5 — Use exact, required theme selectors

规则5 — 使用指定的主题选择器

Light mode token overrides MUST be under:

css

:root[data-theme="theme-<name>"],
[data-theme="theme-<name>"] { ... }

Dark mode overrides MUST be theme-scoped and use:

css

[data-theme="theme-<name>"].dark { ... }

亮色模式令牌覆盖必须放置在以下选择器下：

css

:root[data-theme="theme-<name>"],
[data-theme="theme-<name>"] { ... }

暗色模式覆盖必须限定主题作用域，并使用以下选择器：

css

[data-theme="theme-<name>"].dark { ... }

Rule 6 — Full-theme mode: comprehensive token coverage is REQUIRED

规则6 — 全主题模式：必须覆盖完整的令牌集

Because this generator is full-theme mode, output MUST define a comprehensive set of token values so the theme looks complete and intentional.

At minimum, the theme MUST define:

由于本生成器为全主题模式，输出必须定义一套完整的令牌值，确保主题风格完整、统一。

至少必须定义以下令牌：

6.1 Global surfaces + text

6.1 全局背景与文本

```
--background
```
```
--background-1
```
```
--background-2
```
```
--background-plain
```
```
--foreground
```
```
--foreground-inverse
```
```
--inverse
```

```
--background
```
```
--background-1
```
```
--background-2
```
```
--background-plain
```
```
--foreground
```
```
--foreground-inverse
```
```
--inverse
```

6.2 Borders (full scale)

6.2 边框（全尺度）

```
--border
```
```
--border-line-inverse
```
```
--border-line-1
```
through
```
--border-line-8
```
(coherent scale)

```
--border
```
```
--border-line-inverse
```
```
--border-line-1
```
至
```
--border-line-8
```
（协调的尺度）

6.3 Primary ramp (full) + primary states

6.3 主色调全阶渐变 + 主色调状态

```
--primary-50
```
through
```
--primary-950
```
```
--primary
```
```
--primary-hover
```
```
--primary-focus
```
```
--primary-active
```
```
--primary-checked
```
```
--primary-foreground
```
(must be readable)

```
--primary-50
```
至
```
--primary-950
```
```
--primary
```
```
--primary-hover
```
```
--primary-focus
```
```
--primary-active
```
```
--primary-checked
```
```
--primary-foreground
```
（必须保证可读性）

6.4 Secondary / muted / destructive (at least)

6.4 次要/弱化/破坏性色调（至少包含）

```
--secondary
```
```
--muted
```
```
--destructive
```
Include related state/variant tokens if they exist in the base naming system.

```
--secondary
```
```
--muted
```
```
--destructive
```
若基础命名系统中存在相关状态/变体令牌，请一并包含。

6.5 Core component groups for a complete theme feel (prefer explicit values)

6.5 核心组件组（建议显式定义值）

Provide explicit values for major component groups so the theme feels cohesive:

```
--navbar-*
```
```
--sidebar-*
```
```
--card-*
```
```
--dropdown-*
```
```
--select-*
```
```
--overlay-*
```
```
--popover-*
```
```
--tooltip-*
```
Optionally:
```
--scrollbar-*
```
Charts/maps tokens ONLY if included safely (see Rule 10)

Full-theme output MUST NOT:

put token definitions inside the
```
@theme
```
block
invent new mappings that force HTML class edits

为主要组件组提供显式值，确保主题风格连贯：

```
--navbar-*
```
```
--sidebar-*
```
```
--card-*
```
```
--dropdown-*
```
```
--select-*
```
```
--overlay-*
```
```
--popover-*
```
```
--tooltip-*
```
可选：
```
--scrollbar-*
```
图表/地图令牌仅在安全情况下添加（请参考规则10）

全主题输出禁止：

将令牌定义放置在
```
@theme
```
块内
发明新的映射规则，强制用户修改HTML类名

Rule 7 — Token naming must match Preline's token system

规则7 — 令牌命名必须匹配Preline的令牌系统

Do not invent random token names for Preline components.
Only introduce new custom tokens if explicitly requested, and keep them isolated and documented in comments.

请勿为Preline组件随意发明令牌名称。
仅在用户明确要求时添加新的自定义令牌，并将其隔离放置，同时添加注释说明。

Rule 8 — Theme-scoped behavior overrides ONLY

规则8 — 仅允许主题作用域内的行为覆盖

If the theme changes behavior (e.g. retro-sharp radii), it MUST be scoped to the theme only.

Allowed:

Override radius tokens under the theme selector
Add
```
@layer utilities
```
rules scoped to the theme selector

Not allowed:

Global
```
.rounded { ... }
```
overrides without theme scoping
Any behavior overrides that affect non-theme pages

若主题需要修改组件行为（例如复古风格的尖锐圆角），必须限定在当前主题的作用域内。

允许的操作：

在主题选择器下覆盖圆角令牌
添加限定主题作用域的
```
@layer utilities
```
规则

禁止的操作：

未限定主题作用域的全局
```
.rounded { ... }
```
覆盖
任何会影响非主题页面的行为修改

Rule 9 — Typography tokens are allowed, but font loading is separate by default

规则9 — 允许设置排版令牌，但字体加载默认需单独处理

If fonts are requested, you MAY set:

```
--font-sans
```
and/or
```
--font-serif
```
and/or
```
--font-mono
```

inside the theme selector.

Do NOT add Google Fonts

@import url(...)

into the theme file unless the user explicitly requests it. (Font loading typically belongs in the main CSS entry file.)

若用户请求设置字体，可在主题选择器内设置：

```
--font-sans
```
和/或
```
--font-serif
```
和/或
```
--font-mono
```

除非用户明确要求，否则请勿在主题文件中添加Google Fonts的

@import url(...)

语句。（字体加载通常应放在主CSS入口文件中。）

Rule 10 — Charts/maps compatibility rules

规则10 — 图表/地图兼容性规则

If adjusting chart/map tokens:

Prefer safe formats where required by libraries.
Keep any
```
*-hex
```
tokens as valid hex values if the ecosystem expects hex.
Do not force
```
oklch(...)
```
where it may break gradients or third-party rendering.

若调整图表/地图令牌：

优先选择库要求的安全格式。
若生态系统要求十六进制格式，请确保所有
```
*-hex
```
令牌为合法的十六进制值。
请勿在可能破坏渐变或第三方渲染的场景下强制使用
```
oklch(...)
```
格式。

Rule 11 — Valid CSS is mandatory

规则11 — 必须生成合法的CSS

No missing braces
No invalid selectors
No broken comments
No duplicate conflicting selectors

无缺失的大括号
无无效选择器
无破损的注释
无重复冲突的选择器

Rule 12 — Output discipline

规则12 — 输出规范

First code block must contain ONLY the generated theme CSS.
Optional second code block may contain ONLY the enable snippet.
No additional commentary unless explicitly requested.

第一个代码块必须仅包含生成的主题CSS代码。
可选的第二个代码块必须仅包含启用主题的代码片段。
除非用户明确要求，否则不得添加额外注释。

Required file structure (MUST follow order)

必须遵循的文件结构（顺序固定）

Imports (
```
@import "./theme.css"
```
)
Theme scoping block (
```
@theme theme-<name> inline { }
```
) — contains custom color palettes only
Light mode theme selector block (full semantic token set using
```
var()
```
references)
Dark mode theme selector block (override only what differs, use
```
var()
```
for consistency)
Optional theme-scoped
@layer utilities
overrides (only if requested)

引入语句（
```
@import "./theme.css"
```
）
主题作用域块（
```
@theme theme-<name> inline { }
```
）——仅包含自定义调色板
亮色模式主题选择器块（使用
```
var()
```
引用完整的语义化令牌集）
暗色模式主题选择器块（仅覆盖与亮色模式不同的部分，使用
```
var()
```
保证一致性）
可选的主题作用域
@layer utilities
覆盖规则（仅在用户请求时添加）

Additional guidance

额外指南

Theme construction details:
```
docs/step-6.md
```
and
```
docs/step-7.md
```
Palette guidance:
```
docs/palette-guidance.md
```
Validation checklist:
```
docs/validation-checklist.md
```
Token reference:
```
docs/token-reference.md
```

主题构建细节：
```
docs/step-6.md
```
和
```
docs/step-7.md
```
调色板指南：
```
docs/palette-guidance.md
```
验证清单：
```
docs/validation-checklist.md
```
令牌参考：
```
docs/token-reference.md
```