Component Development Guide

Comprehensive instructions for developing Svelte components that maintain consistency with the established Workilo design system and architecture.

Project Structure

src/
├── lib/
│   ├── components/
│   │   ├── dashboard/          # Dashboard-specific components
│   │   ├── workflows/          # Workflow-specific components
│   │   ├── app/               # App shell components
│   │   ├── auth/              # Authentication components
│   │   └── [feature]/         # Feature-specific folders
│   ├── styles/                # CSS files per feature
│   └── workalongs.ts          # Data definitions
└── routes/
    ├── app/                   # Protected app routes
    │   ├── workflows/         # Workflow pages
    │   ├── workalongs/        # Workalong management
    │   └── [feature]/         # Other app features
    └── [public]/              # Public marketing pages

Design System & Branding

Workilo Color Variables

--wk-primary: #10B981
--wk-secondary: #6D28D9
--wk-accent: #FF8A00

Bootstrap 5 Integration

  • Use Bootstrap 5 utility classes as primary styling method
  • Custom Workilo variables override Bootstrap defaults
  • Bootstrap Icons (bi-*) for all iconography
  • Responsive grid system (col-*, row, g-*)

Component Architecture Patterns

Standard Component Structure

<script lang="ts">
  // Props with TypeScript types
  export let data: ComponentData[];
  export let isLoading = false;

  // Internal state
  let internalState = '';

  // Functions
  function handleAction() {
    // Component logic
  }
</script>

<!-- Main template -->
<div class="component-container">
  <!-- Content -->
</div>

<style>
  /* Component-specific styles */
</style>

Component Categories

Dashboard Components

Display metrics, quick actions, overview data. Use cards with shadow and hover effects.

Workflow Components

Display workflow states, phases, progress. Include status-based styling and progress indicators.

Standard Card Pattern

<div class="card border-0 shadow-sm h-100">
  <div class="card-header bg-transparent border-0 pb-0">
    <h5 class="card-title mb-0">
      <i class="bi bi-[icon] me-2 text-primary"></i>
      Title
    </h5>
  </div>
  <div class="card-body">
    <!-- Content -->
  </div>
</div>

<style>
  .card {
    transition: transform 0.2s ease, box-shadow 0.2s ease;
  }
  
  .card:hover {
    transform: translateY(-2px);
    box-shadow: 0 8px 25px rgba(0, 0, 0, 0.1) !important;
  }
</style>

Responsive Design Requirements

Bootstrap 5 Breakpoints

  • xs: < 576px (mobile)
  • sm: ≥ 576px
  • md: ≥ 768px
  • lg: ≥ 992px
  • xl: ≥ 1200px
  • xxl: ≥ 1400px

Mobile-First Grid Pattern

<div class="row g-3">
  <div class="col-12 col-lg-6"><!-- Content --></div>
  <div class="col-12 col-lg-6"><!-- Content --></div>
</div>

Data Patterns

Workflow Data Structure

interface Workflow {
  title: string;
  basedOn: string;
  subtitle: string;
  workalongs: Workalong[];
  phases: WorkflowPhase[];
}

interface Workalong {
  name: string;
  role: string;
  color: string;
  avatar: string;
}

Component Creation Checklist

Before Starting
  • Identify component purpose and category
  • Review existing similar components
  • Define TypeScript interfaces
  • Plan responsive behavior
During Development
  • Use Bootstrap 5 utilities for styling
  • Implement hover effects and transitions
  • Add proper TypeScript types
  • Include responsive design
  • Use Workilo color variables
  • Follow naming conventions (workalongs, not agents)

Important Notes

  • Always use "workalongs" not "agents" - This is humanized terminology
  • Bootstrap 5 first - Use utility classes before custom CSS
  • Mobile responsive - Test all components on mobile
  • Workilo branding - Use custom color variables
  • TypeScript - Always type your props and data
  • Authentication - All /app/* routes are protected

Common Patterns & Snippets

Page Header Pattern

<div class="d-flex justify-content-between align-items-center mb-4">
  <div>
    <h1 class="h2 mb-1">Page Title</h1>
    <p class="text-muted mb-0">Page description</p>
  </div>
  <div class="d-flex gap-2">
    <button class="btn btn-outline-secondary">Secondary Action</button>
    <button class="btn btn-primary">Primary Action</button>
  </div>
</div>

Status Function Pattern

function getStatusIcon(status: string) {
  switch(status) {
    case 'done': return 'bi-check-circle-fill';
    case 'in-progress': return 'bi-arrow-clockwise';
    case 'pending': return 'bi-circle';
    default: return 'bi-circle';
  }
}