@stephen-lord/docs 1.0.0

package/dist/awesome-claude-skills/slack-gif-creator/core/typography.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""
+Typography System - Professional text rendering with outlines, shadows, and effects.
+
+This module provides high-quality text rendering that looks crisp and professional
+in GIFs, with outlines for readability and effects for visual impact.
+"""
+
+from PIL import Image, ImageDraw, ImageFont
+from typing import Optional
+
+
+# Typography scale - proportional sizing system
+TYPOGRAPHY_SCALE = {
+    'h1': 60,      # Large headers
+    'h2': 48,      # Medium headers
+    'h3': 36,      # Small headers
+    'title': 50,   # Title text
+    'body': 28,    # Body text
+    'small': 20,   # Small text
+    'tiny': 16,    # Tiny text
+}
+
+
+def get_font(size: int, bold: bool = False) -> ImageFont.FreeTypeFont:
+    """
+    Get a font with fallback support.
+
+    Args:
+        size: Font size in pixels
+        bold: Use bold variant if available
+
+    Returns:
+        ImageFont object
+    """
+    # Try multiple font paths for cross-platform support
+    font_paths = [
+        # macOS fonts
+        "/System/Library/Fonts/Helvetica.ttc",
+        "/System/Library/Fonts/SF-Pro.ttf",
+        "/Library/Fonts/Arial Bold.ttf" if bold else "/Library/Fonts/Arial.ttf",
+        # Linux fonts
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf" if bold else "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+        # Windows fonts
+        "C:\\Windows\\Fonts\\arialbd.ttf" if bold else "C:\\Windows\\Fonts\\arial.ttf",
+    ]
+
+    for font_path in font_paths:
+        try:
+            return ImageFont.truetype(font_path, size)
+        except:
+            continue
+
+    # Ultimate fallback
+    return ImageFont.load_default()
+
+
+def draw_text_with_outline(
+    frame: Image.Image,
+    text: str,
+    position: tuple[int, int],
+    font_size: int = 40,
+    text_color: tuple[int, int, int] = (255, 255, 255),
+    outline_color: tuple[int, int, int] = (0, 0, 0),
+    outline_width: int = 3,
+    centered: bool = False,
+    bold: bool = True
+) -> Image.Image:
+    """
+    Draw text with outline for maximum readability.
+
+    This is THE most important function for professional-looking text in GIFs.
+    The outline ensures text is readable on any background.
+
+    Args:
+        frame: PIL Image to draw on
+        text: Text to draw
+        position: (x, y) position
+        font_size: Font size in pixels
+        text_color: RGB color for text fill
+        outline_color: RGB color for outline
+        outline_width: Width of outline in pixels (2-4 recommended)
+        centered: If True, center text at position
+        bold: Use bold font variant
+
+    Returns:
+        Modified frame
+    """
+    draw = ImageDraw.Draw(frame)
+    font = get_font(font_size, bold=bold)
+
+    # Calculate position for centering
+    if centered:
+        bbox = draw.textbbox((0, 0), text, font=font)
+        text_width = bbox[2] - bbox[0]
+        text_height = bbox[3] - bbox[1]
+        x = position[0] - text_width // 2
+        y = position[1] - text_height // 2
+        position = (x, y)
+
+    # Draw outline by drawing text multiple times offset in all directions
+    x, y = position
+    for offset_x in range(-outline_width, outline_width + 1):
+        for offset_y in range(-outline_width, outline_width + 1):
+            if offset_x != 0 or offset_y != 0:
+                draw.text((x + offset_x, y + offset_y), text, fill=outline_color, font=font)
+
+    # Draw main text on top
+    draw.text(position, text, fill=text_color, font=font)
+
+    return frame
+
+
+def draw_text_with_shadow(
+    frame: Image.Image,
+    text: str,
+    position: tuple[int, int],
+    font_size: int = 40,
+    text_color: tuple[int, int, int] = (255, 255, 255),
+    shadow_color: tuple[int, int, int] = (0, 0, 0),
+    shadow_offset: tuple[int, int] = (3, 3),
+    centered: bool = False,
+    bold: bool = True
+) -> Image.Image:
+    """
+    Draw text with drop shadow for depth.
+
+    Args:
+        frame: PIL Image to draw on
+        text: Text to draw
+        position: (x, y) position
+        font_size: Font size in pixels
+        text_color: RGB color for text
+        shadow_color: RGB color for shadow
+        shadow_offset: (x, y) offset for shadow
+        centered: If True, center text at position
+        bold: Use bold font variant
+
+    Returns:
+        Modified frame
+    """
+    draw = ImageDraw.Draw(frame)
+    font = get_font(font_size, bold=bold)
+
+    # Calculate position for centering
+    if centered:
+        bbox = draw.textbbox((0, 0), text, font=font)
+        text_width = bbox[2] - bbox[0]
+        text_height = bbox[3] - bbox[1]
+        x = position[0] - text_width // 2
+        y = position[1] - text_height // 2
+        position = (x, y)
+
+    # Draw shadow
+    shadow_pos = (position[0] + shadow_offset[0], position[1] + shadow_offset[1])
+    draw.text(shadow_pos, text, fill=shadow_color, font=font)
+
+    # Draw main text
+    draw.text(position, text, fill=text_color, font=font)
+
+    return frame
+
+
+def draw_text_with_glow(
+    frame: Image.Image,
+    text: str,
+    position: tuple[int, int],
+    font_size: int = 40,
+    text_color: tuple[int, int, int] = (255, 255, 255),
+    glow_color: tuple[int, int, int] = (255, 200, 0),
+    glow_radius: int = 5,
+    centered: bool = False,
+    bold: bool = True
+) -> Image.Image:
+    """
+    Draw text with glow effect for emphasis.
+
+    Args:
+        frame: PIL Image to draw on
+        text: Text to draw
+        position: (x, y) position
+        font_size: Font size in pixels
+        text_color: RGB color for text
+        glow_color: RGB color for glow
+        glow_radius: Radius of glow effect
+        centered: If True, center text at position
+        bold: Use bold font variant
+
+    Returns:
+        Modified frame
+    """
+    draw = ImageDraw.Draw(frame)
+    font = get_font(font_size, bold=bold)
+
+    # Calculate position for centering
+    if centered:
+        bbox = draw.textbbox((0, 0), text, font=font)
+        text_width = bbox[2] - bbox[0]
+        text_height = bbox[3] - bbox[1]
+        x = position[0] - text_width // 2
+        y = position[1] - text_height // 2
+        position = (x, y)
+
+    # Draw glow layers with decreasing opacity (simulated with same color at different offsets)
+    x, y = position
+    for radius in range(glow_radius, 0, -1):
+        for offset_x in range(-radius, radius + 1):
+            for offset_y in range(-radius, radius + 1):
+                if offset_x != 0 or offset_y != 0:
+                    draw.text((x + offset_x, y + offset_y), text, fill=glow_color, font=font)
+
+    # Draw main text
+    draw.text(position, text, fill=text_color, font=font)
+
+    return frame
+
+
+def draw_text_in_box(
+    frame: Image.Image,
+    text: str,
+    position: tuple[int, int],
+    font_size: int = 40,
+    text_color: tuple[int, int, int] = (255, 255, 255),
+    box_color: tuple[int, int, int] = (0, 0, 0),
+    box_alpha: float = 0.7,
+    padding: int = 10,
+    centered: bool = True,
+    bold: bool = True
+) -> Image.Image:
+    """
+    Draw text in a semi-transparent box for guaranteed readability.
+
+    Args:
+        frame: PIL Image to draw on
+        text: Text to draw
+        position: (x, y) position
+        font_size: Font size in pixels
+        text_color: RGB color for text
+        box_color: RGB color for background box
+        box_alpha: Opacity of box (0.0-1.0)
+        padding: Padding around text in pixels
+        centered: If True, center at position
+        bold: Use bold font variant
+
+    Returns:
+        Modified frame
+    """
+    # Create a separate layer for the box with alpha
+    overlay = Image.new('RGBA', frame.size, (0, 0, 0, 0))
+    draw_overlay = ImageDraw.Draw(overlay)
+    draw = ImageDraw.Draw(frame)
+
+    font = get_font(font_size, bold=bold)
+
+    # Get text dimensions
+    bbox = draw.textbbox((0, 0), text, font=font)
+    text_width = bbox[2] - bbox[0]
+    text_height = bbox[3] - bbox[1]
+
+    # Calculate box position
+    if centered:
+        box_x = position[0] - (text_width + padding * 2) // 2
+        box_y = position[1] - (text_height + padding * 2) // 2
+        text_x = position[0] - text_width // 2
+        text_y = position[1] - text_height // 2
+    else:
+        box_x = position[0] - padding
+        box_y = position[1] - padding
+        text_x = position[0]
+        text_y = position[1]
+
+    # Draw semi-transparent box
+    box_coords = [
+        box_x,
+        box_y,
+        box_x + text_width + padding * 2,
+        box_y + text_height + padding * 2
+    ]
+    alpha_value = int(255 * box_alpha)
+    draw_overlay.rectangle(box_coords, fill=(*box_color, alpha_value))
+
+    # Composite overlay onto frame
+    frame_rgba = frame.convert('RGBA')
+    frame_rgba = Image.alpha_composite(frame_rgba, overlay)
+    frame = frame_rgba.convert('RGB')
+
+    # Draw text on top
+    draw = ImageDraw.Draw(frame)
+    draw.text((text_x, text_y), text, fill=text_color, font=font)
+
+    return frame
+
+
+def get_text_size(text: str, font_size: int, bold: bool = True) -> tuple[int, int]:
+    """
+    Get the dimensions of text without drawing it.
+
+    Args:
+        text: Text to measure
+        font_size: Font size in pixels
+        bold: Use bold font variant
+
+    Returns:
+        (width, height) tuple
+    """
+    font = get_font(font_size, bold=bold)
+    # Create temporary image to measure
+    temp_img = Image.new('RGB', (1, 1))
+    draw = ImageDraw.Draw(temp_img)
+    bbox = draw.textbbox((0, 0), text, font=font)
+    width = bbox[2] - bbox[0]
+    height = bbox[3] - bbox[1]
+    return (width, height)
+
+
+def get_optimal_font_size(text: str, max_width: int, max_height: int,
+                          start_size: int = 60) -> int:
+    """
+    Find the largest font size that fits within given dimensions.
+
+    Args:
+        text: Text to size
+        max_width: Maximum width in pixels
+        max_height: Maximum height in pixels
+        start_size: Starting font size to try
+
+    Returns:
+        Optimal font size
+    """
+    font_size = start_size
+    while font_size > 10:
+        width, height = get_text_size(text, font_size)
+        if width <= max_width and height <= max_height:
+            return font_size
+        font_size -= 2
+    return 10  # Minimum font size
+
+
+def scale_font_for_frame(base_size: int, frame_width: int, frame_height: int) -> int:
+    """
+    Scale font size proportionally to frame dimensions.
+
+    Useful for maintaining relative text size across different GIF dimensions.
+
+    Args:
+        base_size: Base font size for 480x480 frame
+        frame_width: Actual frame width
+        frame_height: Actual frame height
+
+    Returns:
+        Scaled font size
+    """
+    # Use average dimension for scaling
+    avg_dimension = (frame_width + frame_height) / 2
+    base_dimension = 480  # Reference dimension
+    scale_factor = avg_dimension / base_dimension
+    return max(10, int(base_size * scale_factor))

package/dist/awesome-claude-skills/slack-gif-creator/core/validators.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""
+Validators - Check if GIFs meet Slack's requirements.
+
+These validators help ensure your GIFs meet Slack's size and dimension constraints.
+"""
+
+from pathlib import Path
+
+
+def check_slack_size(gif_path: str | Path, is_emoji: bool = True) -> tuple[bool, dict]:
+    """
+    Check if GIF meets Slack size limits.
+
+    Args:
+        gif_path: Path to GIF file
+        is_emoji: True for emoji GIF (64KB limit), False for message GIF (2MB limit)
+
+    Returns:
+        Tuple of (passes: bool, info: dict with details)
+    """
+    gif_path = Path(gif_path)
+
+    if not gif_path.exists():
+        return False, {'error': f'File not found: {gif_path}'}
+
+    size_bytes = gif_path.stat().st_size
+    size_kb = size_bytes / 1024
+    size_mb = size_kb / 1024
+
+    limit_kb = 64 if is_emoji else 2048
+    limit_mb = limit_kb / 1024
+
+    passes = size_kb <= limit_kb
+
+    info = {
+        'size_bytes': size_bytes,
+        'size_kb': size_kb,
+        'size_mb': size_mb,
+        'limit_kb': limit_kb,
+        'limit_mb': limit_mb,
+        'passes': passes,
+        'type': 'emoji' if is_emoji else 'message'
+    }
+
+    # Print feedback
+    if passes:
+        print(f"✓ {size_kb:.1f} KB - within {limit_kb} KB limit")
+    else:
+        print(f"✗ {size_kb:.1f} KB - exceeds {limit_kb} KB limit")
+        overage_kb = size_kb - limit_kb
+        overage_percent = (overage_kb / limit_kb) * 100
+        print(f"  Over by: {overage_kb:.1f} KB ({overage_percent:.1f}%)")
+        print(f"  Try: fewer frames, fewer colors, or simpler design")
+
+    return passes, info
+
+
+def validate_dimensions(width: int, height: int, is_emoji: bool = True) -> tuple[bool, dict]:
+    """
+    Check if dimensions are suitable for Slack.
+
+    Args:
+        width: Frame width in pixels
+        height: Frame height in pixels
+        is_emoji: True for emoji GIF, False for message GIF
+
+    Returns:
+        Tuple of (passes: bool, info: dict with details)
+    """
+    info = {
+        'width': width,
+        'height': height,
+        'is_square': width == height,
+        'type': 'emoji' if is_emoji else 'message'
+    }
+
+    if is_emoji:
+        # Emoji GIFs should be 128x128
+        optimal = width == height == 128
+        acceptable = width == height and 64 <= width <= 128
+
+        info['optimal'] = optimal
+        info['acceptable'] = acceptable
+
+        if optimal:
+            print(f"✓ {width}x{height} - optimal for emoji")
+            passes = True
+        elif acceptable:
+            print(f"⚠ {width}x{height} - acceptable but 128x128 is optimal")
+            passes = True
+        else:
+            print(f"✗ {width}x{height} - emoji should be square, 128x128 recommended")
+            passes = False
+    else:
+        # Message GIFs should be square-ish and reasonable size
+        aspect_ratio = max(width, height) / min(width, height) if min(width, height) > 0 else float('inf')
+        reasonable_size = 320 <= min(width, height) <= 640
+
+        info['aspect_ratio'] = aspect_ratio
+        info['reasonable_size'] = reasonable_size
+
+        # Check if roughly square (within 2:1 ratio)
+        is_square_ish = aspect_ratio <= 2.0
+
+        if is_square_ish and reasonable_size:
+            print(f"✓ {width}x{height} - good for message GIF")
+            passes = True
+        elif is_square_ish:
+            print(f"⚠ {width}x{height} - square-ish but unusual size")
+            passes = True
+        elif reasonable_size:
+            print(f"⚠ {width}x{height} - good size but not square-ish")
+            passes = True
+        else:
+            print(f"✗ {width}x{height} - unusual dimensions for Slack")
+            passes = False
+
+    return passes, info
+
+
+def validate_gif(gif_path: str | Path, is_emoji: bool = True) -> tuple[bool, dict]:
+    """
+    Run all validations on a GIF file.
+
+    Args:
+        gif_path: Path to GIF file
+        is_emoji: True for emoji GIF, False for message GIF
+
+    Returns:
+        Tuple of (all_pass: bool, results: dict)
+    """
+    from PIL import Image
+
+    gif_path = Path(gif_path)
+
+    if not gif_path.exists():
+        return False, {'error': f'File not found: {gif_path}'}
+
+    print(f"\nValidating {gif_path.name} as {'emoji' if is_emoji else 'message'} GIF:")
+    print("=" * 60)
+
+    # Check file size
+    size_pass, size_info = check_slack_size(gif_path, is_emoji)
+
+    # Check dimensions
+    try:
+        with Image.open(gif_path) as img:
+            width, height = img.size
+            dim_pass, dim_info = validate_dimensions(width, height, is_emoji)
+
+            # Count frames
+            frame_count = 0
+            try:
+                while True:
+                    img.seek(frame_count)
+                    frame_count += 1
+            except EOFError:
+                pass
+
+            # Get duration if available
+            try:
+                duration_ms = img.info.get('duration', 100)
+                total_duration = (duration_ms * frame_count) / 1000
+                fps = frame_count / total_duration if total_duration > 0 else 0
+            except:
+                duration_ms = None
+                total_duration = None
+                fps = None
+
+    except Exception as e:
+        return False, {'error': f'Failed to read GIF: {e}'}
+
+    print(f"\nFrames: {frame_count}")
+    if total_duration:
+        print(f"Duration: {total_duration:.1f}s @ {fps:.1f} fps")
+
+    all_pass = size_pass and dim_pass
+
+    results = {
+        'file': str(gif_path),
+        'passes': all_pass,
+        'size': size_info,
+        'dimensions': dim_info,
+        'frame_count': frame_count,
+        'duration_seconds': total_duration,
+        'fps': fps
+    }
+
+    print("=" * 60)
+    if all_pass:
+        print("✓ All validations passed!")
+    else:
+        print("✗ Some validations failed")
+    print()
+
+    return all_pass, results
+
+
+def get_optimization_suggestions(results: dict) -> list[str]:
+    """
+    Get suggestions for optimizing a GIF based on validation results.
+
+    Args:
+        results: Results dict from validate_gif()
+
+    Returns:
+        List of suggestion strings
+    """
+    suggestions = []
+
+    if not results.get('passes', False):
+        size_info = results.get('size', {})
+        dim_info = results.get('dimensions', {})
+
+        # Size suggestions
+        if not size_info.get('passes', True):
+            overage = size_info['size_kb'] - size_info['limit_kb']
+            if size_info['type'] == 'emoji':
+                suggestions.append(f"Reduce file size by {overage:.1f} KB:")
+                suggestions.append("  - Limit to 10-12 frames")
+                suggestions.append("  - Use 32-40 colors maximum")
+                suggestions.append("  - Remove gradients (solid colors compress better)")
+                suggestions.append("  - Simplify design")
+            else:
+                suggestions.append(f"Reduce file size by {overage:.1f} KB:")
+                suggestions.append("  - Reduce frame count or FPS")
+                suggestions.append("  - Use fewer colors (128 → 64)")
+                suggestions.append("  - Reduce dimensions")
+
+        # Dimension suggestions
+        if not dim_info.get('optimal', True) and dim_info.get('type') == 'emoji':
+            suggestions.append("For optimal emoji GIF:")
+            suggestions.append("  - Use 128x128 dimensions")
+            suggestions.append("  - Ensure square aspect ratio")
+
+    return suggestions
+
+
+# Convenience function for quick checks
+def is_slack_ready(gif_path: str | Path, is_emoji: bool = True, verbose: bool = True) -> bool:
+    """
+    Quick check if GIF is ready for Slack.
+
+    Args:
+        gif_path: Path to GIF file
+        is_emoji: True for emoji GIF, False for message GIF
+        verbose: Print detailed feedback
+
+    Returns:
+        True if ready, False otherwise
+    """
+    if verbose:
+        passes, results = validate_gif(gif_path, is_emoji)
+        if not passes:
+            suggestions = get_optimization_suggestions(results)
+            if suggestions:
+                print("\nSuggestions:")
+                for suggestion in suggestions:
+                    print(suggestion)
+        return passes
+    else:
+        size_pass, _ = check_slack_size(gif_path, is_emoji)
+        return size_pass