@tidyfactor/design 1.5.0

package/scripts/test_build.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""
+Extended Build Integrity & Quality Test Suite
+Checks files, broken local links, duplicate IDs, accessibility (alt tags, ARIA attributes),
+and external CDNs to ensure production-grade deployment quality.
+
+Exit Codes:
+    0 = Success
+    1 = Test Failures Found
+"""
+
+import re
+import sys
+from pathlib import Path
+
+# Project root is the parent directory of this script
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+
+
+class TestSuite:
+    def __init__(self):
+        self.failures = []
+        self.warnings = []
+
+    def log_failure(self, message):
+        self.failures.append(message)
+
+    def log_warning(self, message):
+        self.warnings.append(message)
+
+    def run_tests(self):
+        print("="*60)
+        print("         RUNNING EXTENDED BUILD INTEGRITY TESTS")
+        print("="*60)
+
+        self.test_production_files_exist()
+        self.test_index_html_links()
+        self.test_css_urls()
+        self.test_duplicate_ids()
+        self.test_accessibility()
+        self.test_external_cdn_dependencies()
+
+        print("\n" + "="*60)
+        print("TEST RESULTS SUMMARY")
+        print("="*60)
+        
+        if self.failures:
+            print(f"\n[FAIL] {len(self.failures)} TEST FAILURE(S) FOUND:")
+            for fail in self.failures:
+                print(f"  - [FAIL] {fail}")
+        else:
+            print("\n[SUCCESS] ALL INTEGRITY AND ACCESSIBILITY TESTS PASSED SUCCESSFULLY!")
+
+        if self.warnings:
+            print(f"\n[WARN] {len(self.warnings)} WARNING(S) ENCOUNTERED:")
+            for warn in self.warnings:
+                print(f"  - [WARN] {warn}")
+
+        print("="*60)
+        return len(self.failures) == 0
+
+    # 1. Check generated minified CSS and JS exist
+    def test_production_files_exist(self):
+        print("\n[TEST] Verifying production minified files exist...")
+        required_files = [
+            "assets/css/style.min.css",
+            "assets/js/bundle.min.js"
+        ]
+        
+        for rel_path in required_files:
+            file_path = PROJECT_ROOT / rel_path
+            if not file_path.exists():
+                self.log_failure(f"Production file is missing: {rel_path}")
+            elif file_path.stat().st_size == 0:
+                self.log_failure(f"Production file is empty: {rel_path}")
+            else:
+                print(f"  [OK] {rel_path} is present ({file_path.stat().st_size} bytes)")
+
+    # 2. Check broken local links in index.html
+    def test_index_html_links(self):
+        print("\n[TEST] Scanning index.html for broken local asset links...")
+        index_path = PROJECT_ROOT / "index.html"
+        if not index_path.exists():
+            self.log_failure("index.html does not exist in project root!")
+            return
+
+        with open(index_path, "r", encoding="utf-8") as f:
+            html = f.read()
+
+        # Regex patterns to find local files (excluding external http/https/double slash)
+        patterns = {
+            "stylesheets": r'<link[^>]*href=["\'](?!https?:\/\/|\/\/)([^"\']+)["\']',
+            "scripts": r'<script[^>]*src=["\'](?!https?:\/\/|\/\/)([^"\']+)["\']',
+            "images": r'<img[^>]*src=["\'](?!https?:\/\/|\/\/)([^"\']+)["\']',
+            "video_sources": r'<source[^>]*src=["\'](?!https?:\/\/|\/\/)([^"\']+)["\']',
+            "video_posters": r'<video[^>]*poster=["\'](?!https?:\/\/|\/\/)([^"\']+)["\']'
+        }
+
+        for category, regex in patterns.items():
+            matches = re.findall(regex, html)
+            print(f"  Checking {len(matches)} local {category} references...")
+            for match in matches:
+                # Remove version query string if present (e.g. ?v=2.1.3)
+                clean_path = match.split("?")[0]
+                
+                # Exclude mailto, tel, or hash links
+                if clean_path.startswith(("#", "mailto:", "tel:", "javascript:")) or not clean_path.strip():
+                    continue
+
+                full_path = PROJECT_ROOT / clean_path
+                if not full_path.exists():
+                    self.log_failure(f"Broken {category} link in index.html: '{clean_path}' does not exist on disk.")
+
+    # 3. Check assets referenced in CSS via url()
+    def test_css_urls(self):
+        print("\n[TEST] Scanning style.css for broken url() links...")
+        css_path = PROJECT_ROOT / "assets/css/style.css"
+        if not css_path.exists():
+            self.log_failure("assets/css/style.css is missing!")
+            return
+
+        with open(css_path, "r", encoding="utf-8") as f:
+            css = f.read()
+
+        # Find all url(...) patterns
+        urls = re.findall(r'url\([\'"]?([^\'"\)]+)[\'"]?\)', css)
+        css_dir = css_path.parent
+        print(f"  Checking {len(urls)} url() links inside CSS...")
+
+        for url in urls:
+            # Skip external fonts, data URIs, or anchor links
+            if url.startswith(("http://", "https://", "//", "data:")) or not url.strip():
+                continue
+
+            # CSS urls are relative to the CSS file itself
+            resolved_path = (css_dir / url.split("?")[0]).resolve()
+            if not resolved_path.exists():
+                self.log_failure(f"Broken link in style.css url(): '{url}' (resolved to '{resolved_path.relative_to(PROJECT_ROOT)}') does not exist.")
+
+    # 4. Check for duplicate element IDs in index.html
+    def test_duplicate_ids(self):
+        print("\n[TEST] Auditing index.html for duplicate element IDs...")
+        index_path = PROJECT_ROOT / "index.html"
+        if not index_path.exists():
+            return
+
+        with open(index_path, "r", encoding="utf-8") as f:
+            html = f.read()
+
+        ids = re.findall(r'id=["\']([^"\']+)["\']', html)
+        seen_ids = {}
+        for elem_id in ids:
+            seen_ids[elem_id] = seen_ids.get(elem_id, 0) + 1
+
+        duplicates = {k: v for k, v in seen_ids.items() if v > 1}
+        
+        if duplicates:
+            for k, v in duplicates.items():
+                self.log_failure(f"Duplicate element ID found: '#{k}' appears {v} times in HTML.")
+        else:
+            print(f"  [OK] Checked {len(ids)} element IDs. No duplicates found.")
+
+    # 5. Accessibility Audit (alt attributes, ARIA roles, Heading levels)
+    def test_accessibility(self):
+        print("\n[TEST] Auditing accessibility (alt tags, ARIA attributes, headings)...")
+        index_path = PROJECT_ROOT / "index.html"
+        if not index_path.exists():
+            return
+
+        with open(index_path, "r", encoding="utf-8") as f:
+            html = f.read()
+
+        # 5.1 Check img alt attributes
+        images = re.findall(r'<img([^>]*src=["\']([^"\']+)["\']([^>]*))>', html)
+        print(f"  Auditing {len(images)} images for screen reader alt tags...")
+        for img_tag, src, _ in images:
+            if "alt=" not in img_tag:
+                self.log_failure(f"Image tag is missing required 'alt' attribute: src='{src}'")
+
+        # 5.2 Check single h1 tag outline
+        h1s = re.findall(r'<h1[^>]*>.*?</h1>', html, re.DOTALL)
+        if len(h1s) != 1:
+            self.log_failure(f"SEO/Outline mismatch: index.html must have exactly one <h1> tag (found {len(h1s)}).")
+        else:
+            print("  [OK] Document contains exactly one <h1> tag.")
+
+        # 5.3 Verify critical interactive element accessibility properties
+        # Hamburger checks
+        hamburger = re.search(r'<button[^>]*id=["\']hamburger["\'][^>]*>', html)
+        if hamburger:
+            tag = hamburger.group(0)
+            if "aria-expanded=" not in tag or "aria-controls=" not in tag or "aria-label=" not in tag:
+                self.log_failure("Interactive Hamburger menu button is missing vital accessibility attributes (aria-expanded, aria-controls, or aria-label).")
+            else:
+                print("  [OK] Hamburger menu accessibility attributes are correct.")
+        
+        # Interactive dots check
+        dots = re.findall(r'<div[^>]*class=["\']process__dot["\'][^>]*>', html)
+        for i, dot_tag in enumerate(dots):
+            if 'role="button"' not in dot_tag or 'tabindex="0"' not in dot_tag or 'aria-label=' not in dot_tag:
+                self.log_failure(f"Process step indicator dot {i+1} is missing vital accessibility attributes (role=\"button\", tabindex=\"0\", or aria-label).")
+
+    # 6. Audit for unauthorized external CDN scripts
+    def test_external_cdn_dependencies(self):
+        print("\n[TEST] Auditing for external CDN script dependencies...")
+        index_path = PROJECT_ROOT / "index.html"
+        if not index_path.exists():
+            return
+
+        with open(index_path, "r", encoding="utf-8") as f:
+            html = f.read()
+
+        # Search for scripts with external http/https/double-slash sources
+        cdn_scripts = re.findall(r'<script[^>]*src=["\'](https?:\/\/|\/\/)([^"\']+)["\']', html)
+        
+        # Check if any external CDN JS scripts exist
+        if cdn_scripts:
+            for protocol, url in cdn_scripts:
+                # We flag external CDN JS scripts as failures because local versions are required
+                self.log_failure(f"External script CDN dependency detected: '{protocol}{url}'. Only local assets are allowed.")
+        else:
+            print("  [OK] No external CDN JavaScript script tags detected. Fully self-contained local stack.")
+
+
+if __name__ == "__main__":
+    suite = TestSuite()
+    success = suite.run_tests()
+    sys.exit(0 if success else 1)

package/templates/design-system/base.css

@@ -0,0 +1,75 @@
+/* ==========================================================================
+   TidyFactor Design System — Base CSS (base.css)
+   CSS Reset, element defaults, typography rules, & logical properties
+   ========================================================================== */
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  font-size: 16px;
+  scroll-behavior: smooth;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  background-color: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+  font-size: var(--text-base);
+  line-height: 1.6;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  transition: background-color var(--duration-base) var(--ease-out-quint),
+              color var(--duration-base) var(--ease-out-quint);
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-heading);
+  color: var(--color-text);
+  font-weight: 700;
+  line-height: 1.25;
+  margin-bottom: var(--space-4);
+}
+
+h1 { font-size: var(--text-4xl); }
+h2 { font-size: var(--text-3xl); }
+h3 { font-size: var(--text-2xl); }
+h4 { font-size: var(--text-xl); }
+
+a {
+  color: var(--color-primary);
+  text-decoration: none;
+  transition: color var(--duration-fast) ease;
+}
+
+a:hover {
+  color: var(--color-primary-hover);
+}
+
+img, svg, video {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+
+button, input, select, textarea {
+  font: inherit;
+  color: inherit;
+}
+
+/* RTL Logical Properties Support */
+[dir="rtl"] {
+  text-align: right;
+}
+
+:focus-visible {
+  outline: none;
+  box-shadow: var(--shadow-focus);
+}

package/templates/design-system/components.css

@@ -0,0 +1,229 @@
+/* ==========================================================================
+   TidyFactor Design System — Component Library (components.css)
+   Reusable UI components (buttons, cards, bento grids, badges, navbars)
+   ========================================================================== */
+
+/* Containers & Layout System */
+.container {
+  width: 100%;
+  max-width: 1280px;
+  margin-inline: auto;
+  padding-inline: var(--space-6);
+}
+
+.grid-12 {
+  display: grid;
+  grid-template-columns: repeat(12, 1fr);
+  gap: var(--space-6);
+}
+
+/* Button Component Suite */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  padding: var(--space-3) var(--space-6);
+  font-weight: 600;
+  font-size: var(--text-sm);
+  border-radius: var(--radius-md);
+  border: 1px solid transparent;
+  cursor: pointer;
+  transition: all var(--duration-fast) var(--ease-out-quint);
+  user-select: none;
+}
+
+.btn:active {
+  transform: scale(0.98);
+}
+
+.btn-primary {
+  background-color: var(--color-primary);
+  color: #FFFFFF;
+}
+
+.btn-primary:hover {
+  background-color: var(--color-primary-hover);
+  box-shadow: var(--shadow-md);
+}
+
+.btn-secondary {
+  background-color: var(--color-surface-subtle);
+  color: var(--color-text);
+  border-color: var(--color-border);
+}
+
+.btn-secondary:hover {
+  background-color: var(--color-border);
+}
+
+.btn-outline {
+  background-color: transparent;
+  color: var(--color-text);
+  border-color: var(--color-border);
+}
+
+.btn-outline:hover {
+  background-color: var(--color-surface-subtle);
+  border-color: var(--color-primary);
+}
+
+/* Card & Surface Components */
+.card {
+  background-color: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-xl);
+  padding: var(--space-6);
+  box-shadow: var(--shadow-sm);
+  transition: transform var(--duration-base) var(--ease-out-quint),
+              box-shadow var(--duration-base) var(--ease-out-quint);
+}
+
+.card:hover {
+  box-shadow: var(--shadow-md);
+  transform: translateY(-2px);
+}
+
+/* Bento Box Grid Component */
+.bento-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+  gap: var(--space-6);
+}
+
+.bento-tile {
+  background-color: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-2xl);
+  padding: var(--space-8);
+  box-shadow: var(--shadow-sm);
+  position: relative;
+  overflow: hidden;
+  transition: transform var(--duration-base) var(--ease-out-quint);
+}
+
+.bento-tile:hover {
+  transform: translateY(-4px);
+  box-shadow: var(--shadow-lg);
+}
+
+/* Badges & Pills */
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  padding: var(--space-1) var(--space-3);
+  font-size: var(--text-xs);
+  font-weight: 600;
+  border-radius: var(--radius-full);
+  background-color: var(--color-primary-light);
+  color: var(--color-primary);
+  border: 1px solid color-mix(in srgb, var(--color-primary) 30%, transparent);
+}
+
+/* Header & Navbar Pill */
+.navbar {
+  position: sticky;
+  top: var(--space-4);
+  z-index: 100;
+  background-color: color-mix(in srgb, var(--color-surface) 85%, transparent);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-2xl);
+  padding: var(--space-3) var(--space-6);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  box-shadow: var(--shadow-md);
+}
+
+.nav-links {
+  display: flex;
+  gap: var(--space-6);
+  list-style: none;
+}
+
+.nav-link {
+  color: var(--color-text-muted);
+  font-weight: 500;
+  font-size: var(--text-sm);
+}
+
+.nav-link:hover, .nav-link.active {
+  color: var(--color-primary);
+}
+
+/* Hero Section */
+.hero {
+  padding-block: var(--space-16);
+  text-align: center;
+}
+
+.hero-title {
+  font-size: clamp(2.5rem, 6vw, 4.5rem);
+  letter-spacing: -0.02em;
+  margin-bottom: var(--space-4);
+}
+
+.hero-subtitle {
+  font-size: var(--text-xl);
+  color: var(--color-text-muted);
+  max-width: 700px;
+  margin-inline: auto;
+  margin-bottom: var(--space-8);
+}
+
+/* Neobrutalism Signature Component Suite */
+.sticker-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: 0.25rem 0.75rem;
+  font-size: var(--text-xs);
+  font-weight: 800;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  border-radius: var(--radius-md);
+  border: 2px solid #000000;
+  box-shadow: 2px 2px 0px 0px #000000;
+  background-color: var(--color-primary);
+  color: #FFFFFF;
+}
+
+.card-neobrutal {
+  background-color: var(--color-surface);
+  border: 3px solid #000000;
+  border-radius: var(--radius-lg);
+  box-shadow: 6px 6px 0px 0px #000000;
+  padding: var(--space-6);
+  transition: transform var(--duration-fast) var(--ease-out-quint), box-shadow var(--duration-fast) var(--ease-out-quint);
+}
+
+.card-neobrutal:hover {
+  transform: translate(-2px, -2px);
+  box-shadow: 8px 8px 0px 0px #000000;
+}
+
+.github-social-card {
+  background-color: #0D1117;
+  border: 2px solid #000000;
+  border-radius: var(--radius-lg);
+  color: #F0F6FC;
+  padding: var(--space-4);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+
+.metric-strip {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  border-top: 3px solid #000000;
+  border-bottom: 3px solid #000000;
+  background-color: var(--color-surface);
+}
+
+.metric-item {
+  padding: var(--space-4) var(--space-6);
+  text-align: center;
+  border-inline-end: 2px solid color-mix(in srgb, var(--color-border) 40%, transparent);
+}

package/templates/design-system/interactions.js

@@ -0,0 +1,31 @@
+/**
+ * TidyFactor Design System — Shared UI Interactions (interactions.js)
+ */
+document.addEventListener('DOMContentLoaded', () => {
+  // Theme Toggle Handler
+  const themeToggles = document.querySelectorAll('[data-theme-toggle]');
+  themeToggles.forEach(toggle => {
+    toggle.addEventListener('click', () => {
+      const currentTheme = document.documentElement.getAttribute('data-theme') || 'light';
+      const nextTheme = currentTheme === 'dark' ? 'light' : 'dark';
+      document.documentElement.setAttribute('data-theme', nextTheme);
+      localStorage.setItem('tf-theme', nextTheme);
+    });
+  });
+
+  // Restore saved theme preference
+  const savedTheme = localStorage.getItem('tf-theme');
+  if (savedTheme) {
+    document.documentElement.setAttribute('data-theme', savedTheme);
+  }
+
+  // Direction (RTL / LTR) Toggle Handler
+  const dirToggles = document.querySelectorAll('[data-dir-toggle]');
+  dirToggles.forEach(toggle => {
+    toggle.addEventListener('click', () => {
+      const currentDir = document.documentElement.getAttribute('dir') || 'ltr';
+      const nextDir = currentDir === 'rtl' ? 'ltr' : 'rtl';
+      document.documentElement.setAttribute('dir', nextDir);
+    });
+  });
+});

package/templates/design-system/motion.js

@@ -0,0 +1,42 @@
+/**
+ * TidyFactor Design System — Motion & Reveal Choreography (motion.js)
+ */
+document.addEventListener('DOMContentLoaded', () => {
+  // Check prefers-reduced-motion
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  if (prefersReducedMotion) return;
+
+  const revealElements = document.querySelectorAll('[data-reveal]');
+  
+  const observerOptions = {
+    root: null,
+    rootMargin: '0px',
+    threshold: 0.15
+  };
+
+  const observer = new IntersectionObserver((entries, observer) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        entry.target.classList.add('is-revealed');
+        observer.unobserve(entry.target);
+      }
+    });
+  }, observerOptions);
+
+  revealElements.forEach(el => {
+    el.style.opacity = '0';
+    el.style.transform = 'translateY(20px)';
+    el.style.transition = 'opacity 400ms cubic-bezier(0.16, 1, 0.3, 1), transform 400ms cubic-bezier(0.16, 1, 0.3, 1)';
+    observer.observe(el);
+  });
+
+  // Inject active class styles dynamically
+  const style = document.createElement('style');
+  style.textContent = `
+    [data-reveal].is-revealed {
+      opacity: 1 !important;
+      transform: translateY(0) !important;
+    }
+  `;
+  document.head.appendChild(style);
+});

package/templates/design-system/tokens.css

@@ -0,0 +1,81 @@
+/* ==========================================================================
+   TidyFactor Design System — Design Tokens (tokens.css)
+   Single Source of Truth for visual variables, colors, typography, & motion
+   ========================================================================== */
+
+:root {
+  /* Brand Primary Colors */
+  --color-primary: #4F46E5;
+  --color-primary-hover: #4338CA;
+  --color-primary-light: #EEF2FF;
+  --color-secondary: #06B6D4;
+  --color-accent: #F59E0B;
+
+  /* Light Theme Surfaces & Text */
+  --color-bg: #F8FAFC;
+  --color-surface: #FFFFFF;
+  --color-surface-subtle: #F1F5F9;
+  --color-text: #0F172A;
+  --color-text-muted: #64748B;
+  --color-border: #E2E8F0;
+
+  /* Typography Scale */
+  --font-heading: 'El Messiri', 'Outfit', sans-serif;
+  --font-body: 'Tajawal', 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+  --text-4xl: 2.25rem;
+  --text-5xl: 3rem;
+
+  /* Spacing System */
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-6: 1.5rem;
+  --space-8: 2rem;
+  --space-12: 3rem;
+  --space-16: 4rem;
+  --space-24: 6rem;
+
+  /* Border Radii */
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+  --radius-2xl: 1.5rem;
+  --radius-full: 9999px;
+
+  /* Elevation Shadows */
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
+  --shadow-focus: 0 0 0 3px color-mix(in srgb, var(--color-primary) 40%, transparent);
+
+  /* Motion Timing */
+  --duration-fast: 150ms;
+  --duration-base: 250ms;
+  --duration-slow: 400ms;
+  --ease-out-quint: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+/* Dark Theme Overrides */
+[data-theme="dark"] {
+  --color-bg: #0F172A;
+  --color-surface: #1E293B;
+  --color-surface-subtle: #334155;
+  --color-text: #F8FAFC;
+  --color-text-muted: #94A3B8;
+  --color-border: #334155;
+  --color-primary-light: rgba(79, 70, 229, 0.2);
+  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.4);
+  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);
+  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.5);
+}