AI Workflows

Core Workflows

Matrix UI's MCP server provides four main workflow categories that can be combined for complex AI-driven development tasks.

Complete Workflow Examples

1. Feature Development Workflow

Building a user profile feature from scratch:

// Step 1: Discovery - Find relevant components
const searchResults = await matrix_search_components({
  query: "user profile display with avatar and contact info",
  filters: {
    category: "layout",
    hasAccessibility: true
  }
})

// Step 2: Get detailed specifications
const cardDetails = await matrix_get_component({
  name: "Card",
  includeExamples: true,
  includeProps: true
})

const avatarDetails = await matrix_get_component({
  name: "Avatar",
  includeExamples: true
})

// Step 3: Generate implementation
const profileCard = await matrix_generate_component({
  component: "Card",
  config: {
    variant: "default",
    className: "w-full max-w-sm",
    children: "ProfileContent"
  },
  language: "tsx"
})

// Step 4: Compose complex layout
const completeProfile = await matrix_compose_layout({
  layout: "flex",
  components: [
    {
      component: "Avatar",
      config: { size: "lg", src: "user.avatar" },
      position: "start"
    },
    {
      component: "Card",
      config: { className: "flex-1" },
      position: "center"
    }
  ],
  responsive: true
})

// Step 5: Validation
const validation = await matrix_validate_usage({
  component: "Card",
  props: { className: "w-full max-w-sm" },
  children: profileContent,
  context: "user-profile"
})

// Step 6: Accessibility check
const a11yResults = await matrix_check_accessibility({
  code: completeProfile.data.code,
  level: "AA",
  checks: ["aria-labels", "keyboard-nav", "color-contrast"]
})

2. Theme Customization Workflow

Creating and applying a custom brand theme:

// Step 1: Generate custom theme from brand colors
const brandTheme = await matrix_generate_theme({
  name: "corporate",
  colors: {
    primary: "#003366",    // Corporate blue
    secondary: "#66ccff",  // Light blue
    accent: "#ff6600"      // Orange accent
  },
  mode: "both",
  radius: "0.25rem"
})

// Step 2: Preview theme with key components
const themePreview = await matrix_preview_theme({
  theme: brandTheme.data.theme,
  components: ["Button", "Card", "Dialog", "Alert"],
  format: "html"
})

// Step 3: Get specific design tokens
const colorTokens = await matrix_get_design_tokens({
  theme: "corporate",
  category: "colors"
})

const typographyTokens = await matrix_get_design_tokens({
  theme: "corporate", 
  category: "typography"
})

// Step 4: Generate themed components
const themedButton = await matrix_generate_component({
  component: "Button",
  config: {
    variant: "default", // Uses theme primary color
    size: "lg"
  },
  theme: "corporate"
})

// Step 5: Validate theme compliance
const themeCompliance = await matrix_check_theme_compliance({
  code: themedButton.data.code,
  theme: "corporate",
  strict: true
})

3. Accessibility-First Workflow

Building components with accessibility as the primary concern:

// Step 1: Find accessibility-compliant components
const accessibleComponents = await matrix_find_by_capability({
  capability: "interactive",
  value: true,
  category: "forms"
})

// Filter for AAA compliance
const aaaComponents = accessibleComponents.data.components.filter(
  c => c.accessibility?.wcagLevel === "AAA"
)

// Step 2: Get accessibility specifications
const formDetails = await matrix_get_component({
  name: "Form",
  includeExamples: true,
  includeAccessibility: true
})

// Step 3: Generate accessible form
const accessibleForm = await matrix_generate_component({
  component: "Form",
  config: {
    fields: [
      {
        type: "input",
        label: "Full Name",
        required: true,
        ariaLabel: "Enter your full name",
        ariaDescribedBy: "name-help"
      },
      {
        type: "email", 
        label: "Email Address",
        required: true,
        ariaLabel: "Enter your email address",
        validation: "email"
      }
    ],
    submitLabel: "Create Account",
    resetLabel: "Clear Form"
  }
})

// Step 4: Comprehensive accessibility validation
const a11yValidation = await matrix_check_accessibility({
  code: accessibleForm.data.code,
  level: "AAA",
  checks: [
    "aria-labels",
    "keyboard-nav", 
    "focus-visible",
    "color-contrast",
    "semantic-html"
  ]
})

// Step 5: Get improvement suggestions focused on accessibility
const a11yImprovements = await matrix_suggest_improvements({
  code: accessibleForm.data.code,
  focus: ["accessibility", "ux"]
})

// Step 6: Validate final implementation
const finalValidation = await matrix_validate_usage({
  component: "Form",
  props: accessibleForm.data.props,
  children: accessibleForm.data.children,
  context: "registration"
})

Workflow Patterns

Sequential Pattern

Execute tools in a specific order for predictable results:

// Always follow this order for component development:
1. Discovery (search/list) → Find components
2. Specification (get_component) → Understand details  
3. Implementation (generate) → Create code
4. Validation (validate_usage) → Check correctness
5. Quality (accessibility/theme) → Ensure standards
6. Improvement (suggest) → Optimize result

Parallel Pattern

Execute independent tools simultaneously for efficiency:

// These can run in parallel:
const [componentDetails, examples, props] = await Promise.all([
  matrix_get_component({ name: "Button" }),
  matrix_get_examples({ component: "Button", type: "advanced" }),  
  matrix_get_props({ component: "Button" })
])

// Validation can also run in parallel:
const [usageValidation, a11yCheck, themeCheck] = await Promise.all([
  matrix_validate_usage({ component: "Button", props: buttonProps }),
  matrix_check_accessibility({ code: buttonCode, level: "AA" }),
  matrix_check_theme_compliance({ code: buttonCode })
])

Iterative Pattern

Refine results through multiple iterations:

// Iterative improvement workflow:
let currentCode = await matrix_generate_component({ component: "Form", config: initialConfig })

for (let iteration = 0; iteration < 3; iteration++) {
  // Validate current iteration
  const validation = await matrix_validate_usage({
    component: "Form",
    props: currentCode.data.props
  })
  
  if (validation.data.valid && validation.data.errors.length === 0) {
    break // Perfect result achieved
  }
  
  // Get improvement suggestions
  const improvements = await matrix_suggest_improvements({
    code: currentCode.data.code,
    focus: ["best-practices", "performance"]
  })
  
  // Apply improvements and regenerate
  const improvedConfig = applyImprovements(initialConfig, improvements.data.suggestions)
  currentCode = await matrix_generate_component({ 
    component: "Form", 
    config: improvedConfig 
  })
}

Error Handling in Workflows

Graceful Degradation

async function safeComponentGeneration(componentName, config) {
  try {
    // Try preferred approach
    const result = await matrix_generate_component({
      component: componentName,
      config: config
    })
    
    return result
  } catch (error) {
    if (error.code === 'COMPONENT_NOT_FOUND') {
      // Fallback: search for similar components
      const alternatives = await matrix_search_components({
        query: componentName,
        filters: { category: config.category }
      })
      
      if (alternatives.data.components.length > 0) {
        // Try with closest match
        return await matrix_generate_component({
          component: alternatives.data.components[0].name,
          config: config
        })
      }
    }
    
    // Final fallback: basic component
    return await matrix_generate_component({
      component: 'div',
      config: { className: 'fallback-component', ...config }
    })
  }
}

Validation Recovery

async function validateWithRecovery(component, props, children) {
  const validation = await matrix_validate_usage({
    component,
    props,
    children
  })
  
  if (!validation.data.valid) {
    // Try to fix common issues automatically
    const fixes = validation.data.errors.map(error => {
      switch (error.type) {
        case 'missing-required-prop':
          return { prop: error.field, value: getDefaultValue(error.field) }
        case 'invalid-prop-type':
          return { prop: error.field, value: convertType(props[error.field]) }
        default:
          return null
      }
    }).filter(Boolean)
    
    // Apply fixes and re-validate
    const fixedProps = { ...props, ...Object.fromEntries(fixes.map(f => [f.prop, f.value])) }
    return await matrix_validate_usage({
      component,
      props: fixedProps,
      children
    })
  }
  
  return validation
}

Performance Optimization

Caching Strategies

• Cache component specifications locally
• Reuse theme and design token queries
• Store validation results for identical configurations
• Implement request deduplication for parallel calls

Batch Processing

// Process multiple components efficiently
async function batchComponentGeneration(components) {
  // Group by component type for efficient processing
  const grouped = components.reduce((acc, comp) => {
    acc[comp.component] = acc[comp.component] || []
    acc[comp.component].push(comp.config)
    return acc
  }, {})
  
  // Process each group in parallel
  const results = await Promise.all(
    Object.entries(grouped).map(([component, configs]) =>
      Promise.all(configs.map(config => 
        matrix_generate_component({ component, config })
      ))
    )
  )
  
  return results.flat()
}

Next Steps