@tidyfactor/design 1.5.0

package/scripts/_utils.py

@@ -0,0 +1,60 @@
+"""Shared utilities for the Cinematic Landing Kit asset pipeline."""
+
+import re
+
+try:
+    from PIL import Image
+except ImportError:
+    Image = None
+
+
+def crop_cover_16_9(img, target_w: int = 1280, target_h: int = 720):
+    """Crop-resize an image to a target 16:9 frame (object-cover style)."""
+    if Image is None:
+        raise ImportError("Pillow is required for crop_cover_16_9. Run:  pip install Pillow")
+    img = img.convert("RGB")
+    img_ratio = img.width / img.height
+    target_ratio = target_w / target_h
+    if img_ratio > target_ratio:
+        new_width = int(target_ratio * img.height)
+        offset = (img.width - new_width) // 2
+        img = img.crop((offset, 0, offset + new_width, img.height))
+    else:
+        new_height = int(img.width / target_ratio)
+        offset = (img.height - new_height) // 2
+        img = img.crop((0, offset, img.width, offset + new_height))
+    return img.resize((target_w, target_h), Image.Resampling.LANCZOS)
+
+
+_NATURAL_SORT_RE = re.compile(r"(\d+)")
+
+
+def natural_sort_key(s: str):
+    """Sort key for filenames with embedded numbers.
+
+    'k2.jpg' sorts before 'k10.jpg', matching human expectations.
+    """
+    parts = _NATURAL_SORT_RE.split(s)
+    return [int(p) if p.isdigit() else p.lower() for p in parts]
+
+
+def split_spec(spec: str) -> list[str]:
+    """Split 'src:dest[:opts]' with Windows drive-letter awareness.
+
+    A single-alpha character immediately before ':' is treated as a drive-letter
+    prefix (e.g. C:\\path) rather than a field separator.  All other colons are
+    normal field delimiters.
+    """
+    parts: list[str] = []
+    current = ""
+    for ch in spec:
+        if ch == ":":
+            if len(current) == 1 and current[0].isalpha():
+                current += ch
+            else:
+                parts.append(current)
+                current = ""
+        else:
+            current += ch
+    parts.append(current)
+    return parts

package/scripts/build.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+"""
+Main Production Build Orchestrator
+Runs all production build steps in sequence:
+  1. Bundles and minifies JS and CSS assets.
+  2. Scans and optimizes all images in assets/image/.
+  3. Executes the build test suite. Aborts the build on failure.
+  4. Performs cache-busting on index.html, updating asset query strings (?v=) with a timestamp.
+  5. Packages the clean production-ready files into release/deploy.zip.
+
+Usage:
+    python scripts/build.py
+"""
+
+import os
+import re
+import sys
+import time
+import zipfile
+import subprocess
+from pathlib import Path
+
+# Paths relative to this script (inside scripts/)
+SCRIPTS_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPTS_DIR.parent
+
+
+def run_command(command_args, description):
+    print(f"\n>>> Running: {description}...")
+    try:
+        # Run sub-script and redirect output to stdout
+        result = subprocess.run(
+            [sys.executable] + command_args, 
+            stdout=subprocess.PIPE, 
+            stderr=subprocess.PIPE, 
+            text=True,
+            check=True
+        )
+        print(result.stdout)
+        return True
+    except subprocess.CalledProcessError as e:
+        print(f"  [ERROR] {description} failed.")
+        print(e.stdout)
+        print(e.stderr)
+        return False
+    except Exception as e:
+        print(f"  [ERROR] Failed to run command: {e}")
+        return False
+
+
+def update_cache_busting_versions():
+    print("\n>>> Running: index.html Cache-Busting Version Updates...")
+    index_path = PROJECT_ROOT / "index.html"
+    if not index_path.exists():
+        print("  [ERROR] index.html not found, skipping version updates.")
+        return
+
+    # Use current datetime stamp as unique version query string
+    version_stamp = time.strftime("%Y%m%d%H%M%S")
+    print(f"  Target version code: {version_stamp}")
+
+    with open(index_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Regex matches to replace query strings in href and src attributes
+    new_content = re.sub(
+        r'(href=["\']assets/css/style\.min\.css)\?v=[^"\'\s]*([\x22\x27])',
+        r'\1?v=' + version_stamp + r'\2',
+        content
+    )
+    
+    new_content = re.sub(
+        r'(src=["\']assets/js/bundle\.min\.js)\?v=[^"\'\s]*([\x22\x27])',
+        r'\1?v=' + version_stamp + r'\2',
+        new_content
+    )
+
+    if content != new_content:
+        with open(index_path, "w", encoding="utf-8") as f:
+            f.write(new_content)
+        print(f"  [SUCCESS] index.html asset references updated with version code '?v={version_stamp}'.")
+    else:
+        print("  [INFO] No version references updated in index.html.")
+
+
+def package_release():
+    print("\n>>> Running: Packaging Clean Production Release...")
+    release_dir = PROJECT_ROOT / "release"
+    release_dir.mkdir(exist_ok=True)
+    
+    zip_path = release_dir / "deploy.zip"
+    if zip_path.exists():
+        try:
+            zip_path.unlink()
+        except Exception as e:
+            print(f"  [ERROR] Could not delete old release package: {e}")
+            sys.exit(1)
+
+    print(f"  Creating ZIP archive: {zip_path.relative_to(PROJECT_ROOT)}")
+    
+    try:
+        with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zipf:
+            # 1. Add index.html
+            index_path = PROJECT_ROOT / "index.html"
+            if index_path.exists():
+                zipf.write(index_path, "index.html")
+                print("  + index.html")
+                
+            # 2. Recurse assets/
+            assets_dir = PROJECT_ROOT / "assets"
+            added_count = 0
+            for root, _, files in os.walk(assets_dir):
+                for file in files:
+                    file_path = Path(root) / file
+                    
+                    # Compute relative path string
+                    rel_path = file_path.relative_to(PROJECT_ROOT)
+                    rel_path_str = rel_path.as_posix()
+                    
+                    # Skip backups and system dotfiles
+                    if "_backup" in file_path.name or file_path.name.startswith("."):
+                        continue
+                    
+                    # Clean production exclusions:
+                    # - Under assets/css/: skip style.css (keep style.min.css)
+                    if rel_path_str.startswith("assets/css/"):
+                        if file_path.name == "style.css":
+                            continue
+                            
+                    # - Under assets/js/: skip main.js and unneeded library folders (keep only bundle.min.js)
+                    if rel_path_str.startswith("assets/js/"):
+                        if file_path.name != "bundle.min.js":
+                            continue
+                    
+                    zipf.write(file_path, rel_path)
+                    added_count += 1
+            print(f"  + assets/ ({added_count} files included, unminified files and libraries excluded)")
+            
+        print(f"  [SUCCESS] Created release package successfully: release/deploy.zip")
+    except Exception as e:
+        print(f"  [ERROR] Failed to compile ZIP archive: {e}")
+        sys.exit(1)
+
+
+def main():
+    start_time = time.time()
+    
+    print("="*60)
+    print("      NOOR AL-ISLAM LANDING PAGE — PRODUCTION BUILDER")
+    print("="*60)
+
+    # 1. Run Minifier & Bundler
+    assets_success = run_command(
+        [str(SCRIPTS_DIR / "minify_assets.py")], 
+        "Minifying and Bundling CSS & JS Assets"
+    )
+    if not assets_success:
+        print("Build aborted due to JS/CSS bundling errors.")
+        sys.exit(1)
+
+    # 2. Run Image Optimizer
+    images_success = run_command(
+        [str(SCRIPTS_DIR / "optimize_images.py"), "assets/image"],
+        "Optimizing Project Images"
+    )
+    if not images_success:
+        print("  [WARNING] Image optimization script reported warnings/errors. Continuing build...")
+
+    # 3. Run Build Integrity Tests
+    tests_success = run_command(
+        [str(SCRIPTS_DIR / "test_build.py")],
+        "Executing Automated Test Suite"
+    )
+    if not tests_success:
+        print("\n[FAIL] BUILD ABORTED: The automated test suite reported failures.")
+        print("Please resolve the failures listed above before deploying.")
+        sys.exit(1)
+
+    # 4. Cache Busting Version Updater
+    update_cache_busting_versions()
+
+    # 5. Package ZIP Release
+    package_release()
+
+    end_time = time.time()
+    elapsed = end_time - start_time
+    
+    print("\n" + "="*60)
+    print(f"[SUCCESS] PRODUCTION BUILD & PACKAGING COMPLETED IN {elapsed:.2f}s!")
+    print("="*60)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_alpha.py

@@ -0,0 +1,52 @@
+import argparse
+import os
+import sys
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Pillow is required. Run:  pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+def check_alpha(path):
+    if not os.path.exists(path):
+        print(f"- {path}: file not found")
+        return
+    try:
+        with Image.open(path) as img:
+            if img.mode == 'RGBA':
+                alpha = img.split()[3]
+                extrema = alpha.getextrema()
+                has_transparency = extrema[0] < 255
+                print(f"- {path}: RGBA  alpha_range={extrema}  transparent={has_transparency}")
+            else:
+                print(f"- {path}: {img.mode}  no alpha channel")
+    except Exception as e:
+        print(f"- {path}: ERROR  {e}")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Check whether images have an alpha (transparency) channel."
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help="One or more image file paths. If a path is a directory, all PNG/WEBP files inside it are checked.",
+    )
+    args = parser.parse_args()
+
+    if not args.paths:
+        parser.print_help()
+        sys.exit(0)
+
+    print("Alpha Channel Check:")
+    for p in args.paths:
+        if os.path.isdir(p):
+            for f in sorted(os.listdir(p)):
+                if f.lower().endswith((".png", ".webp", ".tga")):
+                    check_alpha(os.path.join(p, f))
+        else:
+            check_alpha(p)
+
+if __name__ == "__main__":
+    main()

package/scripts/extract_palette.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""
+extract_palette.py — Design System Palette & Color Extraction Tool
+Extracts dominant brand colors, background tones, text colors, and WCAG contrast scores
+from reference screenshots, logos, or hero images to generate brand.json and tokens.css.
+
+Dependencies:
+    pip install pillow
+
+Usage:
+    python scripts/extract_palette.py assets/logo.png --json brand.json
+    python scripts/extract_palette.py reference_shot.png --css design-system/tokens.css
+"""
+
+import os
+import sys
+import json
+import argparse
+from PIL import Image
+
+def get_rgb_luminance(rgb):
+    """Calculates relative luminance according to WCAG 2.1 specifications."""
+    r, g, b = [x / 255.0 for x in rgb]
+    r = r / 12.92 if r <= 0.03928 else ((r + 0.055) / 1.055) ** 2.4
+    g = g / 12.92 if g <= 0.03928 else ((g + 0.055) / 1.055) ** 2.4
+    b = b / 12.92 if b <= 0.03928 else ((b + 0.055) / 1.055) ** 2.4
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+def contrast_ratio(rgb1, rgb2):
+    """Calculates WCAG contrast ratio between two RGB colors (1 to 21)."""
+    l1 = get_rgb_luminance(rgb1)
+    l2 = get_rgb_luminance(rgb2)
+    lighter = max(l1, l2)
+    darker = min(l1, l2)
+    return (lighter + 0.05) / (darker + 0.05)
+
+def rgb_to_hex(rgb):
+    return f"#{rgb[0]:02X}{rgb[1]:02X}{rgb[2]:02X}"
+
+def extract_dominant_colors(image_path, num_colors=5):
+    if not os.path.exists(image_path):
+        print(f"ERROR: File not found: {image_path}", file=sys.stderr)
+        return None
+    
+    img = Image.open(image_path).convert("RGB")
+    img.thumbnail((200, 200), Image.Resampling.LANCZOS)
+    
+    # Quantize image to extract primary color palette
+    quantized = img.quantize(colors=num_colors, method=Image.Quantize.MEDIANCUT)
+    palette = quantized.getpalette()[:num_colors * 3]
+    
+    colors = []
+    for i in range(0, len(palette), 3):
+        rgb = tuple(palette[i:i+3])
+        colors.append(rgb)
+    
+    return colors
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract brand color palettes and WCAG contrast metrics.")
+    parser.add_argument("input", help="Path to input image (logo, screenshot, brand photo)")
+    parser.add_argument("--json", "-j", help="Output path for brand.json update")
+    parser.add_argument("--css", "-c", help="Output path for tokens.css variables")
+    
+    args = parser.parse_args()
+    
+    colors = extract_dominant_colors(args.input)
+    if not colors:
+        sys.exit(1)
+        
+    hex_colors = [rgb_to_hex(c) for c in colors]
+    
+    primary = hex_colors[0]
+    secondary = hex_colors[1] if len(hex_colors) > 1 else "#06B6D4"
+    accent = hex_colors[2] if len(hex_colors) > 2 else "#F59E0B"
+    dark_bg = "#0F172A"
+    light_bg = "#F8FAFC"
+    
+    cr_on_dark = contrast_ratio(colors[0], (15, 23, 42))
+    cr_on_light = contrast_ratio(colors[0], (248, 250, 252))
+    
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding='utf-8')
+        except Exception:
+            pass
+    print(f"[OK] Extracted Palette from {args.input}:")
+    print(f"  Primary:   {primary} (WCAG Contrast vs Dark: {cr_on_dark:.2f}:1, Light: {cr_on_light:.2f}:1)")
+    print(f"  Secondary: {secondary}")
+    print(f"  Accent:    {accent}")
+    
+    if args.json:
+        brand_data = {}
+        if os.path.exists(args.json):
+            try:
+                with open(args.json, "r", encoding="utf-8") as f:
+                    brand_data = json.load(f)
+            except Exception:
+                brand_data = {}
+
+        if "colors" not in brand_data or not isinstance(brand_data["colors"], dict):
+            brand_data["colors"] = {}
+
+        # Handle brand.json v2 dual-mode schema if present
+        if "light" in brand_data["colors"] and isinstance(brand_data["colors"]["light"], dict):
+            brand_data["colors"]["light"]["primary"] = primary
+            brand_data["colors"]["light"]["secondary"] = secondary
+            brand_data["colors"]["light"]["accent"] = accent
+            if "dark" in brand_data["colors"] and isinstance(brand_data["colors"]["dark"], dict):
+                brand_data["colors"]["dark"]["secondary"] = secondary
+                brand_data["colors"]["dark"]["accent"] = accent
+        else:
+            # Fallback for flat structure
+            brand_data["colors"]["primary"] = primary
+            brand_data["colors"]["secondary"] = secondary
+            brand_data["colors"]["accent"] = accent
+            brand_data["colors"]["neutralDark"] = dark_bg
+            brand_data["colors"]["neutralLight"] = light_bg
+
+        with open(args.json, "w", encoding="utf-8") as f:
+            json.dump(brand_data, f, indent=2)
+        print(f"✓ Palette updated in: {args.json}")
+        
+    if args.css:
+        css_vars = f"""/* Auto-generated Design Tokens from {args.input} */
+:root {{
+  --color-primary: {primary};
+  --color-secondary: {secondary};
+  --color-accent: {accent};
+  --color-dark: {dark_bg};
+  --color-light: {light_bg};
+}}
+"""
+        with open(args.css, "a", encoding="utf-8") as f:
+            f.write(css_vars)
+        print(f"✓ CSS Variables appended to: {args.css}")
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_transitions.py

@@ -0,0 +1,105 @@
+import argparse
+import os
+import sys
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Required package not installed. Run:  pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+from _utils import crop_cover_16_9, natural_sort_key
+
+TARGET_W, TARGET_H = 1280, 720
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description=(
+            "Generate a JPEG frame-sequence from N keyframe images using eased cross-blends. "
+            "Output frames are named f000.jpg, f001.jpg, … and are suitable for scrubbing on a <canvas>."
+        ),
+    )
+    parser.add_argument(
+        "--keyframes-dir",
+        "-k",
+        required=True,
+        help="Directory containing numbered keyframe images (k1.png k2.png … or any sorted order).",
+    )
+    parser.add_argument(
+        "--output-dir",
+        "-o",
+        default="assets/seq",
+        help="Directory to write the output frame sequence (default: assets/seq).",
+    )
+    parser.add_argument(
+        "--src-dir",
+        help="Optional directory to save the normalised 1280x720 keyframes (default: <output-dir>/../seq-src).",
+    )
+    parser.add_argument(
+        "--total-frames",
+        "-f",
+        type=int,
+        default=93,
+        help="Total number of output frames (default: 93).",
+    )
+    parser.add_argument(
+        "--quality",
+        "-q",
+        type=int,
+        default=80,
+        help="JPEG quality for output frames (default: 80).",
+    )
+    args = parser.parse_args()
+
+    kf_dir = args.keyframes_dir
+    if not os.path.isdir(kf_dir):
+        print(f"Error: keyframes directory '{kf_dir}' does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    kf_files = sorted(
+        (f for f in os.listdir(kf_dir)
+         if os.path.splitext(f)[1].lower() in {".png", ".jpg", ".jpeg", ".webp"}),
+        key=natural_sort_key,
+    )
+    if len(kf_files) < 2:
+        print(f"Error: at least 2 keyframe images are required; found {len(kf_files)} in '{kf_dir}'.", file=sys.stderr)
+        sys.exit(1)
+
+    os.makedirs(args.output_dir, exist_ok=True)
+    src_dir = args.src_dir or os.path.join(os.path.dirname(args.output_dir), "seq-src")
+    os.makedirs(src_dir, exist_ok=True)
+
+    keyframes = []
+    for i, fname in enumerate(kf_files):
+        path = os.path.join(kf_dir, fname)
+        img = crop_cover_16_9(Image.open(path))
+        keyframes.append(img)
+        dest = os.path.join(src_dir, f"k{i + 1}.jpg")
+        img.save(dest, "JPEG", quality=90)
+        print(f"[keyframe] {path} -> {dest}")
+
+    n_segments = len(keyframes) - 1
+    total_frames = args.total_frames
+    seg_frames = total_frames // n_segments
+    remainder = total_frames - seg_frames * n_segments
+
+    frame_idx = 0
+    for seg in range(n_segments):
+        start_img = keyframes[seg]
+        end_img = keyframes[seg + 1]
+        count = seg_frames + (1 if seg < remainder else 0)
+        for j in range(count):
+            # When count == 1 the single frame is an unblended copy of start_img
+            # (t = 0 / 1 = 0, blend weight 0 → pure start_img).
+            t = j / max(count - 1, 1)
+            ease_t = t * t * (3.0 - 2.0 * t)
+            blended = Image.blend(start_img, end_img, ease_t)
+            dest = os.path.join(args.output_dir, f"f{frame_idx:03d}.jpg")
+            blended.save(dest, "JPEG", quality=args.quality)
+            frame_idx += 1
+
+    print(f"[done] Generated {frame_idx} frames in {args.output_dir}/")
+
+if __name__ == "__main__":
+    main()

package/scripts/inspect_images.py

@@ -0,0 +1,48 @@
+import argparse
+import os
+import sys
+
+try:
+    from PIL import Image
+except ImportError:
+    print("Pillow is required. Run:  pip install Pillow", file=sys.stderr)
+    sys.exit(1)
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".webp", ".tiff", ".bmp", ".tga"}
+
+def inspect(path):
+    try:
+        with Image.open(path) as img:
+            print(f"- {path}:  size={img.size}  format={img.format}  mode={img.mode}")
+    except Exception as e:
+        print(f"- {path}: ERROR  {e}")
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Print size, format, and colour-mode of image files."
+    )
+    parser.add_argument(
+        "paths",
+        nargs="*",
+        help=(
+            "One or more image file paths or directories. "
+            "Directories are scanned for common image extensions."
+        ),
+    )
+    args = parser.parse_args()
+
+    if not args.paths:
+        parser.print_help()
+        sys.exit(0)
+
+    print("Image Inspection:")
+    for p in args.paths:
+        if os.path.isdir(p):
+            for f in sorted(os.listdir(p)):
+                if os.path.splitext(f)[1].lower() in IMAGE_EXTENSIONS:
+                    inspect(os.path.join(p, f))
+        else:
+            inspect(p)
+
+if __name__ == "__main__":
+    main()