name: "Figma to Laravel Component Update"
description: "Update existing Laravel Twig + LESS component from new Figma design"
version: "1.0.0"

# Workflow Execution Configuration
execution:
  mode: "strict"
  step_tracking: "mandatory"
  abort_on_skip: true
  completion_verification: true

metadata:
  category: "update"
  complexity: "medium"
  estimated_time: "5-10 minutes"
  prerequisites:
    - "Existing component in codebase"
    - "Figma URL with specific node selection"
    - "Figma MCP server access"
    - "Playwright MCP server access"

variables:
  figma_url: "{figma_url}"
  node_id: "{node_id}"
  component_name: "{component_name}"
  component_type: "{component_type}"
  twig_path: "{twig_path}"
  less_path: "{less_path}"

# Mandatory Steps Checklist
mandatory_steps:
  - "locate-existing-component"
  - "read-current-implementation"
  - "capture-figma-design"
  - "analyze-changes"
  - "update-twig-template"
  - "validate-twig-template"
  - "update-less-stylesheet"
  - "validate-less-syntax"
  - "build-and-test"
  - "playwright-validation"
  - "quality-validation"

steps:
  # Step 1: Locate Existing Component
  - id: "locate-existing-component"
    name: "Locate Existing Component Files"
    type: "discovery"
    required: true
    workflow:
      actions:
        - "Search for Twig template in sites/default/templates/includes/"
        - "Search for LESS stylesheet in sites/default/css/"
        - "Determine component type (page_blocks, elements, partials, page_structure)"
        - "Validate both files exist"
      search_locations:
        twig:
          - "sites/default/templates/includes/page_blocks/{component_name}.twig"
          - "sites/default/templates/includes/elements/{component_name}.twig"
          - "sites/default/templates/includes/partials/{component_name}.twig"
          - "sites/default/templates/includes/page_structure/{component_name}.twig"
        less:
          - "sites/default/css/blocks/{component_name}.less"
          - "sites/default/css/elements/{component_name}.less"
          - "sites/default/css/page_structure/{component_name}.less"
      on_not_found:
        action: "stop"
        message: |
          ❌ Component "{component_name}" not found.

          Browse existing components at: http://localhost/component
          Or search: find sites/default/templates/includes -name "*{component_name}*"

  # Step 2: Read Current Implementation
  - id: "read-current-implementation"
    name: "Read and Analyze Current Implementation"
    type: "analysis"
    required: true
    depends_on: ["locate-existing-component"]
    workflow:
      actions:
        - "Read existing Twig template"
        - "Read existing LESS stylesheet"
        - "Document current variables and props"
        - "Document current CMS data mappings"
        - "Document current dummy data structure"
        - "Document current HTML structure and BEM classes"
      outputs:
        - current_variables: "List of template variables"
        - current_cms_fields: "List of CMS field mappings"
        - current_classes: "List of CSS classes used"
        - current_structure: "HTML structure overview"

  # Step 3: Capture Figma Design
  - id: "capture-figma-design"
    name: "Capture New Figma Design"
    type: "workflow"
    required: true
    depends_on: ["read-current-implementation"]
    workflow:
      actions:
        - "Extract node ID from Figma URL"
        - "Use mcp__figma-desktop__get_design_context to get design details"
        - "Use mcp__figma-desktop__get_screenshot to capture reference"
        - "Save screenshot to .frontend/figma-selections/{component_name}-figma-update-{date}.png"
      output_variables:
        - figma_design: "Design context from Figma"
        - reference_screenshot: "Path to saved screenshot"

  # Step 4: Analyze Changes
  - id: "analyze-changes"
    name: "Analyze Changes Between Current and New Design"
    type: "analysis"
    required: true
    depends_on: ["capture-figma-design"]
    workflow:
      actions:
        - "Compare current structure with Figma design"
        - "Identify structural changes (added/removed elements)"
        - "Identify style changes (colors, spacing, typography)"
        - "Identify responsive behavior changes"
        - "Document breaking changes"
        - "Create update plan"
      change_categories:
        structural:
          - "New HTML elements"
          - "Removed HTML elements"
          - "Changed element hierarchy"
        stylistic:
          - "Color changes"
          - "Spacing changes"
          - "Typography changes"
          - "Layout changes"
        responsive:
          - "Breakpoint behavior changes"
          - "Mobile layout changes"
        breaking:
          - "New required variables"
          - "Changed variable names"
          - "CMS structure changes"

  # Step 5: Update Twig Template
  - id: "update-twig-template"
    name: "Update Twig Template"
    type: "modification"
    required: true
    depends_on: ["analyze-changes"]
    workflow:
      actions:
        - "Preserve existing variable names where possible"
        - "Preserve dummy data block structure"
        - "Update HTML structure to match Figma"
        - "Add new variables with sensible defaults"
        - "Update component documentation comments"
        - "Add update timestamp comment"
      preservation_rules:
        - "Keep existing variable names"
        - "Keep CMS data mapping format"
        - "Keep dummy data block for show_dummy_data"
        - "Keep backward compatibility"
      critical_rules:
        - "NO asset() function - use /sites/default/{{ variable }}"
        - "Use .button class for buttons (no custom button CSS)"
        - "Use .headingStyle() mixin for headings"
        - "Use <div> for |raw content, NEVER <p>"

  # Step 6: Validate Twig Template
  - id: "validate-twig-template"
    name: "Validate Twig Template"
    type: "validation"
    required: true
    depends_on: ["update-twig-template"]
    validation:
      checks:
        - file: "{twig_path}"
          not_contains: ["asset("]
          error_message: "❌ CRITICAL: Twig template uses asset() function. Use direct paths."
          severity: "error"
        - pattern: "<p[^>]*>.*\\|raw.*</p>"
          file: "{twig_path}"
          error_message: "❌ CRITICAL: Detected <p> tag wrapping |raw content. Use <div>."
          severity: "error"
      on_failure:
        action: "stop"
        message: "❌ Twig template validation failed."

  # Step 7: Update LESS Stylesheet
  - id: "update-less-stylesheet"
    name: "Update LESS Stylesheet"
    type: "modification"
    required: true
    depends_on: ["update-twig-template"]
    workflow:
      actions:
        - "Preserve BEM class naming where possible"
        - "Map colors to design system variables"
        - "Use .headingStyle() mixin for typography"
        - "Update responsive breakpoints"
        - "Remove obsolete styles"
        - "Add new styles for new elements"
        - "Add update timestamp comment"
      design_system_mapping:
        colors:
          - "var(--primary_color)"
          - "var(--secondary_color)"
          - "var(--text_color)"
          - "var(--light_color)"
          - "var(--dark_color)"
        typography:
          - ".headingStyle(h1) through .headingStyle(h6)"
        spacing:
          - "var(--top_bottom_gutter)"
          - "@gutter_width"
          - "@gutter_width_mobile"
        breakpoints:
          - "@mobile"
          - "@flyout"
          - "@medium_width"

  # Step 8: Validate LESS Syntax
  - id: "validate-less-syntax"
    name: "Validate LESS Syntax"
    type: "validation"
    required: true
    depends_on: ["update-less-stylesheet"]
    validation:
      pre_build_checks:
        - pattern: "\\.extend\\("
          severity: "error"
          message: "Use &:extend(.class all) instead of .extend(.class)"
        - pattern: "calc\\([^~]"
          severity: "warning"
          message: "calc() should use escaped strings: ~\"calc(...)\""
      on_error:
        action: "stop"
        message: "❌ LESS syntax errors detected."

  # Step 9: Build and Test
  - id: "build-and-test"
    name: "Build and Test"
    type: "command"
    required: true
    depends_on: ["validate-less-syntax"]
    command:
      commands:
        - "npm run dev"
      working_directory: "."
      timeout: 120
    on_error:
      action: "stop"
      message: "❌ Build failed. Check for syntax errors."

  # Step 10: Playwright Visual Validation
  - id: "playwright-validation"
    name: "Playwright Visual Validation"
    type: "workflow"
    required: true
    depends_on: ["build-and-test"]
    workflow:
      description: "Test component at ALL breakpoints - MANDATORY"
      actions:
        - "Navigate to component preview URL"
        - "Test at mobile (375px)"
        - "Test at tablet (768px)"
        - "Test at desktop (1024px)"
        - "Test at wide (1440px)"
        - "Capture screenshots at each breakpoint"
        - "Check for console errors"
      validation_url: "http://localhost/component/preview/{component_type}/{component_name}.twig"
      breakpoints:
        - width: 375
          height: 800
          name: "mobile"
        - width: 768
          height: 1024
          name: "tablet"
        - width: 1024
          height: 768
          name: "desktop"
        - width: 1440
          height: 900
          name: "wide"
      on_failure:
        action: "fix_and_retry"
        message: "Fix LESS stylesheet, rebuild, and re-test ALL breakpoints"

  # Step 12: Quality Validation
  - id: "quality-validation"
    name: "Final Quality Validation"
    type: "validation"
    required: true
    depends_on: ["playwright-validation"]
    validation:
      quality_gates:
        - visual_accuracy: ">= 98%"
        - console_errors: "0"
        - responsive_breakpoints: "all_passing"
        - backward_compatible: "true"
        - design_system_compliance: ">= 85%"
      on_failure:
        action: "stop"
        message: "❌ Quality validation failed."

workflow_completion:
  all_steps_must_complete: true
  verify_mandatory_steps: true

  success_message: |
    🎉 **Component Update Complete!**

    ✅ **Modified Files:**
    - `{twig_path}`
    - `{less_path}`

    ✅ **Created Files:**
    - `.frontend/figma-selections/{component_name}-figma-update-{date}.png`

    ✅ **Validation Status:**
    - Build: ✓
    - Mobile (375px): ✓
    - Tablet (768px): ✓
    - Desktop (1024px): ✓
    - Wide (1440px): ✓
    - Console Errors: 0

    📄 **Preview:**
    - http://localhost/component/preview/{component_type}/{component_name}.twig

  failure_message: |
    ❌ **Component Update Failed**

    Please check error messages above.
    Common issues:
    - Component not found
    - Build errors
    - Responsive breakpoint failures
    - Design system variable mismatches

    After fixing issues, re-run: /mtc-update <figma-url> {component_name}
