CompanySite/.agents/frontend-specialist/DESIGN_SYSTEM_GUIDE.md

Design System Guide - WorkRoot IT Solutions

Color Palette

Primary Colors (Cyan)

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)

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)

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

font-sans: 'Plus Jakarta Sans', system-ui, sans-serif
font-mono: 'JetBrains Mono', monospace

Font Sizes

/* 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

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

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

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

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

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

/* 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

/* 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

/* 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

/* 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

<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

<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

<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

<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

<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

<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

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

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

<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

ease-out: Good for entrances
ease-in: Good for exits
ease-in-out: Good for looping animations

Duration

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)

transition-all duration-500 hover:-translate-y-2 hover:shadow-2xl

Hover Effect (Button)

transition-all hover:scale-105 hover:shadow-2xl

Entrance Animation

opacity-0 animate-slide-up

With inline style:

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

Accessibility

Focus States

Always include visible focus states:

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:

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

Responsive Breakpoints

/* 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

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

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

Section

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

Grid Layouts

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