indee-demo/.cursor/rules/visual-design-system.mdc

---
description: 
alwaysApply: true
---

# Visual Design System Principles

## Typography Philosophy

### Bold, Statement Typography

Large, confident typography that dominates visual hierarchy. Text is a design element, not just content.

**Scale Guidelines**:
- Hero Text: 6-9rem (96-144px)
- Page Titles: 3-4rem (48-64px)
- Section Headers: 2-3rem (32-48px)
- Body Text: 1-1.125rem (16-18px)
- Small Text: 0.875rem (14px)

```css
.hero-text {
  font-size: clamp(4rem, 10vw, 9rem);
  font-weight: 700;
  line-height: 1.1;
}
```

## Gradient-Based Visual Hierarchy

Use gradients strategically to create visual interest without clutter.

```css
/* Text gradient */
.gradient-heading {
  background: linear-gradient(to right, #ffffff, #9ca3af);
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}
```

## Glass Morphism

Create depth through semi-transparent layers with backdrop blur.

```css
.glass-card {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(12px);
  -webkit-backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}
```

### Usage Guidelines

- ✅ Cards and containers over complex backgrounds
- ✅ Navigation bars with fixed positioning
- ✅ Modal overlays and dialogs
- ❌ Body text containers (readability issues)
- ❌ Form inputs (confusing UX)

## Color System Architecture

**Core Color Constants** - Always use these exact values:

```javascript
const coreColors = {
  // Pure Black - Use for backgrounds in dark mode
  black: '#0a0a0a',
  
  // Pure White Text - Use for text on dark backgrounds
  white: '#FAFAFA',
  
  // Note: In light mode, reverse these:
  // - Background: #FAFAFA
  // - Text: #0a0a0a
};
```

**Semantic Color Tokens** - Define colors by purpose, not appearance:

```javascript
const colors = {
  brand: {
    primary: '#F7931A',
    secondary: '#8E44AD',
  },
  neutral: {
    50: '#FAFAFA',
    900: '#0a0a0a',
  },
  semantic: {
    success: '#22C55E',
    error: '#EF4444',
  },
};
```

**Color Usage Rules:**
- ✅ DO use `#0a0a0a` for pure black backgrounds
- ✅ DO use `#FAFAFA` for white text on dark backgrounds
- ✅ DO reverse in light mode (bg: `#FAFAFA`, text: `#0a0a0a`)
- ❌ DON'T use `#000000` or `#FFFFFF`
- ❌ DON'T hardcode colors without using design tokens

## Shadow & Glow Systems

Use shadows sparingly for depth perception:

```css
.shadow-card {
  box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1),
              0 2px 4px -1px rgba(0, 0, 0, 0.06);
}

.glow-on-hover:hover {
  box-shadow: 0 0 20px rgba(255, 255, 255, 0.1);
}
```

## Spacing System

**8px Base Grid** - All spacing follows 8px increments:

```javascript
const spacing = {
  1: '0.25rem',  // 4px
  2: '0.5rem',   // 8px
  4: '1rem',     // 16px
  8: '2rem',     // 32px
  16: '4rem',    // 64px
  32: '8rem',    // 128px
};
```

## Border Radius System

```css
rounded-lg   /* 8px  - buttons */
rounded-2xl  /* 16px - cards */
rounded-3xl  /* 24px - modals */
rounded-full /* 9999px - circles/pills */
```

## Responsive Breakpoints

Mobile-first progressive enhancement:

```javascript
const breakpoints = {
  sm: '640px',   // Mobile landscape
  md: '768px',   // Tablets
  lg: '1024px',  // Laptop
  xl: '1280px',  // Desktop
};
```

## Dark Mode

Design with both modes from the start:

```css
:root {
  /* Light Mode */
  --bg-primary: #FAFAFA;
  --text-primary: #0a0a0a;
}

[data-theme="dark"] {
  /* Dark Mode */
  --bg-primary: #0a0a0a;
  --text-primary: #FAFAFA;
}
```

**CRITICAL COLOR RULES:**
- Pure black is ALWAYS `#0a0a0a` (not `#000000`)
- White text is ALWAYS `#FAFAFA` (not `#FFFFFF`)
- These colors reverse in light vs dark mode
- Never use pure `#000` or `#FFF`

## Hover State Patterns

All interactive elements provide immediate feedback:

```css
.interactive {
  transition: all 0.3s ease;
}

.interactive:hover {
  transform: translateY(-2px);
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
}
```