casper-design-system

Casper Studios 设计系统

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

生成任何 UI 代码前，请完整阅读本文档 以及下方列出的参考文件。你 必须 阅读这些参考文件——其中包含正确生成 UI 所需的规则和代码示例。跳过这些文件会导致生成的 UI 不正确，也不符合品牌风格。

每个项目都必须阅读：

• references/components.md — 务必阅读。可复用组件：统计卡片、列表项、筛选栏、看板、个人资料卡片、产品卡片、动态消息流、Toast 通知、表单验证状态。凡是在布局中构建 UI 元素时都必须阅读。
• references/theme.css — 务必阅读。Tailwind CSS v4 主题令牌。将此文件原样复制到你的项目中。
• assets/ — 包含 Casper Studios 的 Logo SVG，共 4 个版本（default、variant、mono-black、mono-white）。根据背景颜色使用正确的版本——请参阅下方的 Logo 部分。

根据平台必须阅读：

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

不可妥协： 未先阅读对应平台的参考文件，不要生成 UI。如果不确定项目属于 Web 还是移动端，请先询问用户，再继续。

---

开始生成前：必需的上下文

生成任何 UI 代码前，请向用户确认以下内容。如果用户的提示已经明确说明这些内容，则无需询问，可直接继续。否则，请先询问，再生成任何内容。

1. 平台 — 这是 Web 应用还是移动应用？（决定应遵循哪个参考文件。）
2. 暗色模式 — 界面是否需要支持暗色模式，还是仅使用浅色模式？（决定是否实现 .dark 类覆盖、使用 bg-neutral-0 作为表面，并包含 mono-white Logo 版本。）

不要对这些内容作默认假设。如果用户说“给我做一个仪表盘”，你并不知道这是 Web 端还是移动端，也不知道是否需要暗色模式。请先询问。

---

概述

Casper 的美学风格是简洁而权威——一种专业的 SaaS 风格，显得高端而不刻意。通过充足的留白、克制的紫色强调色和圆润柔和的表面，打造值得信赖且现代的界面。想象一下 Linear 与 Notion 的结合：结构清晰、疏朗透气、从容自信。

---

核心原则

1. 留白是一种设计特性。 使用充足的内边距，让各个区块之间留有呼吸空间。绝不拥挤。
2. 只用一种强调色，并且谨慎使用。 品牌紫色（#5900FF）用于活动状态、主要按钮和关键 CTA——除此之外不用于其他地方。如果所有内容都是紫色，那就没有任何内容显得突出。
3. 圆润但不显得稚气。 卡片默认使用 10px 圆角（shadcn 默认值）。按钮和输入框使用 8px。营造现代感，但不显得像玩具。
4. 保持扁平，只略加层次。 不使用厚重的阴影。卡片使用 shadow-sm，弹出层使用 shadow-md。页面内元素绝不使用 shadow-lg。
5. 内容优先于界面装饰。 UI 应当隐于无形。让用户关注数据，而非设计。

---

技术栈

• React（Vite）与 TypeScript
• Tailwind CSS v4 — 使用 references/theme.css 中的主题文件作为 Casper 品牌覆盖样式
• shadcn/ui — 首先初始化标准的 shadcn/ui 项目（shadcn init），然后叠加 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 作为回退字体。通过 Google Fonts 加载或打包

---

色彩系统

该调色板有意保持克制。大多数 UI 使用中性灰色与白色，并以紫色作为醒目的强调色。

使用规则

角色	令牌	十六进制	使用场景
品牌强调色	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——参见“深色模式”部分）

语义颜色

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

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

禁止事项

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

---

字体排印

所有文本均使用 DM Sans，并以 sans-serif 作为回退字体（font-family: 'DM Sans', sans-serif）。等宽字体（font-mono）仅可用于代码块、数据标签和 ID。

比例

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

规则

• 标题始终使用 medium 字重（500），绝不使用粗体（700）
• 除了以说明文字字号显示的微型元数据标签（例如表格列标题中的 "STATUS"、"OWNER"）外，绝不使用全大写
• 链接默认使用 brand-500 颜色且不带下划线，悬停时显示下划线
• 不要使用此比例以外的字号。如果某处看起来不合适，应调整间距，而不是字号

---

间距与布局

间距比例

使用 Tailwind 的默认间距比例。常用值：

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

布局规则

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

---

阴影与层级

设计整体以扁平为主。阴影用于表示层级，而非装饰。

Token	用途
shadow-sm	卡片、未交互时的输入框
shadow-md	下拉菜单、弹出框、工具提示
shadow-lg	仅用于模态框、命令面板、遮罩层
shadow-overlay	shadow-lg 的语义别名 — 值完全相同。用于模态框/抽屉，让代码中的意图更清晰

绝不要将 shadow-lg（或其别名 shadow-overlay）用于卡片或页面内元素。这些样式仅用于浮动层。

---

圆角

主题文件（references/theme.css）使用 shadcn/ui 圆角系统——在 :root 中定义一个 --radius 基础变量，通过 calc() 控制整个圆角范围。该变量通过 @theme inline 映射到 Tailwind 类。不会覆盖 Tailwind v4 的默认值。

Token	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 的圆角更锐利或更圆润，只需修改此值——所有 Token 都会自动重新计算。

卡片始终使用 rounded-lg（10px）。按钮和输入框始终使用 rounded-md（8px）。卡片内的嵌套元素若非交互元素，应使用 rounded-sm（6px）以保持视觉层级——内层圆角应始终小于外层圆角。

---

图标

• 仅使用 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 徽标

Casper Studios 徽标有四种变体，存放在 assets/ 中。请根据徽标所在的背景使用正确的变体：

变体	文件	使用场景
默认（全彩）	assets/logo-on-white-default.svg	浅色／白色背景。渐变图标 + 紫色“CASPER” + 深色“STUDIOS”。这是主徽标——请尽可能使用。
变体（全彩）	assets/logo-on-white-variant.svg	浅色／白色背景，需要全黑文字而非紫色 + 深灰色文字时使用。图标使用相同的渐变效果。
单色黑	assets/logo-mono-black.svg	无法使用彩色的浅色背景（例如印刷、灰度场景）。灰度图标 + 近黑色文字。
单色白	assets/logo-mono-white.svg	仅用于深色背景。 灰色图标 + 白色文字。徽标位于深色表面时（深色导航栏、深色主视觉区域、叠加层、深色模式），请使用此变体。

规则

• 浅色模式（默认）：使用 logo-on-white-default.svg 或 logo-on-white-variant.svg
• 深色模式或深色表面：使用 logo-mono-white.svg——切勿将默认或黑色 Logo 放在深色背景上
• Logo 应显示在侧边栏标题栏（Web）或顶部栏（移动端），尺寸遵循相应模式中的定义
• 切勿不成比例地调整 Logo 大小——保持原始宽高比
• 切勿将 Logo 放在杂乱的背景或对比度较低的表面上。如果对比度不足，请使用可见度最佳的单色变体
• Logo 周围的最小留白：所有边均为 8px

---

shadcn/ui 组件主题设置

使用 shadcn/ui 组件作为基础层。使用 references/theme.css 中的 CSS 变量设置主题。以下是特定组件的配置方式：

Button

• 主要按钮：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（胶囊形）。高度为 22px。说明文字加粗（12px，字重为 500）。
• 语义徽标：使用柔和色背景和较深色文本。例如，成功徽标使用 success-50 背景和 success-700 文本。
• 中性徽标：neutral-100 背景、neutral-700 文本。
• 品牌徽标：brand-50 背景、brand-700 文本。
• 表示状态时，标签前始终包含一个小圆点或图标。

Card

• 白色背景（bg-neutral-0）。1px neutral-200 边框。rounded-lg（10px）。shadow-sm。
• 内部边距：至少 16px，宽松型卡片使用 24px。
• 卡片标题：Heading 3（16px/500），可选的“查看全部”链接右对齐。
• 使用 1px neutral-200 分隔线将标题与内容分开。

Table

• 使用 shadcn <Table>。表格本身不加外边框——由父级 Card 提供容器。
• 列标题：说明文字加粗（12px/500），颜色为 neutral-500，使用大写形式。
• 行高：48-56px。行之间使用 1px neutral-200 底部边框分隔。
• 行悬停：neutral-50 背景。
• 不使用交替行颜色。

Input / Textarea

• 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）和简短提示文本（例如“例如 [email protected]”）。占位文本是辅助提示，不是标签。
• 选择输入框遵循相同模式：上方显示可见标签，内部使用弱化显示的占位文本。
• 字段之间的间距：16px（space-y-4 或 gap-4）。
• 默认高度：48px（h-12）。用于独立页面、表单、模态框和任何顶层内容区域中的输入框。
• 紧凑高度：36px（h-9）。输入框位于较小容器内时使用——卡片、面板、表格行、筛选栏、行内搜索框。与紧凑按钮的逻辑相同。

侧边栏（应用外壳）

完整的侧边栏代码模式请参阅 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。

选项卡

• 使用 shadcn <Tabs>。采用下划线样式。
• 激活的选项卡：底部边框为 brand-500（2px），文本为 neutral-900。
• 未激活的选项卡：无边框，文本为 neutral-500。悬停时：文本为 neutral-900。

对话框 / Sheet

• 覆盖层：不透明度为 black/50。
• 容器：白色背景，rounded-xl（14px），shadow-overlay。
• 始终在右上角包含一个关闭按钮（X 图标）。

---

组合模式

规则和代码示例请参阅相应的参考文件：

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

---

Web 与移动端上下文

每个项目都是Web 应用程序或移动应用程序——两者的布局方式截然不同。到达此处之前，必须已阅读相应平台的参考文件（如本文档顶部所述）。如果还没有，请停止并立即阅读：

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

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

---

图像占位符

没有真实图像时，请使用柔和的渐变网格背景，而不是灰色方块。这些背景应像抽象艺术，而不是加载状态。

渐变配方（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。这些是占位符，应呈现出经过精心设计的美感。

---

转场与动画

每次状态变化都应流畅自然，不要生硬切换。网页和移动端都适用：

• 交互元素（按钮、输入框、卡片）：使用 transition-colors 或 Tailwind 默认时长（约 150ms）的 transition-all。悬停、聚焦和激活等状态变化绝不能显得突兀。
• 页面转场：在视图之间导航时，使用轻微的滑动或淡入淡出效果。采用 150–300ms 的 ease-out 转场，既能保持响应迅速，又不会显得迟钝。
• 模态框、对话框、底部弹层：始终为其添加进场和退场动画。底部弹层从对应边缘（左侧、右侧或底部）滑入；对话框／模态框从约 95% 放大至 100%，同时淡入。遮罩背景应淡入（opacity 0→50%），而不是瞬间出现。
• 列表和内容加载：新项目出现时（例如，获取数据后），优先使用轻微的淡入或交错动画，而不是突然弹出。

屏幕上的任何内容都不应突然“出现”或“消失”——每次视觉变化都应有短暂、流畅的转场。

---

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

每个屏幕至少有三种状态：有内容、为空和出错。AI 生成的界面几乎总是只展示顺利流程，并使用虚假数据。精致的界面也会考虑另外两种状态。

空状态

当列表、表格或内容区域尚无数据时（首次使用、无搜索结果、筛选条件已清除）：

• 在内容区域垂直居中显示一个 Lucide 图标（48px，neutral-300）、一个简短标题（Heading 3）和一行正文（neutral-500）
• 可在文字下方添加一个主要操作按钮（例如“创建你的第一个项目”）
• 不要显示只有表头、没有行的空表格——这看起来像是故障，而不是功能
• 不要使用插画或复杂图形。仅保留文字和图标，保持简洁。

错误状态

发生问题时（网络故障、权限被拒绝、服务器错误）：

• 使用与空状态相同的居中布局，但图标颜色改为 error-500
• 图标：根据情境选择——网络错误使用 WifiOff，权限错误使用 ShieldX，通用情况使用 AlertTriangle
• 标题：简短易懂（“出了点问题”“无法加载项目”）
• 正文：用一句话说明应如何处理（“检查网络连接后重试”）
• 操作可以重试时，添加一个“重试”按钮（secondary 变体）

加载状态

正在获取内容时：

• 初始页面加载时：显示一个居中的加载图标（Loader2 图标，带有 animate-spin，24px，neutral-400）。除非明确要求，否则不要使用骨架屏——它会增加复杂度，却不能让设计更清晰
• 行内更新时（例如，提交表单、加载更多项目）：将触发按钮的标签替换为旋转图标和“正在加载…”，并禁用按钮
• 下拉刷新或延迟加载时：在列表顶部或底部显示一个小型加载图标，颜色为 neutral-400

反模式规则“静态模型中不要使用动画骨架屏或闪烁效果”仍然适用——但在交互式界面中，加载图标使用简单的 animate-spin 没问题。

---

表单验证与错误反馈

输入控件需要清晰提示错误状态。网页和移动端都适用。代码示例请参阅 references/components.md 中的“表单验证状态”部分。

行为规则

• 在字段失焦时验证（用户离开字段时），而不是每次按键都验证——按键时验证会让人觉得咄咄逼人
• 在相关字段正下方显示行内错误。不要将错误集中显示在表单顶部——用户不应该到处寻找错误
• 用户修正输入且字段有效后，立即移除错误状态（在内容变更时，而不是失焦时）
• 如果提交的表单存在错误，应滚动到第一个无效字段并将其聚焦

成功确认（提交后）

表单成功提交后，请提供明确的反馈。不要只是悄无声息地跳转离开：

• 选项 A：显示 Toast 通知确认操作，然后跳转到下一个逻辑页面
• 选项 B：显示内联成功消息，替换表单内容（适用于“重置密码”等单一用途页面）

---

Toast 通知

用于确认操作、显示错误或提供信息的临时反馈消息。请使用 shadcn 的 Sonner toast 组件。代码示例和完整的变体表请参见 references/components.md 中的 Toast Notification 部分。

位置与行为

• Web：右下角，距边缘 16px
• 移动端：顶部居中，位于状态栏／顶部栏区域下方
• 持续时间：默认 4000ms，包含操作链接的消息为 6000ms。错误 toast 应持续显示，直到用户将其关闭
• 堆叠：最多同时显示 3 条。新 toast 会将较旧的向上（Web）或向下（移动端）推移
• 动画：从边缘滑入并渐显。关闭时滑出并渐隐。效果应与“Transitions & Animations”部分一致——流畅，绝不瞬间完成

---

数据可视化配色方案

渲染图表（Recharts、Chart.js 等）时，请按顺序使用以下颜色序列，让数据可视化呈现出与品牌一致的风格。配色从品牌紫色开始，并扩展至一系列易于区分的色相：

顺序	名称	十六进制	用途
1	品牌色	#5900FF	主要数据系列、单指标图表
2	蓝绿色	#14B8A6	次要系列
3	琥珀色	#F59E0B	第三系列
4	玫瑰色	#F43F5E	第四系列，或在对比中表示“负向”
5	天蓝色	#0EA5E9	第五系列
6	青柠色	#84CC16	第六系列

规则

• 对于单指标图表（单个条形、单条折线或单个环形图），始终使用 Brand（#5900FF）
• 对于双系列对比，使用 Brand + Teal
• 按顺序使用颜色——不要跳过或打乱顺序。图表之间保持一致，能让仪表板更协调
• 面积图使用 10% 不透明度填充（例如，品牌色面积填充使用 #5900FF1A）
• 网格线：neutral-200。坐标轴标签：neutral-500，说明文字大小（12px）。坐标轴线：neutral-300
• 工具提示：白色背景、shadow-md、rounded-md、neutral-200 边框——与弹出层采用相同样式
• 绝不要用品牌紫色表示“负向”或“下降”值——这类值请使用玫瑰色。紫色始终表示中性或正向

---

深色模式

深色模式默认关闭。仅当用户或客户端明确提出要求时才实现。需要深色模式时，请遵循以下规则——不要自行发挥，创建反转配色方案。

工作原理

主题文件（references/theme.css）包含一个 .dark 类代码块，用于覆盖 CSS 自定义属性。在 <html> 或某个包装元素上添加 class="dark"，即可切换整个配色系统，无需更改任何组件代码。中性色阶会反转，因此现有实用类（text-neutral-900、bg-neutral-50、border-neutral-200）会自动生成正确的深色模式值。

深色模式下的令牌行为

你无需在代码中更改令牌名称——.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（极深紫色）	色调背景会反转

bg-white 与 bg-neutral-0——关键区别

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。

深色模式下的阴影

阴影在深色表面上几乎不可见。.dark 块会提高阴影的不透明度，使层次效果仍可察觉；不过，卡片的边界主要应依靠 neutral-200 边框来呈现（该边框在深色模式下对应柔和的深灰色分隔线）。

Logo

使用 assets/logo-mono-white.svg——这是唯一获准用于深色表面的变体。

深色模式下的禁忌

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

---

反模式（请勿使用）

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

---

输出前检查清单

交付任何 UI 代码之前，请确认：

• 使用 DM Sans 字体系列（并以 sans-serif 作为回退字体）
• 品牌紫色仅用于交互/激活状态的元素
• 卡片具有 bg-neutral-0 + neutral-200 边框 + rounded-lg + shadow-sm
• 未使用未经授权的颜色、字体或阴影
• 所有图标均来自 Lucide React
• 在可用的情况下使用 shadcn 组件（而非自定义复刻组件）
• 间距宽松舒适——没有任何元素显得拥挤
• 页面背景为 neutral-50，而非白色
• 已处理空状态（而不只是使用虚假数据展示理想情况）
• 表单输入验证失败时显示错误样式（红色边框 + 下方提示）
• 操作通过 toast 或行内确认提供反馈
• 图表（如有）按顺序使用数据可视化调色板
• 所有表单输入框都有可见的外部标签（不在输入框内部）
• 占位符文本使用弱化样式（neutral-400、常规字重）
• Casper Studios 徽标根据背景使用正确的变体（浅色背景用默认变体，深色背景用 mono-white）
• 如果要求深色模式：应用 .dark 类，徽标使用 mono-white 变体，表面使用 bg-neutral-0（而非 bg-white）
• 圆角：按钮/输入框使用 rounded-md（8px），卡片使用 rounded-lg（10px），导航项/内部元素使用 rounded-sm（6px）
• 按钮/输入框高度：默认 48px（h-12），在卡片、面板、表格或其他紧凑容器内为 36px（h-9）

Web 应用的附加检查项：

• 侧边栏遵循 240px / 分组导航 / 激活状态模式
• 响应式布局：适用于 1280px、768px 和 375px 屏幕

移动应用的附加检查项：

• 在 iPhone 16 设备边框内渲染（393×852、外侧圆角 40px、边框 8px）
• 主要操作按钮固定在底部，并带有安全区域内边距
• 导航使用底部标签栏，而非侧边栏
• 按钮和输入框高度为 48px（与全局默认值相同——无需移动端覆盖）
• 大多数点击目标至少为 44×44px（密集型 UI 中可以更小，但不应作为默认值）
• 仅使用单列布局——不要使用多列网格
• 字体排版使用移动端字号（H1：24px，H2：18px）