agent-skill-kit 3.9.135

package/.agent/skills/studio/scripts/utils/css-templates.ts

@@ -0,0 +1,169 @@
+// @ts-nocheck
+/**
+ * CSS Template Generators - Studio Design System
+ * ===============================================
+ * Utilities for generating CSS variables and token systems
+ * Used by formatMasterMd() and formatPageOverrideMd()
+ */
+
+/**
+ * Generate CSS custom properties for color palette
+ * @param {Object} colorData - Color palette data from design system
+ * @returns {string} CSS custom properties block
+ */
+export function generateColorVars(colorData) {
+    if (!colorData) return '';
+
+    const lines = [];
+    lines.push(':root {');
+
+    if (colorData.primary) {
+        lines.push(`  --color-primary: ${colorData.primary};`);
+    }
+    if (colorData.secondary) {
+        lines.push(`  --color-secondary: ${colorData.secondary};`);
+    }
+    if (colorData.cta) {
+        lines.push(`  --color-cta: ${colorData.cta};`);
+    }
+    if (colorData.background) {
+        lines.push(`  --color-bg: ${colorData.background};`);
+    }
+    if (colorData.text) {
+        lines.push(`  --color-text: ${colorData.text};`);
+    }
+    if (colorData.border) {
+        lines.push(`  --color-border: ${colorData.border};`);
+    }
+
+    lines.push('}');
+    return lines.join('\n');
+}
+
+/**
+ * Generate 7-level spacing scale (xs to 3xl)
+ * Based on 4px base unit (common design system standard)
+ * @returns {string} CSS spacing variables
+ */
+export function generateSpacingScale() {
+    const spacings = {
+        'xs': '4px',   // 0.25rem
+        'sm': '8px',   // 0.5rem
+        'md': '16px',  // 1rem
+        'lg': '24px',  // 1.5rem
+        'xl': '32px',  // 2rem
+        '2xl': '48px', // 3rem
+        '3xl': '64px'  // 4rem
+    };
+
+    const lines = [];
+    lines.push(':root {');
+
+    for (const [size, value] of Object.entries(spacings)) {
+        lines.push(`  --spacing-${size}: ${value};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+    lines.push('/* Usage Examples:');
+    lines.push(' * padding: var(--spacing-md);  // 16px');
+    lines.push(' * margin-top: var(--spacing-lg);  // 24px');
+    lines.push(' * gap: var(--spacing-sm);  // 8px');
+    lines.push(' */');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate 4-level shadow depth system
+ * Based on Material Design elevation principles
+ * @returns {string} CSS shadow variables
+ */
+export function generateShadowDepths() {
+    const shadows = {
+        'sm': '0 1px 2px 0 rgba(0, 0, 0, 0.05)',  // Cards, buttons
+        'md': '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)',  // Dropdowns
+        'lg': '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)',  // Modals
+        'xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)'  // Overlays
+    };
+
+    const lines = [];
+    lines.push(':root {');
+
+    for (const [depth, value] of Object.entries(shadows)) {
+        lines.push(`  --shadow-${depth}: ${value};`);
+    }
+
+    lines.push('}');
+    lines.push('');
+    lines.push('/* Usage Examples:');
+    lines.push(' * box-shadow: var(--shadow-sm);  // Subtle card elevation');
+    lines.push(' * box-shadow: var(--shadow-md);  // Dropdown menus');
+    lines.push(' * box-shadow: var(--shadow-lg);  // Modal dialogs');
+    lines.push(' * box-shadow: var(--shadow-xl);  // Full-page overlays');
+    lines.push(' */');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate border radius scale
+ * @returns {string} CSS border radius variables
+ */
+export function generateBorderRadiusScale() {
+    const radii = {
+        'none': '0',
+        'sm': '0.125rem',  // 2px
+        'md': '0.375rem',  // 6px
+        'lg': '0.5rem',    // 8px
+        'xl': '0.75rem',   // 12px
+        'full': '9999px'   // Fully rounded
+    };
+
+    const lines = [];
+    lines.push(':root {');
+
+    for (const [size, value] of Object.entries(radii)) {
+        lines.push(`  --radius-${size}: ${value};`);
+    }
+
+    lines.push('}');
+
+    return lines.join('\n');
+}
+
+/**
+ * Generate complete CSS token system
+ * Combines all token generators
+ * @param {Object} colorData - Color palette from design system
+ * @returns {string} Complete CSS variables block
+ */
+export function generateTokenSystem(colorData) {
+    const sections = [];
+
+    sections.push('/* === Design Tokens === */');
+    sections.push('');
+
+    // Colors
+    if (colorData && Object.keys(colorData).length > 0) {
+        sections.push('/* Colors */');
+        sections.push(generateColorVars(colorData));
+        sections.push('');
+    }
+
+    // Spacing
+    sections.push('/* Spacing Scale */');
+    sections.push(generateSpacingScale());
+    sections.push('');
+
+    // Shadows
+    sections.push('/* Shadow Depths */');
+    sections.push(generateShadowDepths());
+    sections.push('');
+
+    // Border Radius
+    sections.push('/* Border Radius */');
+    sections.push(generateBorderRadiusScale());
+
+    return sections.join('\n');
+}

package/.agent/skills/studio/scripts/utils/css-validator.ts

@@ -0,0 +1,95 @@
+// @ts-nocheck
+/**
+ * CSS Validator - Studio Design System
+ * =====================================
+ * Validates generated CSS syntax using css-tree parser
+ * Non-blocking validation with optional strict mode
+ */
+
+import * as cssTree from 'css-tree';
+
+/**
+ * Validate CSS syntax
+ * @param {string} css - CSS string to validate
+ * @param {Object} options - Validation options
+ * @param {boolean} options.strict - If true, throw error on invalid CSS
+ * @returns {{ valid: boolean, errors: Array<{message: string, line: number, column: number}> }}
+ */
+export function validateCss(css, options = {}) {
+    const { strict = false } = options;
+    const errors = [];
+
+    if (!css || typeof css !== 'string') {
+        return { valid: true, errors: [] }; // Empty/null CSS is valid
+    }
+
+    try {
+        // Parse CSS - cssTree.parse throws on syntax errors
+        cssTree.parse(css, {
+            onParseError: (error) => {
+                errors.push({
+                    message: error.message,
+                    line: error.line || 0,
+                    column: error.column || 0
+                });
+            }
+        });
+    } catch (parseError) {
+        errors.push({
+            message: parseError.message,
+            line: parseError.line || 0,
+            column: parseError.column || 0
+        });
+    }
+
+    const valid = errors.length === 0;
+
+    if (strict && !valid) {
+        throw new Error(`CSS validation failed:\n${errors.map(e => `  Line ${e.line}: ${e.message}`).join('\n')}`);
+    }
+
+    return { valid, errors };
+}
+
+/**
+ * Validate CSS and return formatted result for logging
+ * @param {string} css - CSS string to validate
+ * @param {string} context - Context description for error messages
+ * @returns {string|null} Error message or null if valid
+ */
+export function validateCssWithContext(css, context = 'CSS') {
+    const result = validateCss(css);
+    
+    if (!result.valid) {
+        const errorLines = result.errors.map(e => 
+            `  Line ${e.line}, Col ${e.column}: ${e.message}`
+        ).join('\n');
+        return `⚠️ ${context} validation warnings:\n${errorLines}`;
+    }
+    
+    return null;
+}
+
+/**
+ * Extract CSS blocks from markdown and validate each
+ * @param {string} markdown - Markdown content with CSS code blocks
+ * @returns {{ valid: boolean, warnings: string[] }}
+ */
+export function validateMarkdownCss(markdown) {
+    const cssBlockRegex = /```css\n([\s\S]*?)```/g;
+    const warnings = [];
+    let match;
+
+    while ((match = cssBlockRegex.exec(markdown)) !== null) {
+        const cssContent = match[1].trim();
+        const validation = validateCss(cssContent);
+        
+        if (!validation.valid) {
+            validation.errors.forEach(err => {
+                warnings.push(`CSS block error (line ${err.line}): ${err.message}`);
+            });
+        }
+    }
+
+    return { valid: warnings.length === 0, warnings };
+}

package/.agent/skills/studio/scripts/utils/csv-loader.ts

@@ -0,0 +1,52 @@
+/**
+ * CSV Loader Utility - Studio Scripts
+ * ====================================
+ * CSV parsing with UTF-8 encoding support
+ */
+
+import { readFile } from 'fs/promises';
+import { parse } from 'csv-parse/sync';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Data directory path (relative to scripts/)
+export const DATA_DIR = join(__dirname, '..', '..', 'data');
+
+export type CSVRow = Record<string, string>;
+
+/**
+ * Load CSV file and return array of objects
+ */
+export async function loadCSV(filepath: string): Promise<CSVRow[]> {
+    try {
+        const fullPath = join(DATA_DIR, filepath);
+        const content = await readFile(fullPath, 'utf-8');
+
+        const records: CSVRow[] = parse(content, {
+            columns: true,
+            skip_empty_lines: true,
+            trim: true,
+            encoding: 'utf-8'
+        });
+
+        return records;
+    } catch (error: unknown) {
+        console.error(`Error loading CSV: ${filepath}`, error instanceof Error ? error.message : String(error));
+        return [];
+    }
+}
+
+/**
+ * Load CSV and check if file exists
+ */
+export async function loadCSVSafe(filepath: string): Promise<{ exists: boolean; data: CSVRow[] }> {
+    try {
+        const data = await loadCSV(filepath);
+        return { exists: true, data };
+    } catch {
+        return { exists: false, data: [] };
+    }
+}

package/.agent/skills/studio/scripts/utils/intelligent-overrides.ts

@@ -0,0 +1,129 @@
+// @ts-nocheck
+/**
+ * Intelligent Page Override Generator - Studio Design System
+ * ============================================================
+ * Generates intelligent page-specific overrides using multi-domain search
+ * This is the core logic for Phase 5 - matches Python version exactly
+ */
+
+import { search } from '../core.js';
+import { detectPageType } from './page-type-detector.ts';
+
+/**
+ * Generate intelligent overrides based on page type using layered search
+ * @param {string} pageName - Page name (e.g., "dashboard", "checkout")
+ * @param {string} pageQuery - Optional query for context (e.g., "SaaS dashboard")
+ * @param {Object} designSystem - Base design system object
+ * @returns {Promise<Object>} Override object with layout, spacing, typography, colors, components, recommendations
+ */
+export async function generateIntelligentOverrides(pageName, pageQuery, designSystem) {
+    const pageLower = (pageName || '').toLowerCase();
+    const queryLower = (pageQuery || '').toLowerCase();
+    const combinedContext = `${pageLower} ${queryLower}`.trim();
+
+    // Search across multiple domains for page-specific guidance
+    const styleSearch = await search(combinedContext, 'style', 1);
+    const uxSearch = await search(combinedContext, 'ux', 3);
+    const landingSearch = await search(combinedContext, 'landing', 1);
+
+    // Extract results from search response
+    const styleResults = styleSearch?.results || [];
+    const uxResults = uxSearch?.results || [];
+    const landingResults = landingSearch?.results || [];
+
+    // Detect page type from search results or context
+    const pageType = detectPageType(combinedContext, styleResults);
+
+    // Build overrides from search results
+    const layout = {};
+    const spacing = {};
+    const typography = {};
+    const colors = {};
+    const components = [];
+    const uniqueComponents = [];
+    const recommendations = [];
+
+    // Extract style-based overrides
+    if (styleResults.length > 0) {
+        const style = styleResults[0];
+        const styleName = style['Style Category'] || '';
+        const keywords = (style['Keywords'] || '').toLowerCase();
+        const bestFor = style['Best For'] || '';
+        const effects = style['Effects & Animation'] || '';
+
+        // Infer layout from style keywords
+        const dataKeywords = ['data', 'dense', 'dashboard', 'grid'];
+        const minimalKeywords = ['minimal', 'simple', 'clean', 'single'];
+
+        if (dataKeywords.some(kw => keywords.includes(kw))) {
+            layout['Max Width'] = '1400px or full-width';
+            layout['Grid'] = '12-column grid for data flexibility';
+            spacing['Content Density'] = 'High — optimize for information display';
+        } else if (minimalKeywords.some(kw => keywords.includes(kw))) {
+            layout['Max Width'] = '800px (narrow, focused)';
+            layout['Layout'] = 'Single column, centered';
+            spacing['Content Density'] = 'Low — focus on clarity';
+        } else {
+            layout['Max Width'] = '1200px (standard)';
+            layout['Layout'] = 'Full-width sections, centered content';
+        }
+
+        if (effects) {
+            recommendations.push(`Effects: ${effects}`);
+        }
+    }
+
+    // Extract UX guidelines as recommendations
+    for (const ux of uxResults) {
+        const category = ux['Category'] || '';
+        const doText = ux['Do'] || '';
+        const dontText = ux["Don't"] || '';
+
+        if (doText) {
+            recommendations.push(`${category}: ${doText}`);
+        }
+        if (dontText) {
+            components.push(`Avoid: ${dontText}`);
+        }
+    }
+
+    // Extract landing pattern info for section structure
+    if (landingResults.length > 0) {
+        const landing = landingResults[0];
+        const sections = landing['Section Order'] || '';
+        const ctaPlacement = landing['Primary CTA Placement'] || '';
+        const colorStrategy = landing['Color Strategy'] || '';
+
+        if (sections) {
+            layout['Sections'] = sections;
+        }
+        if (ctaPlacement) {
+            recommendations.push(`CTA Placement: ${ctaPlacement}`);
+        }
+        if (colorStrategy) {
+            colors['Strategy'] = colorStrategy;
+        }
+    }
+
+    // Add page-type specific defaults if no search results
+    if (Object.keys(layout).length === 0) {
+        layout['Max Width'] = '1200px';
+        layout['Layout'] = 'Responsive grid';
+    }
+
+    if (recommendations.length === 0) {
+        recommendations.push('Refer to MASTER.md for all design rules');
+        recommendations.push('Add specific overrides as needed for this page');
+    }
+
+    return {
+        page_type: pageType,
+        layout,
+        spacing,
+        typography,
+        colors,
+        components,
+        unique_components: uniqueComponents,
+        recommendations
+    };
+}

package/.agent/skills/studio/scripts/utils/page-override-formatter.ts

@@ -0,0 +1,143 @@
+// @ts-nocheck
+/**
+ * Page Override Formatter - Studio Design System
+ * ================================================
+ * Formats page-specific override markdown files
+ * Final component of Phase 6 - matches Python version exactly
+ */
+
+import { generateIntelligentOverrides } from './intelligent-overrides.ts';
+
+/**
+ * Format a page-specific override file with intelligent AI-generated content
+ * @param {Object} designSystem - Base design system object
+ * @param {string} pageName - Page name (e.g., "dashboard", "checkout")
+ * @param {string} pageQuery - Optional query for additional context
+ * @returns {Promise<string>} Formatted markdown content for page override file
+ */
+export async function formatPageOverrideMd(designSystem, pageName, pageQuery = null) {
+    const project = designSystem.project_name || 'PROJECT';
+    const timestamp = new Date().toISOString(); // Full ISO 8601 UTC format
+    const pageTitle = pageName
+        .replace(/-/g, ' ')
+        .replace(/_/g, ' ')
+        .split(' ')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+
+    // Detect page type and generate intelligent overrides
+    const pageOverrides = await generateIntelligentOverrides(pageName, pageQuery, designSystem);
+
+    const lines = [];
+
+    lines.push(`# ${pageTitle} Page Overrides`);
+    lines.push('');
+    lines.push(`> **PROJECT:** ${project}`);
+    lines.push(`> **Generated:** ${timestamp}`);
+    lines.push(`> **Page Type:** ${pageOverrides.page_type || 'General'}`);
+    lines.push('');
+    lines.push('> ⚠️ **IMPORTANT:** Rules in this file **override** the Master file (`design-system/MASTER.md`).');
+    lines.push('> Only deviations from the Master are documented here. For all other rules, refer to the Master.');
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+
+    // Page-specific rules with actual content
+    lines.push('## Page-Specific Rules');
+    lines.push('');
+
+    // Layout Overrides
+    lines.push('### Layout Overrides');
+    lines.push('');
+    const layout = pageOverrides.layout || {};
+    if (Object.keys(layout).length > 0) {
+        for (const [key, value] of Object.entries(layout)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master layout');
+    }
+    lines.push('');
+
+    // Spacing Overrides
+    lines.push('### Spacing Overrides');
+    lines.push('');
+    const spacing = pageOverrides.spacing || {};
+    if (Object.keys(spacing).length > 0) {
+        for (const [key, value] of Object.entries(spacing)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master spacing');
+    }
+    lines.push('');
+
+    // Typography Overrides
+    lines.push('### Typography Overrides');
+    lines.push('');
+    const typography = pageOverrides.typography || {};
+    if (Object.keys(typography).length > 0) {
+        for (const [key, value] of Object.entries(typography)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master typography');
+    }
+    lines.push('');
+
+    // Color Overrides
+    lines.push('### Color Overrides');
+    lines.push('');
+    const colors = pageOverrides.colors || {};
+    if (Object.keys(colors).length > 0) {
+        for (const [key, value] of Object.entries(colors)) {
+            lines.push(`- **${key}:** ${value}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master colors');
+    }
+    lines.push('');
+
+    // Component Overrides
+    lines.push('### Component Overrides');
+    lines.push('');
+    const components = pageOverrides.components || [];
+    if (components.length > 0) {
+        for (const comp of components) {
+            lines.push(`- ${comp}`);
+        }
+    } else {
+        lines.push('- No overrides — use Master component specs');
+    }
+    lines.push('');
+
+    // Page-Specific Components
+    lines.push('---');
+    lines.push('');
+    lines.push('## Page-Specific Components');
+    lines.push('');
+    const uniqueComponents = pageOverrides.unique_components || [];
+    if (uniqueComponents.length > 0) {
+        for (const comp of uniqueComponents) {
+            lines.push(`- ${comp}`);
+        }
+    } else {
+        lines.push('- No unique components for this page');
+    }
+    lines.push('');
+
+    // Recommendations
+    lines.push('---');
+    lines.push('');
+    lines.push('## Recommendations');
+    lines.push('');
+    const recommendations = pageOverrides.recommendations || [];
+    if (recommendations.length > 0) {
+        for (const rec of recommendations) {
+            lines.push(`- ${rec}`);
+        }
+    }
+    lines.push('');
+
+    return lines.join('\n');
+}