Skip to content

DESIGN_SYSTEM_DOCUMENTATION.md

Latest commit

 

History

History
878 lines (685 loc) · 19.9 KB

DESIGN_SYSTEM_DOCUMENTATION.md

File metadata and controls

878 lines (685 loc) · 19.9 KB

ProLevel Solutions - Complete Design System & Structure Documentation

🎨 Design System Overview

This document provides a comprehensive guide to replicate the ProLevel Solutions design system on any website.

📁 Project Structure

prolevel-ai-visibility/
├── src/
│   ├── assets/           # Static assets (logos, images)
│   │   └── logo/         # Brand logos
│   ├── components/       # React components
│   │   ├── ui/          # shadcn/ui base components + enhanced versions
│   │   ├── animations/  # Animation components
│   │   └── *.tsx        # Page-specific components
│   ├── design-system/   # Design tokens and utilities
│   │   └── tokens.ts    # Centralized design tokens
│   ├── hooks/           # Custom React hooks
│   ├── lib/             # Utilities and helpers
│   ├── pages/           # Page components (React Router)
│   ├── App.tsx          # Main app component with routes
│   ├── main.tsx         # React entry point
│   └── index.css        # Global styles and Tailwind directives
├── public/              # Public static files
│   └── lovable-uploads/ # Uploaded images and assets
├── tailwind.config.ts   # Tailwind configuration
├── tsconfig.json        # TypeScript configuration
└── vite.config.ts       # Vite build configuration

🎨 Color System

Brand Colors (Red/Orange Gradient Theme)

// Primary Brand Colors
--primary: 0 100% 60%        // Red (#FF3333)
--primary-foreground: 0 0% 100%  // White text

// Gold/Amber Accents
--gold: 0 100% 60%           // Gold accent
--gold-light: 0 100% 70%     // Light gold
--gold-dark: 0 100% 50%      // Dark gold
--gold-muted: 0 50% 50%      // Muted gold

// Accessible Gold (AAA Compliance)
gold-accessible: hsl(0 100% 75%)       // 7:1 contrast
gold-accessible-dark: hsl(0 100% 65%)  // High contrast

// Semantic Colors
--background: 0 0% 0%        // Pure black (#000000)
--foreground: 0 0% 100%      // Pure white
--muted: 240 5% 26%          // Dark gray
--muted-foreground: 240 5% 65%  // Light gray text
--border: 240 6% 10%         // Subtle borders

Brand Color Scales

// Red Brand Scale (50-900)
brand: {
  50: '#fef2f2',   100: '#fee2e2',   200: '#fecaca',
  300: '#fca5a5',  400: '#f87171',   500: '#ef4444',
  600: '#dc2626',  700: '#b91c1c',   800: '#991b1b',
  900: '#7f1d1d'
}

// Orange/Neutral Scale
brandOrange: {
  50: '#fafafa',   100: '#f5f5f5',   200: '#e5e5e5',
  300: '#d4d4d4',  400: '#a3a3a3',   500: '#737373',
  600: '#525252',  700: '#404040',   800: '#262626',
  900: '#000000'
}

📏 Typography System

Font Families

font-display: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
font-sans: Inter, sans-serif

Type Scale (Responsive)

// Headings
h1: text-3xl sm:text-4xl md:text-5xl lg:text-7xl  // Main hero
h2: text-2xl sm:text-3xl md:text-4xl lg:text-5xl  // Section titles
h3: text-xl sm:text-2xl md:text-3xl               // Subsection titles
h4: text-lg sm:text-xl md:text-2xl                // Card titles

// Body Text
base: text-sm md:text-base                        // Body text
large: text-base sm:text-lg md:text-xl            // Large body
small: text-xs sm:text-sm                         // Small text

Font Weights

light: 300
normal: 400
medium: 500
semibold: 600
bold: 700
extrabold: 800

📐 Spacing System

Base Scale (4px increments)

spacing: {
  0: '0px',      0.5: '2px',   1: '4px',    1.5: '6px',
  2: '8px',      2.5: '10px',  3: '12px',   3.5: '14px',
  4: '16px',     5: '20px',    6: '24px',   7: '28px',
  8: '32px',     9: '36px',    10: '40px',  11: '44px',
  12: '48px',    14: '56px',   16: '64px',  20: '80px',
  24: '96px',    28: '112px',  32: '128px', 36: '144px',
  40: '160px',   44: '176px',  48: '192px', 52: '208px',
  56: '224px',   60: '240px',  64: '256px', 72: '288px',
  80: '320px',   96: '384px'
}

Container Padding (Responsive)

Mobile: px-4 (16px)
Tablet: px-6 (24px)
Desktop: px-8 (32px)
Large: px-12 (48px)

Section Spacing

Hero Section: pt-24 pb-16 md:py-32
Standard Section: py-12 md:py-16 lg:py-20
Tight Section: py-8 md:py-12

🎭 Shadow System

Elevation Shadows (Stripe-style depth)

elevation-1: '0 1px 2px 0 rgba(0, 0, 0, 0.05)'              // Subtle lift
elevation-2: '0 4px 6px -1px rgba(0, 0, 0, 0.1)'            // Standard card
elevation-3: '0 10px 15px -3px rgba(0, 0, 0, 0.1)'          // Hovered card
elevation-4: '0 20px 25px -5px rgba(0, 0, 0, 0.1)'          // Modal/dialog
elevation-5: '0 25px 50px -12px rgba(0, 0, 0, 0.25)'        // Maximum depth

Glow Shadows (Brand accent)

glow-subtle: '0 0 20px hsl(0 100% 60% / 0.2)'
glow-moderate: '0 0 30px hsl(0 100% 60% / 0.3)'
glow-intense: '0 0 40px hsl(0 100% 60% / 0.4)'
glow-extreme: '0 0 60px hsl(0 100% 60% / 0.5)'

Focus Ring (Accessibility - AAA)

focus-default: '0 0 0 2px hsl(var(--primary)), 0 0 0 4px hsl(var(--primary) / 0.3)'
focus-inset: 'inset 0 0 0 2px hsl(var(--primary))'
focus-large: '0 0 0 3px hsl(var(--primary)), 0 0 0 6px hsl(var(--primary) / 0.3)'

🧩 Component Library

Enhanced Components (src/components/ui/)

1. EnhancedButton

Variants: default | gradient | outline | ghost | glow
Sizes: sm | md | lg | xl
Props: icon, iconPosition (left|right), fullWidth, loading

Usage:

<EnhancedButton variant="gradient" size="lg" icon={<Rocket />} iconPosition="right">
  Get Started
</EnhancedButton>

2. EnhancedCard

Variants: default | glass | gradient | elevated | bordered
Features: Hover effects, animations, backdrop blur

Usage:

<EnhancedCard variant="glass">
  <EnhancedCardHeader>
    <EnhancedCardTitle>Title</EnhancedCardTitle>
  </EnhancedCardHeader>
  <EnhancedCardContent>Content</EnhancedCardContent>
</EnhancedCard>

3. StatsCard

Props: label, value, icon, color, trend, suffix, prefix
Features: Animated numbers, trend indicators

4. SectionHeader

Props: badge, badgeIcon, title, description, align, gradient

5. FeatureGrid

Props: columns (1-4), gap, features[]
Responsive: Stacks on mobile, grid on desktop

Animation Components (src/components/animations/)

1. ScrollReveal

Props: direction (up|down|left|right), delay, children
Triggers: On viewport intersection

2. ScrollProgress

Fixed progress bar at top showing scroll percentage

3. AnimatedGradient

Animated background gradient overlay

4. EnhancedParticles

Props: particleCount, speed, opacity
Features: Adaptive performance, mobile optimization

📱 Mobile Optimization Standards

Touch Targets (WCAG AAA)

Minimum: 44px × 44px
Recommended: 48px × 48px
Large elements: 56px × 56px

Classes:
.touch-target: min-w-[44px] min-h-[44px]
.touch-target-lg: min-w-[48px] min-h-[48px]
.touch-target-xl: min-w-[56px] min-h-[56px]

Responsive Grids

// Standard pattern
grid-cols-1 md:grid-cols-2 lg:grid-cols-3

// Common layouts
grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4  // 4-column
grid-cols-2 lg:grid-cols-4                                 // Stats
grid-cols-1 md:grid-cols-2                                 // Two-column

Text Overflow Protection

Classes to add:
- break-words
- hyphens-auto
- line-clamp-{n}
- truncate

Button Patterns

// Mobile-first buttons
w-full sm:w-auto              // Full width on mobile
min-h-[44px] md:min-h-[48px]  // Touch-friendly height

🎬 Animation System

Keyframe Animations

// Fades
fade-in: 0.4s ease-out
fade-in-up: 0.5s ease-out
fade-out: 0.5s ease-out

// Scales
scale-in: 0.3s ease-out
pulse-zoom: 2s ease-in-out infinite

// Slides
slide-in-up: 0.3s ease-out

// Marquee (logos, text)
marquee: 30s linear infinite
marquee-slow: 48s linear infinite
marquee-fast: 10s linear infinite
marquee-slower: 120s linear infinite

// Special effects
shimmer: 2s linear infinite
float: 6s ease-in-out infinite
pulse-glow: 3s ease-in-out infinite
particle-rise: var(--duration, 15s) ease-in-out infinite

Timing Functions

ease-smooth: cubic-bezier(0.4, 0, 0.2, 1)
ease-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55)
ease-elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6)

🔧 Utility Classes (index.css)

Gradients

.gradient-text: Linear gradient text effect
.gradient-text-shine: Animated gradient text
.gradient-gold: Gold gradient background
.gradient-gold-radial: Radial gold gradient

Glass Morphism

.glass-card: backdrop-blur-md bg-white/5 border border-white/10
.glass-surface: backdrop-blur-lg bg-black/40

Interactive

.tap-feedback: Active scale down effect
.hover-lift: Hover translate up
.hover-glow: Hover glow effect
.touch-manipulation: Optimizes touch events

Accessibility

.sr-only: Screen reader only content
.focus-visible: ring-2 ring-primary

Safe Area (Notched Devices)

.safe-bottom: pb-safe
.pb-safe: padding-bottom: calc(0.5rem + env(safe-area-inset-bottom))
.pt-safe: padding-top: calc(0.5rem + env(safe-area-inset-top))

🗂️ Page Templates

Standard Page Structure

<>
  <SEOHead title="Page Title" description="..." url="..." />
  <div className="min-h-screen flex flex-col bg-black relative">
    <ScrollProgress />
    <EnhancedParticles />
    <AnimatedGradient />
    <Navbar />

    <main className="flex-1 relative z-10">
      {/* Hero Section */}
      <section className="pt-24 pb-16 md:py-32 px-4">
        <div className="container mx-auto">
          <SectionHeader
            badge="Badge Text"
            badgeIcon={<Icon />}
            title="Main Title"
            description="Description"
            align="center"
            gradient={true}
          />
        </div>
      </section>

      {/* Content Sections */}
      <ScrollReveal direction="up" delay={0.2}>
        <section className="py-12 md:py-16 px-4">
          {/* Section content */}
        </section>
      </ScrollReveal>

      {/* CTA Section */}
      <section className="py-16 px-4">
        <div className="container mx-auto max-w-4xl text-center">
          {/* Call to action */}
        </div>
      </section>
    </main>

    <Footer />
    <MobileStickyFooter />
    <MobileBottomNav />
  </div>
</>

📊 Grid Layouts

Container Widths

max-w-screen-sm: 640px    // Small content
max-w-screen-md: 768px    // Medium content
max-w-4xl: 896px          // Standard content
max-w-6xl: 1152px         // Wide content
max-w-7xl: 1280px         // Full-width sections

Common Grid Patterns

// Stats Grid (4 columns)
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 md:gap-6">

// Feature Grid (3 columns)
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 md:gap-8">

// Two Column Layout
<div className="grid grid-cols-1 md:grid-cols-2 gap-8 md:gap-12">

// Masonry Grid (varied heights)
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 auto-rows-auto">

🎯 Icon System

Icon Library: lucide-react

Common Icons:

import {
  Rocket, Target, Award, CheckCircle2, TrendingUp,
  Sparkles, Eye, Cpu, Headphones, ShoppingCart,
  Mail, Phone, MapPin, ExternalLink, ArrowRight,
  Menu, X, Home, User, Settings, Search
} from "lucide-react";

Icon Sizing:

Small: w-4 h-4 (16px)
Medium: w-5 h-5 (20px)
Large: w-6 h-6 (24px)
XLarge: w-8 h-8 (32px)
Hero: w-12 h-12 (48px)

// Responsive
w-4 h-4 sm:w-5 sm:h-5 md:w-6 md:h-6

🔗 Navigation System

Desktop Navbar

  • Logo (left)
  • Navigation links (center)
  • CTA button (right)
  • Sticky on scroll with backdrop blur
  • Height: h-16 md:h-20

Mobile Navigation

  1. Hamburger Menu: Full-screen drawer overlay
  2. MobileBottomNav: Sticky bottom navigation (< 768px)
    • 4 primary navigation items
    • 56px touch targets
    • Active state indicators
    • Safe area support

Footer

  • 5-column grid on desktop → 2 columns tablet → 1 column mobile
  • Newsletter signup
  • Social media icons (48px touch targets)
  • Back-to-top button

🎨 Design Patterns

Card Hover Effects

// Glass card with hover lift
className="glass-card hover:scale-105 hover:shadow-glow-moderate transition-all duration-300"

// Elevated card with glow
className="bg-black/40 border border-primary/20 hover:border-primary/40 hover:shadow-elevation-3"

Button Patterns

// Primary CTA
<EnhancedButton variant="gradient" size="xl" fullWidth>

// Secondary action
<EnhancedButton variant="outline" size="lg">

// Ghost action
<EnhancedButton variant="ghost" size="md">

Badge Patterns

// Status badge
<Badge variant="default">Active</Badge>

// Category badge
<Badge variant="outline">Technology</Badge>

// Count badge
<Badge variant="secondary">12</Badge>

⚡ Performance Optimizations

Code Splitting

// Lazy load heavy components
const AIVisibility = lazy(() => import("@/pages/AIVisibility"));
const Analytics = lazy(() => import("@/pages/Analytics"));

Image Optimization

// Lazy loading
<img loading="lazy" ... />

// Responsive images
<img
  src="image.jpg"
  srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
  sizes="(max-width: 640px) 100vw, 640px"
/>

Particle System

// Adaptive particle count
Mobile: 24 particles (20% of base)
Tablet: 60 particles (50% of base)
Desktop: 120 particles (100% of base)

// Respects prefers-reduced-motion

🌐 SEO Structure

SEOHead Component

<SEOHead
  title="Page Title | ProLevel Solutions"
  description="Page description (155-160 chars)"
  url="https://prolevelsolutions.com/page"
  keywords="keyword1, keyword2, keyword3"
  ogImage="/lovable-uploads/og-image.jpg"
/>

Semantic HTML

<header>   - Site header with navigation
<nav>      - Navigation menus
<main>     - Main content area
<article>  - Self-contained content
<section>  - Thematic groupings
<aside>    - Sidebar content
<footer>   - Site footer

🔐 Accessibility Checklist

✅ Must-Have Features

  • All interactive elements have min 44px touch targets
  • Focus states visible on all interactive elements
  • ARIA labels on icon-only buttons
  • Semantic HTML structure (header, nav, main, footer)
  • Alt text on all images
  • Form labels properly associated with inputs
  • Color contrast ≥ 7:1 for AAA compliance
  • Keyboard navigation works throughout
  • Skip to content link
  • Heading hierarchy (h1 → h2 → h3)
  • Error messages announced to screen readers
  • Loading states communicated
  • Landmark regions defined (role attributes)

🚀 Deployment Configuration

Vite Config

export default defineConfig({
  plugins: [react()],
  build: {
    outDir: 'dist',
    sourcemap: false,
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom', 'react-router-dom'],
          ui: ['@radix-ui/react-accordion', '@radix-ui/react-dialog']
        }
      }
    }
  }
});

Tailwind Purge

content: [
  "./pages/**/*.{ts,tsx}",
  "./components/**/*.{ts,tsx}",
  "./app/**/*.{ts,tsx}",
  "./src/**/*.{ts,tsx}",
]

📦 Dependencies

Core

"react": "^18.3.1",
"react-dom": "^18.3.1",
"react-router-dom": "^6.27.0"

UI & Styling

"tailwindcss": "^3.4.1",
"@radix-ui/react-*": "Latest",
"framer-motion": "^11.11.17",
"lucide-react": "^0.462.0",
"class-variance-authority": "^0.7.0",
"clsx": "^2.1.1",
"tailwind-merge": "^2.5.4"

Forms & Validation

"react-hook-form": "^7.54.0",
"zod": "^3.23.8",
"@hookform/resolvers": "^3.9.1"

🎓 Quick Start Guide

To Replicate This Design:

  1. Install Dependencies
npm install
  1. Copy Design System Files
  • tailwind.config.ts - Full configuration
  • src/index.css - Global styles and utilities
  • src/design-system/tokens.ts - Design tokens
  • src/components/ui/* - All UI components
  1. Copy Enhanced Components
  • src/components/ui/enhanced-button.tsx
  • src/components/ui/enhanced-card.tsx
  • src/components/ui/stats-card.tsx
  • src/components/ui/section-header.tsx
  • src/components/animations/* - All animation components
  1. Use Page Templates
  • Copy structure from src/pages/Index.tsx for homepage
  • Use section patterns from other pages
  • Maintain mobile-first responsive approach
  1. Apply Mobile Optimizations
  • All grids: grid-cols-1 md:grid-cols-{n}
  • All text: Responsive sizing text-sm md:text-base
  • All buttons: min-h-[44px] + w-full sm:w-auto
  • All spacing: py-8 md:py-12 patterns

📞 Component Examples

Hero Section

<section className="pt-24 pb-16 md:py-32 px-4">
  <div className="container mx-auto max-w-6xl text-center">
    <SectionHeader
      badge="Welcome"
      badgeIcon={<Sparkles className="w-4 h-4" />}
      title="Transform Your Business with AI"
      description="Enterprise-grade AI solutions that deliver measurable results"
      align="center"
      gradient={true}
    />
    <div className="flex flex-col sm:flex-row gap-4 justify-center mt-8">
      <EnhancedButton variant="gradient" size="xl" icon={<Rocket />}>
        Get Started
      </EnhancedButton>
      <EnhancedButton variant="outline" size="xl">
        Learn More
      </EnhancedButton>
    </div>
  </div>
</section>

Stats Section

<section className="py-12 md:py-16 px-4">
  <div className="container mx-auto max-w-6xl">
    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 md:gap-6">
      <StatsCard
        label="Projects Completed"
        value={120}
        icon={CheckCircle2}
        color="text-green-500"
        trend={{ value: 15, direction: "up", label: "this month" }}
      />
      <StatsCard
        label="Client Satisfaction"
        value={100}
        suffix="%"
        icon={Award}
        color="text-gold"
      />
    </div>
  </div>
</section>

Feature Grid

<section className="py-16 px-4">
  <div className="container mx-auto max-w-7xl">
    <SectionHeader
      badge="Features"
      title="Why Choose Us"
      description="Everything you need to succeed"
      align="center"
    />
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6 md:gap-8 mt-12">
      {features.map((feature, index) => (
        <EnhancedCard key={index} variant="glass">
          <EnhancedCardHeader>
            <div className="flex items-center gap-4">
              <div className="p-3 bg-primary/20 rounded-lg">
                <feature.icon className="w-6 h-6 text-primary" />
              </div>
              <EnhancedCardTitle>{feature.title}</EnhancedCardTitle>
            </div>
          </EnhancedCardHeader>
          <EnhancedCardContent>
            <p className="text-sm md:text-base text-muted-foreground">
              {feature.description}
            </p>
          </EnhancedCardContent>
        </EnhancedCard>
      ))}
    </div>
  </div>
</section>

🎯 Brand Guidelines

Logo Usage

  • Minimum size: 120px width
  • Clear space: Equal to height of logo
  • Backgrounds: White or dark (black, dark gray)
  • Color variations: Full color, white, black

Voice & Tone

  • Professional: Enterprise-grade solutions
  • Innovative: Cutting-edge AI technology
  • Results-Driven: Measurable business impact
  • Accessible: Easy to understand technical concepts

Imagery Style

  • Modern, clean, high-tech
  • Dark backgrounds with vibrant accents
  • Gradients and glows for emphasis
  • Abstract tech patterns and particles

This documentation provides everything needed to replicate the ProLevel Solutions design system on any website. All components, patterns, and optimizations are production-ready and mobile-optimized.