# Design System Guide - WorkRoot IT Solutions

## Color Palette

### Primary Colors (Cyan)
```css
primary-50:  #ecfeff  /* Lightest - backgrounds, badges */
primary-100: #cffafe  /* Very light - highlights */
primary-200: #a5f3fc  /* Light - hover states */
primary-300: #67e8f9  /* Medium light - text accents, gradients */
primary-400: #22d3ee  /* Medium - interactive elements */
primary-500: #0891b2  /* Base - main brand color */
primary-600: #0e7490  /* Medium dark - hover states for buttons */
primary-700: #155e75  /* Dark - active states */
primary-800: #164e63  /* Darker - text on light backgrounds */
primary-900: #083344  /* Darkest - deep backgrounds */
```

**Usage**:
- CTAs and action buttons
- Links and interactive elements
- Icons and accents
- Gradients (300-600)
- Focus rings

### Secondary Colors (Slate)
```css
secondary-50:  #f8fafc  /* Lightest - page backgrounds */
secondary-100: #f1f5f9  /* Very light - card backgrounds */
secondary-200: #e2e8f0  /* Light - borders, dividers */
secondary-300: #cbd5e1  /* Medium light - disabled states */
secondary-400: #94a3b8  /* Medium - placeholder text */
secondary-500: #64748b  /* Base - secondary text */
secondary-600: #475569  /* Medium dark - body text */
secondary-700: #334155  /* Dark - headings */
secondary-800: #1e293b  /* Darker - primary headings, dark text */
secondary-900: #0f172a  /* Darkest - hero backgrounds */
```

**Usage**:
- Text colors
- Backgrounds (sections)
- Borders and dividers
- Neutral elements

### Accent Colors (Amber)
```css
accent-50:  #fffbeb  /* Lightest - subtle highlights */
accent-100: #fef3c7  /* Very light - badges */
accent-200: #fde68a  /* Light - backgrounds */
accent-300: #fcd34d  /* Medium light - hover states */
accent-400: #fbbf24  /* Medium - stars, ratings */
accent-500: #f59e0b  /* Base - primary accent */
accent-600: #d97706  /* Medium dark - hover states */
accent-700: #b45309  /* Dark - active states */
accent-800: #92400e  /* Darker - text */
accent-900: #78350f  /* Darkest - deep accents */
```

**Usage**:
- Trust badges
- Star ratings
- Warning/attention elements
- Energy/enthusiasm accents

## Typography

### Font Families
```css
font-sans: 'Plus Jakarta Sans', system-ui, sans-serif
font-mono: 'JetBrains Mono', monospace
```

### Font Sizes
```css
/* Hero Headlines */
text-8xl: 6rem (96px)    - Hero H1 desktop
text-7xl: 4.5rem (72px)  - Hero H1 tablet
text-6xl: 3.75rem (60px) - Hero H1 mobile
text-5xl: 3rem (48px)    - Section H2 desktop

/* Section Headlines */
text-4xl: 2.25rem (36px) - Section H2 tablet/mobile
text-3xl: 1.875rem (30px) - Section H3
text-2xl: 1.5rem (24px)  - Card titles

/* Body Text */
text-xl: 1.25rem (20px)  - Large body, intro text
text-lg: 1.125rem (18px) - Button text, emphasized body
text-base: 1rem (16px)   - Standard body
text-sm: 0.875rem (14px) - Captions, meta text
```

### Font Weights
```css
font-bold: 700      - Headlines, strong emphasis
font-semibold: 600  - Subheadings, buttons
font-medium: 500    - Emphasized body text
font-regular: 400   - Body text
font-light: 300     - De-emphasized text (use sparingly)
```

### Line Heights
```css
leading-tight: 1.25     - Large headlines
leading-snug: 1.375     - Subheadings
leading-normal: 1.5     - Standard body
leading-relaxed: 1.625  - Long-form content
```

### Letter Spacing
```css
tracking-tight: -0.025em   - Large headlines
tracking-normal: 0         - Body text
tracking-wide: 0.025em     - Small caps
tracking-wider: 0.05em     - Uppercase labels
```

## Spacing System

### Padding/Margin Scale
```css
p-1:  0.25rem (4px)
p-2:  0.5rem (8px)
p-3:  0.75rem (12px)
p-4:  1rem (16px)      - Base spacing unit
p-5:  1.25rem (20px)
p-6:  1.5rem (24px)    - Card padding (mobile)
p-8:  2rem (32px)      - Card padding (desktop)
p-10: 2.5rem (40px)    - Large card padding
p-12: 3rem (48px)
p-16: 4rem (64px)
p-20: 5rem (80px)      - Section padding (mobile)
p-24: 6rem (96px)      - Section padding (desktop)
```

### Section Spacing
- **Mobile**: py-20 (5rem / 80px)
- **Desktop**: py-24 (6rem / 96px)

### Card Spacing
- **Mobile**: p-6 to p-8 (24px-32px)
- **Desktop**: p-8 to p-10 (32px-40px)

### Grid Gaps
- **Small**: gap-4 (1rem / 16px)
- **Medium**: gap-6 (1.5rem / 24px)
- **Large**: gap-8 (2rem / 32px)

## Border Radius

```css
rounded-lg: 0.5rem (8px)     - Buttons (small)
rounded-xl: 0.75rem (12px)   - Buttons (large)
rounded-2xl: 1rem (16px)     - Small cards
rounded-3xl: 1.5rem (24px)   - Large cards
rounded-full: 9999px         - Pills, avatars
```

**Usage Guide**:
- **Buttons**: rounded-xl (12px)
- **Cards**: rounded-2xl or rounded-3xl (16-24px)
- **Badges**: rounded-full
- **Icons**: rounded-xl (12px)

## Shadows

```css
/* Elevation System */
shadow-sm:  Small - Subtle elevation
shadow:     Base - Default cards
shadow-lg:  Large - Elevated cards
shadow-xl:  Extra Large - Modal, dropdown
shadow-2xl: Huge - Featured elements

/* Custom Shadows */
hover:shadow-2xl hover:shadow-primary/30  - Button hover (colored)
hover:shadow-2xl hover:shadow-primary/50  - Card hover (colored)
```

**Usage**:
- Default cards: shadow-lg
- Hover cards: shadow-2xl
- Buttons: shadow-xl on hover with color glow

## Gradients

### Background Gradients
```css
/* Hero Section */
bg-gradient-to-br from-secondary-900 via-secondary-800 to-primary-900

/* CTA Sections */
bg-gradient-to-br from-secondary-900 via-primary-900 to-primary-800

/* Light Sections */
bg-gradient-to-b from-secondary-50 to-white
```

### Text Gradients
```css
/* Headline Accent */
text-transparent bg-clip-text bg-gradient-to-r from-primary-400 via-primary-300 to-accent-400

/* Subtle Highlight */
text-transparent bg-clip-text bg-gradient-to-r from-primary-300 to-accent-400
```

### Button Gradients
```css
/* Primary Button */
bg-gradient-to-r from-primary-500 to-primary-600

/* Icon Background */
bg-gradient-to-br from-primary-500 to-primary-600
```

## Component Patterns

### Buttons

#### Primary CTA
```html
<a class="inline-flex items-center justify-center rounded-xl bg-gradient-to-r from-primary-500 to-primary-600 px-10 py-5 text-lg font-bold text-white transition-all hover:shadow-2xl hover:shadow-primary/50 hover:scale-105 focus:outline-none focus:ring-2 focus:ring-primary-400 focus:ring-offset-2">
  Button Text
  <svg class="ml-2 w-5 h-5"><!-- Arrow icon --></svg>
</a>
```

#### Secondary CTA
```html
<a class="inline-flex items-center justify-center rounded-xl border-2 border-white/30 bg-white/5 backdrop-blur-sm px-10 py-5 text-lg font-bold text-white transition-all hover:bg-white/10 hover:border-white/50">
  Button Text
</a>
```

#### Tertiary/Link Button
```html
<a class="inline-flex items-center text-primary-600 font-semibold hover:text-primary-700 transition-colors">
  <svg class="w-5 h-5 mr-2"><!-- Icon --></svg>
  Link Text
</a>
```

### Cards

#### Benefit Card
```html
<div class="group relative bg-gradient-to-br from-secondary-50 to-white rounded-2xl p-8 border border-secondary-100 hover:border-primary/30 hover:shadow-2xl transition-all duration-500 hover:-translate-y-2">
  <!-- Icon -->
  <div class="w-16 h-16 rounded-2xl bg-gradient-to-br from-primary-500 to-primary-600 flex items-center justify-center mb-6 group-hover:scale-110 group-hover:rotate-6 transition-all duration-500 shadow-lg">
    <svg class="w-8 h-8 text-white"><!-- Icon --></svg>
  </div>
  <!-- Content -->
  <h3 class="text-2xl font-bold text-secondary-900 mb-3">Title</h3>
  <p class="text-secondary-600 leading-relaxed">Description</p>
</div>
```

#### Service Card
```html
<div class="group relative bg-white rounded-3xl p-10 shadow-lg border-2 border-secondary-100 hover:border-primary-400 hover:shadow-2xl transition-all duration-500 overflow-hidden">
  <div class="absolute inset-0 bg-gradient-to-br from-primary-50/0 to-primary-50/0 group-hover:from-primary-50/50 group-hover:to-transparent transition-all duration-500"></div>
  <div class="relative z-10">
    <!-- Content -->
  </div>
</div>
```

### Badges

#### Section Badge
```html
<span class="inline-block px-4 py-2 rounded-full bg-primary-50 text-primary-700 text-sm font-bold uppercase tracking-wider">
  Badge Text
</span>
```

#### Trust Badge
```html
<div class="inline-flex items-center gap-2 px-4 py-2 rounded-full bg-white/10 backdrop-blur-sm border border-white/20">
  <svg class="w-5 h-5 text-accent-400"><!-- Icon --></svg>
  <span class="text-sm font-medium text-white">Badge Text</span>
</div>
```

### Icons

#### Icon Container (Standalone)
```html
<div class="w-16 h-16 rounded-2xl bg-gradient-to-br from-primary-500 to-primary-600 flex items-center justify-center shadow-lg">
  <svg class="w-8 h-8 text-white"><!-- Icon --></svg>
</div>
```

#### Icon Container (In Card)
```html
<div class="w-16 h-16 rounded-2xl bg-gradient-to-br from-primary-500 to-primary-600 flex items-center justify-center mb-6 group-hover:scale-110 transition-transform duration-500 shadow-xl">
  <svg class="w-8 h-8 text-white"><!-- Icon --></svg>
</div>
```

## Animation Guidelines

### Timing Functions
```css
ease-out: Good for entrances
ease-in: Good for exits
ease-in-out: Good for looping animations
```

### Duration
```css
duration-200: 200ms - Quick feedback (hover states)
duration-300: 300ms - Standard transitions
duration-500: 500ms - Dramatic effects
duration-700: 700ms - Slow, deliberate animations
```

### Common Patterns

#### Hover Effect (Card)
```css
transition-all duration-500 hover:-translate-y-2 hover:shadow-2xl
```

#### Hover Effect (Button)
```css
transition-all hover:scale-105 hover:shadow-2xl
```

#### Entrance Animation
```css
opacity-0 animate-slide-up
```

With inline style:
```html
<div class="opacity-0 animate-slide-up" style="animation-delay: 0.2s;">
```

## Accessibility

### Focus States
Always include visible focus states:
```css
focus:outline-none focus:ring-2 focus:ring-primary-400 focus:ring-offset-2
```

### Color Contrast
Minimum ratios (WCAG AA):
- Normal text: 4.5:1
- Large text (18px+): 3:1
- UI components: 3:1

### Touch Targets
Minimum size: 44x44px (48x48px recommended)

### Motion
Respect prefers-reduced-motion:
```css
@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}
```

## Responsive Breakpoints

```css
/* Mobile First */
/* Default: 0-639px */

sm: 640px   /* Small tablets */
md: 768px   /* Tablets */
lg: 1024px  /* Small laptops */
xl: 1280px  /* Laptops */
2xl: 1536px /* Large screens */
```

### Usage Pattern
```html
<!-- Mobile: stack vertically -->
<!-- Tablet: 2 columns -->
<!-- Desktop: 4 columns -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-8">
```

## Icon Library

Use Heroicons (already included via SVG):
- Outline style for regular UI
- Solid style for filled states

Common icons:
- Arrow right: Navigation, CTAs
- Check circle: Success, completion
- Lightning bolt: Speed, performance
- Shield: Security
- Heart: Satisfaction, love
- Building: Enterprise, business
- Clock: 24/7, support
- Briefcase: Projects, work

## Layout Patterns

### Container
```html
<div class="container-wrapper">
  <!-- Max-width: 1280px (7xl), responsive padding -->
</div>
```

### Section
```html
<section class="py-24 bg-white">
  <div class="container-wrapper">
    <!-- Content -->
  </div>
</section>
```

### Grid Layouts
```html
<!-- 4 column grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-8">

<!-- 2 column grid -->
<div class="grid grid-cols-1 lg:grid-cols-2 gap-16">
```

## Best Practices

### Do's ✅
- Use consistent spacing (multiples of 4px)
- Maintain visual hierarchy
- Limit to 3-4 accent colors per page
- Use semantic color names
- Include hover states on interactive elements
- Test on multiple screen sizes
- Ensure sufficient color contrast
- Use loading states for async actions

### Don'ts ❌
- Don't mix border radius styles
- Don't use arbitrary values (use Tailwind scale)
- Don't skip focus states
- Don't use color alone to convey meaning
- Don't animate layout-triggering properties
- Don't make clickable areas too small
- Don't use pure black (#000000) on pure white
- Don't nest more than 3 levels of cards

---

**Version**: 1.0
**Last Updated**: 2026-03-21
**Maintainer**: frontend-specialist agent