figma
Monitoring and alerting system for Figma prop changes and Code Connect rendering errors
Summary
Code Connect currently lacks monitoring capabilities to detect when Figma component prop changes break Code Connect rendering, leading to silent failures that only surface when developers manually check Dev Mode. This creates a poor developer experience and can result in incorrect code examples being shown to design system consumers.
Problem Description
Current Pain Points:
- Silent failures: CLI validation passes but Figma shows "Failed to load Code Connect example"
- No proactive detection: Prop changes in Figma (additions, removals, renames) can break Code Connect without any notification
- Manual discovery only: Developers must manually check each component in Figma Dev Mode to verify connections are working
- No feedback loop: When connections break in Figma, there's no way for developers to be automatically informed
Real-world scenario:
A designer adds a new prop to a Figma component or renames an existing one. The Code Connect file now has a mismatch, causing "Failed to load Code Connect example" in Dev Mode. Developers and other designers continue using the broken connection, potentially getting incorrect or outdated code examples, until someone manually discovers the issue.
Requested Features
1. Webhook system for Figma prop changes
- Ability to subscribe to component property changes (additions, deletions, renames, type changes)
- Webhook notifications when connected components are modified
- Include before/after prop schemas in webhook payload
2. Health check endpoint/command
- API endpoint or CLI command to verify all published Code Connect files are rendering correctly in Figma
- Return status of each connection (working/broken) with specific error details
- Could be implemented as
npx figma connect validate --health-check
3. Alerting mechanism for rendering failures
- Integration options for notifications (Slack, email, webhook) when "Failed to load Code Connect example" occurs
- Configurable alerting thresholds and schedules
- Batch reporting of multiple failures
4. Enhanced error reporting from Figma side
- Detailed error logs accessible via API when Code Connect rendering fails
- Specific error types (missing props, type mismatches, template errors)
- Error context including which props are causing issues
Current Workarounds and Limitations
Based on community research, current approaches include:
- Manual checking in Figma Dev Mode after each publish
- Regular republishing schedules hoping to catch issues
- Defensive prop mapping with fallbacks
- CI/CD validation (but this only catches syntax errors, not Figma rendering issues)
These workarounds are insufficient for production design systems where reliability is critical.
Related Issues
This request relates to existing issues where CLI validation passes but Figma rendering fails:
- #93 - Components pass validation but show errors in Figma UI
- #97 - Props with dashes cause "Failed to load Code Connect example"
- #155 - Boolean props display inconsistencies
- #40 - Conditional prop mapping failures
Use Cases
- Design system maintenance: Automatically detect when component updates break Code Connect
- CI/CD integration: Fail builds when Code Connect health checks fail
- Team notifications: Alert relevant teams when connections break
- Debugging: Get detailed error information to quickly fix broken connections
- Compliance: Ensure all published components have working Code Connect examples
Benefits
- Improved reliability: Proactive detection prevents broken examples from being consumed
- Better developer experience: Automatic alerts reduce manual monitoring overhead
- Faster resolution: Detailed error reporting enables quicker fixes
- Design system quality: Ensures code examples stay synchronized with design changes
Additional Context
For HTML-based Code Connect implementations specifically, this monitoring becomes even more critical since template rendering can fail silently with complex prop mappings and conditional logic.
Environment:
- Code Connect version: v1.3.2
- Framework: HTML
- Use case: Design system monitoring and maintenance
Hi @george-apazidis, great proposal! You can add my issue to the list #325. Lack of template execution error details is a huge pain and makes debugging templates extremely hard.
