constellai 0.3.0

package/skills/design/uupm-brand/scripts/validate-asset.cjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+/**
+ * validate-asset.cjs
+ *
+ * Validates marketing assets against brand guidelines.
+ * Checks: file naming, dimensions, file size, metadata.
+ *
+ * Usage:
+ *   node validate-asset.cjs <asset-path>
+ *   node validate-asset.cjs <asset-path> --json
+ *   node validate-asset.cjs <asset-path> --fix
+ *
+ * For color validation of images, use with extract-colors.cjs
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// Validation rules
+const RULES = {
+  naming: {
+    pattern: /^[a-z]+_[a-z0-9-]+_[a-z0-9-]+_\d{8}(_[a-z0-9-]+)?\.[a-z]+$/,
+    description:
+      "{type}_{campaign}_{description}_{timestamp}_{variant}.{ext}",
+    examples: [
+      "banner_claude-launch_hero-image_20251209.png",
+      "logo_brand-refresh_horizontal_20251209_dark.svg",
+    ],
+  },
+  dimensions: {
+    banner: { minWidth: 600, minHeight: 300 },
+    logo: { minWidth: 100, minHeight: 100 },
+    design: { minWidth: 800, minHeight: 600 },
+    video: { minWidth: 640, minHeight: 480 },
+    default: { minWidth: 100, minHeight: 100 },
+  },
+  fileSize: {
+    image: { max: 5 * 1024 * 1024, recommended: 1 * 1024 * 1024 },
+    video: { max: 100 * 1024 * 1024, recommended: 50 * 1024 * 1024 },
+    svg: { max: 500 * 1024, recommended: 100 * 1024 },
+  },
+  formats: {
+    image: ["png", "jpg", "jpeg", "webp", "gif"],
+    vector: ["svg"],
+    video: ["mp4", "mov", "webm"],
+    document: ["pdf", "psd", "ai", "fig"],
+  },
+};
+
+/**
+ * Parse asset filename
+ */
+function parseFilename(filename) {
+  const parts = filename.replace(/\.[^.]+$/, "").split("_");
+
+  if (parts.length < 4) {
+    return null;
+  }
+
+  return {
+    type: parts[0],
+    campaign: parts[1],
+    description: parts[2],
+    timestamp: parts[3],
+    variant: parts.length > 4 ? parts[4] : null,
+    extension: path.extname(filename).slice(1).toLowerCase(),
+  };
+}
+
+/**
+ * Validate filename convention
+ */
+function validateFilename(filename) {
+  const issues = [];
+  const suggestions = [];
+
+  // Check pattern match
+  if (!RULES.naming.pattern.test(filename)) {
+    issues.push("Filename does not match naming convention");
+    suggestions.push(`Expected format: ${RULES.naming.description}`);
+    suggestions.push(`Examples: ${RULES.naming.examples.join(", ")}`);
+  }
+
+  // Parse and check components
+  const parsed = parseFilename(filename);
+  if (parsed) {
+    // Check timestamp format
+    if (!/^\d{8}$/.test(parsed.timestamp)) {
+      issues.push("Timestamp should be YYYYMMDD format");
+    }
+
+    // Check kebab-case for campaign and description
+    if (parsed.campaign && !/^[a-z0-9-]+$/.test(parsed.campaign)) {
+      issues.push("Campaign name should be kebab-case");
+    }
+
+    if (parsed.description && !/^[a-z0-9-]+$/.test(parsed.description)) {
+      issues.push("Description should be kebab-case");
+    }
+
+    // Check valid type
+    const validTypes = [
+      "banner",
+      "logo",
+      "design",
+      "video",
+      "infographic",
+      "icon",
+      "photo",
+    ];
+    if (!validTypes.includes(parsed.type)) {
+      suggestions.push(`Consider using type: ${validTypes.join(", ")}`);
+    }
+  }
+
+  return { valid: issues.length === 0, issues, suggestions, parsed };
+}
+
+/**
+ * Validate file size
+ */
+function validateFileSize(filepath, extension) {
+  const issues = [];
+  const warnings = [];
+
+  const stats = fs.statSync(filepath);
+  const size = stats.size;
+
+  let limits;
+  if (RULES.formats.video.includes(extension)) {
+    limits = RULES.fileSize.video;
+  } else if (extension === "svg") {
+    limits = RULES.fileSize.svg;
+  } else {
+    limits = RULES.fileSize.image;
+  }
+
+  if (size > limits.max) {
+    issues.push(
+      `File size (${formatBytes(size)}) exceeds maximum (${formatBytes(
+        limits.max
+      )})`
+    );
+  } else if (size > limits.recommended) {
+    warnings.push(
+      `File size (${formatBytes(size)}) exceeds recommended (${formatBytes(
+        limits.recommended
+      )})`
+    );
+  }
+
+  return { valid: issues.length === 0, issues, warnings, size };
+}
+
+/**
+ * Validate file format
+ */
+function validateFormat(extension) {
+  const issues = [];
+  const info = { category: null };
+
+  const allFormats = [
+    ...RULES.formats.image,
+    ...RULES.formats.vector,
+    ...RULES.formats.video,
+    ...RULES.formats.document,
+  ];
+
+  if (!allFormats.includes(extension)) {
+    issues.push(`Unsupported file format: .${extension}`);
+    return { valid: false, issues, info };
+  }
+
+  // Determine category
+  if (RULES.formats.image.includes(extension)) info.category = "image";
+  else if (RULES.formats.vector.includes(extension)) info.category = "vector";
+  else if (RULES.formats.video.includes(extension)) info.category = "video";
+  else if (RULES.formats.document.includes(extension))
+    info.category = "document";
+
+  return { valid: true, issues, info };
+}
+
+/**
+ * Check if asset exists in manifest
+ */
+function checkManifest(filepath) {
+  const manifestPath = path.join(process.cwd(), ".assets", "manifest.json");
+
+  if (!fs.existsSync(manifestPath)) {
+    return { registered: false, message: "Manifest not found" };
+  }
+
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    const relativePath = path.relative(process.cwd(), filepath);
+    const found = manifest.assets?.find(
+      (a) => a.path === relativePath || a.path === filepath
+    );
+
+    return {
+      registered: !!found,
+      message: found ? "Asset registered in manifest" : "Asset not in manifest",
+      asset: found,
+    };
+  } catch {
+    return { registered: false, message: "Error reading manifest" };
+  }
+}
+
+/**
+ * Generate suggested filename
+ */
+function suggestFilename(original, parsed) {
+  if (!parsed) return null;
+
+  const today = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+  const type = parsed.type || "asset";
+  const campaign = parsed.campaign || "general";
+  const description = parsed.description || "untitled";
+  const ext = parsed.extension || "png";
+
+  return `${type}_${campaign}_${description}_${today}.${ext}`;
+}
+
+/**
+ * Format bytes to human readable
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 Bytes";
+  const k = 1024;
+  const sizes = ["Bytes", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+}
+
+/**
+ * Main validation function
+ */
+function validateAsset(assetPath) {
+  const results = {
+    path: assetPath,
+    filename: path.basename(assetPath),
+    valid: true,
+    issues: [],
+    warnings: [],
+    suggestions: [],
+    checks: {},
+  };
+
+  // Check file exists
+  if (!fs.existsSync(assetPath)) {
+    results.valid = false;
+    results.issues.push(`File not found: ${assetPath}`);
+    return results;
+  }
+
+  const filename = path.basename(assetPath);
+  const extension = path.extname(filename).slice(1).toLowerCase();
+
+  // 1. Validate filename
+  const filenameResult = validateFilename(filename);
+  results.checks.filename = filenameResult;
+  if (!filenameResult.valid) {
+    results.issues.push(...filenameResult.issues);
+    results.suggestions.push(...filenameResult.suggestions);
+  }
+
+  // 2. Validate format
+  const formatResult = validateFormat(extension);
+  results.checks.format = formatResult;
+  if (!formatResult.valid) {
+    results.issues.push(...formatResult.issues);
+  }
+
+  // 3. Validate file size
+  const sizeResult = validateFileSize(assetPath, extension);
+  results.checks.fileSize = sizeResult;
+  if (!sizeResult.valid) {
+    results.issues.push(...sizeResult.issues);
+  }
+  results.warnings.push(...sizeResult.warnings);
+
+  // 4. Check manifest registration
+  const manifestResult = checkManifest(assetPath);
+  results.checks.manifest = manifestResult;
+  if (!manifestResult.registered) {
+    results.warnings.push("Asset not registered in manifest.json");
+    results.suggestions.push(
+      "Register asset in .assets/manifest.json for tracking"
+    );
+  }
+
+  // 5. Suggest corrected filename if needed
+  if (!filenameResult.valid && filenameResult.parsed) {
+    const suggested = suggestFilename(filename, filenameResult.parsed);
+    if (suggested) {
+      results.suggestions.push(`Suggested filename: ${suggested}`);
+    }
+  }
+
+  // Overall validity
+  results.valid = results.issues.length === 0;
+
+  return results;
+}
+
+/**
+ * Format output for console
+ */
+function formatOutput(results) {
+  const lines = [];
+
+  lines.push("\n" + "=".repeat(60));
+  lines.push(`ASSET VALIDATION: ${results.filename}`);
+  lines.push("=".repeat(60));
+
+  lines.push(`\nStatus: ${results.valid ? "PASS" : "FAIL"}`);
+  lines.push(`Path: ${results.path}`);
+
+  if (results.issues.length > 0) {
+    lines.push("\nISSUES:");
+    results.issues.forEach((issue) => lines.push(`  - ${issue}`));
+  }
+
+  if (results.warnings.length > 0) {
+    lines.push("\nWARNINGS:");
+    results.warnings.forEach((warning) => lines.push(`  - ${warning}`));
+  }
+
+  if (results.suggestions.length > 0) {
+    lines.push("\nSUGGESTIONS:");
+    results.suggestions.forEach((suggestion) =>
+      lines.push(`  - ${suggestion}`)
+    );
+  }
+
+  // File size info
+  if (results.checks.fileSize?.size) {
+    lines.push(`\nFile Size: ${formatBytes(results.checks.fileSize.size)}`);
+  }
+
+  lines.push("\n" + "=".repeat(60));
+
+  return lines.join("\n");
+}
+
+/**
+ * Main
+ */
+function main() {
+  const args = process.argv.slice(2);
+  const jsonOutput = args.includes("--json");
+  const assetPath = args.find((a) => !a.startsWith("--"));
+
+  if (!assetPath) {
+    console.error("Usage: node validate-asset.cjs <asset-path> [--json]");
+    console.error("\nExamples:");
+    console.error(
+      "  node validate-asset.cjs assets/banners/social-media/banner_launch_hero_20251209.png"
+    );
+    console.error(
+      "  node validate-asset.cjs assets/logos/icon-only/logo-icon.svg --json"
+    );
+    process.exit(1);
+  }
+
+  // Resolve path
+  const resolvedPath = path.isAbsolute(assetPath)
+    ? assetPath
+    : path.join(process.cwd(), assetPath);
+
+  // Validate
+  const results = validateAsset(resolvedPath);
+
+  // Output
+  if (jsonOutput) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(formatOutput(results));
+  }
+
+  // Exit with appropriate code
+  process.exit(results.valid ? 0 : 1);
+}
+
+main();

package/skills/design/uupm-brand/templates/brand-guidelines-starter.md

@@ -0,0 +1,275 @@
+# Brand Guidelines v1.0
+
+> Last updated: {DATE}
+> Status: Draft
+
+## Quick Reference
+
+| Element | Value |
+|---------|-------|
+| Primary Color | #2563EB |
+| Secondary Color | #8B5CF6 |
+| Primary Font | Inter |
+| Voice | Professional, Helpful, Clear |
+
+---
+
+## 1. Color Palette
+
+### Primary Colors
+
+| Name | Hex | RGB | Usage |
+|------|-----|-----|-------|
+| Primary Blue | #2563EB | rgb(37,99,235) | CTAs, headers, links |
+| Primary Dark | #1D4ED8 | rgb(29,78,216) | Hover states, emphasis |
+
+### Secondary Colors
+
+| Name | Hex | RGB | Usage |
+|------|-----|-----|-------|
+| Secondary Purple | #8B5CF6 | rgb(139,92,246) | Accents, highlights |
+| Accent Green | #10B981 | rgb(16,185,129) | Success, positive states |
+
+### Neutral Palette
+
+| Name | Hex | RGB | Usage |
+|------|-----|-----|-------|
+| Background | #FFFFFF | rgb(255,255,255) | Page backgrounds |
+| Surface | #F9FAFB | rgb(249,250,251) | Cards, sections |
+| Text Primary | #111827 | rgb(17,24,39) | Headings, body text |
+| Text Secondary | #6B7280 | rgb(107,114,128) | Captions, muted text |
+| Border | #E5E7EB | rgb(229,231,235) | Dividers, borders |
+
+### Semantic Colors
+
+| State | Hex | Usage |
+|-------|-----|-------|
+| Success | #22C55E | Positive actions, confirmations |
+| Warning | #F59E0B | Cautions, pending states |
+| Error | #EF4444 | Errors, destructive actions |
+| Info | #3B82F6 | Informational messages |
+
+### Accessibility
+
+- Text on white background: 7.2:1 contrast ratio (AAA)
+- Primary on white: 4.6:1 contrast ratio (AA)
+- All interactive elements meet WCAG 2.1 AA standards
+
+---
+
+## 2. Typography
+
+### Font Stack
+
+```css
+--font-heading: 'Inter', system-ui, -apple-system, sans-serif;
+--font-body: 'Inter', system-ui, -apple-system, sans-serif;
+--font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+```
+
+### Type Scale
+
+| Element | Size (Desktop) | Size (Mobile) | Weight | Line Height |
+|---------|----------------|---------------|--------|-------------|
+| H1 | 48px | 32px | 700 | 1.2 |
+| H2 | 36px | 28px | 600 | 1.25 |
+| H3 | 28px | 24px | 600 | 1.3 |
+| H4 | 24px | 20px | 600 | 1.35 |
+| Body | 16px | 16px | 400 | 1.5 |
+| Body Large | 18px | 18px | 400 | 1.6 |
+| Small | 14px | 14px | 400 | 1.5 |
+| Caption | 12px | 12px | 400 | 1.4 |
+
+### Font Loading
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+---
+
+## 3. Logo Usage
+
+### Variants
+
+| Variant | File | Use Case |
+|---------|------|----------|
+| Full Horizontal | logo-full-horizontal.svg | Headers, documents |
+| Stacked | logo-stacked.svg | Square spaces |
+| Icon Only | logo-icon.svg | Favicons, small spaces |
+| Monochrome | logo-mono.svg | Limited color contexts |
+
+### Clear Space
+
+Minimum clear space = height of the logo icon (mark)
+
+### Minimum Size
+
+| Context | Minimum Width |
+|---------|---------------|
+| Digital - Full Logo | 120px |
+| Digital - Icon | 24px |
+| Print - Full Logo | 35mm |
+| Print - Icon | 10mm |
+
+### Don'ts
+
+- Don't rotate or skew the logo
+- Don't change colors outside approved palette
+- Don't add shadows or effects
+- Don't crop or modify proportions
+- Don't place on busy backgrounds without sufficient contrast
+
+---
+
+## 4. Voice & Tone
+
+### Brand Personality
+
+| Trait | Description |
+|-------|-------------|
+| **Professional** | Expert knowledge, authoritative yet approachable |
+| **Helpful** | Solution-focused, actionable guidance |
+| **Clear** | Direct communication, jargon-free |
+| **Confident** | Assured without being arrogant |
+
+### Voice Chart
+
+| Trait | We Are | We Are Not |
+|-------|--------|------------|
+| Professional | Expert, knowledgeable | Stuffy, corporate |
+| Helpful | Supportive, empowering | Patronizing |
+| Clear | Direct, concise | Vague, wordy |
+| Confident | Assured, trustworthy | Arrogant, overselling |
+
+### Tone by Context
+
+| Context | Tone | Example |
+|---------|------|---------|
+| Marketing | Engaging, benefit-focused | "Create campaigns that convert." |
+| Documentation | Clear, instructional | "Run the command to start." |
+| Error messages | Calm, solution-focused | "Try refreshing the page." |
+| Success | Brief, celebratory | "Campaign published!" |
+
+### Prohibited Terms
+
+| Avoid | Reason |
+|-------|--------|
+| Revolutionary | Overused |
+| Best-in-class | Vague claim |
+| Seamless | Overused |
+| Synergy | Corporate jargon |
+| Leverage | Use "use" instead |
+
+---
+
+## 5. Imagery Guidelines
+
+### Photography Style
+
+- **Lighting:** Natural, soft lighting preferred
+- **Subjects:** Real people, authentic scenarios
+- **Color treatment:** Maintain brand colors in post
+- **Composition:** Clean, focused subjects
+
+### Illustrations
+
+- Style: Modern, flat design with subtle gradients
+- Colors: Brand palette only
+- Line weight: 2px consistent stroke
+- Corners: 4px rounded
+
+### Icons
+
+- Style: Outlined, 24px base grid
+- Stroke: 1.5px consistent
+- Corner radius: 2px
+- Fill: None (outline only)
+
+---
+
+## 6. Design Components
+
+### Buttons
+
+| Type | Background | Text | Border Radius |
+|------|------------|------|---------------|
+| Primary | #2563EB | #FFFFFF | 8px |
+| Secondary | Transparent | #2563EB | 8px |
+| Tertiary | Transparent | #6B7280 | 8px |
+
+### Spacing Scale
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Tight spacing |
+| sm | 8px | Compact elements |
+| md | 16px | Standard spacing |
+| lg | 24px | Section spacing |
+| xl | 32px | Large gaps |
+| 2xl | 48px | Section dividers |
+
+### Border Radius
+
+| Element | Radius |
+|---------|--------|
+| Buttons | 8px |
+| Cards | 12px |
+| Inputs | 8px |
+| Modals | 16px |
+| Pills/Tags | 9999px |
+
+---
+
+## AI Image Generation
+
+### Base Prompt Template
+
+Always prepend to image generation prompts:
+
+```
+{DESCRIBE YOUR VISUAL STYLE HERE - mood, colors with hex codes, lighting, atmosphere}
+```
+
+### Style Keywords
+
+| Category | Keywords |
+|----------|----------|
+| **Lighting** | {e.g., soft lighting, dramatic, natural} |
+| **Mood** | {e.g., professional, energetic, calm} |
+| **Composition** | {e.g., centered, rule of thirds, minimal} |
+| **Treatment** | {e.g., high contrast, muted, vibrant} |
+| **Aesthetic** | {e.g., modern, vintage, minimalist} |
+
+### Visual Mood Descriptors
+
+- {Mood descriptor 1}
+- {Mood descriptor 2}
+- {Mood descriptor 3}
+
+### Visual Don'ts
+
+| Avoid | Reason |
+|-------|--------|
+| {Item to avoid} | {Why to avoid it} |
+
+### Example Prompts
+
+**Hero Banner:**
+```
+{Example prompt for hero banners}
+```
+
+**Social Media Post:**
+```
+{Example prompt for social graphics}
+```
+
+---
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | {DATE} | Initial guidelines |