@jack200714/mafw 4.5.1

package/.opencode/skills/design-system/references/token-architecture.md

@@ -0,0 +1,224 @@
+# Token Architecture
+
+Three-layer token system for scalable, themeable design systems.
+
+## Layer Overview
+
+```
+┌─────────────────────────────────────────┐
+│  Component Tokens                       │  Per-component overrides
+│  --button-bg, --card-padding            │
+├─────────────────────────────────────────┤
+│  Semantic Tokens                        │  Purpose-based aliases
+│  --color-primary, --spacing-section     │
+├─────────────────────────────────────────┤
+│  Primitive Tokens                       │  Raw design values
+│  --color-blue-600, --space-4            │
+└─────────────────────────────────────────┘
+```
+
+## Why Three Layers?
+
+| Layer | Purpose | When to Change |
+|-------|---------|----------------|
+| Primitive | Base values (colors, sizes) | Rarely - foundational |
+| Semantic | Meaning assignment | Theme switching |
+| Component | Component customization | Per-component needs |
+
+## Layer 1: Primitive Tokens
+
+Raw design values without semantic meaning.
+
+```css
+:root {
+  /* Colors */
+  --color-gray-50: #F9FAFB;
+  --color-gray-900: #111827;
+  --color-blue-500: #3B82F6;
+  --color-blue-600: #2563EB;
+
+  /* Spacing (4px base) */
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-4: 1rem;     /* 16px */
+  --space-6: 1.5rem;   /* 24px */
+
+  /* Typography */
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+
+  /* Radius */
+  --radius-sm: 0.25rem;
+  --radius-default: 0.5rem;
+  --radius-lg: 0.75rem;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
+  --shadow-default: 0 1px 3px rgb(0 0 0 / 0.1);
+}
+```
+
+## Layer 2: Semantic Tokens
+
+Purpose-based aliases that reference primitives.
+
+```css
+:root {
+  /* Background */
+  --color-background: var(--color-gray-50);
+  --color-foreground: var(--color-gray-900);
+
+  /* Primary */
+  --color-primary: var(--color-blue-600);
+  --color-primary-hover: var(--color-blue-700);
+
+  /* Secondary */
+  --color-secondary: var(--color-gray-100);
+  --color-secondary-foreground: var(--color-gray-900);
+
+  /* Muted */
+  --color-muted: var(--color-gray-100);
+  --color-muted-foreground: var(--color-gray-500);
+
+  /* Destructive */
+  --color-destructive: var(--color-red-600);
+  --color-destructive-foreground: white;
+
+  /* Spacing */
+  --spacing-component: var(--space-4);
+  --spacing-section: var(--space-6);
+}
+```
+
+## Layer 3: Component Tokens
+
+Component-specific tokens referencing semantic layer.
+
+```css
+:root {
+  /* Button */
+  --button-bg: var(--color-primary);
+  --button-fg: white;
+  --button-hover-bg: var(--color-primary-hover);
+  --button-padding-x: var(--space-4);
+  --button-padding-y: var(--space-2);
+  --button-radius: var(--radius-default);
+
+  /* Input */
+  --input-bg: var(--color-background);
+  --input-border: var(--color-gray-300);
+  --input-focus-ring: var(--color-primary);
+  --input-padding: var(--space-2) var(--space-3);
+
+  /* Card */
+  --card-bg: var(--color-background);
+  --card-border: var(--color-gray-200);
+  --card-padding: var(--space-4);
+  --card-radius: var(--radius-lg);
+  --card-shadow: var(--shadow-default);
+}
+```
+
+## Dark Mode
+
+Override semantic tokens for dark theme:
+
+```css
+.dark {
+  --color-background: var(--color-gray-900);
+  --color-foreground: var(--color-gray-50);
+  --color-muted: var(--color-gray-800);
+  --color-muted-foreground: var(--color-gray-400);
+  --color-secondary: var(--color-gray-800);
+}
+```
+
+## Naming Convention
+
+```
+--{category}-{item}-{variant}-{state}
+
+Examples:
+--color-primary           # category-item
+--color-primary-hover     # category-item-state
+--button-bg-hover         # component-property-state
+--space-section-sm        # category-semantic-variant
+```
+
+## Categories
+
+| Category | Examples |
+|----------|----------|
+| color | primary, secondary, muted, destructive |
+| space | 1, 2, 4, 8, section, component |
+| font-size | xs, sm, base, lg, xl |
+| radius | sm, default, lg, full |
+| shadow | sm, default, lg |
+| duration | fast, normal, slow |
+
+## File Organization
+
+```
+tokens/
+├── primitives.css     # Raw values
+├── semantic.css       # Purpose aliases
+├── components.css     # Component tokens
+└── index.css          # Imports all
+```
+
+Or single file with layer comments:
+
+```css
+/* === PRIMITIVES === */
+:root { ... }
+
+/* === SEMANTIC === */
+:root { ... }
+
+/* === COMPONENTS === */
+:root { ... }
+
+/* === DARK MODE === */
+.dark { ... }
+```
+
+## Migration from Flat Tokens
+
+Before (flat):
+```css
+--button-primary-bg: #2563EB;
+--button-secondary-bg: #F3F4F6;
+```
+
+After (three-layer):
+```css
+/* Primitive */
+--color-blue-600: #2563EB;
+--color-gray-100: #F3F4F6;
+
+/* Semantic */
+--color-primary: var(--color-blue-600);
+--color-secondary: var(--color-gray-100);
+
+/* Component */
+--button-bg: var(--color-primary);
+--button-secondary-bg: var(--color-secondary);
+```
+
+## W3C DTCG Alignment
+
+Token JSON format (W3C Design Tokens Community Group):
+
+```json
+{
+  "color": {
+    "blue": {
+      "600": {
+        "$value": "#2563EB",
+        "$type": "color"
+      }
+    }
+  }
+}
+```

package/.opencode/skills/design-system/scripts/embed-tokens.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * embed-tokens.cjs
+ * Reads design-tokens.css and outputs embeddable inline CSS.
+ * Use when generating standalone HTML files (infographics, slides, etc.)
+ *
+ * Usage:
+ *   node embed-tokens.cjs           # Output full CSS
+ *   node embed-tokens.cjs --minimal # Output only commonly used tokens
+ *   node embed-tokens.cjs --style   # Wrap in <style> tags
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Find project root (look for assets/design-tokens.css)
+function findProjectRoot(startDir) {
+  let dir = startDir;
+  while (dir !== '/') {
+    if (fs.existsSync(path.join(dir, 'assets', 'design-tokens.css'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+const projectRoot = findProjectRoot(process.cwd());
+if (!projectRoot) {
+  console.error('Error: Could not find assets/design-tokens.css');
+  process.exit(1);
+}
+
+const tokensPath = path.join(projectRoot, 'assets', 'design-tokens.css');
+
+// Minimal tokens commonly used in infographics/slides
+const MINIMAL_TOKENS = [
+  '--primitive-spacing-',
+  '--primitive-fontSize-',
+  '--primitive-fontWeight-',
+  '--primitive-lineHeight-',
+  '--primitive-radius-',
+  '--primitive-shadow-glow-',
+  '--primitive-gradient-',
+  '--primitive-duration-',
+  '--color-primary',
+  '--color-secondary',
+  '--color-accent',
+  '--color-background',
+  '--color-surface',
+  '--color-foreground',
+  '--color-border',
+  '--typography-font-',
+  '--card-',
+];
+
+function extractTokens(css, minimal = false) {
+  // Extract :root block
+  const rootMatch = css.match(/:root\s*\{([^}]+)\}/g);
+  if (!rootMatch) return '';
+
+  let allVars = [];
+  for (const block of rootMatch) {
+    const vars = block.match(/--[\w-]+:\s*[^;]+;/g) || [];
+    allVars = allVars.concat(vars);
+  }
+
+  if (minimal) {
+    allVars = allVars.filter(v =>
+      MINIMAL_TOKENS.some(token => v.includes(token))
+    );
+  }
+
+  // Dedupe
+  allVars = [...new Set(allVars)];
+
+  return `:root {\n  ${allVars.join('\n  ')}\n}`;
+}
+
+// Parse args
+const args = process.argv.slice(2);
+const minimal = args.includes('--minimal');
+const wrapStyle = args.includes('--style');
+
+try {
+  const css = fs.readFileSync(tokensPath, 'utf-8');
+  let output = extractTokens(css, minimal);
+
+  if (wrapStyle) {
+    output = `<style>\n/* Design Tokens (embedded for standalone HTML) */\n${output}\n</style>`;
+  } else {
+    output = `/* Design Tokens (embedded for standalone HTML) */\n${output}`;
+  }
+
+  console.log(output);
+} catch (err) {
+  console.error(`Error reading tokens: ${err.message}`);
+  process.exit(1);
+}

package/.opencode/skills/design-system/scripts/fetch-background.py

@@ -0,0 +1,317 @@
+#!/usr/bin/env python3
+"""
+Background Image Fetcher
+Fetches real images from Pexels for slide backgrounds.
+Uses web scraping (no API key required) or WebFetch tool integration.
+"""
+
+import json
+import csv
+import re
+import sys
+from pathlib import Path
+
+# Project root relative to this script
+PROJECT_ROOT = Path(__file__).parent.parent.parent.parent.parent
+TOKENS_PATH = PROJECT_ROOT / 'assets' / 'design-tokens.json'
+BACKGROUNDS_CSV = Path(__file__).parent.parent / 'data' / 'slide-backgrounds.csv'
+
+
+def resolve_token_reference(ref: str, tokens: dict) -> str:
+    """Resolve token reference like {primitive.color.ocean-blue.500} to hex value."""
+    if not ref or not ref.startswith('{') or not ref.endswith('}'):
+        return ref  # Already a value, not a reference
+
+    # Parse reference: {primitive.color.ocean-blue.500}
+    path = ref[1:-1].split('.')  # ['primitive', 'color', 'ocean-blue', '500']
+    current = tokens
+    for key in path:
+        if isinstance(current, dict):
+            current = current.get(key)
+        else:
+            return None  # Invalid path
+    # Return $value if it's a token object
+    if isinstance(current, dict) and '$value' in current:
+        return current['$value']
+    return current
+
+
+def load_brand_colors():
+    """Load colors from assets/design-tokens.json for overlay gradients.
+
+    Resolves semantic token references to actual hex values.
+    """
+    try:
+        with open(TOKENS_PATH) as f:
+            tokens = json.load(f)
+
+        colors = tokens.get('primitive', {}).get('color', {})
+        semantic = tokens.get('semantic', {}).get('color', {})
+
+        # Try semantic tokens first (preferred) - resolve references
+        if semantic:
+            primary_ref = semantic.get('primary', {}).get('$value')
+            secondary_ref = semantic.get('secondary', {}).get('$value')
+            accent_ref = semantic.get('accent', {}).get('$value')
+            background_ref = semantic.get('background', {}).get('$value')
+
+            primary = resolve_token_reference(primary_ref, tokens)
+            secondary = resolve_token_reference(secondary_ref, tokens)
+            accent = resolve_token_reference(accent_ref, tokens)
+            background = resolve_token_reference(background_ref, tokens)
+
+            if primary and secondary:
+                return {
+                    'primary': primary,
+                    'secondary': secondary,
+                    'accent': accent or primary,
+                    'background': background or '#0D0D0D',
+                }
+
+        # Fallback: find first color palette with 500 value (primary)
+        primary_keys = ['ocean-blue', 'coral', 'blue', 'primary']
+        secondary_keys = ['golden-amber', 'purple', 'amber', 'secondary']
+        accent_keys = ['emerald', 'mint', 'green', 'accent']
+
+        primary_color = None
+        secondary_color = None
+        accent_color = None
+
+        for key in primary_keys:
+            if key in colors and isinstance(colors[key], dict):
+                primary_color = colors[key].get('500', {}).get('$value')
+                if primary_color:
+                    break
+
+        for key in secondary_keys:
+            if key in colors and isinstance(colors[key], dict):
+                secondary_color = colors[key].get('500', {}).get('$value')
+                if secondary_color:
+                    break
+
+        for key in accent_keys:
+            if key in colors and isinstance(colors[key], dict):
+                accent_color = colors[key].get('500', {}).get('$value')
+                if accent_color:
+                    break
+
+        background = colors.get('dark', {}).get('800', {}).get('$value', '#0D0D0D')
+
+        return {
+            'primary': primary_color or '#3B82F6',
+            'secondary': secondary_color or '#F59E0B',
+            'accent': accent_color or '#10B981',
+            'background': background,
+        }
+    except (FileNotFoundError, KeyError, TypeError):
+        # Fallback defaults
+        return {
+            'primary': '#3B82F6',
+            'secondary': '#F59E0B',
+            'accent': '#10B981',
+            'background': '#0D0D0D',
+        }
+
+
+def load_backgrounds_config():
+    """Load background configuration from CSV."""
+    config = {}
+    try:
+        with open(BACKGROUNDS_CSV, newline='') as f:
+            reader = csv.DictReader(f)
+            for row in reader:
+                config[row['slide_type']] = row
+    except FileNotFoundError:
+        print(f"Warning: {BACKGROUNDS_CSV} not found")
+    return config
+
+
+def get_overlay_css(style: str, brand_colors: dict) -> str:
+    """Generate overlay CSS using brand colors from design-tokens.json."""
+    overlays = {
+        'gradient-dark': f"linear-gradient(135deg, {brand_colors['background']}E6, {brand_colors['background']}B3)",
+        'gradient-brand': f"linear-gradient(135deg, {brand_colors['primary']}CC, {brand_colors['secondary']}99)",
+        'gradient-accent': f"linear-gradient(135deg, {brand_colors['accent']}99, transparent)",
+        'blur-dark': f"rgba(13,13,13,0.8)",
+        'desaturate-dark': f"rgba(13,13,13,0.7)",
+    }
+    return overlays.get(style, overlays['gradient-dark'])
+
+
+# Curated high-quality images from Pexels (free to use, pre-selected for brand aesthetic)
+CURATED_IMAGES = {
+    'hero': [
+        'https://images.pexels.com/photos/3861969/pexels-photo-3861969.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/2582937/pexels-photo-2582937.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/1089438/pexels-photo-1089438.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'vision': [
+        'https://images.pexels.com/photos/3183150/pexels-photo-3183150.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3182812/pexels-photo-3182812.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3184291/pexels-photo-3184291.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'team': [
+        'https://images.pexels.com/photos/3184418/pexels-photo-3184418.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3184338/pexels-photo-3184338.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3182773/pexels-photo-3182773.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'testimonial': [
+        'https://images.pexels.com/photos/3184465/pexels-photo-3184465.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/1181622/pexels-photo-1181622.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'cta': [
+        'https://images.pexels.com/photos/3184339/pexels-photo-3184339.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3184298/pexels-photo-3184298.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'problem': [
+        'https://images.pexels.com/photos/3760529/pexels-photo-3760529.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/897817/pexels-photo-897817.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'solution': [
+        'https://images.pexels.com/photos/3184292/pexels-photo-3184292.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3184644/pexels-photo-3184644.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'hook': [
+        'https://images.pexels.com/photos/2582937/pexels-photo-2582937.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/1089438/pexels-photo-1089438.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'social': [
+        'https://images.pexels.com/photos/3184360/pexels-photo-3184360.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3184287/pexels-photo-3184287.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+    'demo': [
+        'https://images.pexels.com/photos/1181675/pexels-photo-1181675.jpeg?auto=compress&cs=tinysrgb&w=1920',
+        'https://images.pexels.com/photos/3861958/pexels-photo-3861958.jpeg?auto=compress&cs=tinysrgb&w=1920',
+    ],
+}
+
+
+def get_curated_images(slide_type: str) -> list:
+    """Get curated images for slide type."""
+    return CURATED_IMAGES.get(slide_type, CURATED_IMAGES.get('hero', []))
+
+
+def get_pexels_search_url(keywords: str) -> str:
+    """Generate Pexels search URL for manual lookup."""
+    import urllib.parse
+    return f"https://www.pexels.com/search/{urllib.parse.quote(keywords)}/"
+
+
+def get_background_image(slide_type: str) -> dict:
+    """
+    Get curated image matching slide type and brand aesthetic.
+    Uses pre-selected Pexels images (no API/scraping needed).
+    """
+    brand_colors = load_brand_colors()
+    config = load_backgrounds_config()
+
+    slide_config = config.get(slide_type)
+    overlay_style = 'gradient-dark'
+    keywords = slide_type
+
+    if slide_config:
+        keywords = slide_config.get('search_keywords', slide_config.get('image_category', slide_type))
+        overlay_style = slide_config.get('overlay_style', 'gradient-dark')
+
+    # Get curated images
+    urls = get_curated_images(slide_type)
+    if urls:
+        return {
+            'url': urls[0],
+            'all_urls': urls,
+            'overlay': get_overlay_css(overlay_style, brand_colors),
+            'attribution': 'Photo from Pexels (free to use)',
+            'source': 'pexels-curated',
+            'search_url': get_pexels_search_url(keywords),
+        }
+
+    # Fallback: provide search URL for manual selection
+    return {
+        'url': None,
+        'overlay': get_overlay_css(overlay_style, brand_colors),
+        'keywords': keywords,
+        'search_url': get_pexels_search_url(keywords),
+        'available_types': list(CURATED_IMAGES.keys()),
+    }
+
+
+def generate_css_for_background(result: dict, slide_class: str = '.slide-with-bg') -> str:
+    """Generate CSS for a background slide."""
+    if not result.get('url'):
+        search_url = result.get('search_url', '')
+        return f"""/* No image scraped. Search manually: {search_url} */
+/* Overlay ready: {result.get('overlay', 'gradient-dark')} */
+"""
+
+    return f"""{slide_class} {{
+    background-image: url('{result['url']}');
+    background-size: cover;
+    background-position: center;
+    position: relative;
+}}
+
+{slide_class}::before {{
+    content: '';
+    position: absolute;
+    inset: 0;
+    background: {result['overlay']};
+}}
+
+{slide_class} .content {{
+    position: relative;
+    z-index: 1;
+}}
+
+/* {result.get('attribution', 'Pexels')} - {result.get('search_url', '')} */
+"""
+
+
+def main():
+    """CLI entry point."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description='Get background images for slides')
+    parser.add_argument('slide_type', nargs='?', help='Slide type (hero, vision, team, etc.)')
+    parser.add_argument('--list', action='store_true', help='List available slide types')
+    parser.add_argument('--css', action='store_true', help='Output CSS for the background')
+    parser.add_argument('--json', action='store_true', help='Output JSON')
+    parser.add_argument('--colors', action='store_true', help='Show brand colors')
+    parser.add_argument('--all', action='store_true', help='Show all curated URLs')
+
+    args = parser.parse_args()
+
+    if args.colors:
+        colors = load_brand_colors()
+        print("\nBrand Colors (from design-tokens.json):")
+        for name, value in colors.items():
+            print(f"  {name}: {value}")
+        return
+
+    if args.list:
+        print("\nAvailable slide types (curated images):")
+        for slide_type, urls in CURATED_IMAGES.items():
+            print(f"  {slide_type}: {len(urls)} images")
+        return
+
+    if not args.slide_type:
+        parser.print_help()
+        return
+
+    result = get_background_image(args.slide_type)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    elif args.css:
+        print(generate_css_for_background(result))
+    elif args.all:
+        print(f"\nAll images for '{args.slide_type}':")
+        for i, url in enumerate(result.get('all_urls', []), 1):
+            print(f"  {i}. {url}")
+    else:
+        print(f"\nImage URL: {result['url']}")
+        print(f"Alternatives: {len(result.get('all_urls', []))} available (use --all)")
+        print(f"Overlay: {result['overlay']}")
+
+
+if __name__ == '__main__':
+    main()