casper-design-system

What this skill does

# Casper Studios Design System

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.

---

## 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.

1. **Platform** — Is this a web application or a mobile application? (Determines which reference file to follow.)
2. **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.

---

## 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.

---

## Core Principles

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

---

## 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

---

## Color System

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

### 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) |

### 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

### 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`)

---

## 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.

### 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,