1#!/usr/bin/env python3
2"""
3HTML Design Token Validator
4Ensures all HTML assets (slides, infographics, etc.) use design tokens.
5Source of truth: assets/design-tokens.css
6 
7Usage:
8  python html-token-validator.py                    # Validate all HTML assets
9  python html-token-validator.py --type slides      # Validate only slides
10  python html-token-validator.py --type infographics # Validate only infographics
11  python html-token-validator.py path/to/file.html  # Validate specific file
12  python html-token-validator.py --fix              # Auto-fix issues (WIP)
13"""
14 
15import re
16import json
17import sys
18from pathlib import Path
19from typing import Dict, List, Tuple, Optional
20 
21# Project root relative to this script
22PROJECT_ROOT = Path(__file__).parent.parent.parent.parent.parent
23TOKENS_JSON_PATH = PROJECT_ROOT / 'assets' / 'design-tokens.json'
24TOKENS_CSS_PATH = PROJECT_ROOT / 'assets' / 'design-tokens.css'
25 
26# Asset directories to validate
27ASSET_DIRS = {
28    'slides': PROJECT_ROOT / 'assets' / 'designs' / 'slides',
29    'infographics': PROJECT_ROOT / 'assets' / 'infographics',
30}
31 
32# Patterns that indicate hardcoded values (should use tokens)
33FORBIDDEN_PATTERNS = [
34    (r'#[0-9A-Fa-f]{3,8}\b', 'hex color'),
35    (r'rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)', 'rgb color'),
36    (r'rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[\d.]+\s*\)', 'rgba color'),
37    (r'hsl\([^)]+\)', 'hsl color'),
38    (r"font-family:\s*'[^v][^a][^r][^']*',", 'hardcoded font'),  # Exclude var()
39    (r'font-family:\s*"[^v][^a][^r][^"]*",', 'hardcoded font'),
40]
41 
42# Allowed rgba patterns (brand colors with transparency - CSS limitation)
43# These are derived from brand tokens but need rgba for transparency
44ALLOWED_RGBA_PATTERNS = [
45    r'rgba\(\s*59\s*,\s*130\s*,\s*246',    # --color-primary (#3B82F6)
46    r'rgba\(\s*245\s*,\s*158\s*,\s*11',    # --color-secondary (#F59E0B)
47    r'rgba\(\s*16\s*,\s*185\s*,\s*129',    # --color-accent (#10B981)
48    r'rgba\(\s*20\s*,\s*184\s*,\s*166',    # --color-accent alt (#14B8A6)
49    r'rgba\(\s*0\s*,\s*0\s*,\s*0',         # black transparency (common)
50    r'rgba\(\s*255\s*,\s*255\s*,\s*255',   # white transparency (common)
51    r'rgba\(\s*15\s*,\s*23\s*,\s*42',      # --color-surface (#0F172A)
52    r'rgba\(\s*7\s*,\s*11\s*,\s*20',       # --color-background (#070B14)
53]
54 
55# Allowed exceptions (external images, etc.)
56ALLOWED_EXCEPTIONS = [
57    'pexels.com', 'unsplash.com', 'youtube.com', 'ytimg.com',
58    'googlefonts', 'fonts.googleapis.com', 'fonts.gstatic.com',
59]
60 
61 
62class ValidationResult:
63    """Validation result for a single file."""
64    def __init__(self, file_path: Path):
65        self.file_path = file_path
66        self.errors: List[str] = []
67        self.warnings: List[str] = []
68        self.passed = True
69 
70    def add_error(self, msg: str):
71        self.errors.append(msg)
72        self.passed = False
73 
74    def add_warning(self, msg: str):
75        self.warnings.append(msg)
76 
77 
78def load_css_variables() -> Dict[str, str]:
79    """Load CSS variables from design-tokens.css."""
80    variables = {}
81    if TOKENS_CSS_PATH.exists():
82        content = TOKENS_CSS_PATH.read_text()
83        # Extract --var-name: value patterns
84        for match in re.finditer(r'(--[\w-]+):\s*([^;]+);', content):
85            variables[match.group(1)] = match.group(2).strip()
86    return variables
87 
88 
89def is_inside_block(content: str, match_pos: int, open_tag: str, close_tag: str) -> bool:
90    """Check if position is inside a specific HTML block."""
91    pre = content[:match_pos]
92    tag_open = pre.rfind(open_tag)
93    tag_close = pre.rfind(close_tag)
94    return tag_open > tag_close
95 
96 
97def is_allowed_exception(context: str) -> bool:
98    """Check if the hardcoded value is in an allowed exception context."""
99    context_lower = context.lower()
100    return any(exc in context_lower for exc in ALLOWED_EXCEPTIONS)
101 
102 
103def is_allowed_rgba(match_text: str) -> bool:
104    """Check if rgba pattern uses brand colors (allowed for transparency)."""
105    return any(re.match(pattern, match_text) for pattern in ALLOWED_RGBA_PATTERNS)
106 
107 
108def get_context(content: str, pos: int, chars: int = 100) -> str:
109    """Get surrounding context for a match position."""
110    start = max(0, pos - chars)
111    end = min(len(content), pos + chars)
112    return content[start:end]
113 
114 
115def validate_html(content: str, file_path: Path, verbose: bool = False) -> ValidationResult:
116    """
117    Validate HTML content for design token compliance.
118 
119    Checks:
120    1. design-tokens.css import present
121    2. No hardcoded colors in CSS (except in <script> for Chart.js)
122    3. No hardcoded fonts
123    4. Uses var(--token-name) pattern
124    """
125    result = ValidationResult(file_path)
126 
127    # 1. Check for design-tokens.css import
128    if 'design-tokens.css' not in content:
129        result.add_error("Missing design-tokens.css import")
130 
131    # 2. Check for forbidden patterns in CSS
132    for pattern, description in FORBIDDEN_PATTERNS:
133        for match in re.finditer(pattern, content):
134            match_text = match.group()
135            match_pos = match.start()
136            context = get_context(content, match_pos)
137 
138            # Skip if in <script> block (Chart.js allowed)
139            if is_inside_block(content, match_pos, '<script', '</script>'):
140                if verbose:
141                    result.add_warning(f"Allowed in <script>: {match_text}")
142                continue
143 
144            # Skip if in allowed exception context (external URLs)
145            if is_allowed_exception(context):
146                if verbose:
147                    result.add_warning(f"Allowed external: {match_text}")
148                continue
149 
150            # Skip rgba using brand colors (needed for transparency effects)
151            if description == 'rgba color' and is_allowed_rgba(match_text):
152                if verbose:
153                    result.add_warning(f"Allowed brand rgba: {match_text}")
154                continue
155 
156            # Skip if part of var() reference (false positive)
157            if 'var(' in context and match_text in context:
158                # Check if it's a fallback value in var()
159                var_pattern = rf'var\([^)]*{re.escape(match_text)}[^)]*\)'
160                if re.search(var_pattern, context):
161                    continue
162 
163            # Error if in <style> or inline style
164            if is_inside_block(content, match_pos, '<style', '</style>'):
165                result.add_error(f"Hardcoded {description} in <style>: {match_text}")
166            elif 'style="' in context:
167                result.add_error(f"Hardcoded {description} in inline style: {match_text}")
168 
169    # 3. Check for required var() usage indicators
170    token_patterns = [
171        r'var\(--color-',
172        r'var\(--primitive-',
173        r'var\(--typography-',
174        r'var\(--card-',
175        r'var\(--button-',
176    ]
177    token_count = sum(len(re.findall(p, content)) for p in token_patterns)
178 
179    if token_count < 5:
180        result.add_warning(f"Low token usage ({token_count} var() references). Consider using more design tokens.")
181 
182    return result
183 
184 
185def validate_file(file_path: Path, verbose: bool = False) -> ValidationResult:
186    """Validate a single HTML file."""
187    if not file_path.exists():
188        result = ValidationResult(file_path)
189        result.add_error("File not found")
190        return result
191 
192    content = file_path.read_text()
193    return validate_html(content, file_path, verbose)
194 
195 
196def validate_directory(dir_path: Path, verbose: bool = False) -> List[ValidationResult]:
197    """Validate all HTML files in a directory."""
198    results = []
199    if dir_path.exists():
200        for html_file in sorted(dir_path.glob('*.html')):
201            results.append(validate_file(html_file, verbose))
202    return results
203 
204 
205def print_result(result: ValidationResult, verbose: bool = False):
206    """Print validation result for a file."""
207    status = "✓" if result.passed else "✗"
208    print(f"  {status} {result.file_path.name}")
209 
210    if result.errors:
211        for error in result.errors[:5]:  # Limit output
212            print(f"      ├─ {error}")
213        if len(result.errors) > 5:
214            print(f"      └─ ... and {len(result.errors) - 5} more errors")
215 
216    if verbose and result.warnings:
217        for warning in result.warnings[:3]:
218            print(f"      [warn] {warning}")
219 
220 
221def print_summary(all_results: Dict[str, List[ValidationResult]]):
222    """Print summary of all validation results."""
223    total_files = 0
224    total_passed = 0
225    total_errors = 0
226 
227    print("\n" + "=" * 60)
228    print("HTML DESIGN TOKEN VALIDATION SUMMARY")
229    print("=" * 60)
230 
231    for asset_type, results in all_results.items():
232        if not results:
233            continue
234 
235        passed = sum(1 for r in results if r.passed)
236        failed = len(results) - passed
237        errors = sum(len(r.errors) for r in results)
238 
239        total_files += len(results)
240        total_passed += passed
241        total_errors += errors
242 
243        status = "✓" if failed == 0 else "✗"
244        print(f"\n{status} {asset_type.upper()}: {passed}/{len(results)} passed")
245 
246        for result in results:
247            if not result.passed:
248                print_result(result)
249 
250    print("\n" + "-" * 60)
251    if total_errors == 0:
252        print(f"✓ ALL PASSED: {total_passed}/{total_files} files valid")
253    else:
254        print(f"✗ FAILED: {total_files - total_passed}/{total_files} files have issues ({total_errors} total errors)")
255    print("-" * 60)
256 
257    return total_errors == 0
258 
259 
260def main():
261    """CLI entry point."""
262    import argparse
263 
264    parser = argparse.ArgumentParser(
265        description='Validate HTML assets for design token compliance',
266        formatter_class=argparse.RawDescriptionHelpFormatter,
267        epilog="""
268Examples:
269  %(prog)s                           # Validate all HTML assets
270  %(prog)s --type slides             # Validate only slides
271  %(prog)s --type infographics       # Validate only infographics
272  %(prog)s path/to/file.html         # Validate specific file
273  %(prog)s --colors                  # Show brand colors from tokens
274"""
275    )
276    parser.add_argument('files', nargs='*', help='Specific HTML files to validate')
277    parser.add_argument('-t', '--type', choices=['slides', 'infographics', 'all'],
278                        default='all', help='Asset type to validate')
279    parser.add_argument('-v', '--verbose', action='store_true', help='Show warnings')
280    parser.add_argument('--colors', action='store_true', help='Print CSS variables from tokens')
281    parser.add_argument('--fix', action='store_true', help='Auto-fix issues (experimental)')
282 
283    args = parser.parse_args()
284 
285    # Show colors mode
286    if args.colors:
287        variables = load_css_variables()
288        print("\nDesign Tokens (from design-tokens.css):")
289        print("-" * 40)
290        for name, value in sorted(variables.items())[:30]:
291            print(f"  {name}: {value}")
292        if len(variables) > 30:
293            print(f"  ... and {len(variables) - 30} more")
294        return
295 
296    all_results: Dict[str, List[ValidationResult]] = {}
297 
298    # Validate specific files
299    if args.files:
300        results = []
301        for file_path in args.files:
302            path = Path(file_path)
303            if path.exists():
304                results.append(validate_file(path, args.verbose))
305            else:
306                result = ValidationResult(path)
307                result.add_error("File not found")
308                results.append(result)
309        all_results['specified'] = results
310    else:
311        # Validate by type
312        types_to_check = ASSET_DIRS.keys() if args.type == 'all' else [args.type]
313 
314        for asset_type in types_to_check:
315            if asset_type in ASSET_DIRS:
316                results = validate_directory(ASSET_DIRS[asset_type], args.verbose)
317                all_results[asset_type] = results
318 
319    # Print results
320    success = print_summary(all_results)
321 
322    if not success:
323        sys.exit(1)
324 
325 
326if __name__ == '__main__':
327    main()
328