casper-design-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Casper Studios Design System

Casper Studios 设计系统

A clean, elevated SaaS design system built on shadcn/ui, Tailwind CSS v4, and React (Vite). Every interface generated for Casper Studios — whether a client demo, internal tool, or quick prototype — must follow these rules to maintain a consistent, professional visual identity across the team.

Before generating any UI code, read this file completely and the reference files listed below. You MUST read the reference files — they contain rules and code examples that are required for correct output. Skipping them will produce incorrect, off-brand UI.

Required for EVERY project:

references/components.md
— ALWAYS read. Reusable pieces: stat cards, list items, filter bars, kanban boards, profile cards, product cards, activity feeds, toast notifications, form validation states. Required whenever building UI elements inside a layout.
references/theme.css
— ALWAYS read. Tailwind CSS v4 theme tokens. Copy this file into your project as-is.
assets/
— Contains Casper Studios logo SVGs in 4 variants (default, variant, mono-black, mono-white). Use the correct variant based on background color — see the Logo section below.

Required based on platform:

references/web-layouts.md
— MUST read when the project is a web application. Web-specific responsive rules + code examples: app shell, sidebar nav, dashboard grid, data table page, page header.
references/mobile.md
— MUST read when the project is a mobile application. Mobile-specific rules + code examples: device frame, top bar, bottom tab navigation, form patterns, pinned-button layout, list views, card stacks, full screen compositions, contextual actions (menus + bottom sheets).

Non-negotiable: Do not generate UI without reading the platform reference file first. If you are unsure whether the project is web or mobile, ask the user before proceeding.

这是一个基于shadcn/ui、Tailwind CSS v4和**React (Vite)**构建的简洁高端的SaaS设计系统。为Casper Studios生成的所有界面——无论是客户演示、内部工具还是快速原型——都必须遵循这些规则，以在团队内保持一致、专业的视觉标识。

在生成任何UI代码之前，请完整阅读本文档以及下方列出的参考文件。你必须阅读参考文件——它们包含生成正确输出所需的规则和代码示例。跳过这些文件会生成不符合品牌规范的错误界面。

所有项目的必选内容：

references/components.md
— 务必阅读。可复用组件：统计卡片、列表项、筛选栏、看板、个人资料卡片、产品卡片、活动流、提示通知、表单验证状态。在布局内构建UI元素时必须使用。
references/theme.css
— 务必阅读。Tailwind CSS v4主题令牌。直接将此文件复制到你的项目中。
assets/
— 包含4种变体的Casper Studios Logo SVG文件（默认版、变体版、单色黑色版、单色白色版）。根据背景颜色选择正确的变体——详见下方Logo章节。

基于平台的必选内容：

references/web-layouts.md
— 当项目为Web应用时必须阅读。Web端专属响应式规则+代码示例：应用外壳、侧边栏导航、仪表盘网格、数据表页面、页面头部。
references/mobile.md
— 当项目为移动应用时必须阅读。移动端专属规则+代码示例：设备框架、顶部栏、底部标签导航、表单模式、固定按钮布局、列表视图、卡片堆叠、全屏布局、上下文操作（菜单+底部弹窗）。

硬性要求： 未阅读对应平台的参考文件，不得生成UI。若不确定项目是Web还是移动应用，请先询问用户。

Before You Generate: Required Context

生成前须知：必要上下文

Before producing any UI code, confirm the following with the user. If their prompt already answers these clearly, proceed without asking. If not, ask before generating anything.

Platform — Is this a web application or a mobile application? (Determines which reference file to follow.)
Dark mode — Should the interface support dark mode, or is it light mode only? (Determines whether to implement
```
.dark
```
class overrides, use
```
bg-neutral-0
```
for surfaces, and include the mono-white logo variant.)

Do NOT assume defaults for these. If the user says "build me a dashboard," you don't know if it's web or mobile, or if it needs dark mode. Ask.

在生成任何UI代码之前，请与用户确认以下内容。若用户的提示已明确回答这些问题，可直接进行；若未明确，请先询问。

平台 — 这是Web应用还是移动应用？（决定需遵循哪个参考文件。）
深色模式 — 界面是否需要支持深色模式，还是仅使用浅色模式？（决定是否实现
```
.dark
```
类覆盖、使用
```
bg-neutral-0
```
作为表面背景，以及是否使用单色白色Logo变体。）

请勿假设默认值。若用户说“帮我做一个仪表盘”，你无法确定它是Web还是移动应用，也无法确定是否需要深色模式，必须询问。

Summary

概述

The Casper aesthetic is clean authority — a professional SaaS style that feels premium without trying too hard. It uses generous whitespace, a restrained purple accent, and soft rounded surfaces to create interfaces that feel trustworthy and modern. Think Linear meets Notion: structured, breathable, quietly confident.

Casper的美学风格是简洁权威——一种专业的SaaS风格，兼具高级感却不刻意。它使用充裕的留白、克制的紫色强调色和柔和的圆角表面，打造出值得信赖且现代的界面。可以理解为Linear与Notion的结合：结构化、透气、低调自信。

Core Principles

核心原则

Whitespace is a feature. Generous padding, breathing room between sections. Never cram.
One accent, used sparingly. Brand purple (
```
#5900FF
```
) appears on active states, primary buttons, and key CTAs — nowhere else. If everything is purple, nothing is.
Rounded but not bubbly. 10px default radius for cards (shadcn default). Buttons and inputs use 8px. Feels modern without feeling like a toy.
Flat with depth hints. No heavy shadows. Use
```
shadow-sm
```
for cards,
```
shadow-md
```
for popovers. Never use
```
shadow-lg
```
on in-page elements.
Content over chrome. The UI should disappear. Users notice the data, not the design.

留白是特色。充裕的内边距、区块间的呼吸空间。绝不过度拥挤。
单一强调色，谨慎使用。品牌紫色（
```
#5900FF
```
）仅用于激活状态、主按钮和关键CTA——其他地方不得使用。若所有元素都是紫色，就没有重点了。
圆角但不浮夸。卡片默认圆角为10px（shadcn默认值）。按钮和输入框使用8px圆角。既现代又不会显得幼稚。
扁平化但有层次暗示。不使用厚重阴影。卡片使用
```
shadow-sm
```
，弹出层使用
```
shadow-md
```
。页面内元素绝不能使用
```
shadow-lg
```
。
内容优先于装饰。UI应隐形。用户关注的是数据，而非设计。

Tech Stack

技术栈

React (Vite) with TypeScript
Tailwind CSS v4 — Use the theme file at
```
references/theme.css
```
as Casper brand overrides
shadcn/ui — Initialize a standard shadcn/ui project first (
```
shadcn init
```
), then layer Casper brand tokens from
```
references/theme.css
```
on top. The shadcn semantic layer (
```
bg-background
```
,
```
text-foreground
```
,
```
bg-primary
```
,
```
border-border
```
, etc.) is the base — Casper's theme.css adds brand colors, typography, shadows, and spacing on top of it, not as a replacement. Use shadcn components directly. Do NOT create custom base components that duplicate shadcn functionality
Lucide React — Icon library. Always use Lucide, never Heroicons or FontAwesome
Fonts —
```
DM Sans
```
with
```
sans-serif
```
as fallback for all UI text. Load via Google Fonts or bundle

React (Vite) + TypeScript
Tailwind CSS v4 — 使用
```
references/theme.css
```
中的主题文件作为Casper品牌覆盖配置。shadcn的语义层（
```
bg-background
```
、
```
text-foreground
```
、
```
bg-primary
```
、
```
border-border
```
等）是基础——Casper的theme.css在其之上添加品牌颜色、排版、阴影和间距配置，而非替换。直接使用shadcn组件，请勿创建重复shadcn功能的自定义基础组件。
Lucide React — 图标库。务必使用Lucide，不得使用Heroicons或FontAwesome。
字体 — 所有UI文本使用
```
DM Sans
```
，后备字体为
```
sans-serif
```
。等宽字体（
```
font-mono
```
）仅适用于代码块、数据标签和ID。

Color System

色彩系统

The palette is intentionally restrained. Most of the UI is neutral gray + white, with purple as a sharp accent.

调色板刻意保持克制。UI大部分为中性灰+白色，搭配紫色作为鲜明强调色。

Usage Rules

使用规则

Role	Token	Hex	When to use
Brand accent	`brand-500`	`#5900FF`	Active nav items, primary buttons, links, focus rings
Brand subtle	`brand-50`	`#EEE5FF`	Active nav background, selected row highlight, hover tints
Brand light	`brand-100`	`#DECCFF`	Icon circle backgrounds, soft tag fills
Default text	`neutral-950`	`#0A0A0A`	Page titles, headings
Body text	`neutral-900`	`#171717`	Primary body text
Subtext	`neutral-500`	`#737373`	Metadata, timestamps, secondary labels
Borders	`neutral-200`	`#E5E5E5`	Card borders, dividers, table lines
Surface	`neutral-50`	`#FAFAFA`	Page background behind cards
Card surface	`neutral-0`	`#FFFFFF`	Card backgrounds, panels (use `bg-neutral-0` for dark mode compatibility — see Dark Mode section)

角色	令牌	十六进制值	使用场景
品牌强调色	`brand-500`	`#5900FF`	激活的导航项、主按钮、链接、焦点环
品牌浅色调	`brand-50`	`#EEE5FF`	激活的导航背景、选中行高亮、悬停色调
品牌淡色调	`brand-100`	`#DECCFF`	图标圆形背景、柔和标签填充
默认文本	`neutral-950`	`#0A0A0A`	页面标题、标题文本
正文文本	`neutral-900`	`#171717`	主要正文文本
辅助文本	`neutral-500`	`#737373`	元数据、时间戳、次要标签
边框	`neutral-200`	`#E5E5E5`	卡片边框、分隔线、表格线条
页面背景	`neutral-50`	`#FAFAFA`	卡片后方的页面背景
卡片背景	`neutral-0`	`#FFFFFF`	卡片背景、面板（为兼容深色模式，请使用 `bg-neutral-0` ——详见深色模式章节）

Semantic Colors

语义色彩

Use these ONLY for status indicators, badges, and contextual feedback — never as decorative accents.

Success —
```
success-500
```
(
```
#22C55E
```
) for badges/icons,
```
success-50
```
for pill backgrounds
Error —
```
error-500
```
(
```
#EF4444
```
) for badges/icons,
```
error-50
```
for pill backgrounds
Warning —
```
warning-500
```
(
```
#F59E0B
```
) for badges/icons,
```
warning-50
```
for pill backgrounds

仅将这些颜色用于状态指示器、徽章和上下文反馈——切勿用作装饰性强调色。

成功 —
```
success-500
```
（
```
#22C55E
```
）用于徽章/图标，
```
success-50
```
用于胶囊背景
错误 —
```
error-500
```
（
```
#EF4444
```
）用于徽章/图标，
```
error-50
```
用于胶囊背景
警告 —
```
warning-500
```
（
```
#F59E0B
```
）用于徽章/图标，
```
warning-50
```
用于胶囊背景

What NOT to do

禁止操作

Do NOT use brand purple for backgrounds on large surfaces
Do NOT use semantic colors decoratively
Do NOT introduce new colors. If you need a new shade, use the neutral scale
Do NOT use opacity-based colors when a token exists (e.g., don't do
```
text-black/50
```
, use
```
neutral-500
```
)

不得将品牌紫色用于大面积背景
不得将语义色彩用于装饰
不得引入新颜色。若需要新色调，请使用中性色阶
已有对应令牌时，不得使用基于透明度的颜色（例如，请勿使用
```
text-black/50
```
，应使用
```
neutral-500
```
）

Typography

排版

All text is set in DM Sans with sans-serif as fallback (

font-family: 'DM Sans', sans-serif

). Monospace (

font-mono

) is acceptable for code blocks, data labels, and IDs only.

所有文本均使用DM Sans，后备字体为

sans-serif

（

font-family: 'DM Sans', sans-serif

）。等宽字体（

font-mono

）仅适用于代码块、数据标签和ID。

Scale

字号体系

Style	Size	Weight	Line Height	Use
Heading 1	30px	500	36px	Page titles only. One per view.
Heading 2	20px	500	24px	Section titles within a page
Heading 3	16px	500	20px	Card titles, subsection labels
Body	14px	400	20px	Default paragraph and UI text
Body Bold	14px	500	20px	Emphasis within body text, table headers
Caption	12px	400	16px	Timestamps, helper text, metadata
Caption Bold	12px	500	16px	Badge labels, small category tags

样式	字号	字重	行高	使用场景
一级标题	30px	500	36px	仅用于页面标题。每个视图仅一个。
二级标题	20px	500	24px	页面内的区块标题
三级标题	16px	500	20px	卡片标题、子区块标签
正文	14px	400	20px	默认段落和UI文本
粗体正文	14px	500	20px	正文内强调内容、表格表头
说明文本	12px	400	16px	时间戳、辅助文本、元数据
粗体说明文本	12px	500	16px	徽章标签、小型分类标签

Rules

规则

Headings are always
```
medium
```
weight (500), never bold (700)
NEVER use all-caps except for tiny metadata labels (e.g., "STATUS", "OWNER" in table column headers) set at caption size
Links use
```
brand-500
```
color with no underline by default, underline on hover
Do NOT vary font size beyond this scale. If something feels wrong, adjust spacing not font size

标题始终使用
```
medium
```
字重（500），绝不能使用粗体（700）
除了说明文本大小的极小元数据标签（例如，表格列标题中的“STATUS”、“OWNER”），绝不能使用全大写
链接默认使用
```
brand-500
```
颜色且无下划线，悬停时显示下划线
不得超出此字号体系调整字体大小。若觉得不合适，请调整间距而非字号

Spacing & Layout

间距与布局

Spacing Scale

间距体系

Use Tailwind's default spacing scale. Key values:

```
4px
```
(p-1) — icon padding, tight gaps
```
8px
```
(p-2) — badge padding, small gaps
```
12px
```
(p-3) — input padding, card internal gaps
```
16px
```
(p-4) — card padding, section gaps
```
24px
```
(p-6) — between cards, content sections
```
32px
```
(p-8) — major section separation
```
48px
```
(p-12) — page-level padding on large screens

使用Tailwind默认的间距体系。关键值：

```
4px
```
(p-1) — 图标内边距、紧凑间隙
```
8px
```
(p-2) — 徽章内边距、小间隙
```
12px
```
(p-3) — 输入框内边距、卡片内部间隙
```
16px
```
(p-4) — 卡片内边距、区块间隙
```
24px
```
(p-6) — 卡片之间、内容区块之间
```
32px
```
(p-8) — 主要区块分隔
```
48px
```
(p-12) — 大屏幕上的页面级内边距

Layout Rules

布局规则

Page background:
```
neutral-50
```
(
```
#FAFAFA
```
)
Content is always organized inside Cards (white background, border, rounded)
Maximum content width:
```
1280px
```
centered
On pages with a sidebar, sidebar is
```
240px
```
fixed width
Main content area uses remaining space with
```
24px
```
padding

页面背景：
```
neutral-50
```
（
```
#FAFAFA
```
）
内容始终组织在卡片内（白色背景、边框、圆角）
内容最大宽度：
```
1280px
```
，居中对齐
带侧边栏的页面中，侧边栏宽度固定为
```
240px
```
主内容区域使用剩余空间，内边距为
```
24px
```

Shadows & Elevation

阴影与层次

The design is predominantly flat. Shadows are used to indicate layers, not to add decoration.

Token	Use
`shadow-sm`	Cards, inputs at rest
`shadow-md`	Dropdown menus, popovers, tooltips
`shadow-lg`	Modals, command palettes, overlays ONLY
`shadow-overlay`	Semantic alias for `shadow-lg` — identical value. Use on modals/sheets so the intent reads clearly in code

NEVER apply

shadow-lg

(or its alias

shadow-overlay

) to cards or in-page elements. These are reserved for floating layers only.

设计以扁平化为主。阴影仅用于区分层级，而非装饰。

令牌	使用场景
`shadow-sm`	卡片、静止状态的输入框
`shadow-md`	下拉菜单、弹出层、提示框
`shadow-lg`	仅用于模态框、命令面板、覆盖层
`shadow-overlay`	`shadow-lg` 的语义别名——值完全相同。用于模态框/弹窗，使代码意图更清晰

绝不能将

shadow-lg

（或其别名

shadow-overlay

）应用于卡片或页面内元素。这些阴影仅保留给浮动层级使用。

Border Radius

圆角

The theme file (

references/theme.css

) uses the shadcn/ui radius system — a single

--radius

base variable in

:root

that controls the entire scale via

calc()

. This is mapped into Tailwind classes via

@theme inline

. No Tailwind v4 defaults are overridden.

Token	Tailwind Class	Default Value	Use
`--radius-sm`	`rounded-sm`	6px	Inner elements, nav items, small nested controls
`--radius-md`	`rounded-md`	8px	Buttons, inputs, popovers, tooltips, chart tooltips
`--radius-lg`	`rounded-lg`	10px	Cards, panels, large containers
`--radius-xl`	`rounded-xl`	14px	Modal containers, dialogs, hero cards
(Tailwind built-in)	`rounded-full`	9999px	Badges, pills, avatars, icon circles

The base value

--radius: 0.625rem

(10px) is the shadcn default. To make the entire UI sharper or rounder, change this single value — all tokens recalculate automatically.

Cards always use

rounded-lg

(10px). Buttons and inputs always use

rounded-md

(8px). Nested elements inside cards should use

rounded-sm

(6px) for non-interactive elements to maintain visual hierarchy — the inner radius should always be smaller than the outer.

主题文件（

references/theme.css

）使用shadcn/ui的圆角体系——

:root

中的单个

--radius

基础变量通过

calc()

控制整个圆角体系。它通过

@theme inline

映射到Tailwind类。未覆盖任何Tailwind v4默认值。

令牌	Tailwind类	默认值	使用场景
`--radius-sm`	`rounded-sm`	6px	内部元素、导航项、小型嵌套控件
`--radius-md`	`rounded-md`	8px	按钮、输入框、弹出层、提示框、图表提示框
`--radius-lg`	`rounded-lg`	10px	卡片、面板、大型容器
`--radius-xl`	`rounded-xl`	14px	模态框容器、对话框、英雄卡片
(Tailwind内置)	`rounded-full`	9999px	徽章、胶囊、头像、图标圆形

基础值

--radius: 0.625rem

（10px）是shadcn的默认值。若要让整个UI更锐利或更圆润，只需修改这个单一值——所有令牌会自动重新计算。

卡片始终使用

rounded-lg

（10px）。按钮和输入框始终使用

rounded-md

（8px）。卡片内的嵌套元素对于非交互元素应使用

rounded-sm

（6px），以保持视觉层级——内部圆角必须小于外部圆角。

Iconography

图标规范

Use Lucide React exclusively. Import as:
```
import { IconName } from "lucide-react"
```
Default icon size:
```
16px
```
for inline,
```
20px
```
for standalone
Icon color follows its text context (e.g.,
```
neutral-500
```
for subtext,
```
brand-500
```
for active)
For icons inside circular backgrounds (common in lists and dashboards):
- Circle:
```
40px
```
  diameter,
```
brand-50
```
  or
```
brand-100
```
  background,
```
rounded-full
```
- Icon:
```
20px
```
  ,
```
brand-500
```
  color
- For semantic contexts, swap to the matching semantic color pair (e.g.,
```
error-50
```
  bg +
```
error-500
```
  icon)

仅使用Lucide React。导入方式：
```
import { IconName } from "lucide-react"
```
默认图标大小：行内图标为
```
16px
```
，独立图标为
```
20px
```
图标颜色与其所在文本上下文一致（例如，辅助文本使用
```
neutral-500
```
，激活状态使用
```
brand-500
```
）
对于列表和仪表盘中常见的圆形背景内的图标：
- 圆形：直径
```
40px
```
  ，背景为
```
brand-50
```
  或
```
brand-100
```
  ，
```
rounded-full
```
- 图标：
```
20px
```
  ，颜色为
```
brand-500
```
- 语义化场景下，替换为匹配的语义色彩组合（例如，
```
error-50
```
  背景 +
```
error-500
```
  图标）

Casper Studios Logo

Casper Studios Logo规范

The Casper Studios logo has four variants stored in

assets/

. Use the correct variant based on the background it sits on:

Variant	File	When to use
Default (full color)	`assets/logo-on-white-default.svg`	Light/white backgrounds. Gradient icon + purple "CASPER" + dark "STUDIOS". This is the primary logo — use it whenever possible.
Variant (full color)	`assets/logo-on-white-variant.svg`	Light/white backgrounds when you want all-black text instead of purple + dark gray. Same gradient icon.
Mono Black	`assets/logo-mono-black.svg`	Light backgrounds where color is unavailable (e.g., print, grayscale contexts). Grayscale icon + near-black text.
Mono White	`assets/logo-mono-white.svg`	Dark backgrounds only. Gray icon + white text. Use this whenever the logo sits on a dark surface (dark nav bars, dark hero sections, overlays, dark mode).

Casper Studios Logo在

assets/

中有四种变体。根据其所在的背景选择正确的变体：

变体	文件	使用场景
默认（全彩）	`assets/logo-on-white-default.svg`	浅色/白色背景。渐变图标 + 紫色“CASPER” + 深灰色“STUDIOS”。这是主要Logo——尽可能使用。
变体（全彩）	`assets/logo-on-white-variant.svg`	浅色/白色背景，且希望所有文本为黑色而非紫色+深灰色时使用。图标渐变效果相同。
单色黑色	`assets/logo-mono-black.svg`	无法使用颜色的浅色背景（例如，打印、灰度场景）。灰度图标 + 近黑色文本。
单色白色	`assets/logo-mono-white.svg`	仅用于深色背景。灰色图标 + 白色文本。当Logo位于深色表面（深色导航栏、深色英雄区块、覆盖层、深色模式）时使用。

Rules

规则

Light mode (default): Use

logo-on-white-default.svg

logo-on-white-variant.svg

Dark mode or dark surfaces: Use
```
logo-mono-white.svg
```
— never place the default or black logo on a dark background
The logo should appear in the sidebar header (web) or top bar (mobile) at the sizes defined in those patterns
Do NOT resize the logo disproportionately — maintain the original aspect ratio
Do NOT place the logo on busy backgrounds or low-contrast surfaces. If contrast is insufficient, use the mono variant that provides the best visibility
Minimum clear space around the logo:
```
8px
```
on all sides

浅色模式（默认）：使用

logo-on-white-default.svg

或

logo-on-white-variant.svg

深色模式或深色表面：使用
```
logo-mono-white.svg
```
——绝不能在深色背景上使用默认或黑色Logo
Logo应出现在侧边栏头部（Web）或顶部栏（移动）中，尺寸遵循对应模式的定义
不得不成比例地调整Logo大小——保持原始宽高比
不得将Logo放置在杂乱的背景或低对比度的表面上。若对比度不足，请使用可见性最佳的单色变体
Logo周围的最小留白：各边
```
8px
```

shadcn/ui Component Theming

shadcn/ui组件主题配置

Use shadcn/ui components as your base layer. Theme them using the CSS variables in

references/theme.css

. Here is how specific components should be configured:

以shadcn/ui组件为基础层，使用

references/theme.css

中的CSS变量进行主题配置。以下是特定组件的配置方式：

Button

按钮

Primary:
```
brand-500
```
bg,
```
text-white
```
(literal white, not a token),
```
rounded-md
```
. Hover:
```
brand-600
```
.
Secondary: White bg,
```
neutral-200
```
border,
```
neutral-900
```
text,
```
rounded-md
```
. Hover:
```
neutral-50
```
bg.
Ghost: No bg, no border.
```
neutral-600
```
text,
```
rounded-md
```
. Hover:
```
neutral-100
```
bg.
Destructive:
```
error-500
```
bg,
```
text-white
```
,
```
rounded-md
```
.
All buttons:
```
rounded-md
```
(8px),
```
14px
```
font.
Default height:
```
48px
```
(
```
h-12
```
). Use this on standalone pages, forms, modals, and any top-level content area.
Compact height:
```
36px
```
(
```
h-9
```
). Use when the button lives inside a smaller container — cards, panels, table rows, sidebar nav, filter bars, inline actions. The tighter context calls for a tighter control.

主按钮：
```
brand-500
```
背景，
```
text-white
```
（纯白色，非令牌），
```
rounded-md
```
。悬停状态：
```
brand-600
```
。
次按钮：白色背景，
```
neutral-200
```
边框，
```
neutral-900
```
文本，
```
rounded-md
```
。悬停状态：
```
neutral-50
```
背景。
幽灵按钮：无背景、无边框。
```
neutral-600
```
文本，
```
rounded-md
```
。悬停状态：
```
neutral-100
```
背景。
危险按钮：
```
error-500
```
背景，
```
text-white
```
，
```
rounded-md
```
。
所有按钮：
```
rounded-md
```
（8px），
```
14px
```
字体。
默认高度：
```
48px
```
（
```
h-12
```
）。用于独立页面、表单、模态框和任何顶级内容区域的按钮。
紧凑高度：
```
36px
```
（
```
h-9
```
）。当按钮位于较小容器内时使用——卡片、面板、表格行、侧边栏导航、筛选栏、行内操作。紧凑场景需要紧凑控件。

Badge

徽章

```
rounded-full
```
(pill shape). Height
```
22px
```
. Caption-bold text (12px, 500 weight).
Semantic badges: Use pastel bg + darker text. E.g., success badge =
```
success-50
```
bg,
```
success-700
```
text.
Neutral badge:
```
neutral-100
```
bg,
```
neutral-700
```
text.
Brand badge:
```
brand-50
```
bg,
```
brand-700
```
text.
Always include a small dot or icon before the label when indicating status.

```
rounded-full
```
（胶囊形状）。高度
```
22px
```
。粗体说明文本（12px/500字重）。
语义化徽章：使用淡色背景 + 深色文本。例如，成功徽章 =
```
success-50
```
背景，
```
success-700
```
文本。
中性徽章：
```
neutral-100
```
背景，
```
neutral-700
```
文本。
品牌徽章：
```
brand-50
```
背景，
```
brand-700
```
文本。
指示状态时，标签前必须包含一个小点或图标。

Card

卡片

White background (

bg-neutral-0

1px

neutral-200

border.

rounded-lg

(10px).

shadow-sm

Internal padding:
```
16px
```
minimum,
```
24px
```
for spacious cards.
Card headers:
```
Heading 3
```
(16px/500) with optional "View all" link aligned right.
Separate header from content with a
```
1px
```
```
neutral-200
```
divider.

白色背景（
```
bg-neutral-0
```
）。
```
1px
```
```
neutral-200
```
边框。
```
rounded-lg
```
（10px）。
```
shadow-sm
```
。
内部内边距：最小
```
16px
```
，宽敞卡片使用
```
24px
```
。
卡片头部：三级标题（16px/500），右侧可选择性添加“查看全部”链接。
使用
```
1px
```
```
neutral-200
```
分隔线分隔头部与内容。

Table

表格

Use shadcn
```
<Table>
```
. No outer border on the table itself — let the parent Card provide the container.
Column headers: Caption-bold (12px/500),
```
neutral-500
```
color, uppercase.
Row height:
```
48-56px
```
. Rows separated by
```
1px
```
```
neutral-200
```
bottom border.
Row hover:
```
neutral-50
```
background.
No alternating row colors.

使用shadcn
```
<Table>
```
。表格本身无外边框——由父卡片提供容器。
列标题：粗体说明文本（12px/500），
```
neutral-500
```
颜色，全大写。
行高：
```
48-56px
```
。行之间使用
```
1px
```
```
neutral-200
```
下边框分隔。
行悬停：
```
neutral-50
```
背景。
不使用交替行颜色。

Input / Textarea

输入框 / 文本域

```
rounded-md
```
(8px).
```
1px
```
```
neutral-200
```
border.
```
neutral-50
```
bg or white bg.
Focus:
```
2px
```
```
brand-500
```
ring (use Tailwind
```
ring-2 ring-brand-500
```
).
Labels MUST be visible and external — render a
```
<label>
```
element above every input, never inside it. Labels use
```
14px
```
/400 in
```
neutral-900
```
. The gap between label and input is
```
6px
```
(
```
space-y-1.5
```
).
Placeholder text MUST be de-emphasized —
```
neutral-400
```
color, normal weight (400), short hint text (e.g., "e.g. john@email.com"). Placeholders are supplementary hints, not labels.
Select inputs follow the same pattern: visible label above, de-emphasized placeholder inside.
Spacing between fields:
```
16px
```
(
```
space-y-4
```
or
```
gap-4
```
).
Default height:
```
48px
```
(
```
h-12
```
). Use for inputs on standalone pages, forms, modals, and any top-level content area.
Compact height:
```
36px
```
(
```
h-9
```
). Use when the input lives inside a smaller container — cards, panels, table rows, filter bars, inline search fields. Same logic as compact buttons.

```
rounded-md
```
（8px）。
```
1px
```
```
neutral-200
```
边框。
```
neutral-50
```
背景或白色背景。
聚焦状态：
```
2px
```
```
brand-500
```
环（使用Tailwind
```
ring-2 ring-brand-500
```
）。
标签必须可见且位于外部——在每个输入框上方渲染
```
<label>
```
元素，绝不能放在输入框内。标签使用
```
14px
```
/400字重，
```
neutral-900
```
颜色。标签与输入框之间的间距为
```
6px
```
（
```
space-y-1.5
```
）。
占位符文本必须弱化——
```
neutral-400
```
颜色，常规字重（400），简短提示文本（例如，“e.g. john@email.com”）。占位符是补充提示，而非标签。
选择输入框遵循相同模式：上方可见标签，内部弱化占位符。
字段之间的间距：
```
16px
```
（
```
space-y-4
```
或
```
gap-4
```
）。
默认高度：
```
48px
```
（
```
h-12
```
）。用于独立页面、表单、模态框和任何顶级内容区域的输入框。
紧凑高度：
```
36px
```
（
```
h-9
```
）。当输入框位于较小容器内时使用——卡片、面板、表格行、筛选栏、行内搜索框。逻辑与紧凑按钮相同。

Sidebar (App Shell)

侧边栏（应用外壳）

See

references/web-layouts.md

for the full sidebar code pattern. Key specs:

Width:
```
240px
```
. White background. Right border:
```
1px
```
```
neutral-200
```
.
Nav items:
```
36px
```
height (compact — inside sidebar panel),
```
rounded-sm
```
(6px),
```
12px
```
left padding.
- Default:
```
neutral-600
```
  text. Active:
```
brand-50
```
  bg,
```
brand-500
```
  text,
```
font-weight: 500
```
  . Hover:
```
neutral-100
```
  bg.
Group labels: Caption (12px/400),
```
neutral-400
```
,
```
24px
```
top margin between groups.
On mobile: Sidebar collapses to a
```
Sheet
```
(slide-in from left).

完整的侧边栏代码模式请阅读

references/web-layouts.md

。关键规格：

宽度：
```
240px
```
。白色背景。右侧边框：
```
1px
```
```
neutral-200
```
。
导航项：高度
```
36px
```
（紧凑——位于侧边栏面板内），
```
rounded-sm
```
（6px），左侧内边距
```
12px
```
。
- 默认状态：
```
neutral-600
```
  文本。激活状态：
```
brand-50
```
  背景，
```
brand-500
```
  文本，
```
font-weight: 500
```
  。悬停状态：
```
neutral-100
```
  背景。
组标签：说明文本（12px/400），
```
neutral-400
```
颜色，组之间的顶部边距为
```
24px
```
。
移动端：侧边栏折叠为
```
Sheet
```
（从左侧滑入）。

Tabs

标签页

Use shadcn
```
<Tabs>
```
. Underline variant.
Active tab:
```
brand-500
```
bottom border (2px),
```
neutral-900
```
text.
Inactive tab: no border,
```
neutral-500
```
text. Hover:
```
neutral-900
```
text.

使用shadcn
```
<Tabs>
```
。下划线变体。
激活标签：
```
brand-500
```
底部边框（2px），
```
neutral-900
```
文本。
未激活标签：无边框，
```
neutral-500
```
文本。悬停状态：
```
neutral-900
```
文本。

Dialog / Sheet

对话框 / 弹窗

Overlay:
```
black/50
```
opacity.
Container: white bg,
```
rounded-xl
```
(14px),
```
shadow-overlay
```
.
Always include a close button (X icon) top-right.

覆盖层：
```
black/50
```
透明度。
容器：白色背景，
```
rounded-xl
```
（14px），
```
shadow-overlay
```
。
右上角必须包含关闭按钮（X图标）。

Composite Patterns

复合模式

For rules and code examples, read the appropriate reference file:

references/web-layouts.md
— Responsive rules, App Shell, Sidebar Navigation, Dashboard Grid, Data Table Page, Page Header
references/components.md
— Stat Card, List Item Row, Filter Bar, Kanban Board, Profile/Discovery Card, Product Card, Activity Feed Item, Toast Notifications, Form Validation States
references/mobile.md
— Mobile rules, Device Frame Shell, Mobile Top Bar, Bottom Tab Navigation, Mobile Form Layout, Pinned Bottom Button, Mobile List View, Mobile Card Stack, Full Screen Composition, Contextual Actions

规则和代码示例请阅读对应参考文件：

references/web-layouts.md
— 响应式规则、应用外壳、侧边栏导航、仪表盘网格、数据表页面、页面头部
references/components.md
— 统计卡片、列表项行、筛选栏、看板、个人资料/发现卡片、产品卡片、活动流项、提示通知、表单验证状态
references/mobile.md
— 移动端规则、设备框架外壳、移动端顶部栏、底部标签导航、移动端表单布局、底部固定按钮、移动端列表视图、移动端卡片堆叠、全屏布局、上下文操作

Web vs Mobile Context

Web与移动端上下文差异

Every project is either a web application or a mobile application — the layout approach is fundamentally different. You MUST have already read the appropriate platform reference file (as instructed at the top of this document) before reaching this point. If you haven't, stop and read it now:

Web application →
```
references/web-layouts.md
```
(responsive breakpoints, sidebar behavior, layout patterns)
Mobile application (native app, iOS, Android, phone-based experience) →
```
references/mobile.md
```
(device frame, touch targets, pinned buttons, navigation, mobile-specific rules)

Do NOT treat a mobile app as a responsive web page. Mobile apps render inside a device frame and follow entirely different navigation, spacing, and interaction patterns.

每个项目要么是Web应用要么是移动应用——布局方式完全不同。在阅读到本节之前，你必须已经阅读了对应平台的参考文件（如本文档顶部所述）。若未阅读，请立即停止并阅读：

Web应用 →
```
references/web-layouts.md
```
（响应式断点、侧边栏行为、布局模式）
移动应用（原生应用、iOS、Android、基于手机的体验）→
```
references/mobile.md
```
（设备框架、触摸目标、固定按钮、导航、移动端专属规则）

请勿将移动应用视为响应式网页。移动应用在设备框架内渲染，遵循完全不同的导航、间距和交互模式。

Image Placeholders

图片占位符

When no real image is available, use soft gradient mesh backgrounds — NOT gray boxes. These should feel like abstract art, not loading states.

Gradient recipes (CSS

linear-gradient

radial-gradient

combos):

Mint/Teal:

linear-gradient(135deg, #a8edea 0%, #fed6e3 50%, #a8edea 100%)

Peach/Coral:

linear-gradient(135deg, #f6d5c5 0%, #e8b4b8 50%, #d4a0a0 100%)

Purple/Pink:

linear-gradient(135deg, #c3b1e1 0%, #f0c4d0 50%, #e0aed0 100%)

Teal/Emerald:

linear-gradient(135deg, #43e97b 0%, #38f9d7 100%)

Apply

rounded-lg

to image containers. These are placeholders — they should look intentional and beautiful.

当没有真实图片可用时，使用柔和渐变网格背景——而非灰色盒子。它们应看起来像抽象艺术，而非加载状态。

渐变配方（CSS

linear-gradient

或

radial-gradient

组合）：

薄荷/蓝绿色：

linear-gradient(135deg, #a8edea 0%, #fed6e3 50%, #a8edea 100%)

桃色/珊瑚色：

linear-gradient(135deg, #f6d5c5 0%, #e8b4b8 50%, #d4a0a0 100%)

紫色/粉色：

linear-gradient(135deg, #c3b1e1 0%, #f0c4d0 50%, #e0aed0 100%)

蓝绿色/翠绿色：

linear-gradient(135deg, #43e97b 0%, #38f9d7 100%)

为图片容器应用

rounded-lg

。这些是占位符——应看起来有意且美观。

Transitions & Animations

过渡与动画

Every state change should feel smooth and intentional — no hard cuts. This applies across both web and mobile:

Interactive elements (buttons, inputs, cards): Use
```
transition-colors
```
or
```
transition-all
```
with Tailwind's default duration (~150ms). State changes like hover, focus, and active should never feel instantaneous.
Page transitions: When navigating between views, apply a subtle slide or fade. A
```
150–300ms
```
ease-out transition keeps things feeling responsive without sluggish.
Modals, Dialogs, Sheets: Always animate in and out. Sheets slide from their edge (left, right, bottom), dialogs/modals fade + scale up slightly from ~95% to 100%. The overlay backdrop should fade in (
```
opacity 0→50%
```
), not appear instantly.
Lists and content loading: When new items appear (e.g., after a fetch), a subtle fade-in or stagger is preferred over a hard pop-in.

Nothing on screen should ever just "appear" or "disappear" — every visual change gets a brief, smooth transition.

每个状态变化都应流畅且自然——不得生硬切换。这适用于Web和移动端：

交互元素（按钮、输入框、卡片）：使用
```
transition-colors
```
或
```
transition-all
```
，搭配Tailwind默认时长（约150ms）。悬停、聚焦和激活等状态变化绝不能瞬间完成。
页面过渡：在视图间导航时，应用微妙的滑动或淡入淡出效果。
```
150–300ms
```
的缓出过渡既能保持响应性又不会显得迟缓。
模态框、对话框、弹窗：必须有进入和退出动画。弹窗从对应边缘（左、右、下）滑入，对话框/模态框淡入并从约95%略微缩放至100%。覆盖层背景应淡入（
```
opacity 0→50%
```
），而非瞬间出现。
列表和内容加载：当新元素出现时（例如，获取数据后），微妙的淡入或 stagger 效果优于生硬弹出。

屏幕上的任何元素都绝不能“突然出现”或“突然消失”——所有视觉变化都应有短暂、流畅的过渡。

Empty, Error & Loading States

空状态、错误状态与加载状态

Every screen has at least three faces: populated, empty, and broken. AI-generated interfaces almost always show only the happy path with fake data. A polished interface acknowledges the other two.

每个屏幕至少有三种状态：已填充、空、异常。AI生成的界面通常只展示带虚假数据的理想状态。优质界面应考虑另外两种状态。

Empty State

空状态

When a list, table, or content area has no data yet (first-time use, zero results, cleared filters):

Center a Lucide icon (
```
48px
```
,
```
neutral-300
```
) + a short heading (
```
Heading 3
```
) + one line of body text (
```
neutral-500
```
) vertically in the content area
Optionally include a primary action button below the text (e.g., "Create your first project")
Do NOT show an empty table with headers and no rows — that looks like a bug, not a feature
Do NOT use illustrations or complex graphics. Keep it text + icon. Minimal.

当列表、表格或内容区域尚无数据时（首次使用、无结果、筛选后为空）：

在内容区域内垂直居中显示一个Lucide图标（
```
48px
```
，
```
neutral-300
```
） + 简短标题（三级标题） + 一行正文文本（
```
neutral-500
```
）
可选择性地在文本下方添加一个主操作按钮（例如，“创建你的第一个项目”）
不得显示只有表头没有行的空表格——这看起来像bug，而非功能
不得使用插图或复杂图形。保持文本+图标即可。极简风格。

Error State

错误状态

When something goes wrong (network failure, permission denied, server error):

Same centered layout as empty state, but use
```
error-500
```
for the icon color
Icon: contextual —
```
WifiOff
```
for network errors,
```
ShieldX
```
for permission,
```
AlertTriangle
```
as a generic fallback
Heading: brief, human-readable ("Something went wrong", "Couldn't load projects")
Body: one sentence explaining what to do ("Check your connection and try again")
Include a "Retry" button (
```
secondary
```
variant) when the action is retryable

当出现问题时（网络故障、权限不足、服务器错误）：

布局与空状态相同，但图标颜色使用
```
error-500
```
图标：上下文相关——网络错误使用
```
WifiOff
```
，权限问题使用
```
ShieldX
```
，通用 fallback 使用
```
AlertTriangle
```
标题：简短、通俗易懂（“出了点问题”、“无法加载项目”）
正文：一行说明解决方法的文本（“检查网络连接后重试”）
当操作可重试时，包含一个“重试”按钮（次按钮变体）

Loading State

加载状态

When content is being fetched:

For initial page loads: Show a single centered spinner (
```
Loader2
```
icon with
```
animate-spin
```
,
```
24px
```
,
```
neutral-400
```
). No skeleton screens unless explicitly requested — they add complexity without clarifying the design
For inline updates (e.g., submitting a form, loading more items): Swap the trigger button's label to a spinner + "Loading…" and disable the button
For pull-to-refresh or lazy loading: A small spinner at the top or bottom of the list,
```
neutral-400
```

The anti-pattern rule "No animated skeletons or shimmer effects in static mockups" still stands — but a simple

animate-spin

on a loader icon is fine for interactive interfaces.

当内容正在获取时：

初始页面加载：显示单个居中的加载动画（
```
Loader2
```
图标 +
```
animate-spin
```
，
```
24px
```
，
```
neutral-400
```
）。除非明确要求，否则不使用骨架屏——它们会增加复杂度却无法明确设计
行内更新（例如，提交表单、加载更多项）：将触发按钮的标签替换为加载动画 + “加载中…”，并禁用按钮
下拉刷新或懒加载：在列表顶部或底部显示一个小加载动画，
```
neutral-400
```
颜色

静态原型中仍需遵循“禁止使用动画骨架屏或闪烁效果”的反模式规则——但在交互式界面中，为加载图标添加简单的

animate-spin

是可以的。

Form Validation & Error Feedback

表单验证与错误反馈

Inputs need to clearly communicate when something is wrong. This applies to both web and mobile. For code examples, see the Form Validation States section in

references/components.md

输入框需要清晰地传达错误状态。这适用于Web和移动端。代码示例请阅读

references/components.md

中的表单验证状态章节。

Behavioral Rules

行为规则

Validate on blur (when the user leaves the field), not on every keystroke — keystroke validation feels aggressive
Show errors inline, directly below the relevant field. Never collect errors at the top of the form — users shouldn't have to hunt
When the user corrects the input and the field is valid, remove the error state immediately (on change, not on blur)
If the form is submitted with errors, scroll to the first invalid field and focus it

在失焦时验证（当用户离开字段时），而非每次按键时验证——按键验证会显得咄咄逼人
错误信息内联显示，直接在对应字段下方。绝不能将错误收集在表单顶部——用户不应需要寻找错误
当用户修正输入且字段有效时，立即移除错误状态（在输入变化时，而非失焦时）
若表单提交时有错误，滚动到第一个无效字段并聚焦它

Success Confirmation (Post-Submit)

提交成功确认

After a successful form submission, provide clear feedback. Don't just silently navigate away:

Option A: Toast notification confirming the action + navigate to the next logical screen
Option B: Inline success message replacing the form content (useful for single-purpose screens like "Reset password")

表单提交成功后，提供清晰的反馈。不要只是静默跳转：

选项A：提示通知确认操作 + 导航到下一个逻辑页面
选项B：行内成功消息替换表单内容（适用于“重置密码”等单用途页面）

Toast Notifications

提示通知

Transient feedback messages that confirm actions, surface errors, or provide information. Use shadcn's

Sonner

toast component. For code examples and the full variant table, see the Toast Notification section in

references/components.md

用于确认操作、显示错误或提供信息的临时反馈消息。使用shadcn的

Sonner

提示组件。代码示例和完整变体表请阅读

references/components.md

中的提示通知章节。

Positioning & Behavior

定位与行为

Web: Bottom-right corner,
```
16px
```
from the edge
Mobile: Top-center, below the status bar / top bar area
Duration:
```
4000ms
```
default,
```
6000ms
```
for messages with an action link. Error toasts should persist until dismissed
Stacking: Max 3 visible at once. New toasts push older ones up (web) or down (mobile)
Animation: Slide in from the edge + fade. Slide out + fade on dismiss. Should feel like the Transitions & Animations section — smooth, never instant

Web：右下角，距离边缘
```
16px
```
移动端：顶部居中，状态栏/顶部栏下方
时长：默认
```
4000ms
```
，带操作链接的消息使用
```
6000ms
```
。错误提示应保持显示直到被关闭
堆叠：最多同时显示3个。新提示会将旧提示向上（Web）或向下（移动端）推送
动画：从边缘滑入 + 淡入。关闭时滑出 + 淡出。应符合过渡与动画章节的要求——流畅，绝不瞬间完成

Data Visualization Palette

数据可视化调色板

When rendering charts (Recharts, Chart.js, etc.), use this ordered color sequence so data visualizations feel native to the brand. The palette starts with the brand purple and fans out through distinguishable hues:


#5900FF
#14B8A6
#F59E0B
#F43F5E
#0EA5E9
#84CC16

Order	Name	Hex	Use
1	Brand	`#5900FF`	Primary data series, single-metric charts
2	Teal	`#14B8A6`	Secondary series
3	Amber	`#F59E0B`	Tertiary series
4	Rose	`#F43F5E`	Fourth series, or "negative" in comparisons
5	Sky	`#0EA5E9`	Fifth series
6	Lime	`#84CC16`	Sixth series

渲染图表（Recharts、Chart.js等）时，使用此有序颜色序列，使数据可视化与品牌风格一致。调色板从品牌紫色开始，扩展到可区分的色调：


#5900FF
#14B8A6
#F59E0B
#F43F5E
#0EA5E9
#84CC16

顺序	名称	十六进制值	使用场景
1	品牌色	`#5900FF`	主要数据系列、单指标图表
2	蓝绿色	`#14B8A6`	次要数据系列
3	琥珀色	`#F59E0B`	第三数据系列
4	玫瑰色	`#F43F5E`	第四数据系列，或比较中的“负值”
5	天蓝色	`#0EA5E9`	第五数据系列
6	酸橙色	`#84CC16`	第六数据系列

Rules

规则

For single-metric charts (one bar, one line, one donut), always use
```
Brand
```
(
```
#5900FF
```
)
For two-series comparisons, use
```
Brand
```
+
```
Teal
```
Apply colors in order — don't skip or shuffle. Consistency across charts makes dashboards feel cohesive
Use
```
10%
```
opacity fills for area charts (e.g.,
```
#5900FF1A
```
for brand area fill)
Gridlines:
```
neutral-200
```
. Axis labels:
```
neutral-500
```
, caption size (12px). Axis lines:
```
neutral-300
```
Tooltips: White bg,
```
shadow-md
```
,
```
rounded-md
```
,
```
neutral-200
```
border — same treatment as popovers
Never use brand purple for "negative" or "declining" values — use Rose for that. Purple is always neutral-to-positive

单指标图表（单个条形、单条线、单个环形图）始终使用
```
品牌色
```
（
```
#5900FF
```
）
双系列比较使用
```
品牌色
```
+
```
蓝绿色
```
按顺序使用颜色——不得跳过或打乱。图表间的一致性使仪表盘更具凝聚力
面积图使用
```
10%
```
透明度填充（例如，品牌色面积填充使用
```
#5900FF1A
```
）
网格线：
```
neutral-200
```
。轴标签：
```
neutral-500
```
，说明文本大小（12px）。轴线：
```
neutral-300
```
提示框：白色背景，
```
shadow-md
```
，
```
rounded-md
```
，
```
neutral-200
```
边框——与弹出层处理方式相同
绝不能将品牌紫色用于“负值”或“下降”数据——使用玫瑰色。紫色始终代表中性到正值

Dark Mode

深色模式

Dark mode is off by default. Only implement it when explicitly requested by the user or client. When dark mode is requested, follow these rules — do NOT improvise an inverted palette.

深色模式默认关闭。仅当用户或客户明确要求时才实现。当需要深色模式时，请遵循以下规则——不得自行设计反转调色板。

How It Works

工作原理

The theme file (

references/theme.css

) includes a

.dark

class block that overrides CSS custom properties. Adding

class="dark"

<html>

or a wrapper element flips the entire color system without changing any component code. The neutral scale inverts so existing utilities (

text-neutral-900

bg-neutral-50

border-neutral-200

) automatically produce the correct dark-mode values.

主题文件（

references/theme.css

）包含

.dark

类块，用于覆盖CSS自定义属性。在

<html>

或包裹元素上添加

class="dark"

即可切换整个颜色系统，无需修改任何组件代码。中性色阶反转，因此现有工具类（

text-neutral-900

、

bg-neutral-50

、

border-neutral-200

）会自动生成正确的深色模式值。

Token Behavior in Dark Mode

令牌在深色模式下的行为

You don't change token names in your code — the

.dark

override changes the values behind them. Here's what each token resolves to:

Token (unchanged in code)	Light Mode Value	Dark Mode Value	Notes
`bg-neutral-50`	`#FAFAFA` (light gray)	`#171717` (near-black)	Page background
`bg-neutral-0`	`#FFFFFF` (white)	`#0A0A0A` (near-black)	Card surfaces
`border-neutral-200`	`#E5E5E5` (light gray)	`#404040` (dark gray)	Borders / dividers
`text-neutral-950`	`#0A0A0A` (near-black)	`#FFFFFF` (white)	Page titles
`text-neutral-900`	`#171717` (near-black)	`#FAFAFA` (near-white)	Body text
`text-neutral-500`	`#737373` (mid-gray)	`#737373` (mid-gray)	Stays the same — mid-range
`text-neutral-400`	`#A3A3A3` (light gray)	`#A3A3A3` (stays same)	Subtext — readable on dark
`bg-brand-500`	`#5900FF`	`#7A33FF` (lighter)	Brighter for contrast on dark bg
`bg-brand-50`	`#EEE5FF` (light purple)	`#120033` (very dark purple)	Tinted backgrounds invert

你无需修改代码中的令牌名称——

.dark

覆盖会更改其背后的值。以下是每个令牌的对应值：

令牌（代码中不变）	浅色模式值	深色模式值	说明
`bg-neutral-50`	`#FAFAFA` （浅灰色）	`#171717` （近黑色）	页面背景
`bg-neutral-0`	`#FFFFFF` （白色）	`#0A0A0A` （近黑色）	卡片表面
`border-neutral-200`	`#E5E5E5` （浅灰色）	`#404040` （深灰色）	边框 / 分隔线
`text-neutral-950`	`#0A0A0A` （近黑色）	`#FFFFFF` （白色）	页面标题
`text-neutral-900`	`#171717` （近黑色）	`#FAFAFA` （近白色）	正文文本
`text-neutral-500`	`#737373` （中灰色）	`#737373` （中灰色）	保持不变——中间色调
`text-neutral-400`	`#A3A3A3` （浅灰色）	`#A3A3A3` （保持不变）	辅助文本——在深色背景上可读
`bg-brand-500`	`#5900FF`	`#7A33FF` （更浅）	在深色背景上更亮以提高对比度
`bg-brand-50`	`#EEE5FF` （浅紫色）	`#120033` （深紫色）	tinted背景反转

bg-white

bg-neutral-0

— Critical Distinction

bg-white

bg-neutral-0

— 关键区别

Tailwind's built-in

white

and

black

are NOT overridden in dark mode. They always resolve to literal

#FFFFFF

and

#000000

Use text-white
when you mean actual white — e.g., button text on a
```
brand-500
```
background. This stays white in both modes. ✅
Use bg-neutral-0
(not
```
bg-white
```
) for surfaces that should invert in dark mode — e.g., card backgrounds, sidebars, top bars.
```
bg-neutral-0
```
maps to
```
#FFFFFF
```
in light and
```
#0A0A0A
```
in dark. ✅
Use bg-neutral-50
for page backgrounds. Maps to
```
#FAFAFA
```
in light,
```
#171717
```
in dark. ✅

If you use

bg-white

on a card, it will stay bright white in dark mode — blinding. Use

bg-neutral-0

instead.

Tailwind内置的

white

和

black

在深色模式下不会被覆盖。它们始终对应纯

#FFFFFF

和

#000000

。

当需要纯白色时使用**
```
text-white
```
**——例如，
```
brand-500
```
背景上的按钮文本。在两种模式下都保持白色。✅
对于需要在深色模式下反转的表面，使用**
```
bg-neutral-0
```
**（而非
```
bg-white
```
）——例如，卡片背景、侧边栏、顶部栏。
```
bg-neutral-0
```
在浅色模式下对应
```
#FFFFFF
```
，在深色模式下对应
```
#0A0A0A
```
。✅
页面背景使用**
```
bg-neutral-50
```
**。浅色模式下对应
```
#FAFAFA
```
，深色模式下对应
```
#171717
```
。✅

若在卡片上使用

bg-white

，它在深色模式下会保持亮白色——非常刺眼。请改用

bg-neutral-0

。

Shadows in Dark Mode

深色模式下的阴影

Shadows are nearly invisible on dark surfaces. The

.dark

block increases shadow opacity so elevation is still perceptible, but cards should primarily rely on their

neutral-200

border (which maps to a subtle dark gray divider in dark mode) for definition.

阴影在深色表面上几乎不可见。

.dark

块会增加阴影透明度，使层次仍然可感知，但卡片应主要依靠

neutral-200

边框（在深色模式下对应微妙的深灰色分隔线）来定义边界。

Logo

Use

assets/logo-mono-white.svg

— the only variant approved for dark surfaces.

使用

assets/logo-mono-white.svg

——这是唯一批准用于深色表面的变体。

What NOT to Do in Dark Mode

深色模式下的禁止操作

Do NOT manually set dark colors in component code — rely on the
```
.dark
```
class override
Do NOT use
```
bg-white
```
for surfaces — use
```
bg-neutral-0
```
so they invert properly
Do NOT use
```
brand-500
```
for large tinted surfaces — use
```
brand-50
```
(which maps to a dark purple in dark mode)
Do NOT change spacing, radius, or typography — the spatial system is mode-independent

不得在组件代码中手动设置深色颜色——依赖
```
.dark
```
类覆盖
不得对表面使用
```
bg-white
```
——使用
```
bg-neutral-0
```
使其正确反转
不得对大面积tinted表面使用
```
brand-500
```
——使用
```
brand-50
```
（在深色模式下对应深紫色）
不得更改间距、圆角或排版——空间系统与模式无关

Anti-Patterns (Do NOT)

反模式（禁止操作）

No gradients on buttons. Flat solid colors only.
No colored page backgrounds. Background is always
```
neutral-50
```
or
```
neutral-0
```
.
No heavy borders. Max
```
1px
```
for structural borders. Never 2px+.
No rounded-full on cards. Cards are
```
rounded-lg
```
(10px), never circles.
No custom fonts. DM Sans / sans-serif only. Monospace for code.
Prefer icon + label navigation on desktop. Icon-only sidebars are acceptable if a tooltip with the label appears on hover or focus.
No dark mode unless explicitly requested. Default is always light.
No animated skeletons or shimmer effects in static mockups.
No drop shadows on text. Ever.
No border-radius mixing. Don't use the same radius token at different hierarchy levels — e.g.,
```
rounded-lg
```
cards should contain
```
rounded-sm
```
children, not
```
rounded-lg
```
children. The inner radius should always be smaller than the outer.
No floating labels or placeholder-as-label. Labels must always be visible above inputs. Placeholders are hints, not labels — they vanish on focus and users lose context.
No emojis in the UI. Icons only. The only exception is user-generated content — if a user typed an emoji, display it. But never add emojis to labels, headings, buttons, nav items, placeholders, or any system-generated text.

按钮上不得使用渐变。仅使用纯平纯色。
不得使用彩色页面背景。背景始终为
```
neutral-50
```
或
```
neutral-0
```
。
不得使用厚重边框 structural边框最大为
```
1px
```
。绝不能使用2px及以上边框。
卡片不得使用rounded-full。卡片使用
```
rounded-lg
```
（10px），绝不能是圆形。
不得使用自定义字体。仅使用DM Sans / sans-serif。代码使用等宽字体。
桌面端优先使用图标+标签导航。若悬停或聚焦时显示带标签的提示框，则纯图标侧边栏是可以接受的。
除非明确要求，否则不得使用深色模式。默认始终为浅色模式。
静态原型中不得使用动画骨架屏或闪烁效果。
文本上不得使用投影。绝对禁止。
不得混合使用圆角。不同层级不得使用相同的圆角令牌——例如，
```
rounded-lg
```
卡片内应包含
```
rounded-sm
```
子元素，而非
```
rounded-lg
```
子元素。内部圆角必须小于外部圆角。
不得使用浮动标签或占位符作为标签。标签必须始终显示在输入框上方。占位符是提示，而非标签——它们在聚焦时会消失，用户会失去上下文。
UI中不得使用表情符号。仅使用图标。唯一例外是用户生成的内容——若用户输入了表情符号，则显示它。但绝不能在标签、标题、按钮、导航项、占位符或任何系统生成的文本中添加表情符号。

Checklist Before Output

输出前检查清单

Before delivering any UI code, verify:

Uses
```
DM Sans
```
font family (with
```
sans-serif
```
fallback)
Brand purple only on interactive/active elements

Cards have

bg-neutral-0

neutral-200

border +

rounded-lg

shadow-sm

No unauthorized colors, fonts, or shadows
All icons from Lucide React
shadcn components used where available (not custom recreations)
Spacing feels generous — nothing cramped
Page background is
```
neutral-50
```
, not white
Empty states are handled (not just the happy path with fake data)
Form inputs show error styling on validation failure (red border + message below)
Actions provide feedback via toast or inline confirmation
Charts (if present) use the data visualization palette in order
All form inputs have visible external labels (not inside the input)
Placeholder text is de-emphasized (
```
neutral-400
```
, normal weight)
Casper Studios logo uses the correct variant for the background (default on light, mono-white on dark)
If dark mode was requested:
```
.dark
```
class applied, logo uses mono-white variant, surfaces use
```
bg-neutral-0
```
(not
```
bg-white
```
)
Border-radius: buttons/inputs use
```
rounded-md
```
(8px), cards use
```
rounded-lg
```
(10px), nav items/inner elements use
```
rounded-sm
```
(6px)
Button/input heights:
```
48px
```
(
```
h-12
```
) by default,
```
36px
```
(
```
h-9
```
) when inside cards, panels, tables, or other compact containers

在交付任何UI代码之前，请验证：

使用
```
DM Sans
```
字体族（带
```
sans-serif
```
后备字体）
品牌紫色仅用于交互/激活元素

卡片使用

bg-neutral-0

neutral-200

边框 +

rounded-lg

shadow-sm

未使用未经授权的颜色、字体或阴影
所有图标来自Lucide React
尽可能使用shadcn组件（而非自定义重写）
间距充裕——无拥挤内容
页面背景为
```
neutral-50
```
，而非白色
处理了空状态（而非仅展示带虚假数据的理想状态）
表单输入框在验证失败时显示错误样式（红色边框 + 下方消息）
操作通过提示通知或行内确认提供反馈
图表（若有）按顺序使用数据可视化调色板
所有表单输入框有可见的外部标签（不在输入框内）
占位符文本已弱化（
```
neutral-400
```
，常规字重）
Casper Studios Logo根据背景使用了正确的变体（浅色背景用默认版，深色背景用单色白色版）
若要求深色模式：已应用
```
.dark
```
类，Logo使用单色白色变体，表面使用
```
bg-neutral-0
```
（而非
```
bg-white
```
）
圆角：按钮/输入框使用
```
rounded-md
```
（8px），卡片使用
```
rounded-lg
```
（10px），导航项/内部元素使用
```
rounded-sm
```
（6px）
按钮/输入框高度：默认
```
48px
```
（
```
h-12
```
），位于卡片、面板、表格或其他紧凑容器内时使用
```
36px
```
（
```
h-9
```
）

Additional checks for Web Applications:

Web应用额外检查项：

Sidebar follows the 240px / grouped nav / active state pattern
Responsive: works at 1280px, 768px, and 375px

侧边栏遵循240px宽度 / 分组导航 / 激活状态模式
响应式：在1280px、768px和375px分辨率下均可正常工作

Additional checks for Mobile Applications:

移动应用额外检查项：

Rendered inside iPhone 16 device frame (393×852, 40px outer radius, 8px bezel)
Primary action button is pinned to bottom with safe area padding
Navigation uses bottom tab bar, not sidebar
Buttons and inputs are
```
48px
```
height (same as global default — no mobile override needed)
Most tap targets are 44×44px or larger (smaller is OK in dense UI, but not the default)
Single-column layout only — no multi-column grids
Typography uses mobile scale (H1: 24px, H2: 18px)

在iPhone 16设备框架内渲染（393×852，40px外圆角，8px边框）
主操作按钮固定在底部并包含安全区域内边距
使用底部标签导航，而非侧边栏
按钮和输入框高度为
```
48px
```
（与全局默认值相同——无需移动端覆盖）
大多数触摸目标为44×44px或更大（紧凑UI中可更小，但非默认）
仅使用单列布局——无多列网格
排版使用移动端字号体系（一级标题：24px，二级标题：18px）