#!/usr/bin/env python3 """ Figma Style Auditor - Design system analysis and consistency checking Analyzes files for brand compliance, accessibility, and design system health. """ import os import sys import json import math import time from typing import Dict, List, Optional, Union, Any, Tuple from dataclasses import dataclass, field from pathlib import Path import argparse import colorsys try: from figma_client import FigmaClient except ImportError: # Handle case where script is run directly import sys from pathlib import Path sys.path.append(str(Path(__file__).parent)) from figma_client import FigmaClient @dataclass class AuditConfig: """Configuration for design system audits""" check_accessibility: bool = True check_brand_compliance: bool = True check_consistency: bool = True generate_report: bool = True min_contrast_ratio: float = 4.5 # WCAG AA standard min_touch_target: float = 44 # iOS/Material Design standard brand_colors: List[str] = field(default_factory=list) brand_fonts: List[str] = field(default_factory=list) @dataclass class AuditIssue: """Represents a design issue found during audit""" severity: str # 'error', 'warning', 'info' category: str # 'accessibility', 'brand', 'consistency' message: str node_id: str = None node_name: str = None suggestions: List[str] = field(default_factory=list) details: Dict[str, Any] = field(default_factory=dict) class StyleAuditor: """Comprehensive design system auditor for Figma files""" def __init__(self, figma_client: FigmaClient, config: AuditConfig = None): self.client = figma_client self.config = config or AuditConfig() self.issues: List[AuditIssue] = [] def audit_file(self, file_key: str) -> Dict[str, Any]: """Perform comprehensive audit of a Figma file""" print(f"Starting audit of file: {file_key}") self.issues.clear() # Get file data file_data = self.client.get_file(file_key) # Run audit checks if self.config.check_accessibility: self._audit_accessibility(file_data) if self.config.check_brand_compliance: self._audit_brand_compliance(file_data) if self.config.check_consistency: self._audit_consistency(file_data) # Generate summary summary = self._generate_summary() print(f"Audit completed: {len(self.issues)} issues found") return { 'file_key': file_key, 'file_name': file_data.get('name', 'Unknown'), 'audit_timestamp': time.time(), 'summary': summary, 'issues': [self._issue_to_dict(issue) for issue in self.issues], 'recommendations': self._generate_recommendations() } def audit_multiple_files(self, file_keys: List[str]) -> Dict[str, Any]: """Audit multiple files and generate comparative analysis""" all_results = {} aggregated_issues = [] for file_key in file_keys: try: result = self.audit_file(file_key) all_results[file_key] = result aggregated_issues.extend(self.issues) print(f"✓ Audited {result['file_name']}: {len(result['issues'])} issues") except Exception as e: print(f"✗ Failed to audit {file_key}: {e}") all_results[file_key] = {'error': str(e)} # Generate cross-file analysis cross_file_analysis = self._analyze_cross_file_patterns(all_results) return { 'individual_audits': all_results, 'cross_file_analysis': cross_file_analysis, 'total_files': len(file_keys), 'successful_audits': len([r for r in all_results.values() if 'error' not in r]) } def _audit_accessibility(self, file_data: Dict[str, Any]): """Check accessibility compliance (WCAG guidelines)""" def audit_node_accessibility(node): node_type = node.get('type', '') node_name = node.get('name', '') node_id = node.get('id', '') # Check text contrast if node_type == 'TEXT': self._check_text_contrast(node) # Check touch targets if node_type in ['COMPONENT', 'INSTANCE', 'FRAME'] and 'button' in node_name.lower(): self._check_touch_target_size(node) # Check focus indicators if 'interactive' in node_name.lower() or 'button' in node_name.lower(): self._check_focus_indicators(node) # Recursively check children for child in node.get('children', []): audit_node_accessibility(child) if 'document' in file_data: audit_node_accessibility(file_data['document']) def _audit_brand_compliance(self, file_data: Dict[str, Any]): """Check compliance with brand guidelines""" if not self.config.brand_colors and not self.config.brand_fonts: return # Skip if no brand guidelines configured def audit_node_brand(node): # Check color compliance if 'fills' in node: self._check_brand_colors(node) # Check font compliance if node.get('type') == 'TEXT': self._check_brand_fonts(node) # Recursively check children for child in node.get('children', []): audit_node_brand(child) if 'document' in file_data: audit_node_brand(file_data['document']) def _audit_consistency(self, file_data: Dict[str, Any]): """Check internal consistency within the file""" # Collect all styles for analysis colors_used = [] fonts_used = [] spacing_used = [] def collect_styles(node): # Collect colors if 'fills' in node: for fill in node.get('fills', []): if fill.get('type') == 'SOLID': color = fill.get('color', {}) if color: colors_used.append({ 'color': color, 'node_id': node.get('id'), 'node_name': node.get('name', '') }) # Collect fonts if node.get('type') == 'TEXT': style = node.get('style', {}) if style: fonts_used.append({ 'font_family': style.get('fontFamily', ''), 'font_size': style.get('fontSize', 0), 'font_weight': style.get('fontWeight', 400), 'node_id': node.get('id'), 'node_name': node.get('name', '') }) # Collect spacing (approximation from layout) if 'children' in node and len(node['children']) > 1: # This would need more sophisticated analysis pass # Recursively collect from children for child in node.get('children', []): collect_styles(child) if 'document' in file_data: collect_styles(file_data['document']) # Analyze collected styles self._analyze_color_consistency(colors_used) self._analyze_typography_consistency(fonts_used) def _check_text_contrast(self, text_node: Dict[str, Any]): """Check if text has sufficient contrast against background""" # This is a simplified implementation # Real implementation would need to calculate actual contrast fills = text_node.get('fills', []) if not fills: return text_color = fills[0].get('color', {}) if not text_color: return # For now, assume white background (would need parent background detection) bg_color = {'r': 1, 'g': 1, 'b': 1} # White contrast_ratio = self._calculate_contrast_ratio(text_color, bg_color) if contrast_ratio < self.config.min_contrast_ratio: self.issues.append(AuditIssue( severity='error', category='accessibility', message=f'Insufficient color contrast: {contrast_ratio:.1f}:1 (minimum: {self.config.min_contrast_ratio}:1)', node_id=text_node.get('id'), node_name=text_node.get('name', ''), suggestions=[ 'Darken text color or lighten background', 'Use high contrast color combinations', 'Test with accessibility tools' ], details={'contrast_ratio': contrast_ratio, 'text_color': text_color} )) def _check_touch_target_size(self, node: Dict[str, Any]): """Check if interactive elements meet minimum touch target size""" bounds = node.get('absoluteBoundingBox', {}) if not bounds: return width = bounds.get('width', 0) height = bounds.get('height', 0) if width < self.config.min_touch_target or height < self.config.min_touch_target: self.issues.append(AuditIssue( severity='warning', category='accessibility', message=f'Touch target too small: {width}×{height}px (minimum: {self.config.min_touch_target}×{self.config.min_touch_target}px)', node_id=node.get('id'), node_name=node.get('name', ''), suggestions=[ f'Increase size to at least {self.config.min_touch_target}×{self.config.min_touch_target}px', 'Add padding around interactive elements', 'Consider user interaction patterns' ], details={'current_size': {'width': width, 'height': height}} )) def _check_focus_indicators(self, node: Dict[str, Any]): """Check if interactive elements have proper focus indicators""" # This would check for focus states, outlines, etc. # For now, just flag interactive elements that might need focus indicators effects = node.get('effects', []) has_focus_effect = any( effect.get('type') == 'DROP_SHADOW' and 'focus' in str(effect).lower() for effect in effects ) if not has_focus_effect: self.issues.append(AuditIssue( severity='info', category='accessibility', message='Interactive element may need focus indicator', node_id=node.get('id'), node_name=node.get('name', ''), suggestions=[ 'Add focus state with visible outline', 'Use consistent focus indicator style', 'Test keyboard navigation' ] )) def _check_brand_colors(self, node: Dict[str, Any]): """Check if colors match brand guidelines""" if not self.config.brand_colors: return fills = node.get('fills', []) for fill in fills: if fill.get('type') == 'SOLID': color = fill.get('color', {}) if color: hex_color = self._rgb_to_hex(color) if hex_color not in self.config.brand_colors: # Check if it's close to a brand color closest_brand_color = self._find_closest_brand_color(hex_color) self.issues.append(AuditIssue( severity='warning', category='brand', message=f'Non-brand color used: {hex_color}', node_id=node.get('id'), node_name=node.get('name', ''), suggestions=[ f'Consider using brand color: {closest_brand_color}', 'Check brand color palette', 'Use design system colors' ], details={'used_color': hex_color, 'suggested_color': closest_brand_color} )) def _check_brand_fonts(self, text_node: Dict[str, Any]): """Check if fonts match brand guidelines""" if not self.config.brand_fonts: return style = text_node.get('style', {}) font_family = style.get('fontFamily', '') if font_family and font_family not in self.config.brand_fonts: self.issues.append(AuditIssue( severity='warning', category='brand', message=f'Non-brand font used: {font_family}', node_id=text_node.get('id'), node_name=text_node.get('name', ''), suggestions=[ f'Use brand fonts: {", ".join(self.config.brand_fonts)}', 'Check typography guidelines', 'Maintain font consistency' ], details={'used_font': font_family, 'brand_fonts': self.config.brand_fonts} )) def _analyze_color_consistency(self, colors_used: List[Dict[str, Any]]): """Analyze color usage patterns for consistency issues""" # Group similar colors color_groups = {} for color_data in colors_used: color = color_data['color'] hex_color = self._rgb_to_hex(color) # Find similar colors (within tolerance) similar_group = None for group_color in color_groups.keys(): if self._colors_are_similar(hex_color, group_color): similar_group = group_color break if similar_group: color_groups[similar_group].append(color_data) else: color_groups[hex_color] = [color_data] # Flag groups with multiple similar but not identical colors for base_color, group in color_groups.items(): if len(group) > 1: unique_colors = set(self._rgb_to_hex(item['color']) for item in group) if len(unique_colors) > 1: self.issues.append(AuditIssue( severity='info', category='consistency', message=f'Multiple similar colors found: {", ".join(unique_colors)}', suggestions=[ 'Standardize similar colors', 'Use design system color tokens', 'Review color palette' ], details={'similar_colors': list(unique_colors), 'usage_count': len(group)} )) def _analyze_typography_consistency(self, fonts_used: List[Dict[str, Any]]): """Analyze typography usage for consistency""" # Group by font family and size font_combinations = {} for font_data in fonts_used: key = f"{font_data['font_family']}-{font_data['font_size']}pt-{font_data['font_weight']}" if key not in font_combinations: font_combinations[key] = [] font_combinations[key].append(font_data) # Look for too many font variations families = set(font['font_family'] for font in fonts_used) sizes = set(font['font_size'] for font in fonts_used) if len(families) > 3: self.issues.append(AuditIssue( severity='warning', category='consistency', message=f'Too many font families: {len(families)} ({", ".join(families)})', suggestions=[ 'Reduce to 2-3 font families maximum', 'Establish typography hierarchy', 'Use consistent font pairing' ] )) if len(sizes) > 8: self.issues.append(AuditIssue( severity='info', category='consistency', message=f'Many font sizes used: {len(sizes)} different sizes', suggestions=[ 'Create modular typography scale', 'Reduce to 6-8 standard sizes', 'Use consistent size progression' ] )) def _calculate_contrast_ratio(self, color1: Dict[str, float], color2: Dict[str, float]) -> float: """Calculate WCAG contrast ratio between two colors""" def get_luminance(color): """Calculate relative luminance""" def linearize(val): if val <= 0.03928: return val / 12.92 else: return pow((val + 0.055) / 1.055, 2.4) r = linearize(color.get('r', 0)) g = linearize(color.get('g', 0)) b = linearize(color.get('b', 0)) return 0.2126 * r + 0.7152 * g + 0.0722 * b lum1 = get_luminance(color1) lum2 = get_luminance(color2) lighter = max(lum1, lum2) darker = min(lum1, lum2) return (lighter + 0.05) / (darker + 0.05) def _rgb_to_hex(self, color: Dict[str, float]) -> str: """Convert RGB color to hex string""" r = int(color.get('r', 0) * 255) g = int(color.get('g', 0) * 255) b = int(color.get('b', 0) * 255) return f"#{r:02x}{g:02x}{b:02x}" def _colors_are_similar(self, color1: str, color2: str, tolerance: int = 30) -> bool: """Check if two hex colors are similar within tolerance""" def hex_to_rgb(hex_color): hex_color = hex_color.lstrip('#') return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4)) rgb1 = hex_to_rgb(color1) rgb2 = hex_to_rgb(color2) distance = math.sqrt(sum((a - b) ** 2 for a, b in zip(rgb1, rgb2))) return distance < tolerance def _find_closest_brand_color(self, hex_color: str) -> str: """Find the closest brand color to the given color""" if not self.config.brand_colors: return hex_color min_distance = float('inf') closest_color = self.config.brand_colors[0] for brand_color in self.config.brand_colors: if self._colors_are_similar(hex_color, brand_color, tolerance=255): # Use max tolerance for distance calc distance = self._color_distance(hex_color, brand_color) if distance < min_distance: min_distance = distance closest_color = brand_color return closest_color def _color_distance(self, color1: str, color2: str) -> float: """Calculate Euclidean distance between two colors""" def hex_to_rgb(hex_color): hex_color = hex_color.lstrip('#') return tuple(int(hex_color[i:i+2], 16) for i in (0, 2, 4)) rgb1 = hex_to_rgb(color1) rgb2 = hex_to_rgb(color2) return math.sqrt(sum((a - b) ** 2 for a, b in zip(rgb1, rgb2))) def _generate_summary(self) -> Dict[str, Any]: """Generate audit summary statistics""" summary = { 'total_issues': len(self.issues), 'by_severity': { 'error': len([i for i in self.issues if i.severity == 'error']), 'warning': len([i for i in self.issues if i.severity == 'warning']), 'info': len([i for i in self.issues if i.severity == 'info']) }, 'by_category': { 'accessibility': len([i for i in self.issues if i.category == 'accessibility']), 'brand': len([i for i in self.issues if i.category == 'brand']), 'consistency': len([i for i in self.issues if i.category == 'consistency']) } } # Calculate overall score (0-100) max_score = 100 error_penalty = 10 warning_penalty = 3 info_penalty = 1 penalty = (summary['by_severity']['error'] * error_penalty + summary['by_severity']['warning'] * warning_penalty + summary['by_severity']['info'] * info_penalty) summary['score'] = max(0, max_score - penalty) summary['grade'] = self._score_to_grade(summary['score']) return summary def _score_to_grade(self, score: int) -> str: """Convert numeric score to letter grade""" if score >= 90: return 'A' elif score >= 80: return 'B' elif score >= 70: return 'C' elif score >= 60: return 'D' else: return 'F' def _generate_recommendations(self) -> List[str]: """Generate overall recommendations based on audit results""" recommendations = [] error_count = len([i for i in self.issues if i.severity == 'error']) warning_count = len([i for i in self.issues if i.severity == 'warning']) if error_count > 0: recommendations.append(f"Fix {error_count} critical accessibility issues immediately") if warning_count > 5: recommendations.append("Review and address design consistency issues") brand_issues = len([i for i in self.issues if i.category == 'brand']) if brand_issues > 0: recommendations.append("Establish and enforce brand guidelines") consistency_issues = len([i for i in self.issues if i.category == 'consistency']) if consistency_issues > 3: recommendations.append("Create and apply design system standards") if not recommendations: recommendations.append("Great work! Consider periodic design system reviews") return recommendations def _analyze_cross_file_patterns(self, all_results: Dict[str, Any]) -> Dict[str, Any]: """Analyze patterns across multiple files""" # This would analyze common issues across files # For now, return basic aggregation total_issues = 0 common_issues = {} for file_key, result in all_results.items(): if 'error' not in result: total_issues += result['summary']['total_issues'] for issue in result['issues']: issue_type = f"{issue['category']}:{issue['message'].split(':')[0]}" common_issues[issue_type] = common_issues.get(issue_type, 0) + 1 # Find most common issues most_common = sorted(common_issues.items(), key=lambda x: x[1], reverse=True)[:5] return { 'total_issues_across_files': total_issues, 'most_common_issues': most_common, 'files_with_errors': len([r for r in all_results.values() if 'error' not in r and r['summary']['by_severity']['error'] > 0]) } def _issue_to_dict(self, issue: AuditIssue) -> Dict[str, Any]: """Convert AuditIssue to dictionary for JSON serialization""" return { 'severity': issue.severity, 'category': issue.category, 'message': issue.message, 'node_id': issue.node_id, 'node_name': issue.node_name, 'suggestions': issue.suggestions, 'details': issue.details } def generate_report(self, audit_results: Dict[str, Any], output_path: str = None) -> str: """Generate comprehensive audit report""" if not output_path: output_path = 'figma-audit-report.html' html_report = self._create_html_report(audit_results) with open(output_path, 'w') as f: f.write(html_report) print(f"Audit report generated: {output_path}") return output_path def _create_html_report(self, audit_results: Dict[str, Any]) -> str: """Create HTML audit report""" # This would generate a comprehensive HTML report # For now, return basic HTML structure html = f""" Figma Design Audit Report

Figma Design Audit Report

File: {audit_results.get('file_name', 'Unknown')}

Audit Date: {time.strftime('%Y-%m-%d %H:%M:%S')}

Summary

{audit_results['summary']['grade']}
Score: {audit_results['summary']['score']}/100

Total Issues: {audit_results['summary']['total_issues']}

Errors: {audit_results['summary']['by_severity']['error']}

Warnings: {audit_results['summary']['by_severity']['warning']}

Info: {audit_results['summary']['by_severity']['info']}

Issues Found

""" for issue in audit_results['issues']: severity_class = issue['severity'] html += f"""

{issue['category'].title()}: {issue['message']}

Node: {issue.get('node_name', 'N/A')} ({issue.get('node_id', 'N/A')})

Suggestions:

\n" html += """

Recommendations

""" return html def main(): """CLI interface for style auditing""" parser = argparse.ArgumentParser(description='Figma Style Auditor') parser.add_argument('command', choices=['audit-file', 'audit-multiple', 'audit-brand']) parser.add_argument('file_keys', help='File key(s) or path to file list') parser.add_argument('--output', help='Output file for audit report') parser.add_argument('--brand-colors', help='Comma-separated list of brand hex colors') parser.add_argument('--brand-fonts', help='Comma-separated list of brand fonts') parser.add_argument('--min-contrast', type=float, default=4.5, help='Minimum contrast ratio') parser.add_argument('--generate-html', action='store_true', help='Generate HTML report') args = parser.parse_args() try: client = FigmaClient() # Configure auditor config = AuditConfig( min_contrast_ratio=args.min_contrast, brand_colors=args.brand_colors.split(',') if args.brand_colors else [], brand_fonts=args.brand_fonts.split(',') if args.brand_fonts else [], generate_report=args.generate_html ) auditor = StyleAuditor(client, config) if args.command == 'audit-file': file_key = client.parse_file_url(args.file_keys) result = auditor.audit_file(file_key) elif args.command == 'audit-multiple': # Parse file keys (could be comma-separated or from file) if os.path.isfile(args.file_keys): with open(args.file_keys) as f: file_keys = [line.strip() for line in f if line.strip()] else: file_keys = args.file_keys.split(',') file_keys = [client.parse_file_url(key) for key in file_keys] result = auditor.audit_multiple_files(file_keys) # Output results output_content = json.dumps(result, indent=2) if args.output: with open(args.output, 'w') as f: f.write(output_content) print(f"Audit results saved to {args.output}") else: print(output_content) # Generate HTML report if requested if args.generate_html and args.command == 'audit-file': html_path = args.output.replace('.json', '.html') if args.output else 'audit-report.html' auditor.generate_report(result, html_path) except Exception as e: print(f"Error: {e}", file=sys.stderr) sys.exit(1) if __name__ == '__main__': main()