Skip to content

oberconcejo/VS-CODE / .agents/skills/design-system

design-system

Verified

Token architecture, component specifications, and slide generation. Three-layer tokens (primitive→semantic→component), CSS variables, spacing/typography scales, component specs, strategic slide creation. Use for design tokens, systematic design, brand-compliant presentations.

scripts/html-token-validator.py

View on GitHub
#!/usr/bin/env python3
"""
HTML Design Token Validator
Ensures all HTML assets (slides, infographics, etc.) use design tokens.
Source of truth: assets/design-tokens.css

Usage:
  python html-token-validator.py                    # Validate all HTML assets
  python html-token-validator.py --type slides      # Validate only slides
  python html-token-validator.py --type infographics # Validate only infographics
  python html-token-validator.py path/to/file.html  # Validate specific file
  python html-token-validator.py --fix              # Auto-fix issues (WIP)
"""

import re
import json
import sys
import os
from pathlib import Path
from typing import Dict, List, Tuple, Optional

# The skill can be installed outside the project it operates on (user-level
# ~/.claude/skills/, or as a plugin), so the project root cannot be derived from
# this file's location. Resolve it from the working directory instead -- the same
# convention generate-tokens.cjs and validate-tokens.cjs already use via
# process.cwd(). DESIGN_SYSTEM_PROJECT_ROOT overrides it explicitly.
def _find_project_root():
    override = os.environ.get('DESIGN_SYSTEM_PROJECT_ROOT')
    if override:
        return Path(override).resolve()
    start = Path.cwd().resolve()
    markers = (
        Path('assets') / 'design-tokens.json',
        Path('assets') / 'design-tokens.css',
        Path('package.json'),
        Path('.git'),
    )
    for candidate in (start, *start.parents):
        if any((candidate / marker).exists() for marker in markers):
            return candidate
    return start


PROJECT_ROOT = _find_project_root()

# Force UTF-8 on stdout/stderr: this script prints emoji, which raises
# UnicodeEncodeError on a Windows console (cp1252). Same guard as
# src/ui-ux-pro-max/scripts/search.py.
import io

if sys.stdout.encoding and sys.stdout.encoding.lower() != 'utf-8':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
if sys.stderr.encoding and sys.stderr.encoding.lower() != 'utf-8':
    sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
TOKENS_JSON_PATH = PROJECT_ROOT / 'assets' / 'design-tokens.json'
TOKENS_CSS_PATH = PROJECT_ROOT / 'assets' / 'design-tokens.css'

# Asset directories to validate
ASSET_DIRS = {
    'slides': PROJECT_ROOT / 'assets' / 'designs' / 'slides',
    'infographics': PROJECT_ROOT / 'assets' / 'infographics',
}

# Patterns that indicate hardcoded values (should use tokens)
FORBIDDEN_PATTERNS = [
    (r'#[0-9A-Fa-f]{3,8}\b', 'hex color'),
    (r'rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)', 'rgb color'),
    (r'rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[\d.]+\s*\)', 'rgba color'),
    (r'hsl\([^)]+\)', 'hsl color'),
    (r"font-family:\s*'[^v][^a][^r][^']*',", 'hardcoded font'),  # Exclude var()
    (r'font-family:\s*"[^v][^a][^r][^"]*",', 'hardcoded font'),
]

# Allowed rgba patterns (brand colors with transparency - CSS limitation)
# These are derived from brand tokens but need rgba for transparency
ALLOWED_RGBA_PATTERNS = [
    r'rgba\(\s*59\s*,\s*130\s*,\s*246',    # --color-primary (#3B82F6)
    r'rgba\(\s*245\s*,\s*158\s*,\s*11',    # --color-secondary (#F59E0B)
    r'rgba\(\s*16\s*,\s*185\s*,\s*129',    # --color-accent (#10B981)
    r'rgba\(\s*20\s*,\s*184\s*,\s*166',    # --color-accent alt (#14B8A6)
    r'rgba\(\s*0\s*,\s*0\s*,\s*0',         # black transparency (common)
    r'rgba\(\s*255\s*,\s*255\s*,\s*255',   # white transparency (common)
    r'rgba\(\s*15\s*,\s*23\s*,\s*42',      # --color-surface (#0F172A)
    r'rgba\(\s*7\s*,\s*11\s*,\s*20',       # --color-background (#070B14)
]

# Allowed exceptions (external images, etc.)
ALLOWED_EXCEPTIONS = [
    'pexels.com', 'unsplash.com', 'youtube.com', 'ytimg.com',
    'googlefonts', 'fonts.googleapis.com', 'fonts.gstatic.com',
]


class ValidationResult:
    """Validation result for a single file."""
    def __init__(self, file_path: Path):
        self.file_path = file_path
        self.errors: List[str] = []
        self.warnings: List[str] = []
        self.passed = True

    def add_error(self, msg: str):
        self.errors.append(msg)
        self.passed = False

    def add_warning(self, msg: str):
        self.warnings.append(msg)


def load_css_variables() -> Dict[str, str]:
    """Load CSS variables from design-tokens.css."""
    variables = {}
    if TOKENS_CSS_PATH.exists():
        content = TOKENS_CSS_PATH.read_text()
        # Extract --var-name: value patterns
        for match in re.finditer(r'(--[\w-]+):\s*([^;]+);', content):
            variables[match.group(1)] = match.group(2).strip()
    return variables


def is_inside_block(content: str, match_pos: int, open_tag: str, close_tag: str) -> bool:
    """Check if position is inside a specific HTML block."""
    pre = content[:match_pos]
    tag_open = pre.rfind(open_tag)
    tag_close = pre.rfind(close_tag)
    return tag_open > tag_close


def is_allowed_exception(context: str) -> bool:
    """Check if the hardcoded value is in an allowed exception context."""
    context_lower = context.lower()
    return any(exc in context_lower for exc in ALLOWED_EXCEPTIONS)


def is_allowed_rgba(match_text: str) -> bool:
    """Check if rgba pattern uses brand colors (allowed for transparency)."""
    return any(re.match(pattern, match_text) for pattern in ALLOWED_RGBA_PATTERNS)


def get_context(content: str, pos: int, chars: int = 100) -> str:
    """Get surrounding context for a match position."""
    start = max(0, pos - chars)
    end = min(len(content), pos + chars)
    return content[start:end]


def validate_html(content: str, file_path: Path, verbose: bool = False) -> ValidationResult:
    """
    Validate HTML content for design token compliance.

    Checks:
    1. design-tokens.css import present
    2. No hardcoded colors in CSS (except in <script> for Chart.js)
    3. No hardcoded fonts
    4. Uses var(--token-name) pattern
    """
    result = ValidationResult(file_path)

    # 1. Check for design-tokens.css import
    if 'design-tokens.css' not in content:
        result.add_error("Missing design-tokens.css import")

    # 2. Check for forbidden patterns in CSS
    for pattern, description in FORBIDDEN_PATTERNS:
        for match in re.finditer(pattern, content):
            match_text = match.group()
            match_pos = match.start()
            context = get_context(content, match_pos)

            # Skip if in <script> block (Chart.js allowed)
            if is_inside_block(content, match_pos, '<script', '</script>'):
                if verbose:
                    result.add_warning(f"Allowed in <script>: {match_text}")
                continue

            # Skip if in allowed exception context (external URLs)
            if is_allowed_exception(context):
                if verbose:
                    result.add_warning(f"Allowed external: {match_text}")
                continue

            # Skip rgba using brand colors (needed for transparency effects)
            if description == 'rgba color' and is_allowed_rgba(match_text):
                if verbose:
                    result.add_warning(f"Allowed brand rgba: {match_text}")
                continue

            # Skip if part of var() reference (false positive)
            if 'var(' in context and match_text in context:
                # Check if it's a fallback value in var()
                var_pattern = rf'var\([^)]*{re.escape(match_text)}[^)]*\)'
                if re.search(var_pattern, context):
                    continue

            # Error if in <style> or inline style
            if is_inside_block(content, match_pos, '<style', '</style>'):
                result.add_error(f"Hardcoded {description} in <style>: {match_text}")
            elif 'style="' in context:
                result.add_error(f"Hardcoded {description} in inline style: {match_text}")

    # 3. Check for required var() usage indicators
    token_patterns = [
        r'var\(--color-',
        r'var\(--primitive-',
        r'var\(--typography-',
        r'var\(--card-',
        r'var\(--button-',
    ]
    token_count = sum(len(re.findall(p, content)) for p in token_patterns)

    if token_count < 5:
        result.add_warning(f"Low token usage ({token_count} var() references). Consider using more design tokens.")

    return result


def validate_file(file_path: Path, verbose: bool = False) -> ValidationResult:
    """Validate a single HTML file."""
    if not file_path.exists():
        result = ValidationResult(file_path)
        result.add_error("File not found")
        return result

    content = file_path.read_text()
    return validate_html(content, file_path, verbose)


def validate_directory(dir_path: Path, verbose: bool = False) -> List[ValidationResult]:
    """Validate all HTML files in a directory."""
    results = []
    if dir_path.exists():
        for html_file in sorted(dir_path.glob('*.html')):
            results.append(validate_file(html_file, verbose))
    return results


def print_result(result: ValidationResult, verbose: bool = False):
    """Print validation result for a file."""
    status = "✓" if result.passed else "✗"
    print(f"  {status} {result.file_path.name}")

    if result.errors:
        for error in result.errors[:5]:  # Limit output
            print(f"      ├─ {error}")
        if len(result.errors) > 5:
            print(f"      └─ ... and {len(result.errors) - 5} more errors")

    if verbose and result.warnings:
        for warning in result.warnings[:3]:
            print(f"      [warn] {warning}")


def print_summary(all_results: Dict[str, List[ValidationResult]]):
    """Print summary of all validation results."""
    total_files = 0
    total_passed = 0
    total_errors = 0

    print("\n" + "=" * 60)
    print("HTML DESIGN TOKEN VALIDATION SUMMARY")
    print("=" * 60)

    for asset_type, results in all_results.items():
        if not results:
            continue

        passed = sum(1 for r in results if r.passed)
        failed = len(results) - passed
        errors = sum(len(r.errors) for r in results)

        total_files += len(results)
        total_passed += passed
        total_errors += errors

        status = "✓" if failed == 0 else "✗"
        print(f"\n{status} {asset_type.upper()}: {passed}/{len(results)} passed")

        for result in results:
            if not result.passed:
                print_result(result)

    print("\n" + "-" * 60)
    if total_errors == 0:
        print(f"✓ ALL PASSED: {total_passed}/{total_files} files valid")
    else:
        print(f"✗ FAILED: {total_files - total_passed}/{total_files} files have issues ({total_errors} total errors)")
    print("-" * 60)

    return total_errors == 0


def main():
    """CLI entry point."""
    import argparse

    parser = argparse.ArgumentParser(
        description='Validate HTML assets for design token compliance',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s                           # Validate all HTML assets
  %(prog)s --type slides             # Validate only slides
  %(prog)s --type infographics       # Validate only infographics
  %(prog)s path/to/file.html         # Validate specific file
  %(prog)s --colors                  # Show brand colors from tokens
"""
    )
    parser.add_argument('files', nargs='*', help='Specific HTML files to validate')
    parser.add_argument('-t', '--type', choices=['slides', 'infographics', 'all'],
                        default='all', help='Asset type to validate')
    parser.add_argument('-v', '--verbose', action='store_true', help='Show warnings')
    parser.add_argument('--colors', action='store_true', help='Print CSS variables from tokens')
    parser.add_argument('--fix', action='store_true', help='Auto-fix issues (experimental)')

    args = parser.parse_args()

    # Show colors mode
    if args.colors:
        variables = load_css_variables()
        print("\nDesign Tokens (from design-tokens.css):")
        print("-" * 40)
        for name, value in sorted(variables.items())[:30]:
            print(f"  {name}: {value}")
        if len(variables) > 30:
            print(f"  ... and {len(variables) - 30} more")
        return

    all_results: Dict[str, List[ValidationResult]] = {}

    # Validate specific files
    if args.files:
        results = []
        for file_path in args.files:
            path = Path(file_path)
            if path.exists():
                results.append(validate_file(path, args.verbose))
            else:
                result = ValidationResult(path)
                result.add_error("File not found")
                results.append(result)
        all_results['specified'] = results
    else:
        # Validate by type
        types_to_check = ASSET_DIRS.keys() if args.type == 'all' else [args.type]

        for asset_type in types_to_check:
            if asset_type in ASSET_DIRS:
                results = validate_directory(ASSET_DIRS[asset_type], args.verbose)
                all_results[asset_type] = results

    # Print results
    success = print_summary(all_results)

    if not success:
        sys.exit(1)


if __name__ == '__main__':
    main()
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 196kUpdated Claude CodeCodexVerifiedInstall