Skip to content

IMPLEMENTATION_GUIDE.md

Latest commit

 

History

History
577 lines (489 loc) · 16 KB

IMPLEMENTATION_GUIDE.md

File metadata and controls

577 lines (489 loc) · 16 KB

CoreFlow Implementation Guide

Before & After: Component Code Examples

This guide shows how to apply the CoreFlow Design System to your components with practical, copy-paste ready code.

1. Metric Card (Stats Grid)

❌ Before: Low Contrast, Flat

<div className="p-4 rounded-lg border border-slate-700/50 bg-slate-900/50">
  <p className="text-xs text-slate-400 uppercase tracking-wider">Total Escrows</p>
  <p className="text-2xl font-bold text-slate-600">3</p>  {/* ❌ Poor contrast */}
</div>

Issues:

  • Number is slate-600 on slate-900 = ~3:1 contrast (fails WCAG AA)
  • Flat background, no depth
  • No color differentiation between metrics
  • No hover state

✅ After: Accessible, Modern, Interactive

<div className="
  p-4 rounded-lg
  border border-emerald-500/20
  bg-gradient-to-br from-blue-900/20 via-slate-800/30 to-slate-800/20
  backdrop-blur-lg
  shadow-xl shadow-emerald-900/10
  hover:border-emerald-500/40
  hover:shadow-lg hover:shadow-emerald-900/20
  hover:bg-gradient-to-br hover:from-blue-900/30 hover:via-slate-800/40 hover:to-slate-800/30
  transition-all duration-300
  group
">
  {/* Metadata label - smallest, most subtle */}
  <p className="text-xs text-slate-400 uppercase tracking-wider font-medium mb-1">
    Total Escrows
  </p>
  
  {/* Primary metric - largest, most visible */}
  <p className="
    text-3xl font-bold
    bg-gradient-to-r from-blue-600 to-slate-400
    bg-clip-text text-transparent
    mt-2
  ">
    3
  </p>
  
  {/* Optional: Trend indicator */}
  <p className="
    text-xs text-emerald-400 mt-2
    group-hover:text-emerald-300 transition-colors
  ">
    ↑ 1 this week
  </p>
</div>

Improvements:

  • ✅ Number contrast: 9:1+ (AAA compliant)
  • ✅ Color-coded gradient (blue for neutral metric)
  • ✅ Glassmorphism: backdrop-blur-lg + gradient
  • ✅ Hover elevation: Border opacity, shadow, background
  • ✅ Smooth 300ms transition
  • ✅ Unified group hover state

Color Variants by Metric:

{/* Pending - use amber */}
from-amber-900/20 border-amber-500/20 bg-gradient-to-r from-amber-600

{/* Approved - use emerald */}
from-emerald-900/20 border-emerald-500/20 bg-gradient-to-r from-emerald-600

{/* Error - use red */}
from-red-900/20 border-red-500/20 bg-gradient-to-r from-red-600

2. Activity Feed Item (Transaction Card)

❌ Before: Dull, No Visual Hierarchy

<div className="flex items-center justify-between p-3 rounded-lg border border-slate-700/30 bg-slate-800/30 hover:bg-slate-800/50 transition-colors">
  <div className="flex-1 min-w-0">
    <p className="text-sm text-slate-300">Manager Approved • Escrow #2</p>
    <p className="text-xs text-slate-500 mt-1">a1b2c3d4e5f6g7h8...</p>
  </div>
  <span className="px-2 py-1 rounded text-xs bg-emerald-500/10 text-emerald-400">Success</span>
</div>

Issues:

  • Flat background with no gradient
  • Static hover (just opacity change)
  • No depth separation
  • Badge is background-only (no border)
  • Font too similar between content and hash

✅ After: Modern, Layered, Interactive

<div className="
  flex items-center justify-between p-4 rounded-lg
  border border-emerald-500/15
  bg-gradient-to-r from-slate-800/30 to-emerald-900/10
  hover:border-emerald-500/30
  hover:bg-gradient-to-r hover:from-slate-800/40 hover:to-emerald-900/20
  transition-all duration-300
  group
">
  {/* Left: Content Container */}
  <div className="flex-1 min-w-0">
    {/* Primary text - clear action */}
    <p className="
      text-sm font-medium text-slate-200
      group-hover:text-slate-100 transition-colors
    ">
      Manager Approved
      <span className="text-slate-500">• Escrow #2</span>
    </p>
    
    {/* Secondary: Hash in monospace font (visual distinction) */}
    <p className="
      text-xs text-slate-500 font-mono mt-1
      group-hover:text-slate-400 transition-colors
      truncate
    ">
      a1b2c3d4e5f6g7h8...
    </p>
  </div>
  
  {/* Right: Status Badge + Timestamp */}
  <div className="text-right ml-4 flex flex-col items-end gap-2">
    {/* Status badge with border + background (not just background) */}
    <span className="
      px-3 py-1 rounded-full text-xs font-medium
      bg-emerald-500/10 border border-emerald-500/30 text-emerald-400
      group-hover:bg-emerald-500/20 group-hover:border-emerald-500/50
      transition-all
    ">
      Success
    </span>
    
    {/* Timestamp - tertiary text */}
    <p className="text-xs text-slate-500 whitespace-nowrap">2 min ago</p>
  </div>
</div>

Improvements:

  • ✅ Directional gradient: left slate (neutral) → right emerald (accent)
  • ✅ Monospace font for hash (visual distinction)
  • ✅ Badge has border for depth
  • ✅ Hover enlarges badge (bg/border opacity increase)
  • ✅ Text color changes on hover (emerald-400 → emerald-300)
  • ✅ truncate prevents layout shift
  • ✅ Unified group hover experience

Status Badge Variants:

{/* Success - emerald */}
bg-emerald-500/10 border-emerald-500/30 text-emerald-400
group-hover:bg-emerald-500/20 group-hover:border-emerald-500/50

{/* Pending - amber */}
bg-amber-500/10 border-amber-500/30 text-amber-400
group-hover:bg-amber-500/20 group-hover:border-amber-500/50

{/* Error - red */}
bg-red-500/10 border-red-500/30 text-red-400
group-hover:bg-red-500/20 group-hover:border-red-500/50

3. Data Grid (Escrow Details)

❌ Before: Uniform, No Visual Hierarchy

<div className="grid grid-cols-3 gap-4">
  <div className="bg-slate-800/50 p-4 rounded-lg border border-slate-700/30">
    <p className="text-xs text-slate-400 uppercase tracking-wider mb-1">Amount</p>
    <p className="text-lg font-semibold text-slate-100">4,200 USDC</p>
  </div>
  <div className="bg-slate-800/50 p-4 rounded-lg border border-slate-700/30">
    <p className="text-xs text-slate-400 uppercase tracking-wider mb-1">Hours Logged</p>
    <p className="text-lg font-semibold text-slate-100">40h</p>
  </div>
  <div className="bg-slate-800/50 p-4 rounded-lg border border-slate-700/30">
    <p className="text-xs text-slate-400 uppercase tracking-wider mb-1">Rate</p>
    <p className="text-lg font-semibold text-slate-100">$250/hr</p>
  </div>
</div>

Issues:

  • All boxes identical (no color coding)
  • No hover feedback
  • Flat backgrounds
  • Limited visual distinction

✅ After: Color-Coded, Interactive

<div className="grid grid-cols-3 gap-4">
  {/* Amount box - Blue accent */}
  <div className="
    bg-gradient-to-br from-blue-900/20 to-slate-800/30
    p-4 rounded-lg
    border border-blue-500/20
    hover:border-blue-500/40
    hover:shadow-lg hover:shadow-blue-900/10
    transition-all duration-300
    group
  ">
    <p className="text-xs text-slate-400 uppercase tracking-wider font-medium mb-1">
      Amount
    </p>
    <div className="mt-2">
      <p className="text-2xl font-bold text-slate-100">
        4,200
        <span className="text-sm text-slate-400 font-medium ml-1">USDC</span>
      </p>
    </div>
  </div>

  {/* Hours box - Amber accent */}
  <div className="
    bg-gradient-to-br from-amber-900/20 to-slate-800/30
    p-4 rounded-lg
    border border-amber-500/20
    hover:border-amber-500/40
    hover:shadow-lg hover:shadow-amber-900/10
    transition-all duration-300
    group
  ">
    <p className="text-xs text-slate-400 uppercase tracking-wider font-medium mb-1">
      Hours Logged
    </p>
    <p className="text-2xl font-bold text-slate-100 mt-2">
      40<span className="text-sm text-slate-400 font-medium">h</span>
    </p>
  </div>

  {/* Rate box - Emerald accent */}
  <div className="
    bg-gradient-to-br from-emerald-900/20 to-slate-800/30
    p-4 rounded-lg
    border border-emerald-500/20
    hover:border-emerald-500/40
    hover:shadow-lg hover:shadow-emerald-900/10
    transition-all duration-300
    group
  ">
    <p className="text-xs text-slate-400 uppercase tracking-wider font-medium mb-1">
      Rate
    </p>
    <p className="text-2xl font-bold text-slate-100 mt-2">
      $250<span className="text-sm text-slate-400 font-medium">/hr</span>
    </p>
  </div>
</div>

Improvements:

  • ✅ Color-coded: Blue (neutral), Amber (warning), Emerald (success)
  • ✅ Each box has matching colored border
  • ✅ Gradient from color-900/20 to slate-800/30 (blends nicely)
  • ✅ Hover changes border opacity (20% → 40%)
  • ✅ Hover adds shadow with color tint
  • ✅ Units separated in smaller, secondary text

4. Approval Timeline (Status Checklist)

❌ Before: Minimal Visual Feedback

<div className="space-y-2">
  <div className="flex items-center gap-2">
    <div className="w-4 h-4 rounded-full bg-emerald-500" />
    <span className="text-sm text-slate-300">Hours Verified</span>
  </div>
  <div className="flex items-center gap-2">
    <div className="w-4 h-4 rounded-full bg-slate-700" />
    <span className="text-sm text-slate-400">Manager Approval</span>
  </div>
</div>

Issues:

  • Tiny circles (easy to miss)
  • No border/container distinction
  • Icons not clear (filled circle = done, empty = pending?)
  • No visual hierarchy between states

✅ After: Clear, Visible, Professional

<div className="space-y-3">
  {/* Completed - Verified */}
  <div className="flex items-center gap-3">
    <div className="
      w-6 h-6 rounded-full
      flex items-center justify-center text-xs font-bold
      bg-emerald-500/20 text-emerald-400
      border border-emerald-500/50
      flex-shrink-0
    ">
      ✓
    </div>
    <span className="text-sm font-medium text-emerald-400">
      Hours Verified
    </span>
  </div>

  {/* Pending - Awaiting Action */}
  <div className="flex items-center gap-3">
    <div className="
      w-6 h-6 rounded-full
      flex items-center justify-center text-xs font-bold
      bg-blue-500/20 text-blue-400
      border border-blue-500/50
      flex-shrink-0
    ">
      ⟳
    </div>
    <span className="text-sm font-medium text-blue-400">
      Manager Approval
    </span>
  </div>

  {/* Not Started - Inactive */}
  <div className="flex items-center gap-3 opacity-50">
    <div className="
      w-6 h-6 rounded-full
      flex items-center justify-center text-xs font-bold
      bg-slate-700/30 text-slate-600
      border border-slate-600/30
      flex-shrink-0
    ">
      ○
    </div>
    <span className="text-sm text-slate-500">
      Finance Approval
    </span>
  </div>
</div>

Improvements:

  • ✅ Larger circles (w-6 h-6 = 24px, easy to see)
  • ✅ Clear icons: ✓ (done), ⟳ (pending), ○ (not started)
  • ✅ Each state has distinct color (emerald, blue, gray)
  • ✅ Border + background for depth
  • ✅ Text color matches icon (visual cohesion)
  • ✅ flex-shrink-0 prevents icons from shrinking
  • ✅ Inactive state has opacity-50 for visual hierarchy

State Variants:

{/* Completed */}
bg-emerald-500/20 border-emerald-500/50 text-emerald-400
icon: ✓

{/* In Progress */}
bg-blue-500/20 border-blue-500/50 text-blue-400
icon: ⟳

{/* Pending */}
bg-amber-500/20 border-amber-500/50 text-amber-400
icon: ⏱

{/* Failed */}
bg-red-500/20 border-red-500/50 text-red-400
icon: ✕

{/* Disabled */}
bg-slate-700/30 border-slate-600/30 text-slate-600 opacity-50
icon: ○

5. Card Container (Escrow Card)

❌ Before: Flat, Basic Border

<div className="border-slate-700/50 bg-slate-900/50 backdrop-blur-sm overflow-hidden rounded-lg">
  {/* Content */}
</div>

✅ After: Modern, Layered, Premium

<div className="
  rounded-lg overflow-hidden
  border border-emerald-500/20
  bg-gradient-to-br from-slate-800/40 via-slate-800/30 to-emerald-900/20
  backdrop-blur-lg
  shadow-xl shadow-emerald-900/10
  hover:border-emerald-500/40
  hover:shadow-2xl hover:shadow-emerald-900/20
  transition-all duration-300
  group
">
  {/* Content */}
</div>

Improvements:

  • ✅ Multi-stop gradient (from → via → to)
  • ✅ Emerald tint at end (subtle accent)
  • ✅ Larger backdrop blur (lg = 12px)
  • ✅ Shadow has emerald tint (not neutral gray)
  • ✅ Hover increases shadow and border visibility
  • ✅ Smooth 300ms transition

6. Button States (Action Buttons)

❌ Before: Generic

<button className="bg-blue-600 text-white hover:bg-blue-700 px-4 py-2 rounded">
  Manager Approve
</button>

✅ After: Professional with Feedback

{/* Primary Action - Emerald */}
<button className="
  px-4 py-2 rounded-lg font-medium
  bg-emerald-600 text-white
  hover:bg-emerald-700
  active:bg-emerald-800 active:scale-95
  focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:ring-offset-2 focus:ring-offset-slate-950
  disabled:opacity-50 disabled:cursor-not-allowed
  transition-all duration-200
">
  Manager Approve
</button>

{/* Secondary Action - Slate */}
<button className="
  px-4 py-2 rounded-lg font-medium
  bg-slate-700 text-slate-100
  hover:bg-slate-600
  active:bg-slate-800 active:scale-95
  focus:outline-none focus:ring-2 focus:ring-slate-500 focus:ring-offset-2 focus:ring-offset-slate-950
  disabled:opacity-50 disabled:cursor-not-allowed
  transition-all duration-200
">
  Cancel
</button>

{/* Destructive Action - Red */}
<button className="
  px-4 py-2 rounded-lg font-medium
  bg-red-600 text-white
  hover:bg-red-700
  active:bg-red-800 active:scale-95
  focus:outline-none focus:ring-2 focus:ring-red-500 focus:ring-offset-2 focus:ring-offset-slate-950
  disabled:opacity-50 disabled:cursor-not-allowed
  transition-all duration-200
">
  Delete
</button>

Features:

  • ✅ Active state: darker color + scale down (tactile feedback)
  • ✅ Focus ring: 2px ring with offset (keyboard accessible)
  • ✅ Disabled state: opacity reduced, cursor not-allowed
  • ✅ Smooth 200ms transition (faster than cards)
  • ✅ Color-coded: Emerald (primary), Slate (secondary), Red (destructive)

Implementation Checklist

Use this checklist when updating components:

Metric Cards

  • Use gradient backgrounds from-{color}-900/20
  • Number in text-3xl font-bold with gradient text
  • Color-code by status (blue, amber, emerald, red)
  • Add hover elevation (border, shadow)
  • 300ms transition-all

Activity Feed

  • Directional gradient from-slate-800/30 to-emerald-900/10
  • Hash in font-mono for distinction
  • Badge with both border and bg
  • Hover increases badge opacity
  • group-hover for unified states

Data Grid

  • Three colors: blue, amber, emerald
  • from-{color}-900/20 to-slate-800/30 gradient
  • Hover changes border opacity 20%→40%
  • Units separated in smaller text

Timelines

  • Icons: ✓, ⟳, ○, ⏱, ✕
  • Circles: w-6 h-6 (not tiny)
  • Border + background for depth
  • Text color matches icon
  • Inactive state: opacity-50

Cards

  • Multi-stop gradient
  • Emerald-tinted shadow
  • backdrop-blur-lg (not just sm)
  • Hover elevation
  • 300ms smooth transition

Quick Copy-Paste Utilities

/* Glassmorphism card */
.glass-card {
  @apply rounded-lg border border-emerald-500/20 
    bg-gradient-to-br from-slate-800/40 via-slate-800/30 to-emerald-900/20
    backdrop-blur-lg shadow-xl shadow-emerald-900/10
    hover:border-emerald-500/40 hover:shadow-2xl hover:shadow-emerald-900/20
    transition-all duration-300;
}

/* Status badge */
.badge-success {
  @apply px-3 py-1 rounded-full text-xs font-medium
    bg-emerald-500/10 border border-emerald-500/30 text-emerald-400
    group-hover:bg-emerald-500/20 group-hover:border-emerald-500/50
    transition-all;
}

.badge-pending {
  @apply px-3 py-1 rounded-full text-xs font-medium
    bg-amber-500/10 border border-amber-500/30 text-amber-400
    group-hover:bg-amber-500/20 group-hover:border-amber-500/50
    transition-all;
}

/* Metric grid item */
.metric-box {
  @apply bg-gradient-to-br p-4 rounded-lg border
    hover:shadow-lg transition-all duration-300;
}

.metric-box-blue { @apply from-blue-900/20 to-slate-800/30 border-blue-500/20 hover:border-blue-500/40; }
.metric-box-amber { @apply from-amber-900/20 to-slate-800/30 border-amber-500/20 hover:border-amber-500/40; }
.metric-box-emerald { @apply from-emerald-900/20 to-slate-800/30 border-emerald-500/20 hover:border-emerald-500/40; }

Add to globals.css for quick reuse across components!