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.
- 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.
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
- 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.
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, small category tags |
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
Spacing & Layout
Spacing Scale
Use Tailwind's default spacing scale. Key values:
4px (p-1) — icon padding, tight gaps8px (p-2) — badge padding, small gaps12px (p-3) — input padding, card internal gaps16px (p-4) — card padding, section gaps24px (p-6) — between cards, content sections32px (p-8) — major section separation48px (p-12) — page-level padding on large screens
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
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.
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.
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)
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). |
Rules
- Light mode (default): Use
logo-on-white-default.svg or 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
shadcn/ui Component Theming
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:
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.
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.
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.
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.
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. [email protected]"). 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.
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).
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.
Dialog / Sheet
- Overlay:
black/50 opacity.
- Container: white bg,
rounded-xl (14px), shadow-overlay.
- Always include a close button (X icon) top-right.
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 Headerreferences/components.md — Stat Card, List Item Row, Filter Bar, Kanban Board, Profile/Discovery Card, Product Card, Activity Feed Item, Toast Notifications, Form Validation Statesreferences/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
Web vs Mobile Context
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.
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 or radial-gradient combos):
- Mint/Teal:
linear-gradient(135deg, #a8edea 0%, #fed6e3 50%, #a8edea 10
